CUPTI (PDF) - v6.0 (older) - Last updated February 13, 2014 - Send Feedback -

## 2.4. CUPTI Callback API

Functions, types, and enums that implement the CUPTI Callback API.

### Classes

struct
CUpti_CallbackData
  Data passed into a runtime or driver API callback function.
struct
CUpti_ModuleResourceData
  Module data passed into a resource callback function.
struct
CUpti_NvtxData
  Data passed into a NVTX callback function.
struct
CUpti_ResourceData
  Data passed into a resource callback function.
struct
CUpti_SynchronizeData
  Data passed into a synchronize callback function.

### Typedefs

typedef void ( *CUpti_CallbackFunc )( void* userdata, CUpti_CallbackDomain domain, CUpti_CallbackId cbid, const void* cbdata )
  Function type for a callback.
typedef uint32_t CUpti_CallbackId
  An ID for a driver API, runtime API, resource or synchronization callback.
typedef CUpti_CallbackDomain* CUpti_DomainTable
  Pointer to an array of callback domains.
typedef CUpti_Subscriber_st * CUpti_SubscriberHandle
  A callback subscriber.

### Enumerations

enum CUpti_ApiCallbackSite
  Specifies the point in an API call that a callback is issued.
enum CUpti_CallbackDomain
  Callback domains.
enum CUpti_CallbackIdResource
  Callback IDs for resource domain.
enum CUpti_CallbackIdSync
  Callback IDs for synchronization domain.

### Functions

CUptiResult cuptiEnableAllDomains ( uint32_t enable, CUpti_SubscriberHandle subscriber )
  Enable or disable all callbacks in all domains.
CUptiResult cuptiEnableCallback ( uint32_t enable, CUpti_SubscriberHandle subscriber, CUpti_CallbackDomain domain, CUpti_CallbackId cbid )
  Enable or disabled callbacks for a specific domain and callback ID.
CUptiResult cuptiEnableDomain ( uint32_t enable, CUpti_SubscriberHandle subscriber, CUpti_CallbackDomain domain )
  Enable or disabled all callbacks for a specific domain.
CUptiResult cuptiGetCallbackName ( CUpti_CallbackDomain domain, uint32_t cbid, const char** name )
  Get the name of a callback for a specific domain and callback ID.
CUptiResult cuptiGetCallbackState ( uint32_t* enable, CUpti_SubscriberHandle subscriber, CUpti_CallbackDomain domain, CUpti_CallbackId cbid )
  Get the current enabled/disabled state of a callback for a specific domain and function ID.
CUptiResult cuptiSubscribe ( CUpti_SubscriberHandle* subscriber, CUpti_CallbackFunc callback, void* userdata )
  Initialize a callback subscriber with a callback function and user data.
CUptiResult cuptiSupportedDomains ( size_t* domainCount, CUpti_DomainTable* domainTable )
  Get the available callback domains.
CUptiResult cuptiUnsubscribe ( CUpti_SubscriberHandle subscriber )
  Unregister a callback subscriber.

### Typedefs

void ( *CUpti_CallbackFunc )( void* userdata, CUpti_CallbackDomain domain, CUpti_CallbackId cbid, const void* cbdata )

  Function type for a callback. Function type for a callback. The type of the data passed to the callback in `cbdata` depends on the `domain`. If `domain` is CUPTI_CB_DOMAIN_DRIVER_API or CUPTI_CB_DOMAIN_RUNTIME_API the type of `cbdata` will be CUpti_CallbackData. If `domain` is CUPTI_CB_DOMAIN_RESOURCE the type of `cbdata` will be CUpti_ResourceData. If `domain` is CUPTI_CB_DOMAIN_SYNCHRONIZE the type of `cbdata` will be CUpti_SynchronizeData. If `domain` is CUPTI_CB_DOMAIN_NVTX the type of `cbdata` will be CUpti_NvtxData.

###### Parameters

`userdata`
  User data supplied at subscription of the callback
`CUpti_CallbackDomain domain`
`CUpti_CallbackId cbid`
`cbdata`
  Data passed to the callback.

typedef uint32_t CUpti_CallbackId

  An ID for a driver API, runtime API, resource or synchronization callback. An ID for a driver API, runtime API, resource or synchronization callback. Within a driver API callback this should be interpreted as a CUpti_driver_api_trace_cbid value (these values are defined in cupti_driver_cbid.h). Within a runtime API callback this should be interpreted as a CUpti_runtime_api_trace_cbid value (these values are defined in cupti_runtime_cbid.h). Within a resource API callback this should be interpreted as a CUpti_CallbackIdResource value. Within a synchronize API callback this should be interpreted as a CUpti_CallbackIdSync value.

typedef CUpti_CallbackDomain* CUpti_DomainTable

  Pointer to an array of callback domains.

typedef CUpti_Subscriber_st * CUpti_SubscriberHandle

  A callback subscriber.

### Enumerations

enum CUpti_ApiCallbackSite

  Specifies the point in an API call that a callback is issued. This value is communicated to the callback function via CUpti_CallbackData::callbackSite.

  ###### Values

  CUPTI_API_ENTER = 0
    The callback is at the entry of the API call.
  CUPTI_API_EXIT = 1
    The callback is at the exit of the API call.
  CUPTI_API_CBSITE_FORCE_INT = 0x7fffffff
enum CUpti_CallbackDomain

  Callback domains. Each domain represents callback points for a group of related API functions or CUDA driver activity.

  ###### Values

  CUPTI_CB_DOMAIN_INVALID = 0
    Invalid domain.
  CUPTI_CB_DOMAIN_DRIVER_API = 1
    Domain containing callback points for all driver API functions.
  CUPTI_CB_DOMAIN_RUNTIME_API = 2
    Domain containing callback points for all runtime API functions.
  CUPTI_CB_DOMAIN_RESOURCE = 3
    Domain containing callback points for CUDA resource tracking.
  CUPTI_CB_DOMAIN_SYNCHRONIZE = 4
    Domain containing callback points for CUDA synchronization.
  CUPTI_CB_DOMAIN_NVTX = 5
    Domain containing callback points for NVTX API functions.
  CUPTI_CB_DOMAIN_SIZE = 6
  CUPTI_CB_DOMAIN_FORCE_INT = 0x7fffffff
enum CUpti_CallbackIdResource

  Callback IDs for resource domain, CUPTI_CB_DOMAIN_RESOURCE. This value is communicated to the callback function via the `cbid` parameter.

  ###### Values

  CUPTI_CBID_RESOURCE_INVALID = 0
    Invalid resource callback ID.
  CUPTI_CBID_RESOURCE_CONTEXT_CREATED = 1
    A new context has been created.
  CUPTI_CBID_RESOURCE_CONTEXT_DESTROY_STARTING = 2
    A context is about to be destroyed.
  CUPTI_CBID_RESOURCE_STREAM_CREATED = 3
    A new stream has been created.
  CUPTI_CBID_RESOURCE_STREAM_DESTROY_STARTING = 4
    A stream is about to be destroyed.
  CUPTI_CBID_RESOURCE_CU_INIT_FINISHED = 5
    The driver has finished initializing.
  CUPTI_CBID_RESOURCE_MODULE_LOADED = 6
    A module has been loaded.
  CUPTI_CBID_RESOURCE_MODULE_UNLOAD_STARTING = 7
    A module is about to be unloaded.
  CUPTI_CBID_RESOURCE_MODULE_PROFILED = 8
    The current module which is being profiled.
  CUPTI_CBID_RESOURCE_SIZE
  CUPTI_CBID_RESOURCE_FORCE_INT = 0x7fffffff
enum CUpti_CallbackIdSync

  Callback IDs for synchronization domain, CUPTI_CB_DOMAIN_SYNCHRONIZE. This value is communicated to the callback function via the `cbid` parameter.

  ###### Values

  CUPTI_CBID_SYNCHRONIZE_INVALID = 0
    Invalid synchronize callback ID.
  CUPTI_CBID_SYNCHRONIZE_STREAM_SYNCHRONIZED = 1
    Stream synchronization has completed for the stream.
  CUPTI_CBID_SYNCHRONIZE_CONTEXT_SYNCHRONIZED = 2
    Context synchronization has completed for the context.
  CUPTI_CBID_SYNCHRONIZE_SIZE
  CUPTI_CBID_SYNCHRONIZE_FORCE_INT = 0x7fffffff

### Functions

CUptiResult cuptiEnableAllDomains ( uint32_t enable, CUpti_SubscriberHandle subscriber )
  Enable or disable all callbacks in all domains.

  ###### Parameters

  `enable`
    New enable state for all callbacks in all domain. Zero disables all callbacks, non-zero enables all callbacks.
  `subscriber`
    - Handle to callback subscription

  ###### Returns

  - CUPTI_SUCCESS

    on success

  - CUPTI_ERROR_NOT_INITIALIZED

    if unable to initialized CUPTI

  - CUPTI_ERROR_INVALID_PARAMETER

    if `subscriber` is invalid

  ###### Description

  Enable or disable all callbacks in all domains.

  Note:

  Thread-safety: a subscriber must serialize access to cuptiGetCallbackState, cuptiEnableCallback, cuptiEnableDomain, and cuptiEnableAllDomains. For example, if cuptiGetCallbackState(sub, d, *) and cuptiEnableAllDomains(sub) are called concurrently, the results are undefined.

CUptiResult cuptiEnableCallback ( uint32_t enable, CUpti_SubscriberHandle subscriber, CUpti_CallbackDomain domain, CUpti_CallbackId cbid )
  Enable or disabled callbacks for a specific domain and callback ID.

  ###### Parameters

  `enable`
    New enable state for the callback. Zero disables the callback, non-zero enables the callback.
  `subscriber`
    - Handle to callback subscription
  `domain`
    The domain of the callback
  `cbid`
    The ID of the callback

  ###### Returns

  - CUPTI_SUCCESS

    on success

  - CUPTI_ERROR_NOT_INITIALIZED

    if unable to initialized CUPTI

  - CUPTI_ERROR_INVALID_PARAMETER

    if `subscriber`, `domain` or `cbid` is invalid.

  ###### Description

  Enable or disabled callbacks for a subscriber for a specific domain and callback ID.

  Note:

  Thread-safety: a subscriber must serialize access to cuptiGetCallbackState, cuptiEnableCallback, cuptiEnableDomain, and cuptiEnableAllDomains. For example, if cuptiGetCallbackState(sub, d, c) and cuptiEnableCallback(sub, d, c) are called concurrently, the results are undefined.

CUptiResult cuptiEnableDomain ( uint32_t enable, CUpti_SubscriberHandle subscriber, CUpti_CallbackDomain domain )
  Enable or disabled all callbacks for a specific domain.

  ###### Parameters

  `enable`
    New enable state for all callbacks in the domain. Zero disables all callbacks, non-zero enables all callbacks.
  `subscriber`
    - Handle to callback subscription
  `domain`
    The domain of the callback

  ###### Returns

  - CUPTI_SUCCESS

    on success

  - CUPTI_ERROR_NOT_INITIALIZED

    if unable to initialized CUPTI

  - CUPTI_ERROR_INVALID_PARAMETER

    if `subscriber` or `domain` is invalid

  ###### Description

  Enable or disabled all callbacks for a specific domain.

  Note:

  Thread-safety: a subscriber must serialize access to cuptiGetCallbackState, cuptiEnableCallback, cuptiEnableDomain, and cuptiEnableAllDomains. For example, if cuptiGetCallbackEnabled(sub, d, *) and cuptiEnableDomain(sub, d) are called concurrently, the results are undefined.

CUptiResult cuptiGetCallbackName ( CUpti_CallbackDomain domain, uint32_t cbid, const char** name )
  Get the name of a callback for a specific domain and callback ID.

  ###### Parameters

  `domain`
    The domain of the callback
  `cbid`
    The ID of the callback
  `name`
    Returns pointer to the name string on success, NULL otherwise

  ###### Returns

  - CUPTI_SUCCESS

    on success

  - CUPTI_ERROR_INVALID_PARAMETER

    if `name` is NULL, or if `domain` or `cbid` is invalid.

  ###### Description

  Returns a pointer to the name c_string in `**name`.

  Note:

  Names are available only for the DRIVER and RUNTIME domains.

CUptiResult cuptiGetCallbackState ( uint32_t* enable, CUpti_SubscriberHandle subscriber, CUpti_CallbackDomain domain, CUpti_CallbackId cbid )
  Get the current enabled/disabled state of a callback for a specific domain and function ID.

  ###### Parameters

  `enable`
    Returns non-zero if callback enabled, zero if not enabled
  `subscriber`
    Handle to the initialize subscriber
  `domain`
    The domain of the callback
  `cbid`
    The ID of the callback

  ###### Returns

  - CUPTI_SUCCESS

    on success

  - CUPTI_ERROR_NOT_INITIALIZED

    if unable to initialized CUPTI

  - CUPTI_ERROR_INVALID_PARAMETER

    if `enabled` is NULL, or if `subscriber`, `domain` or `cbid` is invalid.

  ###### Description

  Returns non-zero in `*enable` if the callback for a domain and callback ID is enabled, and zero if not enabled.

  Note:

  Thread-safety: a subscriber must serialize access to cuptiGetCallbackState, cuptiEnableCallback, cuptiEnableDomain, and cuptiEnableAllDomains. For example, if cuptiGetCallbackState(sub, d, c) and cuptiEnableCallback(sub, d, c) are called concurrently, the results are undefined.

CUptiResult cuptiSubscribe ( CUpti_SubscriberHandle* subscriber, CUpti_CallbackFunc callback, void* userdata )
  Initialize a callback subscriber with a callback function and user data.

  ###### Parameters

  `subscriber`
    Returns handle to initialize subscriber
  `callback`
    The callback function
  `userdata`
    A pointer to user data. This data will be passed to the callback function via the `userdata` paramater.

  ###### Returns

  - CUPTI_SUCCESS

    on success

  - CUPTI_ERROR_NOT_INITIALIZED

    if unable to initialize CUPTI

  - CUPTI_ERROR_MAX_LIMIT_REACHED

    if there is already a CUPTI subscriber

  - CUPTI_ERROR_INVALID_PARAMETER

    if `subscriber` is NULL

  ###### Description

  Initializes a callback subscriber with a callback function and (optionally) a pointer to user data. The returned subscriber handle can be used to enable and disable the callback for specific domains and callback IDs.

  Note:

  - Only a single subscriber can be registered at a time.

  - This function does not enable any callbacks.

  - Thread-safety: this function is thread safe.

CUptiResult cuptiSupportedDomains ( size_t* domainCount, CUpti_DomainTable* domainTable )
  Get the available callback domains.

  ###### Parameters

  `domainCount`
    Returns number of callback domains
  `domainTable`
    Returns pointer to array of available callback domains

  ###### Returns

  - CUPTI_SUCCESS

    on success

  - CUPTI_ERROR_NOT_INITIALIZED

    if unable to initialize CUPTI

  - CUPTI_ERROR_INVALID_PARAMETER

    if `domainCount` or `domainTable` are NULL

  ###### Description

  Returns in `*domainTable` an array of size `*domainCount` of all the available callback domains.

  Note:

  Thread-safety: this function is thread safe.

CUptiResult cuptiUnsubscribe ( CUpti_SubscriberHandle subscriber )
  Unregister a callback subscriber.

  ###### Parameters

  `subscriber`
    Handle to the initialize subscriber

  ###### Returns

  - CUPTI_SUCCESS

    on success

  - CUPTI_ERROR_NOT_INITIALIZED

    if unable to initialized CUPTI

  - CUPTI_ERROR_INVALID_PARAMETER

    if `subscriber` is NULL or not initialized

  ###### Description

  Removes a callback subscriber so that no future callbacks will be issued to that subscriber.

  Note:

  Thread-safety: this function is thread safe.