CUPTI (PDF) - CUDA Toolkit v5.5 (older) - Last updated May 11, 2013 - Send Feedback

2.4. CUPTI Callback API

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

Classes

struct 
Data passed into a runtime or driver API callback function.
struct 
Data passed into a NVTX callback function.
struct 
Data passed into a resource callback function.
struct 
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. 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. 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. 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_SIZE
CUPTI_CBID_RESOURCE_FORCE_INT = 0x7fffffff
enum CUpti_CallbackIdSync

Callback IDs for synchronization domain. 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. 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.

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

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

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.

CUptiResult cuptiEnableDomain ( uint32_t enable, CUpti_SubscriberHandle subscriber, CUpti_CallbackDomain domain )

Enable or disabled all callbacks for a specific domain. 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.

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

CUptiResult cuptiGetCallbackName ( CUpti_CallbackDomain domain, uint32_t cbid, const char** name )

Get the name of a callback for a specific domain and callback ID. Returns a pointer to the name c_string in **name.

Note:

Names are available only for the DRIVER and RUNTIME domains.

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.

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

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.

CUptiResult cuptiSubscribe ( CUpti_SubscriberHandle* subscriber, CUpti_CallbackFunc callback, void* userdata )

Initialize a callback subscriber with a callback function and user data. 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.

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

CUptiResult cuptiSupportedDomains ( size_t* domainCount, CUpti_DomainTable* domainTable )

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

Note:

Thread-safety: this function is thread safe.

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

CUptiResult cuptiUnsubscribe ( CUpti_SubscriberHandle subscriber )

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

Note:

Thread-safety: this function is thread safe.

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


CUPTI (PDF) - CUDA Toolkit v5.5 (older) - Last updated May 11, 2013 - Send Feedback