PC Sampling

PC Sampling#

Rocprofiler SDK Developer API: PC Sampling

Rocprofiler SDK Developer API 0.6.0

ROCm Profiling API and tools

Enabling PC (Program Counter) Sampling for GPU Activity. More...

Data Structures
struct	rocprofiler_pc_sampling_configuration_t
	PC sampling configuration supported by a GPU agent. More...

struct	rocprofiler_pc_sampling_hw_id_v0_t
	Information about the GPU part where wave was executing at the moment of sampling. More...

struct	rocprofiler_pc_t
	Sampled program counter. More...

struct	rocprofiler_pc_sampling_record_host_trap_v0_t
	ROCProfiler Host-Trap PC Sampling Record. More...

Typedefs
typedef rocprofiler_status_t(*	rocprofiler_available_pc_sampling_configurations_cb_t) (const rocprofiler_pc_sampling_configuration_t configs, unsigned long num_config, void user_data)
	Rocprofiler SDK's callback function to deliver the list of available PC sampling configurations upon the call to the rocprofiler_query_pc_sampling_agent_configurations.

Functions
rocprofiler_status_t	rocprofiler_configure_pc_sampling_service (rocprofiler_context_id_t context_id, rocprofiler_agent_id_t agent_id, rocprofiler_pc_sampling_method_t method, rocprofiler_pc_sampling_unit_t unit, uint64_t interval, rocprofiler_buffer_id_t buffer_id, int flags)
	Function used to configure the PC sampling service on the GPU agent with `agent_id`.

rocprofiler_status_t	rocprofiler_query_pc_sampling_agent_configurations (rocprofiler_agent_id_t agent_id, rocprofiler_available_pc_sampling_configurations_cb_t cb, void *user_data)
	Query PC Sampling Configuration.

Detailed Description

Enabling PC (Program Counter) Sampling for GPU Activity.

Data Structure Documentation

◆ rocprofiler_pc_sampling_configuration_t

struct rocprofiler_pc_sampling_configuration_t

PC sampling configuration supported by a GPU agent.

Definition at line 127 of file pc_sampling.h.

Collaboration diagram for rocprofiler_pc_sampling_configuration_t:

Data Fields
uint64_t	flags
unsigned long	max_interval	the lowest possible frequency for generating samples using method
rocprofiler_pc_sampling_method_t	method	for future use Sampling method supported by the GPU agent. Currently, it can take one of the following two values: ROCPROFILER_PC_SAMPLING_METHOD_HOST_TRAP: a background host kernel thread periodically interrupts waves execution on the GPU to generate PC samples ROCPROFILER_PC_SAMPLING_METHOD_STOCHASTIC: performance monitoring hardware on the GPU periodically interrupts waves to generate PC samples.
unsigned long	min_interval	the highest possible frequencey for generating samples using method.
uint64_t	size	Size of this struct.
rocprofiler_pc_sampling_unit_t	unit	A unit used to specify the interval of the method for samples generation.

◆ rocprofiler_pc_sampling_hw_id_v0_t

struct rocprofiler_pc_sampling_hw_id_v0_t

Information about the GPU part where wave was executing at the moment of sampling.

Definition at line 203 of file pc_sampling.h.

Collaboration diagram for rocprofiler_pc_sampling_hw_id_v0_t:

Data Fields
uint64_t	chiplet: 6	chiplet index (3 bits allocated by the ROCr runtime)
uint64_t	cu_or_wgp_id: 4	Index of compute unit on GFX9 or workgroup processer on other architectures.
uint64_t	microengine_id: 2	ACE (microengine) index.
uint64_t	pipe_id: 4	pipe index
uint64_t	queue_id: 4	queue id
uint64_t	reserved0: 16	Reserved for the future use.
uint64_t	shader_array_id: 1	Shared array index.
uint64_t	shader_engine_id: 5	shared engine index
uint64_t	simd_id: 2	SIMD index.
uint64_t	vm_id: 6	virtual memory ID
uint64_t	wave_id: 7	wave slot index
uint64_t	workgroup_id: 7	thread_group index on GFX9, and workgroup index on GFX10+

◆ rocprofiler_pc_t

struct rocprofiler_pc_t

Sampled program counter.

Definition at line 223 of file pc_sampling.h.

Collaboration diagram for rocprofiler_pc_t:

Data Fields
uint64_t	code_object_id	id of the loaded code object instance that contains sampled PC. This fields holds the value ROCPROFILER_CODE_OBJECT_ID_NONE if the code object cannot be determined (e.g., sampled PC belongs to code generated by self modifying code).
uint64_t	code_object_offset	If code_object_id is different than ROCPROFILER_CODE_OBJECT_ID_NONE, then this field contains the offset of the sampled PC relative to the rocprofiler_callback_tracing_code_object_load_data_t::load_base of the code object instance with code_object_id. To calculate the original virtual address of the sampled PC, one can add the value of this field to the rocprofiler_callback_tracing_code_object_load_data_t::load_base. The value of code_object_offset matches the virtual address of the sampled instruction (PC), only if the code_object_id is equal to the ROCPROFILER_CODE_OBJECT_ID_NONE.

◆ rocprofiler_pc_sampling_record_host_trap_v0_t

struct rocprofiler_pc_sampling_record_host_trap_v0_t

ROCProfiler Host-Trap PC Sampling Record.

Definition at line 249 of file pc_sampling.h.

Collaboration diagram for rocprofiler_pc_sampling_record_host_trap_v0_t:

Data Fields
rocprofiler_correlation_id_t	correlation_id	API launch call id that matches dispatch ID.
uint64_t	dispatch_id	originating kernel dispatch ID
uint64_t	exec_mask	active SIMD lanes when sampled
rocprofiler_pc_sampling_hw_id_v0_t	hw_id	See also ::rocprofiler_pc_sampling_hw_id_0_t
rocprofiler_pc_t	pc	information about sampled program counter
uint32_t	reserved0: 24	wave position within the workgroup (0-31)
uint64_t	size	Size of this struct.
uint64_t	timestamp	timestamp when sample is generated
uint32_t	wave_in_group: 8	wave position within the workgroup (0-31)
rocprofiler_dim3_t	workgroup_id	wave coordinates within the workgroup

Typedef Documentation

◆ rocprofiler_available_pc_sampling_configurations_cb_t

typedef rocprofiler_status_t(* rocprofiler_available_pc_sampling_configurations_cb_t) (const rocprofiler_pc_sampling_configuration_t *configs, unsigned long num_config, void *user_data)

Rocprofiler SDK's callback function to deliver the list of available PC sampling configurations upon the call to the rocprofiler_query_pc_sampling_agent_configurations.

Parameters

[out]	configs	- The array of PC sampling configurations supported by the agent at the moment of invoking rocprofiler_query_pc_sampling_agent_configurations.
[out]	num_config	- The number of configurations contained in the underlying array `configs`. In case the GPU agent does not support PC sampling, the value is 0.
[in]	user_data	- client's private data passed via rocprofiler_query_pc_sampling_agent_configurations

Returns: rocprofiler_status_t

Definition at line 166 of file pc_sampling.h.

Function Documentation

◆ rocprofiler_configure_pc_sampling_service()

rocprofiler_status_t rocprofiler_configure_pc_sampling_service	(	rocprofiler_context_id_t	context_id,
		rocprofiler_agent_id_t	agent_id,
		rocprofiler_pc_sampling_method_t	method,
		rocprofiler_pc_sampling_unit_t	unit,
		uint64_t	interval,
		rocprofiler_buffer_id_t	buffer_id,
		int	flags
	)

Function used to configure the PC sampling service on the GPU agent with agent_id.

Prerequisites are the following:

The client must create a context and supply its context_id. By using this context, the client can start/stop PC sampling on the agent. For more information, please
See also
rocprofiler_start_context/rocprofiler_stop_context.
The user must create a buffer and supply its buffer_id. Rocprofiler-SDK uses the buffer to deliver the PC samples to the client. For more information about the data delivery, please
See also
rocprofiler_create_buffer and

rocprofiler_buffer_tracing_cb_t.
Before calling this function, we recommend querying PC sampling configurations supported by the GPU agent via the
See also
rocprofiler_query_pc_sampling_agent_configurations. The client chooses the method, unit, and interval to match one of the available configurations. Note that the interval must belong to the range of values [available_config.min_interval, available_config.max_interval], where available_config is the instance of the

rocprofiler_pc_sampling_configuration_s supported/available at the moment.
Rocprofiler-SDK checks whether the requsted configuration is actually supported at the moment of calling this function. If the answer is yes, it returns the
See also
ROCPROFILER_STATUS_SUCCESS. Otherwise, it notifies the client about the rejection reason via the returned status code. For more information about the status codes, please

rocprofiler_status_t.
There are a few constraints a client's code needs to be aware of.

Constraint1: A GPU agent can be configured to support at most one running PC sampling configuration at any time, which implies some of the consequences described below. After the tool configures the PC sampling with one of the available configurations, rocprofiler-SDK guarantees that this configuration will be valid for the tool's lifetime. The tool can start and stop the configured PC sampling service whenever convenient.

Constraint2: Since the same GPU agent can be used by multiple processes concurrently, Rocprofiler-SDK cannot guarantee the exclusive access to the PC sampling capability. The consequence is the following scenario. The tool TA that belongs to the process PA, calls the

See also: rocprofiler_query_pc_sampling_agent_configurations that returns the two supported configurations CA and CB by the agent. Then the tool TB of the process PB, configures the PC sampling on the same agent by using the configuration CB. Subsequently, the TA tries configuring the CA on the agent, and it fails. To point out that this case happened, we introduce a special status code; ROCPROFILER_STATUS_ERROR_NOT_AVAILABLE. When this status code is observed by the tool TA, it queries all available configurations again by calling; rocprofiler_query_pc_sampling_agent_configurations, that returns only CB this time. The tool TA can choose CB, so that both TA and TB use the PC sampling capability in the separate processes. Both TA and TB receives samples generated by the kernels launched by the corresponding processes PA and PB, respectively.

Constraint3: Rocprofiler-SDK allows only one context to contain the configured PC sampling service within the process, that implies that at most one of the loaded tools can use PC sampling. One context can contains multiple PC sampling services configured for different GPU agents.

Constraint4: PC sampling feature is not available within the ROCgdb.

Constraint5: PC sampling service cannot be used simultaneously with counter collection service.

Parameters

[in]	context_id	- id of the context used for starting/stopping PC sampling service
[in]	agent_id	- id of the agent on which caller tries using PC sampling capability
[in]	method	- the type of PC sampling the caller tries to use on the agent.
[in]	unit	- The unit appropriate to the PC sampling type/method.
[in]	interval	- frequency at which PC samples are generated
[in]	buffer_id	- id of the buffer used for delivering PC samples
[in]	flags	- for future use

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_SUCCESS	PC sampling service configured successfully
ROCPROFILER_STATUS_ERROR_NOT_AVAILABLE	One of the scenarios is present: PC sampling is already configured with configuration different than requested, PC sampling is requested from a process that runs within the ROCgdb. HSA runtime does not support PC sampling.
ROCPROFILER_STATUS_ERROR_INCOMPATIBLE_KERNEL	the amdgpu driver installed on the system does not support the PC sampling feature
ROCPROFILER_STATUS_ERROR	a general error caused by the amdgpu driver
ROCPROFILER_STATUS_ERROR_CONTEXT_CONFLICT	counter collection service already setup in the context

◆ rocprofiler_query_pc_sampling_agent_configurations()

rocprofiler_status_t rocprofiler_query_pc_sampling_agent_configurations	(	rocprofiler_agent_id_t	agent_id,
		rocprofiler_available_pc_sampling_configurations_cb_t	cb,
		void *	user_data
	)

Query PC Sampling Configuration.

Lists PC sampling configurations a GPU agent with agent_id supports at the moment of invoking the function. Delivers configurations via cb. In case the PC sampling is configured on the GPU agent, the cb delivers information about the active PC sampling configuration. In case the GPU agent does not support PC sampling capability, the cb delivers none PC sampling configurations.

Parameters

[in]	agent_id	- id of the agent for which available configurations will be listed
[in]	cb	- User callback that delivers the available PC sampling configurations
[in]	user_data	- passed to the `cb`

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_ERROR_NOT_AVAILABLE	One of the scenarios is present: PC sampling is requested from a process that runs within the ROCgdb. HSA runtime does not support PC sampling.
ROCPROFILER_STATUS_ERROR_INCOMPATIBLE_KERNEL	the amdgpu driver installed on the system does not support the PC sampling feature.
ROCPROFILER_STATUS_ERROR	a general error caused by the amdgpu driver
ROCPROFILER_STATUS_SUCCESS	`cb` successfully finished

PC Sampling

PC Sampling#

Data Structures

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ rocprofiler_pc_sampling_configuration_t

◆ rocprofiler_pc_sampling_hw_id_v0_t

◆ rocprofiler_pc_t

◆ rocprofiler_pc_sampling_record_host_trap_v0_t

Typedef Documentation

◆ rocprofiler_available_pc_sampling_configurations_cb_t

Function Documentation

◆ rocprofiler_configure_pc_sampling_service()

◆ rocprofiler_query_pc_sampling_agent_configurations()