Thread Trace Service

Thread Trace Service#

Rocprofiler SDK Developer API: Thread Trace Service

Rocprofiler SDK Developer API 0.4.0

ROCm Profiling API and tools

Provides API calls to enable and handle thread trace data. More...

Data Structures
struct	rocprofiler_att_parameter_t

struct	rocprofiler_att_data_type_isa_t

struct	rocprofiler_att_data_type_occupancy_t

union	rocprofiler_att_parameter_t.__unnamed1__

struct	rocprofiler_att_parameter_t.__unnamed1__.__unnamed3__

Typedefs
typedef void(*	rocprofiler_att_shader_data_callback_t) (int64_t shader_engine_id, void *data, unsigned long data_size, rocprofiler_user_data_t userdata)
	Callback to be triggered every time some ATT data is generated by the device.

typedef rocprofiler_status_t(*	rocprofiler_att_parser_isa_callback_t) (char isa_instruction, uint64_t isa_memory_size, uint64_t isa_size, uint64_t marker_id, uint64_t offset, void userdata)
	Callback for rocprofiler to parsed ATT data. The caller must copy a desired instruction on isa_instruction and source_reference, while obeying the max length passed by the caller. If the caller's length is insufficient, then this function writes the minimum sizes to isa_size and source_size and returns ROCPROFILER_STATUS_ERROR_OUT_OF_RESOURCES. If call returns ROCPROFILER_STATUS_SUCCESS, isa_size and source_size are written with bytes used.

typedef uint64_t(*	rocprofiler_att_parser_se_data_callback_t) (int shader_engine_id, uint8_t buffer, uint64_t buffer_size, void *userdata)
	Callback for the ATT parser to retrieve Shader Engine data. Returns the amount of data filled. If no more data is available, then callback return 0 If the space available in the buffer is less than required for parsing the full data, the full data is transfered over multiple calls. When all data has been transfered from current shader_engine_id, the caller has the option to 1) Return -1 on shader_engine ID and parsing terminates 2) Move to the next shader engine.

typedef void(*	rocprofiler_att_parser_trace_callback_t) (rocprofiler_att_parser_data_type_t type, void att_data, void userdata)
	Callback for rocprofiler to return traces back to rocprofiler.

typedef rocprofiler_att_control_flags_t(*	rocprofiler_att_dispatch_callback_t) (rocprofiler_queue_id_t queue_id, const rocprofiler_agent_t agent, rocprofiler_correlation_id_t correlation_id, rocprofiler_kernel_id_t kernel_id, rocprofiler_dispatch_id_t dispatch_id, rocprofiler_user_data_t userdata_shader, void *userdata_config)
	Callback to be triggered every kernel dispatch, indicating to start and/or stop ATT.

Enumerations
enum	rocprofiler_att_parameter_type_t { ROCPROFILER_ATT_PARAMETER_TARGET_CU = 0 , ROCPROFILER_ATT_PARAMETER_SHADER_ENGINE_MASK , ROCPROFILER_ATT_PARAMETER_BUFFER_SIZE , ROCPROFILER_ATT_PARAMETER_SIMD_SELECT , ROCPROFILER_ATT_PARAMETER_PERFCOUNTERS_CTRL , ROCPROFILER_ATT_PARAMETER_PERFCOUNTER , ROCPROFILER_ATT_PARAMETER_LAST }

enum	rocprofiler_att_parser_data_type_t { ROCPROFILER_ATT_PARSER_DATA_TYPE_ISA = 0 , ROCPROFILER_ATT_PARSER_DATA_TYPE_OCCUPANCY }

enum	rocprofiler_att_control_flags_t { ROCPROFILER_ATT_CONTROL_NONE = 0 , ROCPROFILER_ATT_CONTROL_START = 1 , ROCPROFILER_ATT_CONTROL_STOP = 2 , ROCPROFILER_ATT_CONTROL_START_AND_STOP = 3 }

Functions
rocprofiler_status_t	rocprofiler_configure_agent_thread_trace_service (rocprofiler_context_id_t context_id, rocprofiler_att_parameter_t parameters, unsigned long num_parameters, rocprofiler_agent_id_t agent_id, rocprofiler_att_shader_data_callback_t shader_callback, void callback_userdata)
	Configure Thread Trace Service for agent. There may only be one agent profile configured per context and can be only one active context that is profiling a single agent at a time. Multiple agent contexts can be started at the same time if they are profiling different agents.

rocprofiler_status_t	rocprofiler_att_parse_data (rocprofiler_att_parser_se_data_callback_t se_data_callback, rocprofiler_att_parser_trace_callback_t trace_callback, rocprofiler_att_parser_isa_callback_t isa_callback, void *userdata)
	Iterate over all event coordinates for a given agent_t and event_t.

rocprofiler_status_t	rocprofiler_configure_dispatch_thread_trace_service (rocprofiler_context_id_t context_id, rocprofiler_att_parameter_t parameters, unsigned long num_parameters, rocprofiler_att_dispatch_callback_t dispatch_callback, rocprofiler_att_shader_data_callback_t shader_callback, void callback_userdata)
	Enables the advanced thread trace service for dispatch-based tracing. The tool has an option to enable/disable thread trace on every dispatch callback. This service enables kernel serialization.

Detailed Description

Provides API calls to enable and handle thread trace data.

Data Structure Documentation

◆ rocprofiler_att_parameter_t

struct rocprofiler_att_parameter_t

Definition at line 50 of file thread_trace_core.h.

Collaboration diagram for rocprofiler_att_parameter_t:

Data Fields
union rocprofiler_att_parameter_t.__unnamed1__	__unnamed__
rocprofiler_att_parameter_type_t	type

◆ rocprofiler_att_data_type_isa_t

struct rocprofiler_att_data_type_isa_t

Definition at line 132 of file thread_trace_core.h.

Collaboration diagram for rocprofiler_att_data_type_isa_t:

Data Fields
uint64_t	hitcount
uint64_t	latency
uint64_t	marker_id
uint64_t	offset

◆ rocprofiler_att_data_type_occupancy_t

struct rocprofiler_att_data_type_occupancy_t

Definition at line 140 of file thread_trace_core.h.

Collaboration diagram for rocprofiler_att_data_type_occupancy_t:

Data Fields
uint64_t	enabled: 1
uint64_t	marker_id
uint64_t	offset
uint64_t	timestamp: 63

◆ rocprofiler_att_parameter_t.unnamed1

union rocprofiler_att_parameter_t.__unnamed1__

Definition at line 53 of file thread_trace_core.h.

Collaboration diagram for rocprofiler_att_parameter_t.__unnamed1__:

Data Fields
struct rocprofiler_att_parameter_t.__unnamed1__.__unnamed3__	__unnamed__
uint64_t	value

◆ rocprofiler_att_parameter_t.unnamed1.unnamed3

struct rocprofiler_att_parameter_t.__unnamed1__.__unnamed3__

Definition at line 56 of file thread_trace_core.h.

Collaboration diagram for rocprofiler_att_parameter_t.__unnamed1__.__unnamed3__:

Data Fields
rocprofiler_counter_id_t	counter_id
uint64_t	simd_mask: 4

Typedef Documentation

◆ rocprofiler_att_dispatch_callback_t

typedef rocprofiler_att_control_flags_t(* rocprofiler_att_dispatch_callback_t) (rocprofiler_queue_id_t queue_id, const rocprofiler_agent_t *agent, rocprofiler_correlation_id_t correlation_id, rocprofiler_kernel_id_t kernel_id, rocprofiler_dispatch_id_t dispatch_id, rocprofiler_user_data_t *userdata_shader, void *userdata_config)

Callback to be triggered every kernel dispatch, indicating to start and/or stop ATT.

Definition at line 51 of file thread_trace_dispatch.h.

◆ rocprofiler_att_parser_isa_callback_t

typedef rocprofiler_status_t(* rocprofiler_att_parser_isa_callback_t) (char *isa_instruction, uint64_t *isa_memory_size, uint64_t *isa_size, uint64_t marker_id, uint64_t offset, void *userdata)

Callback for rocprofiler to parsed ATT data. The caller must copy a desired instruction on isa_instruction and source_reference, while obeying the max length passed by the caller. If the caller's length is insufficient, then this function writes the minimum sizes to isa_size and source_size and returns ROCPROFILER_STATUS_ERROR_OUT_OF_RESOURCES. If call returns ROCPROFILER_STATUS_SUCCESS, isa_size and source_size are written with bytes used.

Parameters

[out]	isa_instruction	Where to copy the ISA line to.
[out]	isa_memory_size	(Auto) The number of bytes to next instruction. 0 for custom ISA.
[in,out]	isa_size	Size of returned ISA string.
[in]	marker_id	The generated ATT marker for given codeobject ID.
[in]	offset	The offset from base vaddr for given codeobj ID. If marker_id == 0, this parameter is raw virtual address with no codeobj ID information.
[in]	userdata	Arbitrary data pointer to be sent back to the user via callback.

Return values

ROCPROFILER_STATUS_SUCCESS	on success.
ROCPROFILER_STATUS_ERROR	on generic error.
ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT	for invalid offset or invalid marker_id.
ROCPROFILER_STATUS_ERROR_OUT_OF_RESOURCES	for insufficient isa_size or source_size.

Definition at line 96 of file thread_trace_core.h.

◆ rocprofiler_att_parser_se_data_callback_t

typedef uint64_t(* rocprofiler_att_parser_se_data_callback_t) (int *shader_engine_id, uint8_t **buffer, uint64_t *buffer_size, void *userdata)

Callback for the ATT parser to retrieve Shader Engine data. Returns the amount of data filled. If no more data is available, then callback return 0 If the space available in the buffer is less than required for parsing the full data, the full data is transfered over multiple calls. When all data has been transfered from current shader_engine_id, the caller has the option to 1) Return -1 on shader_engine ID and parsing terminates 2) Move to the next shader engine.

Parameters

[out]	shader_engine_id	The ID of given shader engine.
[out]	buffer	The buffer to fill up with SE data.
[out]	buffer_size	The space available in the buffer.
[in]	userdata	Arbitrary data pointer to be sent back to the user via callback.

Returns: Number of bytes remaining in shader engine.

Return values

0	if no more SE data is available. Parsing will stop.
ret	Where 0 > ret > buffer_size for partially filled buffer, and caller moves over to next SE.
buffer_size	if the buffer does not hold enough data for the current shader engine.

Definition at line 121 of file thread_trace_core.h.

◆ rocprofiler_att_parser_trace_callback_t

typedef void(* rocprofiler_att_parser_trace_callback_t) (rocprofiler_att_parser_data_type_t type, void *att_data, void *userdata)

Callback for rocprofiler to return traces back to rocprofiler.

Parameters

[in]	att_data	A datapoint retrieved from thread_trace
[in]	userdata	Arbitrary data pointer to be sent back to the user via callback.

Definition at line 153 of file thread_trace_core.h.

◆ rocprofiler_att_shader_data_callback_t

typedef void(* rocprofiler_att_shader_data_callback_t) (int64_t shader_engine_id, void *data, unsigned long data_size, rocprofiler_user_data_t userdata)

Callback to be triggered every time some ATT data is generated by the device.

Parameters

[in]	shader_engine_id	ID of shader engine, as enabled by SE_MASK
[in]	data	Pointer to the buffer containing the ATT data
[in]	data_size	Number of bytes in "data"
[in]	userdata_dispatch	Passed back to user from rocprofiler_att_dispatch_callback_t()
[in]	userdata_config	Passed back to user from configure_[...]_service()

Definition at line 72 of file thread_trace_core.h.

Enumeration Type Documentation

◆ rocprofiler_att_control_flags_t

enum rocprofiler_att_control_flags_t

Enumerator
ROCPROFILER_ATT_CONTROL_NONE
ROCPROFILER_ATT_CONTROL_START
ROCPROFILER_ATT_CONTROL_STOP
ROCPROFILER_ATT_CONTROL_START_AND_STOP

Definition at line 40 of file thread_trace_dispatch.h.

{
    ROCPROFILER_ATT_CONTROL_NONE           = 0,
    ROCPROFILER_ATT_CONTROL_START          = 1,
    ROCPROFILER_ATT_CONTROL_STOP           = 2,
    ROCPROFILER_ATT_CONTROL_START_AND_STOP = 3
} rocprofiler_att_control_flags_t;

◆ rocprofiler_att_parameter_type_t

enum rocprofiler_att_parameter_type_t

Enumerator
ROCPROFILER_ATT_PARAMETER_TARGET_CU	Select the Target CU or WGP.
ROCPROFILER_ATT_PARAMETER_SHADER_ENGINE_MASK	Bitmask of shader engines.
ROCPROFILER_ATT_PARAMETER_BUFFER_SIZE	Size of combined GPU buffer for ATT.
ROCPROFILER_ATT_PARAMETER_SIMD_SELECT	Bitmask (GFX9) or ID (Navi) of SIMDs.
ROCPROFILER_ATT_PARAMETER_PERFCOUNTERS_CTRL
ROCPROFILER_ATT_PARAMETER_PERFCOUNTER
ROCPROFILER_ATT_PARAMETER_LAST

Definition at line 39 of file thread_trace_core.h.

{
    ROCPROFILER_ATT_PARAMETER_TARGET_CU = 0,       ///< Select the Target CU or WGP
    ROCPROFILER_ATT_PARAMETER_SHADER_ENGINE_MASK,  ///< Bitmask of shader engines.
    ROCPROFILER_ATT_PARAMETER_BUFFER_SIZE,         ///< Size of combined GPU buffer for ATT
    ROCPROFILER_ATT_PARAMETER_SIMD_SELECT,         ///< Bitmask (GFX9) or ID (Navi) of SIMDs
    ROCPROFILER_ATT_PARAMETER_PERFCOUNTERS_CTRL,
    ROCPROFILER_ATT_PARAMETER_PERFCOUNTER,
    ROCPROFILER_ATT_PARAMETER_LAST
} rocprofiler_att_parameter_type_t;

◆ rocprofiler_att_parser_data_type_t

enum rocprofiler_att_parser_data_type_t

Enumerator
ROCPROFILER_ATT_PARSER_DATA_TYPE_ISA
ROCPROFILER_ATT_PARSER_DATA_TYPE_OCCUPANCY

Definition at line 126 of file thread_trace_core.h.

{
    ROCPROFILER_ATT_PARSER_DATA_TYPE_ISA = 0,
    ROCPROFILER_ATT_PARSER_DATA_TYPE_OCCUPANCY,
} rocprofiler_att_parser_data_type_t;

Function Documentation

◆ rocprofiler_att_parse_data()

rocprofiler_status_t rocprofiler_att_parse_data	(	rocprofiler_att_parser_se_data_callback_t	se_data_callback,
		rocprofiler_att_parser_trace_callback_t	trace_callback,
		rocprofiler_att_parser_isa_callback_t	isa_callback,
		void *	userdata
	)

Iterate over all event coordinates for a given agent_t and event_t.

Parameters

[in]	se_data_callback	Callback to return shader engine data from.
[in]	trace_callback	Callback where the trace data is returned to.
[in]	isa_callback	Callback to return ISA lines.
[in]	userdata	Userdata passed back to caller via callback.

◆ rocprofiler_configure_agent_thread_trace_service()

rocprofiler_status_t rocprofiler_configure_agent_thread_trace_service	(	rocprofiler_context_id_t	context_id,
		rocprofiler_att_parameter_t *	parameters,
		unsigned long	num_parameters,
		rocprofiler_agent_id_t	agent_id,
		rocprofiler_att_shader_data_callback_t	shader_callback,
		void *	callback_userdata
	)

Configure Thread Trace Service for agent. There may only be one agent profile configured per context and can be only one active context that is profiling a single agent at a time. Multiple agent contexts can be started at the same time if they are profiling different agents.

Parameters

[in]	context_id	context id
[in]	parameters	List of ATT-specific parameters.
[in]	num_parameters	Number of parameters. Zero is allowed.
[in]	agent_id	agent to configure profiling on.
[in]	shader_callback	Callback fn where the collected data will be sent to.
[in]	callback_userdata	Passed back to user.

◆ rocprofiler_configure_dispatch_thread_trace_service()

rocprofiler_status_t rocprofiler_configure_dispatch_thread_trace_service	(	rocprofiler_context_id_t	context_id,
		rocprofiler_att_parameter_t *	parameters,
		unsigned long	num_parameters,
		rocprofiler_att_dispatch_callback_t	dispatch_callback,
		rocprofiler_att_shader_data_callback_t	shader_callback,
		void *	callback_userdata
	)

Enables the advanced thread trace service for dispatch-based tracing. The tool has an option to enable/disable thread trace on every dispatch callback. This service enables kernel serialization.

Parameters

[in]	context_id	context_id.
[in]	parameters	List of ATT-specific parameters.
[in]	num_parameters	Number of parameters. Zero is allowed.
[in]	dispatch_callback	Control fn which decides when ATT starts/stop collecting.
[in]	shader_callback	Callback fn where the collected data will be sent to.
[in]	callback_userdata	Passed back to user.

Thread Trace Service

Thread Trace Service#

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ rocprofiler_att_parameter_t

◆ rocprofiler_att_data_type_isa_t

◆ rocprofiler_att_data_type_occupancy_t

◆ rocprofiler_att_parameter_t.__unnamed1__

◆ rocprofiler_att_parameter_t.__unnamed1__.__unnamed3__

Typedef Documentation

◆ rocprofiler_att_dispatch_callback_t

◆ rocprofiler_att_parser_isa_callback_t

◆ rocprofiler_att_parser_se_data_callback_t

◆ rocprofiler_att_parser_trace_callback_t

◆ rocprofiler_att_shader_data_callback_t

Enumeration Type Documentation

◆ rocprofiler_att_control_flags_t

◆ rocprofiler_att_parameter_type_t

◆ rocprofiler_att_parser_data_type_t

Function Documentation

◆ rocprofiler_att_parse_data()

◆ rocprofiler_configure_agent_thread_trace_service()

◆ rocprofiler_configure_dispatch_thread_trace_service()

◆ rocprofiler_att_parameter_t.unnamed1

◆ rocprofiler_att_parameter_t.unnamed1.unnamed3