2.5. CUPTI Event API

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

Classes

struct 
A set of event groups.
struct 
A set of event group sets.

Defines

#define CUPTI_EVENT_INVALID
The value that indicates the event value is invalid.
#define CUPTI_EVENT_OVERFLOW
The overflow value for a CUPTI event.

Typedefs

typedef uint32_t  CUpti_EventDomainID
ID for an event domain.
typedef void *  CUpti_EventGroup
A group of events.
typedef uint32_t  CUpti_EventID
ID for an event.
typedef void  ( *CUpti_KernelReplayUpdateFunc )( const char*  kernelName,  int numReplaysDone, void*  customData )
Function type for getting updates on kernel replay.

Enumerations

enum CUpti_DeviceAttribute
Device attributes.
enum CUpti_DeviceAttributeDeviceClass
Device class.
enum CUpti_EventAttribute
Event attributes.
enum CUpti_EventCategory
An event category.
enum CUpti_EventCollectionMethod
The collection method used for an event.
enum CUpti_EventCollectionMode
Event collection modes.
enum CUpti_EventDomainAttribute
Event domain attributes.
enum CUpti_EventGroupAttribute
Event group attributes.
enum CUpti_ReadEventFlags
Flags for cuptiEventGroupReadEvent an cuptiEventGroupReadAllEvents.

Functions

CUptiResult cuptiDeviceEnumEventDomains ( CUdevice device, size_t* arraySizeBytes, CUpti_EventDomainID* domainArray )
Get the event domains for a device.
CUptiResult cuptiDeviceGetAttribute ( CUdevice device, CUpti_DeviceAttribute attrib, size_t* valueSize, void* value )
Read a device attribute.
CUptiResult cuptiDeviceGetEventDomainAttribute ( CUdevice device, CUpti_EventDomainID eventDomain, CUpti_EventDomainAttribute attrib, size_t* valueSize, void* value )
Read an event domain attribute.
CUptiResult cuptiDeviceGetNumEventDomains ( CUdevice device, uint32_t* numDomains )
Get the number of domains for a device.
CUptiResult cuptiDeviceGetTimestamp ( CUcontext context, uint64_t* timestamp )
Read a device timestamp.
CUptiResult cuptiDisableKernelReplayMode ( CUcontext context )
Disable kernel replay mode.
CUptiResult cuptiEnableKernelReplayMode ( CUcontext context )
Enable kernel replay mode.
CUptiResult cuptiEnumEventDomains ( size_t* arraySizeBytes, CUpti_EventDomainID* domainArray )
Get the event domains available on any device.
CUptiResult cuptiEventDomainEnumEvents ( CUpti_EventDomainID eventDomain, size_t* arraySizeBytes, CUpti_EventID* eventArray )
Get the events in a domain.
CUptiResult cuptiEventDomainGetAttribute ( CUpti_EventDomainID eventDomain, CUpti_EventDomainAttribute attrib, size_t* valueSize, void* value )
Read an event domain attribute.
CUptiResult cuptiEventDomainGetNumEvents ( CUpti_EventDomainID eventDomain, uint32_t* numEvents )
Get number of events in a domain.
CUptiResult cuptiEventGetAttribute ( CUpti_EventID event, CUpti_EventAttribute attrib, size_t* valueSize, void* value )
Get an event attribute.
CUptiResult cuptiEventGetIdFromName ( CUdevice device, const char* eventName, CUpti_EventID* event )
Find an event by name.
CUptiResult cuptiEventGroupAddEvent ( CUpti_EventGroup eventGroup, CUpti_EventID event )
Add an event to an event group.
CUptiResult cuptiEventGroupCreate ( CUcontext context, CUpti_EventGroup* eventGroup, uint32_t flags )
Create a new event group for a context.
CUptiResult cuptiEventGroupDestroy ( CUpti_EventGroup eventGroup )
Destroy an event group.
CUptiResult cuptiEventGroupDisable ( CUpti_EventGroup eventGroup )
Disable an event group.
CUptiResult cuptiEventGroupEnable ( CUpti_EventGroup eventGroup )
Enable an event group.
CUptiResult cuptiEventGroupGetAttribute ( CUpti_EventGroup eventGroup, CUpti_EventGroupAttribute attrib, size_t* valueSize, void* value )
Read an event group attribute.
CUptiResult cuptiEventGroupReadAllEvents ( CUpti_EventGroup eventGroup, CUpti_ReadEventFlags flags, size_t* eventValueBufferSizeBytes, uint64_t* eventValueBuffer, size_t* eventIdArraySizeBytes, CUpti_EventID* eventIdArray, size_t* numEventIdsRead )
Read the values for all the events in an event group.
CUptiResult cuptiEventGroupReadEvent ( CUpti_EventGroup eventGroup, CUpti_ReadEventFlags flags, CUpti_EventID event, size_t* eventValueBufferSizeBytes, uint64_t* eventValueBuffer )
Read the value for an event in an event group.
CUptiResult cuptiEventGroupRemoveAllEvents ( CUpti_EventGroup eventGroup )
Remove all events from an event group.
CUptiResult cuptiEventGroupRemoveEvent ( CUpti_EventGroup eventGroup, CUpti_EventID event )
Remove an event from an event group.
CUptiResult cuptiEventGroupResetAllEvents ( CUpti_EventGroup eventGroup )
Zero all the event counts in an event group.
CUptiResult cuptiEventGroupSetAttribute ( CUpti_EventGroup eventGroup, CUpti_EventGroupAttribute attrib, size_t valueSize, void* value )
Write an event group attribute.
CUptiResult cuptiEventGroupSetDisable ( CUpti_EventGroupSet* eventGroupSet )
Disable an event group set.
CUptiResult cuptiEventGroupSetEnable ( CUpti_EventGroupSet* eventGroupSet )
Enable an event group set.
CUptiResult cuptiEventGroupSetsCreate ( CUcontext context, size_t eventIdArraySizeBytes, CUpti_EventID* eventIdArray, CUpti_EventGroupSets** eventGroupPasses )
For a set of events, get the grouping that indicates the number of passes and the event groups necessary to collect the events.
CUptiResult cuptiEventGroupSetsDestroy ( CUpti_EventGroupSets* eventGroupSets )
Destroy a CUpti_EventGroupSets object.
CUptiResult cuptiGetNumEventDomains ( uint32_t* numDomains )
Get the number of event domains available on any device.
CUptiResult cuptiKernelReplaySubscribeUpdate ( CUpti_KernelReplayUpdateFunc updateFunc, void* customData )
Subscribe to kernel replay updates.
CUptiResult cuptiSetEventCollectionMode ( CUcontext context, CUpti_EventCollectionMode mode )
Set the event collection mode.

Defines

#define CUPTI_EVENT_INVALID

Value

((uint64_t)0xFFFFFFFFFFFFFFFEULL)

#define CUPTI_EVENT_OVERFLOW

The CUPTI event value that indicates an overflow.

Value

((uint64_t)0xFFFFFFFFFFFFFFFFULL)

Typedefs

typedef uint32_t CUpti_EventDomainID

ID for an event domain. ID for an event domain. An event domain represents a group of related events. A device may have multiple instances of a domain, indicating that the device can simultaneously record multiple instances of each event within that domain.

typedef void * CUpti_EventGroup

A group of events. An event group is a collection of events that are managed together. All events in an event group must belong to the same domain.

typedef uint32_t CUpti_EventID

ID for an event. An event represents a countable activity, action, or occurrence on the device.

void ( *CUpti_KernelReplayUpdateFunc )( const char*  kernelName,  int numReplaysDone, void*  customData )

Function type for getting updates on kernel replay.

Parameters
kernelName
The mangled kernel name
int numReplaysDone
customData
Pointer of any custom data passed in when subscribing

Enumerations

enum CUpti_DeviceAttribute

CUPTI device attributes. These attributes can be read using cuptiDeviceGetAttribute.

Values
CUPTI_DEVICE_ATTR_MAX_EVENT_ID = 1
Number of event IDs for a device. Value is a uint32_t.
CUPTI_DEVICE_ATTR_MAX_EVENT_DOMAIN_ID = 2
Number of event domain IDs for a device. Value is a uint32_t.
CUPTI_DEVICE_ATTR_GLOBAL_MEMORY_BANDWIDTH = 3
Get global memory bandwidth in Kbytes/sec. Value is a uint64_t.
CUPTI_DEVICE_ATTR_INSTRUCTION_PER_CYCLE = 4
Get theoretical maximum number of instructions per cycle. Value is a uint32_t.
CUPTI_DEVICE_ATTR_INSTRUCTION_THROUGHPUT_SINGLE_PRECISION = 5
Get theoretical maximum number of single precision instructions that can be executed per second. Value is a uint64_t.
CUPTI_DEVICE_ATTR_MAX_FRAME_BUFFERS = 6
Get number of frame buffers for device. Value is a uint64_t.
CUPTI_DEVICE_ATTR_PCIE_LINK_RATE = 7
Get PCIE link rate in Mega bits/sec for device. Return 0 if bus-type is non-PCIE. Value is a uint64_t.
CUPTI_DEVICE_ATTR_PCIE_LINK_WIDTH = 8
Get PCIE link width for device. Return 0 if bus-type is non-PCIE. Value is a uint64_t.
CUPTI_DEVICE_ATTR_PCIE_GEN = 9
Get PCIE generation for device. Return 0 if bus-type is non-PCIE. Value is a uint64_t.
CUPTI_DEVICE_ATTR_DEVICE_CLASS = 10
Get the class for the device. Value is a CUpti_DeviceAttributeDeviceClass.
CUPTI_DEVICE_ATTR_FLOP_SP_PER_CYCLE = 11
Get the peak single precision flop per cycle. Value is a uint64_t.
CUPTI_DEVICE_ATTR_FLOP_DP_PER_CYCLE = 12
Get the peak double precision flop per cycle. Value is a uint64_t.
CUPTI_DEVICE_ATTR_MAX_L2_UNITS = 13
Get number of L2 units. Value is a uint64_t.
CUPTI_DEVICE_ATTR_MAX_SHARED_MEMORY_CACHE_CONFIG_PREFER_SHARED = 14
Get the maximum shared memory for the CU_FUNC_CACHE_PREFER_SHARED preference. Value is a uint64_t.
CUPTI_DEVICE_ATTR_MAX_SHARED_MEMORY_CACHE_CONFIG_PREFER_L1 = 15
Get the maximum shared memory for the CU_FUNC_CACHE_PREFER_L1 preference. Value is a uint64_t.
CUPTI_DEVICE_ATTR_MAX_SHARED_MEMORY_CACHE_CONFIG_PREFER_EQUAL = 16
Get the maximum shared memory for the CU_FUNC_CACHE_PREFER_EQUAL preference. Value is a uint64_t.
CUPTI_DEVICE_ATTR_FLOP_HP_PER_CYCLE = 17
Get the peak half precision flop per cycle. Value is a uint64_t.
CUPTI_DEVICE_ATTR_NVLINK_PRESENT = 18
Check if Nvlink is connected to device. Returns 1, if at least one Nvlink is connected to the device, returns 0 otherwise. Value is a uint32_t.
CUPTI_DEVICE_ATTR_GPU_CPU_NVLINK_BW = 19
Check if Nvlink is present between GPU and CPU. Returns Bandwidth, in Bytes/sec, if Nvlink is present, returns 0 otherwise. Value is a uint64_t.
CUPTI_DEVICE_ATTR_FORCE_INT = 0x7fffffff
enum CUpti_DeviceAttributeDeviceClass

Enumeration of device classes for device attribute CUPTI_DEVICE_ATTR_DEVICE_CLASS.

Values
CUPTI_DEVICE_ATTR_DEVICE_CLASS_TESLA = 0
CUPTI_DEVICE_ATTR_DEVICE_CLASS_QUADRO = 1
CUPTI_DEVICE_ATTR_DEVICE_CLASS_GEFORCE = 2
CUPTI_DEVICE_ATTR_DEVICE_CLASS_TEGRA = 3
enum CUpti_EventAttribute

Event attributes. These attributes can be read using cuptiEventGetAttribute.

Values
CUPTI_EVENT_ATTR_NAME = 0
Event name. Value is a null terminated const c-string.
CUPTI_EVENT_ATTR_SHORT_DESCRIPTION = 1
Short description of event. Value is a null terminated const c-string.
CUPTI_EVENT_ATTR_LONG_DESCRIPTION = 2
Long description of event. Value is a null terminated const c-string.
CUPTI_EVENT_ATTR_CATEGORY = 3
Category of event. Value is CUpti_EventCategory.
CUPTI_EVENT_ATTR_FORCE_INT = 0x7fffffff
enum CUpti_EventCategory

Each event is assigned to a category that represents the general type of the event. A event's category is accessed using cuptiEventGetAttribute and the CUPTI_EVENT_ATTR_CATEGORY attribute.

Values
CUPTI_EVENT_CATEGORY_INSTRUCTION = 0
An instruction related event.
CUPTI_EVENT_CATEGORY_MEMORY = 1
A memory related event.
CUPTI_EVENT_CATEGORY_CACHE = 2
A cache related event.
CUPTI_EVENT_CATEGORY_PROFILE_TRIGGER = 3
A profile-trigger event.
CUPTI_EVENT_CATEGORY_FORCE_INT = 0x7fffffff
enum CUpti_EventCollectionMethod

The collection method indicates how an event is collected.

Values
CUPTI_EVENT_COLLECTION_METHOD_PM = 0
Event is collected using a hardware global performance monitor.
CUPTI_EVENT_COLLECTION_METHOD_SM = 1
Event is collected using a hardware SM performance monitor.
CUPTI_EVENT_COLLECTION_METHOD_INSTRUMENTED = 2
Event is collected using software instrumentation.
CUPTI_EVENT_COLLECTION_METHOD_NVLINK_TC = 3
Event is collected using NvLink throughput counter method.
CUPTI_EVENT_COLLECTION_METHOD_FORCE_INT = 0x7fffffff
enum CUpti_EventCollectionMode

The event collection mode determines the period over which the events within the enabled event groups will be collected.

Values
CUPTI_EVENT_COLLECTION_MODE_CONTINUOUS = 0
Events are collected for the entire duration between the cuptiEventGroupEnable and cuptiEventGroupDisable calls. For devices with compute capability less than 2.0, event values are reset when a kernel is launched. For all other devices event values are only reset when the events are read. For CUDA toolkit v6.0 and older this was the default mode. From CUDA toolkit v6.5 this mode is supported on Tesla devices only.
CUPTI_EVENT_COLLECTION_MODE_KERNEL = 1
Events are collected only for the durations of kernel executions that occur between the cuptiEventGroupEnable and cuptiEventGroupDisable calls. Event collection begins when a kernel execution begins, and stops when kernel execution completes. Event values are reset to zero when each kernel execution begins. If multiple kernel executions occur between the cuptiEventGroupEnable and cuptiEventGroupDisable calls then the event values must be read after each kernel launch if those events need to be associated with the specific kernel launch. This is the default mode from CUDA toolkit v6.5, and it is the only supported mode for non-Tesla (Quadro, GeForce etc.) devices.
CUPTI_EVENT_COLLECTION_MODE_FORCE_INT = 0x7fffffff
enum CUpti_EventDomainAttribute

Event domain attributes. Except where noted, all the attributes can be read using either cuptiDeviceGetEventDomainAttribute or cuptiEventDomainGetAttribute.

Values
CUPTI_EVENT_DOMAIN_ATTR_NAME = 0
Event domain name. Value is a null terminated const c-string.
CUPTI_EVENT_DOMAIN_ATTR_INSTANCE_COUNT = 1
Number of instances of the domain for which event counts will be collected. The domain may have additional instances that cannot be profiled (see CUPTI_EVENT_DOMAIN_ATTR_TOTAL_INSTANCE_COUNT). Can be read only with cuptiDeviceGetEventDomainAttribute. Value is a uint32_t.
CUPTI_EVENT_DOMAIN_ATTR_TOTAL_INSTANCE_COUNT = 3
Total number of instances of the domain, including instances that cannot be profiled. Use CUPTI_EVENT_DOMAIN_ATTR_INSTANCE_COUNT to get the number of instances that can be profiled. Can be read only with cuptiDeviceGetEventDomainAttribute. Value is a uint32_t.
CUPTI_EVENT_DOMAIN_ATTR_COLLECTION_METHOD = 4
Collection method used for events contained in the event domain. Value is a CUpti_EventCollectionMethod.
CUPTI_EVENT_DOMAIN_ATTR_FORCE_INT = 0x7fffffff
enum CUpti_EventGroupAttribute

Event group attributes. These attributes can be read using cuptiEventGroupGetAttribute. Attributes marked [rw] can also be written using cuptiEventGroupSetAttribute.

Values
CUPTI_EVENT_GROUP_ATTR_EVENT_DOMAIN_ID = 0
The domain to which the event group is bound. This attribute is set when the first event is added to the group. Value is a CUpti_EventDomainID.
CUPTI_EVENT_GROUP_ATTR_PROFILE_ALL_DOMAIN_INSTANCES = 1
[rw] Profile all the instances of the domain for this eventgroup. This feature can be used to get load balancing across all instances of a domain. Value is an integer.
CUPTI_EVENT_GROUP_ATTR_USER_DATA = 2
[rw] Reserved for user data.
CUPTI_EVENT_GROUP_ATTR_NUM_EVENTS = 3
Number of events in the group. Value is a uint32_t.
CUPTI_EVENT_GROUP_ATTR_EVENTS = 4
Enumerates events in the group. Value is a pointer to buffer of size sizeof(CUpti_EventID) * num_of_events in the eventgroup. num_of_events can be queried using CUPTI_EVENT_GROUP_ATTR_NUM_EVENTS.
CUPTI_EVENT_GROUP_ATTR_INSTANCE_COUNT = 5
Number of instances of the domain bound to this event group that will be counted. Value is a uint32_t.
CUPTI_EVENT_GROUP_ATTR_FORCE_INT = 0x7fffffff
enum CUpti_ReadEventFlags
Values
CUPTI_EVENT_READ_FLAG_NONE = 0
No flags.
CUPTI_EVENT_READ_FLAG_FORCE_INT = 0x7fffffff

Functions

CUptiResult cuptiDeviceEnumEventDomains ( CUdevice device, size_t* arraySizeBytes, CUpti_EventDomainID* domainArray )
Get the event domains for a device.
Parameters
device
The CUDA device
arraySizeBytes
The size of domainArray in bytes, and returns the number of bytes written to domainArray
domainArray
Returns the IDs of the event domains for the device
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_DEVICE

  • CUPTI_ERROR_INVALID_PARAMETER

    if arraySizeBytes or domainArray are NULL

Description

Returns the event domains IDs in domainArray for a device. The size of the domainArray buffer is given by *arraySizeBytes. The size of the domainArray buffer must be at least numdomains * sizeof(CUpti_EventDomainID) or else all domains will not be returned. The value returned in *arraySizeBytes contains the number of bytes returned in domainArray.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiDeviceGetAttribute ( CUdevice device, CUpti_DeviceAttribute attrib, size_t* valueSize, void* value )
Read a device attribute.
Parameters
device
The CUDA device
attrib
The attribute to read
valueSize
Size of buffer pointed by the value, and returns the number of bytes written to value
value
Returns the value of the attribute
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_DEVICE

  • CUPTI_ERROR_INVALID_PARAMETER

    if valueSize or value is NULL, or if attrib is not a device attribute

  • CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT

    For non-c-string attribute values, indicates that the value buffer is too small to hold the attribute value.

Description

Read a device attribute and return it in *value.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiDeviceGetEventDomainAttribute ( CUdevice device, CUpti_EventDomainID eventDomain, CUpti_EventDomainAttribute attrib, size_t* valueSize, void* value )
Read an event domain attribute.
Parameters
device
The CUDA device
eventDomain
ID of the event domain
attrib
The event domain attribute to read
valueSize
The size of the value buffer in bytes, and returns the number of bytes written to value
value
Returns the attribute's value
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_DEVICE

  • CUPTI_ERROR_INVALID_EVENT_DOMAIN_ID

  • CUPTI_ERROR_INVALID_PARAMETER

    if valueSize or value is NULL, or if attrib is not an event domain attribute

  • CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT

    For non-c-string attribute values, indicates that the value buffer is too small to hold the attribute value.

Description

Returns an event domain attribute in *value. The size of the value buffer is given by *valueSize. The value returned in *valueSize contains the number of bytes returned in value.

If the attribute value is a c-string that is longer than *valueSize, then only the first *valueSize characters will be returned and there will be no terminating null byte.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiDeviceGetNumEventDomains ( CUdevice device, uint32_t* numDomains )
Get the number of domains for a device.
Parameters
device
The CUDA device
numDomains
Returns the number of domains
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_DEVICE

  • CUPTI_ERROR_INVALID_PARAMETER

    if numDomains is NULL

Description

Returns the number of domains in numDomains for a device.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiDeviceGetTimestamp ( CUcontext context, uint64_t* timestamp )
Read a device timestamp.
Parameters
context
A context on the device from which to get the timestamp
timestamp
Returns the device timestamp
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_CONTEXT

  • CUPTI_ERROR_INVALID_PARAMETER

    is timestamp is NULL

Description

Returns the device timestamp in *timestamp. The timestamp is reported in nanoseconds and indicates the time since the device was last reset.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiDisableKernelReplayMode ( CUcontext context )
Disable kernel replay mode.
Parameters
context
The context
Returns

  • CUPTI_SUCCESS

Description

Set profiling mode for the context to non-replay (default) mode. Event collection mode will be set to CUPTI_EVENT_COLLECTION_MODE_KERNEL. All previously enabled event groups and event group sets will be disabled.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEnableKernelReplayMode ( CUcontext context )
Enable kernel replay mode.
Parameters
context
The context
Returns

  • CUPTI_SUCCESS

Description

Set profiling mode for the context to replay mode. In this mode, any number of events can be collected in one run of the kernel. The event collection mode will automatically switch to CUPTI_EVENT_COLLECTION_MODE_KERNEL. In this mode, cuptiSetEventCollectionMode will return CUPTI_ERROR_INVALID_OPERATION.

Note:
  • Kernels might take longer to run if many events are enabled.

  • Thread-safety: this function is thread safe.

CUptiResult cuptiEnumEventDomains ( size_t* arraySizeBytes, CUpti_EventDomainID* domainArray )
Get the event domains available on any device.
Parameters
arraySizeBytes
The size of domainArray in bytes, and returns the number of bytes written to domainArray
domainArray
Returns all the event domains
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_INVALID_PARAMETER

    if arraySizeBytes or domainArray are NULL

Description

Returns all the event domains available on any CUDA-capable device. Event domain IDs are returned in domainArray. The size of the domainArray buffer is given by *arraySizeBytes. The size of the domainArray buffer must be at least numDomains * sizeof(CUpti_EventDomainID) or all domains will not be returned. The value returned in *arraySizeBytes contains the number of bytes returned in domainArray.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventDomainEnumEvents ( CUpti_EventDomainID eventDomain, size_t* arraySizeBytes, CUpti_EventID* eventArray )
Get the events in a domain.
Parameters
eventDomain
ID of the event domain
arraySizeBytes
The size of eventArray in bytes, and returns the number of bytes written to eventArray
eventArray
Returns the IDs of the events in the domain
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_EVENT_DOMAIN_ID

  • CUPTI_ERROR_INVALID_PARAMETER

    if arraySizeBytes or eventArray are NULL

Description

Returns the event IDs in eventArray for a domain. The size of the eventArray buffer is given by *arraySizeBytes. The size of the eventArray buffer must be at least numdomainevents * sizeof(CUpti_EventID) or else all events will not be returned. The value returned in *arraySizeBytes contains the number of bytes returned in eventArray.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventDomainGetAttribute ( CUpti_EventDomainID eventDomain, CUpti_EventDomainAttribute attrib, size_t* valueSize, void* value )
Read an event domain attribute.
Parameters
eventDomain
ID of the event domain
attrib
The event domain attribute to read
valueSize
The size of the value buffer in bytes, and returns the number of bytes written to value
value
Returns the attribute's value
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_EVENT_DOMAIN_ID

  • CUPTI_ERROR_INVALID_PARAMETER

    if valueSize or value is NULL, or if attrib is not an event domain attribute

  • CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT

    For non-c-string attribute values, indicates that the value buffer is too small to hold the attribute value.

Description

Returns an event domain attribute in *value. The size of the value buffer is given by *valueSize. The value returned in *valueSize contains the number of bytes returned in value.

If the attribute value is a c-string that is longer than *valueSize, then only the first *valueSize characters will be returned and there will be no terminating null byte.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventDomainGetNumEvents ( CUpti_EventDomainID eventDomain, uint32_t* numEvents )
Get number of events in a domain.
Parameters
eventDomain
ID of the event domain
numEvents
Returns the number of events in the domain
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_EVENT_DOMAIN_ID

  • CUPTI_ERROR_INVALID_PARAMETER

    if numEvents is NULL

Description

Returns the number of events in numEvents for a domain.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventGetAttribute ( CUpti_EventID event, CUpti_EventAttribute attrib, size_t* valueSize, void* value )
Get an event attribute.
Parameters
event
ID of the event
attrib
The event attribute to read
valueSize
The size of the value buffer in bytes, and returns the number of bytes written to value
value
Returns the attribute's value
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_EVENT_ID

  • CUPTI_ERROR_INVALID_PARAMETER

    if valueSize or value is NULL, or if attrib is not an event attribute

  • CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT

    For non-c-string attribute values, indicates that the value buffer is too small to hold the attribute value.

Description

Returns an event attribute in *value. The size of the value buffer is given by *valueSize. The value returned in *valueSize contains the number of bytes returned in value.

If the attribute value is a c-string that is longer than *valueSize, then only the first *valueSize characters will be returned and there will be no terminating null byte.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventGetIdFromName ( CUdevice device, const char* eventName, CUpti_EventID* event )
Find an event by name.
Parameters
device
The CUDA device
eventName
The name of the event to find
event
Returns the ID of the found event or undefined if unable to find the event
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_DEVICE

  • CUPTI_ERROR_INVALID_EVENT_NAME

    if unable to find an event with name eventName. In this case *event is undefined

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventName or event are NULL

Description

Find an event by name and return the event ID in *event.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventGroupAddEvent ( CUpti_EventGroup eventGroup, CUpti_EventID event )
Add an event to an event group.
Parameters
eventGroup
The event group
event
The event to add to the group
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_EVENT_ID

  • CUPTI_ERROR_OUT_OF_MEMORY

  • CUPTI_ERROR_INVALID_OPERATION

    if eventGroup is enabled

  • CUPTI_ERROR_NOT_COMPATIBLE

    if event belongs to a different event domain than the events already in eventGroup, or if a device limitation prevents event from being collected at the same time as the events already in eventGroup

  • CUPTI_ERROR_MAX_LIMIT_REACHED

    if eventGroup is full

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventGroup is NULL

Description

Add an event to an event group. The event add can fail for a number of reasons:

  • The event group is enabled

  • The event does not belong to the same event domain as the events that are already in the event group

  • Device limitations on the events that can belong to the same group

  • The event group is full

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventGroupCreate ( CUcontext context, CUpti_EventGroup* eventGroup, uint32_t flags )
Create a new event group for a context.
Parameters
context
The context for the event group
eventGroup
Returns the new event group
flags
Reserved - must be zero
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_CONTEXT

  • CUPTI_ERROR_OUT_OF_MEMORY

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventGroup is NULL

Description

Creates a new event group for context and returns the new group in *eventGroup.

Note:
  • flags are reserved for future use and should be set to zero.

  • Thread-safety: this function is thread safe.

CUptiResult cuptiEventGroupDestroy ( CUpti_EventGroup eventGroup )
Destroy an event group.
Parameters
eventGroup
The event group to destroy
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_OPERATION

    if the event group is enabled

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventGroup is NULL

Description

Destroy an eventGroup and free its resources. An event group cannot be destroyed if it is enabled.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventGroupDisable ( CUpti_EventGroup eventGroup )
Disable an event group.
Parameters
eventGroup
The event group
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_HARDWARE

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventGroup is NULL

Description

Disable an event group. Disabling an event group stops collection of events contained in the group.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventGroupEnable ( CUpti_EventGroup eventGroup )
Enable an event group.
Parameters
eventGroup
The event group
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_HARDWARE

  • CUPTI_ERROR_NOT_READY

    if eventGroup does not contain any events

  • CUPTI_ERROR_NOT_COMPATIBLE

    if eventGroup cannot be enabled due to other already enabled event groups

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventGroup is NULL

  • CUPTI_ERROR_HARDWARE_BUSY

    if another client is profiling and hardware is busy

Description

Enable an event group. Enabling an event group zeros the value of all the events in the group and then starts collection of those events.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventGroupGetAttribute ( CUpti_EventGroup eventGroup, CUpti_EventGroupAttribute attrib, size_t* valueSize, void* value )
Read an event group attribute.
Parameters
eventGroup
The event group
attrib
The attribute to read
valueSize
Size of buffer pointed by the value, and returns the number of bytes written to value
value
Returns the value of the attribute
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_PARAMETER

    if valueSize or value is NULL, or if attrib is not an eventgroup attribute

  • CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT

    For non-c-string attribute values, indicates that the value buffer is too small to hold the attribute value.

Description

Read an event group attribute and return it in *value.

Note:

Thread-safety: this function is thread safe but client must guard against simultaneous destruction or modification of eventGroup (for example, client must guard against simultaneous calls to cuptiEventGroupDestroy, cuptiEventGroupAddEvent, etc.), and must guard against simultaneous destruction of the context in which eventGroup was created (for example, client must guard against simultaneous calls to cudaDeviceReset, cuCtxDestroy, etc.).

CUptiResult cuptiEventGroupReadAllEvents ( CUpti_EventGroup eventGroup, CUpti_ReadEventFlags flags, size_t* eventValueBufferSizeBytes, uint64_t* eventValueBuffer, size_t* eventIdArraySizeBytes, CUpti_EventID* eventIdArray, size_t* numEventIdsRead )
Read the values for all the events in an event group.
Parameters
eventGroup
The event group
flags
Flags controlling the reading mode
eventValueBufferSizeBytes
The size of eventValueBuffer in bytes, and returns the number of bytes written to eventValueBuffer
eventValueBuffer
Returns the event values
eventIdArraySizeBytes
The size of eventIdArray in bytes, and returns the number of bytes written to eventIdArray
eventIdArray
Returns the IDs of the events in the same order as the values return in eventValueBuffer.
numEventIdsRead
Returns the number of event IDs returned in eventIdArray
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_HARDWARE

  • CUPTI_ERROR_INVALID_OPERATION

    if eventGroup is disabled

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventGroup, eventValueBufferSizeBytes, eventValueBuffer, eventIdArraySizeBytes, eventIdArray or numEventIdsRead is NULL

  • CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT

    if size of eventValueBuffer or eventIdArray is not sufficient

Description

Read the values for all the events in an event group. The event values are returned in the eventValueBuffer buffer. eventValueBufferSizeBytes indicates the size of eventValueBuffer. The buffer must be at least (sizeof(uint64) * number of events in group) if CUPTI_EVENT_GROUP_ATTR_PROFILE_ALL_DOMAIN_INSTANCES is not set on the group containing the events. The buffer must be at least (sizeof(uint64) * number of domain instances * number of events in group) if CUPTI_EVENT_GROUP_ATTR_PROFILE_ALL_DOMAIN_INSTANCES is set on the group.

The data format returned in eventValueBuffer is:

  • domain instance 0: event0 event1 ... eventN

  • domain instance 1: event0 event1 ... eventN

  • ...

  • domain instance M: event0 event1 ... eventN

The event order in eventValueBuffer is returned in eventIdArray. The size of eventIdArray is specified in eventIdArraySizeBytes. The size should be at least (sizeof(CUpti_EventID) * number of events in group).

If any instance of any event counter overflows, the value returned for that event instance will be CUPTI_EVENT_OVERFLOW.

The only allowed value for flags is CUPTI_EVENT_READ_FLAG_NONE.

Reading events from a disabled event group is not allowed. After being read, an event's value is reset to zero.

Note:

Thread-safety: this function is thread safe but client must guard against simultaneous destruction or modification of eventGroup (for example, client must guard against simultaneous calls to cuptiEventGroupDestroy, cuptiEventGroupAddEvent, etc.), and must guard against simultaneous destruction of the context in which eventGroup was created (for example, client must guard against simultaneous calls to cudaDeviceReset, cuCtxDestroy, etc.). If cuptiEventGroupResetAllEvents is called simultaneously with this function, then returned event values are undefined.

CUptiResult cuptiEventGroupReadEvent ( CUpti_EventGroup eventGroup, CUpti_ReadEventFlags flags, CUpti_EventID event, size_t* eventValueBufferSizeBytes, uint64_t* eventValueBuffer )
Read the value for an event in an event group.
Parameters
eventGroup
The event group
flags
Flags controlling the reading mode
event
The event to read
eventValueBufferSizeBytes
The size of eventValueBuffer in bytes, and returns the number of bytes written to eventValueBuffer
eventValueBuffer
Returns the event value(s)
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_EVENT_ID

  • CUPTI_ERROR_HARDWARE

  • CUPTI_ERROR_INVALID_OPERATION

    if eventGroup is disabled

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventGroup, eventValueBufferSizeBytes or eventValueBuffer is NULL

  • CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT

    if size of eventValueBuffer is not sufficient

Description

Read the value for an event in an event group. The event value is returned in the eventValueBuffer buffer. eventValueBufferSizeBytes indicates the size of the eventValueBuffer buffer. The buffer must be at least sizeof(uint64) if CUPTI_EVENT_GROUP_ATTR_PROFILE_ALL_DOMAIN_INSTANCES is not set on the group containing the event. The buffer must be at least (sizeof(uint64) * number of domain instances) if CUPTI_EVENT_GROUP_ATTR_PROFILE_ALL_DOMAIN_INSTANCES is set on the group.

If any instance of an event counter overflows, the value returned for that event instance will be CUPTI_EVENT_OVERFLOW.

The only allowed value for flags is CUPTI_EVENT_READ_FLAG_NONE.

Reading an event from a disabled event group is not allowed. After being read, an event's value is reset to zero.

Note:

Thread-safety: this function is thread safe but client must guard against simultaneous destruction or modification of eventGroup (for example, client must guard against simultaneous calls to cuptiEventGroupDestroy, cuptiEventGroupAddEvent, etc.), and must guard against simultaneous destruction of the context in which eventGroup was created (for example, client must guard against simultaneous calls to cudaDeviceReset, cuCtxDestroy, etc.). If cuptiEventGroupResetAllEvents is called simultaneously with this function, then returned event values are undefined.

CUptiResult cuptiEventGroupRemoveAllEvents ( CUpti_EventGroup eventGroup )
Remove all events from an event group.
Parameters
eventGroup
The event group
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_OPERATION

    if eventGroup is enabled

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventGroup is NULL

Description

Remove all events from an event group. Events cannot be removed if the event group is enabled.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventGroupRemoveEvent ( CUpti_EventGroup eventGroup, CUpti_EventID event )
Remove an event from an event group.
Parameters
eventGroup
The event group
event
The event to remove from the group
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_EVENT_ID

  • CUPTI_ERROR_INVALID_OPERATION

    if eventGroup is enabled

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventGroup is NULL

Description

Remove event from the an event group. The event cannot be removed if the event group is enabled.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventGroupResetAllEvents ( CUpti_EventGroup eventGroup )
Zero all the event counts in an event group.
Parameters
eventGroup
The event group
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_HARDWARE

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventGroup is NULL

Description

Zero all the event counts in an event group.

Note:

Thread-safety: this function is thread safe but client must guard against simultaneous destruction or modification of eventGroup (for example, client must guard against simultaneous calls to cuptiEventGroupDestroy, cuptiEventGroupAddEvent, etc.), and must guard against simultaneous destruction of the context in which eventGroup was created (for example, client must guard against simultaneous calls to cudaDeviceReset, cuCtxDestroy, etc.).

CUptiResult cuptiEventGroupSetAttribute ( CUpti_EventGroup eventGroup, CUpti_EventGroupAttribute attrib, size_t valueSize, void* value )
Write an event group attribute.
Parameters
eventGroup
The event group
attrib
The attribute to write
valueSize
The size, in bytes, of the value
value
The attribute value to write
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_PARAMETER

    if valueSize or value is NULL, or if attrib is not an event group attribute, or if attrib is not a writable attribute

  • CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT

    Indicates that the value buffer is too small to hold the attribute value.

Description

Write an event group attribute.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventGroupSetDisable ( CUpti_EventGroupSet* eventGroupSet )
Disable an event group set.
Parameters
eventGroupSet
The pointer to the event group set
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_HARDWARE

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventGroupSet is NULL

Description

Disable a set of event groups. Disabling a set of event groups stops collection of events contained in the groups.

Note:
  • Thread-safety: this function is thread safe.

  • If this call fails, some of the event groups in the set may be disabled and other event groups may remain enabled.

CUptiResult cuptiEventGroupSetEnable ( CUpti_EventGroupSet* eventGroupSet )
Enable an event group set.
Parameters
eventGroupSet
The pointer to the event group set
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_HARDWARE

  • CUPTI_ERROR_NOT_READY

    if eventGroup does not contain any events

  • CUPTI_ERROR_NOT_COMPATIBLE

    if eventGroup cannot be enabled due to other already enabled event groups

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventGroupSet is NULL

  • CUPTI_ERROR_HARDWARE_BUSY

    if other client is profiling and hardware is busy

Description

Enable a set of event groups. Enabling a set of event groups zeros the value of all the events in all the groups and then starts collection of those events.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiEventGroupSetsCreate ( CUcontext context, size_t eventIdArraySizeBytes, CUpti_EventID* eventIdArray, CUpti_EventGroupSets** eventGroupPasses )
For a set of events, get the grouping that indicates the number of passes and the event groups necessary to collect the events.
Parameters
context
The context for event collection
eventIdArraySizeBytes
Size of eventIdArray in bytes
eventIdArray
Array of event IDs that need to be grouped
eventGroupPasses
Returns a CUpti_EventGroupSets object that indicates the number of passes required to collect the events and the events to collect on each pass
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_CONTEXT

  • CUPTI_ERROR_INVALID_EVENT_ID

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventIdArray or eventGroupPasses is NULL

Description

The number of events that can be collected simultaneously varies by device and by the type of the events. When events can be collected simultaneously, they may need to be grouped into multiple event groups because they are from different event domains. This function takes a set of events and determines how many passes are required to collect all those events, and which events can be collected simultaneously in each pass.

The CUpti_EventGroupSets returned in eventGroupPasses indicates how many passes are required to collect the events with the numSets field. Within each event group set, the sets array indicates the event groups that should be collected on each pass.

Note:

Thread-safety: this function is thread safe, but client must guard against another thread simultaneously destroying context.

CUptiResult cuptiEventGroupSetsDestroy ( CUpti_EventGroupSets* eventGroupSets )
Destroy a CUpti_EventGroupSets object.
Parameters
eventGroupSets
The object to destroy
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_OPERATION

    if any of the event groups contained in the sets is enabled

  • CUPTI_ERROR_INVALID_PARAMETER

    if eventGroupSets is NULL

Description

Destroy a CUpti_EventGroupSets object.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiGetNumEventDomains ( uint32_t* numDomains )
Get the number of event domains available on any device.
Parameters
numDomains
Returns the number of domains
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_INVALID_PARAMETER

    if numDomains is NULL

Description

Returns the total number of event domains available on any CUDA-capable device.

Note:

Thread-safety: this function is thread safe.

CUptiResult cuptiKernelReplaySubscribeUpdate ( CUpti_KernelReplayUpdateFunc updateFunc, void* customData )
Subscribe to kernel replay updates.
Parameters
updateFunc
The update function pointer
customData
Pointer to any custom data
Returns

  • CUPTI_SUCCESS

Description

When subscribed, the function pointer passed in will be called each time a kernel run is finished during kernel replay. Previously subscribed function pointer will be replaced. Pass in NULL as the function pointer unsubscribes the update.

CUptiResult cuptiSetEventCollectionMode ( CUcontext context, CUpti_EventCollectionMode mode )
Set the event collection mode.
Parameters
context
The context
mode
The event collection mode
Returns

  • CUPTI_SUCCESS

  • CUPTI_ERROR_NOT_INITIALIZED

  • CUPTI_ERROR_INVALID_CONTEXT

  • CUPTI_ERROR_INVALID_OPERATION

    if called when replay mode is enabled

  • CUPTI_ERROR_NOT_SUPPORTED

    if mode is not supported on the device

Description

Set the event collection mode for a context. The mode controls the event collection behavior of all events in event groups created in the context. This API is invalid in kernel replay mode.

Note:

Thread-safety: this function is thread safe.