CUPTI :: CUDA Toolkit Documentation

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