PTI Callback API Reference (Experimental)

PTI Callback API Reference (Experimental)#

Warning

DRAFT DOCUMENTATION - This documentation is currently in draft status and subject to change.

Warning

The Callback API is EXPERIMENTAL and subject to change. APIs and data structures may change in future releases without notice. Use with caution in production environments.

This section provides API documentation for the PTI Callback API (synchronous GPU operation notifications).

Note

Most users should use the PTI View API Reference (View API) instead. The Callback API is only necessary when you need synchronous callbacks during GPU operation lifecycle events.

Overview#

The PTI Callback API provides a low-level subscription mechanism for receiving synchronous notifications about GPU operations as they are appended, dispatched, or completed. Unlike the View API which delivers buffered profiling records, the Callback API delivers real-time callbacks during specific GPU operation lifecycle events.

The Callback API is primarily designed for:

Internal PTI infrastructure - Used internally by PTI Metrics Scope API Reference for per-kernel metrics collection
Advanced profiling tools - Tools requiring immediate notification of GPU operations
Custom correlation systems - Applications needing to inject custom correlation IDs at precise moments
Low-latency monitoring - Systems requiring minimal delay between operation and notification

The API includes:

Core Functions - Subscribe/unsubscribe, enable/disable callback domains
Helper Functions - Convert callback domain and phase enums to strings
Structures - Callback data structures for GPU operations
Enumerators - Callback domains, phases, operation kinds
Type Definitions - Subscriber handles and callback function pointers

Detailed API Documentation#

Core Functions#

pti_result ptiCallbackSubscribe(pti_callback_subscriber_handle *subscriber, pti_callback_function callback, void *user_data)#

Initialize Callback subscriber.

Callback API functions None of the PTI API functions should be called from within a Callback function. Exceptions are helper functions that return character representations of enums.

Parameters:

subscriber – - subscriber handle
callback – - pointer to the callback function
user_data – - user data to be passed to the callback function

Returns:

pti_result

pti_result ptiCallbackUnsubscribe(pti_callback_subscriber_handle subscriber)#: Unsubscribe Callback subscriber. This unsubscribes from all domains, disables the callback, cleans up all resources related to the subscriber handle, and invalidates the handle.

pti_result ptiCallbackEnableDomain(pti_callback_subscriber_handle subscriber, pti_callback_domain domain, uint32_t enter_cb, uint32_t exit_cb)#

Enables callbacks on specific domain.

Parameters:

subscriber – - subscriber handle
domain – - domain to enable
enter_cb – - indicate if callback called on enter/start: 0-no, 1-yes; used only for domains with 2 phases
exit_cb – - indicates if callback is called on exit/end: 0-no, 1-yes; used only for domains with 2 phases

Returns:

pti_result

pti_result ptiCallbackDisableDomain(pti_callback_subscriber_handle subscriber, pti_callback_domain domain)#: Disables callbacks for specific domain.

pti_result ptiCallbackDisableAllDomains(pti_callback_subscriber_handle subscriber)#: Disables the callback of the subscriber for all domains.

Helper Functions#

const char *ptiCallbackDomainTypeToString(pti_callback_domain domain)#

Helper function to return stringified enum members for pti_callback_domain.

Returns:: const char*

const char *ptiCallbackPhaseTypeToString(pti_callback_phase phase)#

Helper function to return stringified enum members for pti_callback_phase.

Returns:: const char*

Structures#

struct pti_callback_gpu_op_data#

Public Members

pti_callback_domain _domain#: domain of the callback

pti_backend_command_list_type _cmd_list_properties#: immediate, mutable,..

pti_backend_command_list_t _cmd_list_handle#: Device back-end command list handle, could be nullptr if unknown or when several operations with different command lists reported together

pti_backend_queue_t _queue_handle#: Device back-end queue handle, could be nullptr if unknown when several operations with different command lists reported together

pti_device_handle_t _device_handle#: Device handle.

pti_callback_phase _phase#: PTI_CB_PHASE_API_ENTER/EXIT.

uint32_t _return_code#: will be valid only for L0 API EXIT, for others will be zero

uint32_t _correlation_id#: ID that corresponds to the same call reported by View API records.

uint32_t _operation_count#: number of operations appended or dispatched to the GPU

pti_gpu_op_details *_operation_details#: pointer to details of operation(s) appended, dispatched or completed

struct pti_gpu_op_details#

Public Members

uint64_t _kernel_handle#: a handle uniquely identifying kernel object as contained in the module at the specific offset it will be zero in case of not implemented yet or for memory operations

const char *_name#: symbolic name of a kernel or memcpy operation

struct pti_internal_callback_data#

Public Members

pti_callback_domain _domain#: domain of the callback

pti_callback_phase _phase#: THREAD START/END or INTERNAL EVENT.

uint32_t _detail#: depending on the domain should be casted/interpreted as a purpose of an internal PTI thread or pti_internal_event_type

const char *_message#: explains details

Enumerators#

enum pti_callback_domain#

Values:

enumerator PTI_CB_DOMAIN_INVALID#

enumerator PTI_CB_DOMAIN_DRIVER_CONTEXT_CREATED#