CUPTI Callback API


Data Structures

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

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_CallbackDomainCUpti_DomainTable
 Pointer to an array of callback domains.
typedef struct
CUpti_Subscriber_st * 
CUpti_SubscriberHandle
 A callback subscriber.

Enumerations

enum  CUpti_ApiCallbackSite {
  CUPTI_API_ENTER = 0,
  CUPTI_API_EXIT = 1
}
 Specifies the point in an API call that a callback is issued. More...
enum  CUpti_CallbackDomain {
  CUPTI_CB_DOMAIN_INVALID = 0,
  CUPTI_CB_DOMAIN_DRIVER_API = 1,
  CUPTI_CB_DOMAIN_RUNTIME_API = 2,
  CUPTI_CB_DOMAIN_RESOURCE = 3,
  CUPTI_CB_DOMAIN_SYNCHRONIZE = 4,
  CUPTI_CB_DOMAIN_NVTX = 5
}
 Callback domains. More...
enum  CUpti_CallbackIdResource {
  CUPTI_CBID_RESOURCE_INVALID = 0,
  CUPTI_CBID_RESOURCE_CONTEXT_CREATED = 1,
  CUPTI_CBID_RESOURCE_CONTEXT_DESTROY_STARTING = 2,
  CUPTI_CBID_RESOURCE_STREAM_CREATED = 3,
  CUPTI_CBID_RESOURCE_STREAM_DESTROY_STARTING = 4,
  CUPTI_CBID_RESOURCE_CU_INIT_FINISHED = 5,
  CUPTI_CBID_RESOURCE_MODULE_LOADED = 6,
  CUPTI_CBID_RESOURCE_MODULE_UNLOAD_STARTING = 7,
  CUPTI_CBID_RESOURCE_MODULE_PROFILED = 8,
  CUPTI_CBID_RESOURCE_GRAPH_CREATED = 9,
  CUPTI_CBID_RESOURCE_GRAPH_DESTROY_STARTING = 10,
  CUPTI_CBID_RESOURCE_GRAPH_CLONED = 11,
  CUPTI_CBID_RESOURCE_GRAPHNODE_CREATE_STARTING = 12,
  CUPTI_CBID_RESOURCE_GRAPHNODE_CREATED = 13,
  CUPTI_CBID_RESOURCE_GRAPHNODE_DESTROY_STARTING = 14,
  CUPTI_CBID_RESOURCE_GRAPHNODE_DEPENDENCY_CREATED = 15,
  CUPTI_CBID_RESOURCE_GRAPHNODE_DEPENDENCY_DESTROY_STARTING = 16,
  CUPTI_CBID_RESOURCE_GRAPHEXEC_CREATE_STARTING = 17,
  CUPTI_CBID_RESOURCE_GRAPHEXEC_CREATED = 18,
  CUPTI_CBID_RESOURCE_GRAPHEXEC_DESTROY_STARTING = 19
}
 Callback IDs for resource domain. More...
enum  CUpti_CallbackIdSync {
  CUPTI_CBID_SYNCHRONIZE_INVALID = 0,
  CUPTI_CBID_SYNCHRONIZE_STREAM_SYNCHRONIZED = 1,
  CUPTI_CBID_SYNCHRONIZE_CONTEXT_SYNCHRONIZED = 2
}
 Callback IDs for synchronization domain. More...

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.

Detailed Description

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

Typedef Documentation

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

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
domain The domain of the callback
cbid The ID of the callback
cbdata Data passed to the callback.

typedef uint32_t CUpti_CallbackId

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.


Enumeration Type Documentation

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

Enumerator:
CUPTI_API_ENTER  The callback is at the entry of the API call.
CUPTI_API_EXIT  The callback is at the exit of the API call.

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

Enumerator:
CUPTI_CB_DOMAIN_INVALID  Invalid domain.
CUPTI_CB_DOMAIN_DRIVER_API  Domain containing callback points for all driver API functions.
CUPTI_CB_DOMAIN_RUNTIME_API  Domain containing callback points for all runtime API functions.
CUPTI_CB_DOMAIN_RESOURCE  Domain containing callback points for CUDA resource tracking.
CUPTI_CB_DOMAIN_SYNCHRONIZE  Domain containing callback points for CUDA synchronization.
CUPTI_CB_DOMAIN_NVTX  Domain containing callback points for NVTX API functions.

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

Enumerator:
CUPTI_CBID_RESOURCE_INVALID  Invalid resource callback ID.
CUPTI_CBID_RESOURCE_CONTEXT_CREATED  A new context has been created.
CUPTI_CBID_RESOURCE_CONTEXT_DESTROY_STARTING  A context is about to be destroyed.
CUPTI_CBID_RESOURCE_STREAM_CREATED  A new stream has been created.
CUPTI_CBID_RESOURCE_STREAM_DESTROY_STARTING  A stream is about to be destroyed.
CUPTI_CBID_RESOURCE_CU_INIT_FINISHED  The driver has finished initializing.
CUPTI_CBID_RESOURCE_MODULE_LOADED  A module has been loaded.
CUPTI_CBID_RESOURCE_MODULE_UNLOAD_STARTING  A module is about to be unloaded.
CUPTI_CBID_RESOURCE_MODULE_PROFILED  The current module which is being profiled.
CUPTI_CBID_RESOURCE_GRAPH_CREATED  CUDA graph has been created.
CUPTI_CBID_RESOURCE_GRAPH_DESTROY_STARTING  CUDA graph is about to be destroyed.
CUPTI_CBID_RESOURCE_GRAPH_CLONED  CUDA graph is cloned.
CUPTI_CBID_RESOURCE_GRAPHNODE_CREATE_STARTING  CUDA graph node is about to be created
CUPTI_CBID_RESOURCE_GRAPHNODE_CREATED  CUDA graph node is created.
CUPTI_CBID_RESOURCE_GRAPHNODE_DESTROY_STARTING  CUDA graph node is about to be destroyed.
CUPTI_CBID_RESOURCE_GRAPHNODE_DEPENDENCY_CREATED  Dependency on a CUDA graph node is created.
CUPTI_CBID_RESOURCE_GRAPHNODE_DEPENDENCY_DESTROY_STARTING  Dependency on a CUDA graph node is destroyed.
CUPTI_CBID_RESOURCE_GRAPHEXEC_CREATE_STARTING  An executable CUDA graph is about to be created.
CUPTI_CBID_RESOURCE_GRAPHEXEC_CREATED  An executable CUDA graph is created.
CUPTI_CBID_RESOURCE_GRAPHEXEC_DESTROY_STARTING  An executable CUDA graph is about to be destroyed.

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

Enumerator:
CUPTI_CBID_SYNCHRONIZE_INVALID  Invalid synchronize callback ID.
CUPTI_CBID_SYNCHRONIZE_STREAM_SYNCHRONIZED  Stream synchronization has completed for the stream.
CUPTI_CBID_SYNCHRONIZE_CONTEXT_SYNCHRONIZED  Context synchronization has completed for the context.


Function Documentation

CUptiResult cuptiEnableAllDomains ( uint32_t  enable,
CUpti_SubscriberHandle  subscriber 
)

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
Return values:
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 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
Return values:
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.

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
Return values:
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 
)

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
Return values:
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 
)

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
Return values:
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 
)

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.
Return values:
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 
)

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
Return values:
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  ) 

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
Return values:
CUPTI_SUCCESS on success
CUPTI_ERROR_NOT_INITIALIZED if unable to initialized CUPTI
CUPTI_ERROR_INVALID_PARAMETER if subscriber is NULL or not initialized


Generated on Thu Feb 7 11:33:26 2019 for Cupti by  doxygen 1.5.8