PTI PC Sampling API Reference (Experimental)

PTI PC Sampling API Reference (Experimental)#

Warning

EXPERIMENTAL API - This API is experimental and subject to change without deprecation in future releases.

This section provides API documentation for the PTI PC Sampling API (GPU EU Stall Sampling).

Overview#

The PTI PC Sampling API provides statistical per-instruction sampling of active execution and stall reasons on GPU kernels. This enables fine-grained performance analysis by identifying instruction-level bottlenecks and stall reasons.

The API includes:

  • Configuration Functions - Enable, configure, and set buffer sizes

  • Collection Control Functions - Start and stop sampling

  • Data Retrieval Functions - Get devices, kernels, stall reasons, and sample data

  • Cleanup Functions - Disable and free resources

  • Structures - Kernel info, stall reasons, instruction data, device status

  • Type Definitions - Handle types for PC sampling

Configuration Functions#

Collection Control Functions#

Data Retrieval Functions#

Cleanup Functions#

Structures#

Data structures for PC sampling:

Note

The pti_pc_sampling_handle_t is an opaque handle type used to identify a PC sampling session. It is created by ptiPcSamplingEnable() and destroyed by ptiPcSamplingDisable().

Detailed API Documentation#

Configuration Functions#

pti_result ptiPcSamplingEnable(pti_pc_sampling_handle_t *handle)#

Create a PC Sampling collection handle.

Parameters:

handle – [out] Pointer to store the created handle

Returns:

PTI_SUCCESS on successful handle creation

Returns:

PTI_ERROR_BAD_ARGUMENT if handle is NULL

Returns:

PTI_ERROR_PC_SAMPLING_ALREADY_ENABLED if another PC sampling handle is still enabled

Returns:

PTI_ERROR_INTERNAL if PTI cannot allocate the collection handle

Returns:

PTI_ERROR_PC_SAMPLING_UNSUPPORTED if the PC Sampling is not supported on the current system

pti_result ptiPcSamplingConfigure(pti_pc_sampling_handle_t handle, const pti_device_handle_t *devices, size_t device_count, uint32_t sampling_period_ns)#

Configure PC Sampling for a collection handle.

Parameters:

  • handle – [in] Collection handle

  • devices – [in] Device filter; NULL profiles all available devices

  • device_count – [in] Number of entries in devices; ignored when devices is NULL

  • sampling_period_ns – [in] Sampling period in nanoseconds for all selected devices; 0 makes PTI use the default period of 100000 ns

Returns:

PTI_SUCCESS on successful configuration

Returns:

PTI_ERROR_BAD_ARGUMENT if handle is NULL

Returns:

PTI_ERROR_PC_SAMPLING_ALREADY_CONFIGURED if handle is already configured or otherwise not in the initial state required for configuration

Returns:

PTI_ERROR_NOT_IMPLEMENTED if a device-filtered configuration is requested

pti_result ptiPcSamplingQueryCollectionBufferSize(pti_pc_sampling_handle_t handle, size_t *buffer_size)#

Query the recommended PC Sampling collection buffer size.

Parameters:

  • handle – [in] Collection handle

  • buffer_size – [out] Pointer to store the collection buffer size in bytes; cannot be NULL

Returns:

PTI_ERROR_NOT_IMPLEMENTED

pti_result ptiPcSamplingSetCollectionBufferSize(pti_pc_sampling_handle_t handle, size_t buffer_size)#

Set the PC Sampling collection buffer size.

Parameters:

  • handle – [in] Collection handle

  • buffer_size – [in] Collection buffer size in bytes for all configured devices

Returns:

PTI_ERROR_NOT_IMPLEMENTED

Collection Control Functions#

pti_result ptiPcSamplingStartCollection(pti_pc_sampling_handle_t handle)#

Start PC Sampling collection.

Parameters:

handle – [in] Collection handle

Returns:

PTI_SUCCESS when collection is started

Returns:

PTI_ERROR_BAD_ARGUMENT if handle is NULL

Returns:

PTI_ERROR_PC_SAMPLING_NOT_CONFIGURED if collection is not in the configured state yet

Returns:

PTI_ERROR_PC_SAMPLING_ALREADY_STARTED if collection is already running

Returns:

PTI_ERROR_PC_SAMPLING_ALREADY_STOPPED if collection was already stopped

pti_result ptiPcSamplingStopCollection(pti_pc_sampling_handle_t handle)#

Stop collection.

Ends the sampling session and makes post-stop query APIs valid. Raw data loading and aggregation are deferred until a later query requests them.

Parameters:

handle – [in] Collection handle

Returns:

PTI_SUCCESS when collection is successfully stopped

Returns:

PTI_ERROR_BAD_ARGUMENT if handle is NULL

Returns:

PTI_ERROR_PC_SAMPLING_NOT_STARTED if collection has not started yet

Returns:

PTI_ERROR_PC_SAMPLING_ALREADY_STOPPED if collection was already stopped

Data Retrieval Functions#

pti_result ptiPcSamplingGetStallReasons(pti_pc_sampling_handle_t handle, pti_pc_sampling_stall_reason_info_t *reasons, size_t *reason_count)#

Retrieve reason names and descriptions common across all profiled devices.

This query is independent of collection lifecycle and may be called immediately after ptiPcSamplingEnable succeeds.

Usage: 1- Call ptiPcSamplingGetStallReasons(handle, NULL, reason_count) to discover the required count; the required count will be written to reason_count. 2- Allocate reasons buffer of size sizeof(pti_pc_sampling_stall_reason_info_t) * (*reason_count) and set _struct_size on each element. 3- Call ptiPcSamplingGetStallReasons(handle, reasons, reason_count) again to get the reason information written to the supplied buffer.

Parameters:

  • handle – [in] Collection handle

  • reasons – [inout] Caller-allocated array of *reason_count elements; set to NULL to query the required count

  • reason_count – [inout] In: size of reasons array; Out: required or actual number of reasons; cannot be NULL

Returns:

PTI_SUCCESS after successful retrieval of the stall-reason count or entries

Returns:

PTI_ERROR_BAD_ARGUMENT if handle is NULL or reason_count is NULL

Returns:

PTI_ERROR_INTERNAL if stall-reason metadata cannot be derived from the configured metric group

pti_result ptiPcSamplingGetProfiledDevices(pti_pc_sampling_handle_t handle, pti_device_handle_t *devices, size_t *device_count)#

Get profiled devices with observed kernels.

Usage: 1- Call ptiPcSamplingGetProfiledDevices(handle, NULL, device_count) to discover the required count; the required count will be written to device_count. 2- Allocate devices buffer of size sizeof(pti_device_handle_t) * (*device_count). 3- Call ptiPcSamplingGetProfiledDevices(handle, devices, device_count) again to get the profiled device handles.

Note that this function will return all devices that could have samples. If there were kernels visible to PTI but no samples were collected for them (e.g. due to short execution time), those devices will still be returned by this function.

Parameters:

  • handle – [in] Collection handle

  • devices – [inout] Caller-allocated array of *device_count elements; set to NULL to query the required count

  • device_count – [inout] In: size of devices array; Out: required or actual number of devices; cannot be NULL

Returns:

PTI_SUCCESS after successful retrieval of profiled device information for a stopped collection

Returns:

PTI_ERROR_BAD_ARGUMENT if handle is NULL or device_count is NULL

Returns:

PTI_ERROR_PC_SAMPLING_NOT_STOPPED if collection has not reached the stopped state yet

pti_result ptiPcSamplingGetDeviceStatus(pti_pc_sampling_handle_t handle, pti_device_handle_t device, pti_pc_sampling_device_status_t *device_status)#

Retrieve PC Sampling collection status for a profiled device.

The returned status reports whether samples were dropped and provides per-device totals for collected samples and sampled PCs.

Parameters:

  • handle – [in] Collection handle

  • device – [in] Profiled device handle

  • device_status – [inout] Caller-allocated device status structure; set _struct_size

Returns:

PTI_SUCCESS after successful status retrieval

Returns:

PTI_ERROR_BAD_ARGUMENT if handle is NULL, device is NULL, device_status is NULL, or device does not match the configured PC sampling device

Returns:

PTI_ERROR_PC_SAMPLING_NOT_STOPPED if collection has not reached the stopped state yet

Returns:

PTI_ERROR_INTERNAL if cannot collect device status

pti_result ptiPcSamplingGetObservedKernelHandles(pti_pc_sampling_handle_t handle, pti_device_handle_t device, uint64_t *kernel_handles, size_t *kernel_count)#

Retrieve observed kernel handles for a profiled device.

Usage: 1- Call ptiPcSamplingGetObservedKernelHandles(handle, device, NULL, kernel_count) to discover the required number of kernel handles. 2- Allocate kernel_handles buffer of size sizeof(uint64_t) * (*kernel_count). 3- Call ptiPcSamplingGetObservedKernelHandles(handle, device, kernel_handles, kernel_count) again to get the kernel handles written to the supplied buffer.

Parameters:

  • handle – [in] Collection handle

  • device – [in] Profiled device handle

  • kernel_handles – [inout] Caller-allocated array of *kernel_count elements; set to NULL to query the required count

  • kernel_count – [inout] In: size of kernel_handles array; Out: required or actual number of kernel handles; cannot be NULL

Returns:

PTI_SUCCESS after successful retrieval of the kernel-handle count or entries

Returns:

PTI_ERROR_BAD_ARGUMENT if handle is NULL, kernel_count is NULL, or device does not match the configured device

Returns:

PTI_ERROR_PC_SAMPLING_NOT_STOPPED if collection has not reached the stopped state yet

Returns:

PTI_ERROR_INTERNAL if cannot collect the kernel-handle count or entries

pti_result ptiPcSamplingGetObservedKernelInfo(pti_pc_sampling_handle_t handle, pti_device_handle_t device, uint64_t kernel_handle, pti_pc_sampling_kernel_info_t *kernel_info)#

Retrieve kernel metadata for one observed kernel.

Caller allocates kernel_info, must set _struct_size, and allocates an _aggregated_samples array of size reason_count from ptiPcSamplingGetStallReasons. If _aggregated_samples is NULL, it is ignored and not populated.

Parameters:

  • handle – [in] Collection handle

  • device – [in] Profiled device handle

  • kernel_handle – [in] Kernel handle returned by ptiPcSamplingGetObservedKernelHandles

  • kernel_info – [inout] Caller-allocated kernel info structure;

Returns:

PTI_SUCCESS after successful retrieval of the observed-kernel metadata

Returns:

PTI_ERROR_BAD_ARGUMENT if handle is NULL, device does not match the configured device, kernel_info is NULL, or kernel_info->_struct_size is too small

Returns:

PTI_ERROR_PC_SAMPLING_NOT_STOPPED if collection has not reached the stopped state yet

Returns:

PTI_ERROR_BAD_ARGUMENT if kernel_handle was not observed during the collection

Returns:

PTI_ERROR_INTERNAL if cannot collect the observed-kernel metadata

pti_result ptiPcSamplingGetSamplesPerInstruction(pti_pc_sampling_handle_t handle, pti_device_handle_t device, uint64_t kernel_handle, pti_pc_sampling_instruction_t *instruction_buffer, size_t instruction_buffer_count, uint64_t *samples_buffer, size_t samples_buffer_count)#

Retrieve instruction-level PC Sampling data for one observed kernel on a profiled device.

Called after ptiPcSamplingGetObservedKernelInfo. The caller allocates:

  • instruction_buffer for kernel_info._instructions_with_samples_count elements

  • samples_buffer for kernel_info._instructions_with_samples_count * kernel_info._reason_count elements

The caller can access the sample count for instruction i and stall reason j with: samples_buffer[i * kernel_info._reason_count + j]

Parameters:

  • handle – [in] Collection handle

  • device – [in] Profiled device handle

  • kernel_handle – [in] Kernel handle returned by ptiPcSamplingGetObservedKernelHandles

  • instruction_buffer – [out] Caller-allocated instruction buffer

  • instruction_buffer_count – [in] Size of instruction_buffer array

  • samples_buffer – [out] Caller-allocated flattened sample-count buffer

  • samples_buffer_count – [in] Size of samples_buffer array

Returns:

PTI_SUCCESS after successful retrieval of the persisted instruction offsets and sample counts

Returns:

PTI_ERROR_BAD_ARGUMENT if handle is NULL, device is NULL, samples_buffer is NULL, instruction_buffer is NULL, or device does not match the configured device

Returns:

PTI_ERROR_PC_SAMPLING_NOT_STOPPED if collection has not reached the stopped state yet

Returns:

PTI_ERROR_INTERNAL if cannot collect the persisted instruction offsets and sample counts

Cleanup Functions#

pti_result ptiPcSamplingDisable(pti_pc_sampling_handle_t handle)#

Disable collection and free PTI resources associated with this handle.

Parameters:

handle – [in] Collection handle

Returns:

PTI_SUCCESS on successful cleanup

Returns:

PTI_ERROR_BAD_ARGUMENT if handle is NULL

Structures#

struct pti_pc_sampling_stall_reason_info_t#

Stall reason name and description entry.

Public Members

size_t _struct_size#

Size of this structure; user settable; required.

const char *_name#

Reason name; owned by PTI.

const char *_description#

Reason description; owned by PTI.

struct pti_pc_sampling_source_info_t#

Source information for a single instruction. Owned by PTI; valid until ptiPcSamplingDisable.

Public Members

const char *_file_path#

Source file path; null if unavailable; owned by PTI.

uint64_t _file_line#

Source line number; 0 if unavailable.

struct pti_pc_sampling_instruction_t#

Per-instruction sampling metrics.

Public Members

uint64_t _instruction_offset#

Instruction offset within kernel.

pti_pc_sampling_source_info_t *_source_info#

Source information; null if unavailable; owned by PTI.

struct pti_pc_sampling_kernel_info_t#

Kernel information returned by ptiPcSamplingGetObservedKernelInfo.

Public Members

size_t _struct_size#

Size of this structure; user settable; required.

pti_device_handle_t _device#

Device on which the kernel ran.

uint64_t _kernel_handle#

Unique kernel identifier.

const char *_kernel_name#

Kernel name; owned by PTI.

size_t _reason_count#

Number of stall reasons with samples for this kernel.

size_t _instructions_with_samples_count#

Count of instructions that have samples for this kernel.

uint64_t *_aggregated_samples#

Array of size _reason_count aggregating stall-sample data for this kernel.

struct pti_pc_sampling_device_status_t#

Per-device PC Sampling collection status.

Public Members

size_t _struct_size#

Size of this structure; user settable; required.

pti_device_handle_t _device#

Device for which the status is reported.

uint32_t _samples_dropped#

1 if samples were dropped for the device; 0 otherwise

uint64_t _total_sample_count#

Total number of collected samples for the device.

uint64_t _total_pc_count#

Total number of sampled PCs for the device.