PC Sampling service

Contents

PC Sampling service#

enum rocprofiler_pc_sampling_configuration_flags_t#

(experimental) Enumeration describing values of flags of rocprofiler_pc_sampling_configuration_t.

Values:

enumerator ROCPROFILER_PC_SAMPLING_CONFIGURATION_FLAGS_NONE#
enumerator ROCPROFILER_PC_SAMPLING_CONFIGURATION_FLAGS_INTERVAL_POW2#
enum rocprofiler_pc_sampling_instruction_type_t#

(experimental) Enumeration describing type of sampled issued instruction.

Values:

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NONE#
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU#

vector ALU instruction

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_MATRIX#

matrix instruction

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_SCALAR#

scalar (memory) instruction

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_TEX#

texture memory instruction

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_LDS#

LDS memory instruction.

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_LDS_DIRECT#

LDS direct memory instruction.

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_FLAT#

flat memory instruction

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_EXPORT#

export instruction

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_MESSAGE#

message instruction

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_BARRIER#

barrier instruction

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_BRANCH_NOT_TAKEN#
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_BRANCH_TAKEN#
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_JUMP#

jump instruction

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_OTHER#

other types of instruction

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST#

no instruction issued

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_DUAL_VALU#
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_BRANCH_TAKEN
enum rocprofiler_pc_sampling_instruction_not_issued_reason_t#

(experimental) Enumeration describing reason for not issuing an instruction.

Values:

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_NONE#
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_NO_INSTRUCTION_AVAILABLE#
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_ALU_DEPENDENCY#
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT#

waitcnt dependency

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_INTERNAL_INSTRUCTION#
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_BARRIER_WAIT#

waiting on a barrier

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_ARBITER_NOT_WIN#
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_ARBITER_WIN_EX_STALL#
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT#
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_SLEEP_WAIT#

wave was sleeping

enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_ALU_DEPENDENCY
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_INTERNAL_INSTRUCTION
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_ARBITER_NOT_WIN
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_ARBITER_WIN_EX_STALL
enumerator ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT
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)#

(experimental) 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.

Param configs:

[out] - The array of PC sampling configurations supported by the agent at the moment of invoking rocprofiler_query_pc_sampling_agent_configurations.

Param num_config:

[out] - The number of configurations contained in the underlying array configs. In case the GPU agent does not support PC sampling, the value is 0.

Param user_data:

[in] - client’s private data passed via rocprofiler_query_pc_sampling_agent_configurations

Return:

rocprofiler_status_t

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)#

(experimental) 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

    Before calling this function, we recommend querying PC sampling configurations supported by the GPU agent via the

    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

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

    See also

    rocprofiler_create_buffer and

    See also

    rocprofiler_buffer_tracing_cb_t.

    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

    See also

    rocprofiler_pc_sampling_configuration_s supported/available at the moment.

    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

    See also

    rocprofiler_status_t.

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

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.

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

See also

ROCPROFILER_STATUS_ERROR_NOT_AVAILABLE. When this status code is observed by the tool TA, it queries all available configurations again by calling

See also

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.

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

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

Parameters:

  • context_id – [in] - id of the context used for starting/stopping PC sampling service

  • agent_id – [in] - id of the agent on which caller tries using PC sampling capability

  • method – [in] - the type of PC sampling the caller tries to use on the agent.

  • unit – [in] - The unit appropriate to the PC sampling type/method.

  • interval – [in] - frequency at which PC samples are generated

  • buffer_id – [in] - id of the buffer used for delivering PC samples

  • flags – [in] - for future use

Return values:

  • ROCPROFILER_STATUS_SUCCESS – PC sampling service configured successfully

  • ROCPROFILER_STATUS_ERROR_NOT_AVAILABLE – One of the scenarios is present:

    1. PC sampling is already configured with configuration different than requested,

    2. PC sampling is requested from a process that runs within the ROCgdb.

    3. HSA runtime does not support PC sampling.

    4. GPU device does not support requested PC sampling method.

  • 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_STATUS_ERROR_INVALID_ARGUMENT – function invoked with an invalid argument

Returns:

rocprofiler_status_t

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)#

(experimental) 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:

  • agent_id – [in] - id of the agent for which available configurations will be listed

  • cb – [in] - User callback that delivers the available PC sampling configurations

  • user_data – [in] - passed to the cb

Return values:

  • ROCPROFILER_STATUS_ERROR_NOT_AVAILABLE – One of the scenarios is present:

    1. PC sampling is requested from a process that runs within the ROCgdb.

    2. 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

Returns:

rocprofiler_status_t

const char *rocprofiler_get_pc_sampling_instruction_type_name(rocprofiler_pc_sampling_instruction_type_t instruction_type)#

(experimental) Return the string encoding of rocprofiler_pc_sampling_instruction_type_t value

Parameters:

instruction_type – [in] instruction type enum value

Returns:

Will return a nullptr if invalid/unsupported rocprofiler_pc_sampling_instruction_type_t value is provided.

const char *rocprofiler_get_pc_sampling_instruction_not_issued_reason_name(rocprofiler_pc_sampling_instruction_not_issued_reason_t not_issued_reason)#

(experimental) Return the string encoding of rocprofiler_pc_sampling_instruction_not_issued_reason_t value

Parameters:

not_issued_reason – [in] no issue reason enum value

Returns:

Will return a nullptr if invalid/unsupported rocprofiler_pc_sampling_instruction_not_issued_reason_t value is provided.

struct rocprofiler_pc_sampling_configuration_t#
#include <rocprofiler-sdk/pc_sampling.h>

(experimental) PC sampling configuration supported by a GPU agent.

struct rocprofiler_pc_sampling_hw_id_v0_t#
#include <rocprofiler-sdk/pc_sampling.h>

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

struct rocprofiler_pc_t#
#include <rocprofiler-sdk/pc_sampling.h>

(experimental) Sampled program counter.

struct rocprofiler_pc_sampling_record_host_trap_v0_t#
#include <rocprofiler-sdk/pc_sampling.h>

(experimental) ROCProfiler Host-Trap PC Sampling Record.

struct rocprofiler_pc_sampling_record_stochastic_header_t#
#include <rocprofiler-sdk/pc_sampling.h>

(experimental) The header of the rocprofiler_pc_sampling_record_stochastic_v0_t, indicating what fields of the rocprofiler_pc_sampling_record_stochastic_v0_t instance are meaningful for the sample.

struct rocprofiler_pc_sampling_snapshot_v0_t#
#include <rocprofiler-sdk/pc_sampling.h>

(experimental) Data provided by stochastic sampling hardware.

struct rocprofiler_pc_sampling_memory_counters_t#
#include <rocprofiler-sdk/pc_sampling.h>

(experimental) Counters of issued but not yet completed instructions.

struct rocprofiler_pc_sampling_record_stochastic_v0_t#
#include <rocprofiler-sdk/pc_sampling.h>

(experimental) ROCProfiler Stochastic PC Sampling Record.

struct rocprofiler_pc_sampling_record_invalid_t#
#include <rocprofiler-sdk/pc_sampling.h>

(experimental) Record representing an invalid PC Sampling Record.

Contents