Discuss PTI library Callback API

[jfedorov]

PTI plans to implement Callback functionality. Some work related to API IDs is already in progress.
Please, provide your comments.

PTI Callback API

Overview

PTI Callback API allows a PTI user to register a callback function that is called at the enter and exit of a driver or runtime function call, as well as critical events happens in PTI itself.

To distinguish the APIs to which a user wants to set a callback, PTI introduces PTI Domains, API Groups and API IDs within API Groups. API Groups are to distinguish, for example, between different APIs that could serve as driver: OpenCL and Level-Zero.
Ones API ID for a function is published in a PTI header file - it is constant and will never change.

Critical events are those that occur during profiling and either prevent profiling from continuing or cause significant data loss or corruption. Some of these events may be explicitly reported through return code from PTI functions. But others may occur during profiling and cannot be reported to the user via the return code. This is what the Callback domain PTI_DOMAIN_PTI_CRITICAL_EVENT is made for.

Data structures

typedef enum _pti_callback_domain {
   PTI_DOMAIN_INVALID = 0,
   PTI_DOMAIN_DRIVER_API = 1,
   PTI_DOMAIN_RUNTIME_API = 2,
   PTI_DOMAIN_PTI_CRITICAL_EVENT = 3
} pti_callback_domain;

typedef enum _pti_api_group_id {
  PTI_API_GROUP_RESERVED  = 0,
  PTI_API_GROUP_LEVELZERO = 1,
  PTI_API_GROUP_OPENCL    = 2,
  PTI_API_GROUP_SYCL      = 3,
} pti_api_group_id;

typedef enum _pti_callback_site {
  PTI_SITE_ENTER = 0, 
  PTI_SITE_EXIT = 1
} pti_callback_site;

typedef struct _pti_apicall_callback_data {
  pti_callback_site    _site;          // ENTER or EXIT
  const char*           _api_name;
  const void*          _args;          // pointer to the arguments passed to the function, 
                                                   // in case arguments not provided by PTI - it will be nullptr
  const char*          _kernel_name;   // valid only for DRIVER or RUNTIME APIs related to GPU kernel submission                                                 
  const void*          _return_code; // will be valid only for L0 API EXIT, for others will be nullptr
  pti_backend_ctx_t   _backend_context_handle; // L0 or OpenCL context
  uint32_t               _correlation_id; // ID that corresponds to the same call reported by View API records
  uint64_t*              _local_data;    // user data passed between ENTER and EXIT

} pti_apicall_callback_data;

typedef struct _pti_critical_event_callback_data {
   pti_result      _pti_event;
   char*            _message;   
} pti_critical_event_callback_data;

typedef void (*pti_callback_function)(
                  void* user_data,
                  pti_callback_domain  domain,
                  pti_api_group_id group_id, // For Driver domain it might be L0, OpenCL.. 
                  uint32_t      api_id,
                  void* cb_data);  // depending on the domain it should be type-casted to the pointer to either pti_apicall_callback_data or pti_critical_event_callback_data

Functions

pti_result ptiCallbackSubscribe(
                pti_callback_subscriber* subscriber,
                pti_callback_function    callback,
                void* user_data);

pti_result ptiCallbackUnsubscribe( pti_callback_subscriber subscriber);

// Enables/Disables callbacks to all APIs within domain
pti_result ptiCallbackEnableDomain(
                uint32_t enable, 
                pti_callback_subscriber subscriber,
                pti_callback_domain  domain);

// Enables/Disables callback for the specific functions within domain and api_group
pti_result ptiCallbackEnable(
                uint32_t enable, 
                pti_callback_subscriber subscriber,
                pti_api_group_id   api_group_id,   // one of L0, OpenCL, Sycl
                pti_api_id    api_id);