CUPTI :: CUDA Toolkit Documentation

< Previous | Next >

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

2.3. CUPTI Activity API

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

Classes

struct CUpti_Activity: The base activity record.
struct CUpti_ActivityAPI: The activity record for a driver or runtime API invocation.
struct CUpti_ActivityBranch: The activity record for source level result branch.
struct CUpti_ActivityCdpKernel: The activity record for CDP (CUDA Dynamic Parallelism) kernel.
struct CUpti_ActivityContext: The activity record for a context.
struct CUpti_ActivityDevice: The activity record for a device.
struct CUpti_ActivityEnvironment: The activity record for CUPTI environmental data.
struct CUpti_ActivityEvent: The activity record for a CUPTI event.
struct CUpti_ActivityEventInstance: The activity record for a CUPTI event with instance information.
struct CUpti_ActivityGlobalAccess: The activity record for source-level global access.
struct CUpti_ActivityKernel: The activity record for kernel. (deprecated).
struct CUpti_ActivityKernel2: The activity record for a kernel (CUDA 5.5 onwards).
struct CUpti_ActivityMarker: The activity record providing a marker which is an instantaneous point in time.
struct CUpti_ActivityMarkerData: The activity record providing detailed information for a marker.
struct CUpti_ActivityMemcpy: The activity record for memory copies.
struct CUpti_ActivityMemcpy2: The activity record for peer-to-peer memory copies.
struct CUpti_ActivityMemset: The activity record for memset.
struct CUpti_ActivityMetric: The activity record for a CUPTI metric.
struct CUpti_ActivityMetricInstance: The activity record for a CUPTI metric with instance information. This activity record represents a CUPTI metric value for a specific metric domain instance (CUPTI_ACTIVITY_KIND_METRIC_INSTANCE). This activity record kind is not produced by the activity API but is included for completeness and ease-of-use. Profile frameworks built on top of CUPTI that collect metric data may choose to use this type to store the collected metric data. This activity record should be used when metric domain instance information needs to be associated with the metric.
struct CUpti_ActivityName: The activity record providing a name.
union CUpti_ActivityObjectKindId: Identifiers for object kinds as specified by CUpti_ActivityObjectKind.
struct CUpti_ActivityOverhead: The activity record for CUPTI and driver overheads.
struct CUpti_ActivityPreemption: The activity record for a preemption of a CDP kernel.
struct CUpti_ActivitySourceLocator: The activity record for source locator.

Defines

#define CUPTI_CORRELATION_ID_UNKNOWN 0
#define CUPTI_GRID_ID_UNKNOWN 0LL
#define CUPTI_SOURCE_LOCATOR_ID_UNKNOWN 0
#define CUPTI_TIMESTAMP_UNKNOWN 0LL

Typedefs

typedef void ( *CUpti_BuffersCallbackCompleteFunc )( CUcontext context, uint32_t streamId, uint8_t* buffer, size_t size, size_t validSize ): Function type for callback used by CUPTI to return a buffer of activity records.
typedef void ( *CUpti_BuffersCallbackRequestFunc )( uint8_t* *buffer, size_t* size, size_t* maxNumRecords ): Function type for callback used by CUPTI to request an empty buffer for storing activity records.

Enumerations

enum CUpti_ActivityAttribute: Activity attributes.
enum CUpti_ActivityComputeApiKind: The kind of a compute API.
enum CUpti_ActivityEnvironmentKind: The kind of environment data. Used to indicate what type of data is being reported by an environment activity record.
enum CUpti_ActivityFlag: Flags associated with activity records.
enum CUpti_ActivityKind: The kinds of activity records.
enum CUpti_ActivityMemcpyKind: The kind of a memory copy, indicating the source and destination targets of the copy.
enum CUpti_ActivityMemoryKind: The kinds of memory accessed by a memory copy.
enum CUpti_ActivityObjectKind: The kinds of activity objects.
enum CUpti_ActivityOverheadKind: The kinds of activity overhead.
enum CUpti_ActivityPreemptionKind: The kind of a preemption activity.
enum CUpti_EnvironmentClocksThrottleReason: Reasons for clock throttling.

Functions

CUptiResult cuptiActivityDequeueBuffer ( CUcontext context, uint32_t streamId, uint8_t** buffer, size_t* validBufferSizeBytes ): Dequeue a buffer containing activity records.
CUptiResult cuptiActivityDisable ( CUpti_ActivityKind kind ): Disable collection of a specific kind of activity record.
CUptiResult cuptiActivityDisableContext ( CUcontext context, CUpti_ActivityKind kind ): Disable collection of a specific kind of activity record for a context.
CUptiResult cuptiActivityEnable ( CUpti_ActivityKind kind ): Enable collection of a specific kind of activity record.
CUptiResult cuptiActivityEnableContext ( CUcontext context, CUpti_ActivityKind kind ): Enable collection of a specific kind of activity record for a context.
CUptiResult cuptiActivityEnqueueBuffer ( CUcontext context, uint32_t streamId, uint8_t* buffer, size_t bufferSizeBytes ): Queue a buffer for activity record collection.
CUptiResult cuptiActivityFlush ( CUcontext context, uint32_t streamId, uint32_t flag ): Wait for all activity records are delivered via the completion callback.
CUptiResult cuptiActivityFlushAll ( uint32_t flag ): Wait for all activity records are delivered via the completion callback.
CUptiResult cuptiActivityGetAttribute ( CUpti_ActivityAttribute attr, size_t* valueSize, void* value ): Read an activity API attribute.
CUptiResult cuptiActivityGetNextRecord ( uint8_t* buffer, size_t validBufferSizeBytes, CUpti_Activity** record ): Iterate over the activity records in a buffer.
CUptiResult cuptiActivityGetNumDroppedRecords ( CUcontext context, uint32_t streamId, size_t* dropped ): Get the number of activity records that were dropped of insufficient buffer space.
CUptiResult cuptiActivityQueryBuffer ( CUcontext context, uint32_t streamId, size_t* validBufferSizeBytes ): Query the status of the buffer at the head of a queue.
CUptiResult cuptiActivityRegisterCallbacks ( CUpti_BuffersCallbackRequestFunc funcBufferRequested, CUpti_BuffersCallbackCompleteFunc funcBufferCompleted ): Registers callback functions with CUPTI for activity buffer handling.
CUptiResult cuptiActivitySetAttribute ( CUpti_ActivityAttribute attr, size_t* valueSize, void* value ): Write an activity API attribute.
CUptiResult cuptiGetDeviceId ( CUcontext context, uint32_t* deviceId ): Get the ID of a device.
CUptiResult cuptiGetStreamId ( CUcontext context, CUstream stream, uint32_t* streamId ): Get the ID of a stream.
CUptiResult cuptiGetTimestamp ( uint64_t* timestamp ): Get the CUPTI timestamp.

Defines

#define CUPTI_CORRELATION_ID_UNKNOWN 0: An invalid/unknown correlation ID. A correlation ID of this value indicates that there is no correlation for the activity record.
#define CUPTI_GRID_ID_UNKNOWN 0LL: An invalid/unknown grid ID.
#define CUPTI_SOURCE_LOCATOR_ID_UNKNOWN 0: The source-locator ID that indicates an unknown source location. There is not an actual CUpti_ActivitySourceLocator object corresponding to this value.
#define CUPTI_TIMESTAMP_UNKNOWN 0LL: An invalid/unknown timestamp for a start, end, queued, submitted, or completed time.

Typedefs

void ( *CUpti_BuffersCallbackCompleteFunc )( CUcontext context, uint32_t streamId, uint8_t* buffer, size_t size, size_t validSize ): Function type for callback used by CUPTI to return a buffer of activity records. This callback function returns to the CUPTI client a buffer containing activity records. The buffer contains validSize bytes of activity records which should be read using cuptiActivityGetNextRecord. The number of dropped records can be read using cuptiActivityGetNumDroppedRecords. After this call CUPTI relinquished ownership of the buffer and will not use it anymore. The client may return the buffer to CUPTI using the CUpti_BuffersCallbackRequestFunc callback.
void ( *CUpti_BuffersCallbackRequestFunc )( uint8_t* *buffer, size_t* size, size_t* maxNumRecords ): Function type for callback used by CUPTI to request an empty buffer for storing activity records. This callback function signals the CUPTI client that an activity buffer is needed by CUPTI. The activity buffer is used by CUPTI to store activity records. The callback function can decline the request by setting *buffer to NULL. In this case CUPTI may drop activity records.

Enumerations

enum CUpti_ActivityAttribute

These attributes are used to control the behavior of the activity API.

Values

CUPTI_ACTIVITY_ATTR_DEVICE_BUFFER_SIZE = 0: The device memory reserved for storing profiling data for non-CDP operations for each stream. The value is a size_t.Larger buffers require less flush operations but consume more device memory. Small buffers might increase the risk of missing timestamps for concurrent kernel records in the asynchronous buffer handling mode if too many kernels are launched/replayed between context synchronizations. This value only applies to new allocations.Set this value before initializing CUDA or before creating a stream to ensure it is considered for the following allocations.Note: The actual amount of device memory per stream reserved by CUPTI might be larger.
CUPTI_ACTIVITY_ATTR_DEVICE_BUFFER_SIZE_CDP = 1: The device memory reserved for storing profiling data for CDP operations for each stream. The value is a size_t.Larger buffers require less flush operations but consume more device memory. This value only applies to new allocations.Set this value before initializing CUDA or before creating a stream to ensure it is considered for the following allocations.Note: The actual amount of device memory per stream reserved by CUPTI might be larger.
CUPTI_ACTIVITY_ATTR_DEVICE_BUFFER_POOL_LIMIT = 2: The maximum number of device memory buffers stored for reuse by CUPTI. The value is a size_t.Buffers can be reused by streams of the same context. Increasing this value reduces the profiling overhead when the application creates and destroys many streams. Setting this value will not modify the number of memory buffers currently stored.Set this value before initializing CUDA to ensure the limit is not exceeded.

enum CUpti_ActivityComputeApiKind

Values

CUPTI_ACTIVITY_COMPUTE_API_UNKNOWN = 0: The compute API is not known.
CUPTI_ACTIVITY_COMPUTE_API_CUDA = 1: The compute APIs are for CUDA.
CUPTI_ACTIVITY_COMPUTE_API_FORCE_INT = 0x7fffffff

enum CUpti_ActivityEnvironmentKind

Values

CUPTI_ACTIVITY_ENVIRONMENT_UNKNOWN = 0: Unknown data.
CUPTI_ACTIVITY_ENVIRONMENT_SPEED = 1: The environment data is related to speed.
CUPTI_ACTIVITY_ENVIRONMENT_TEMPERATURE = 2: The environment data is related to temperature.
CUPTI_ACTIVITY_ENVIRONMENT_POWER = 3: The environment data is related to power.
CUPTI_ACTIVITY_ENVIRONMENT_COOLING = 4: The environment data is related to cooling.
CUPTI_ACTIVITY_ENVIRONMENT_COUNT
CUPTI_ACTIVITY_ENVIRONMENT_KIND_FORCE_INT = 0x7fffffff

enum CUpti_ActivityFlag

Activity record flags. Flags can be combined by bitwise OR to associated multiple flags with an activity record. Each flag is specific to a certain activity kind, as noted below.

Values

CUPTI_ACTIVITY_FLAG_NONE = 0: Indicates the activity record has no flags.
CUPTI_ACTIVITY_FLAG_DEVICE_CONCURRENT_KERNELS = 1<<0: Indicates the activity represents a device that supports concurrent kernel execution. Valid for CUPTI_ACTIVITY_KIND_DEVICE.
CUPTI_ACTIVITY_FLAG_MEMCPY_ASYNC = 1<<0: Indicates the activity represents an asynchronous memcpy operation. Valid for CUPTI_ACTIVITY_KIND_MEMCPY.
CUPTI_ACTIVITY_FLAG_MARKER_INSTANTANEOUS = 1<<0: Indicates the activity represents an instantaneous marker. Valid for CUPTI_ACTIVITY_KIND_MARKER.
CUPTI_ACTIVITY_FLAG_MARKER_START = 1<<1: Indicates the activity represents a region start marker. Valid for CUPTI_ACTIVITY_KIND_MARKER.
CUPTI_ACTIVITY_FLAG_MARKER_END = 1<<2: Indicates the activity represents a region end marker. Valid for CUPTI_ACTIVITY_KIND_MARKER.
CUPTI_ACTIVITY_FLAG_MARKER_COLOR_NONE = 1<<0: Indicates the activity represents a marker that does not specify a color. Valid for CUPTI_ACTIVITY_KIND_MARKER_DATA.
CUPTI_ACTIVITY_FLAG_MARKER_COLOR_ARGB = 1<<1: Indicates the activity represents a marker that specifies a color in alpha-red-green-blue format. Valid for CUPTI_ACTIVITY_KIND_MARKER_DATA.
CUPTI_ACTIVITY_FLAG_GLOBAL_ACCESS_KIND_SIZE_MASK = 0xFF<<0: The number of bytes requested by each thread Valid for CUpti_ActivityGlobalAccess.
CUPTI_ACTIVITY_FLAG_GLOBAL_ACCESS_KIND_LOAD = 1<<8: If bit in this flag is set, the access was load, else it is a store access. Valid for CUpti_ActivityGlobalAccess.
CUPTI_ACTIVITY_FLAG_GLOBAL_ACCESS_KIND_CACHED = 1<<9: If this bit in flag is set, the load access was cached else it is uncached. Valid for CUpti_ActivityGlobalAccess.
CUPTI_ACTIVITY_FLAG_METRIC_OVERFLOWED = 1<<0: If this bit in flag is set, the metric value overflowed. Valid for CUpti_ActivityMetric.
CUPTI_ACTIVITY_FLAG_METRIC_VALUE_INVALID = 1<<1: If this bit in flag is set, the metric value couldn't be calculated. This occurs when a value(s) required to calculate the metric is missing. Valid for CUpti_ActivityMetric.
CUPTI_ACTIVITY_FLAG_FORCE_INT = 0x7fffffff

enum CUpti_ActivityKind

Each activity record kind represents information about a GPU or an activity occurring on a CPU or GPU. Each kind is associated with a activity record structure that holds the information associated with the kind.

See also:

CUpti_Activity

CUpti_ActivityAPI

CUpti_ActivityContext

CUpti_ActivityDevice

CUpti_ActivityEvent

CUpti_ActivityEventInstance

CUpti_ActivityKernel

CUpti_ActivityKernel2

CUpti_ActivityCdpKernel

CUpti_ActivityPreemption

CUpti_ActivityMemcpy

CUpti_ActivityMemcpy2

CUpti_ActivityMemset

CUpti_ActivityMetric

CUpti_ActivityMetricInstance

CUpti_ActivityName

CUpti_ActivityMarker

CUpti_ActivityMarkerData

CUpti_ActivitySourceLocator

CUpti_ActivityGlobalAccess

CUpti_ActivityBranch

CUpti_ActivityOverhead

CUpti_ActivityEnvironment

Values

CUPTI_ACTIVITY_KIND_INVALID = 0: The activity record is invalid.
CUPTI_ACTIVITY_KIND_MEMCPY = 1: A host<->host, host<->device, or device<->device memory copy. The corresponding activity record structure is CUpti_ActivityMemcpy.
CUPTI_ACTIVITY_KIND_MEMSET = 2: A memory set executing on the GPU. The corresponding activity record structure is CUpti_ActivityMemset.
CUPTI_ACTIVITY_KIND_KERNEL = 3: A kernel executing on the GPU. The corresponding activity record structure is CUpti_ActivityKernel2.
CUPTI_ACTIVITY_KIND_DRIVER = 4: A CUDA driver API function execution. The corresponding activity record structure is CUpti_ActivityAPI.
CUPTI_ACTIVITY_KIND_RUNTIME = 5: A CUDA runtime API function execution. The corresponding activity record structure is CUpti_ActivityAPI.
CUPTI_ACTIVITY_KIND_EVENT = 6: An event value. The corresponding activity record structure is CUpti_ActivityEvent.
CUPTI_ACTIVITY_KIND_METRIC = 7: A metric value. The corresponding activity record structure is CUpti_ActivityMetric.
CUPTI_ACTIVITY_KIND_DEVICE = 8: Information about a device. The corresponding activity record structure is CUpti_ActivityDevice.
CUPTI_ACTIVITY_KIND_CONTEXT = 9: Information about a context. The corresponding activity record structure is CUpti_ActivityContext.
CUPTI_ACTIVITY_KIND_CONCURRENT_KERNEL = 10: A (potentially concurrent) kernel executing on the GPU. The corresponding activity record structure is CUpti_ActivityKernel2.
CUPTI_ACTIVITY_KIND_NAME = 11: Thread, device, context, etc. name. The corresponding activity record structure is CUpti_ActivityName.
CUPTI_ACTIVITY_KIND_MARKER = 12: Instantaneous, start, or end marker.
CUPTI_ACTIVITY_KIND_MARKER_DATA = 13: Extended, optional, data about a marker.
CUPTI_ACTIVITY_KIND_SOURCE_LOCATOR = 14: Source information about source level result. The corresponding activity record structure is CUpti_ActivitySourceLocator.
CUPTI_ACTIVITY_KIND_GLOBAL_ACCESS = 15: Results for source-level global acccess. The corresponding activity record structure is CUpti_ActivityGlobalAccess.
CUPTI_ACTIVITY_KIND_BRANCH = 16: Results for source-level branch. The corresponding activity record structure is CUpti_ActivityBranch.
CUPTI_ACTIVITY_KIND_OVERHEAD = 17: Overhead activity records. The corresponding activity record structure is CUpti_ActivityOverhead.
CUPTI_ACTIVITY_KIND_CDP_KERNEL = 18: A CDP (CUDA Dynamic Parallel) kernel executing on the GPU. The corresponding activity record structure is CUpti_ActivityCdpKernel. This activity can not be directly enabled or disabled. It is enabled and disabled through concurrent kernel activity CUPTI_ACTIVITY_KIND_CONCURRENT_KERNEL
CUPTI_ACTIVITY_KIND_PREEMPTION = 19: Preemption activity record indicating a preemption of a CDP (CUDA Dynamic Parallel) kernel executing on the GPU. The corresponding activity record structure is CUpti_ActivityPreemption.
CUPTI_ACTIVITY_KIND_ENVIRONMENT = 20: Environment activity records indicating power, clock, thermal, etc. levels of the GPU. The corresponding activity record structure is CUpti_ActivityEnvironment.
CUPTI_ACTIVITY_KIND_EVENT_INSTANCE = 21: An event value associated with a specific event domain instance. The corresponding activity record structure is CUpti_ActivityEventInstance.
CUPTI_ACTIVITY_KIND_MEMCPY2 = 22: A peer to peer memory copy. The corresponding activity record structure is CUpti_ActivityMemcpy2.
CUPTI_ACTIVITY_KIND_METRIC_INSTANCE = 23: A metric value associated with a specific metric domain instance. The corresponding activity record structure is CUpti_ActivityMetricInstance.
CUPTI_ACTIVITY_KIND_FORCE_INT = 0x7fffffff

enum CUpti_ActivityMemcpyKind

Each kind represents the source and destination targets of a memory copy. Targets are host, device, and array.

Values

CUPTI_ACTIVITY_MEMCPY_KIND_UNKNOWN = 0: The memory copy kind is not known.
CUPTI_ACTIVITY_MEMCPY_KIND_HTOD = 1: A host to device memory copy.
CUPTI_ACTIVITY_MEMCPY_KIND_DTOH = 2: A device to host memory copy.
CUPTI_ACTIVITY_MEMCPY_KIND_HTOA = 3: A host to device array memory copy.
CUPTI_ACTIVITY_MEMCPY_KIND_ATOH = 4: A device array to host memory copy.
CUPTI_ACTIVITY_MEMCPY_KIND_ATOA = 5: A device array to device array memory copy.
CUPTI_ACTIVITY_MEMCPY_KIND_ATOD = 6: A device array to device memory copy.
CUPTI_ACTIVITY_MEMCPY_KIND_DTOA = 7: A device to device array memory copy.
CUPTI_ACTIVITY_MEMCPY_KIND_DTOD = 8: A device to device memory copy.
CUPTI_ACTIVITY_MEMCPY_KIND_HTOH = 9: A host to host memory copy.
CUPTI_ACTIVITY_MEMCPY_KIND_PTOP = 10: A peer to peer memory copy.
CUPTI_ACTIVITY_MEMCPY_KIND_FORCE_INT = 0x7fffffff

enum CUpti_ActivityMemoryKind

Each kind represents the type of the source or destination memory accessed by a memory copy.

Values

CUPTI_ACTIVITY_MEMORY_KIND_UNKNOWN = 0: The source or destination memory kind is unknown.
CUPTI_ACTIVITY_MEMORY_KIND_PAGEABLE = 1: The source or destination memory is pageable.
CUPTI_ACTIVITY_MEMORY_KIND_PINNED = 2: The source or destination memory is pinned.
CUPTI_ACTIVITY_MEMORY_KIND_DEVICE = 3: The source or destination memory is on the device.
CUPTI_ACTIVITY_MEMORY_KIND_ARRAY = 4: The source or destination memory is an array.
CUPTI_ACTIVITY_MEMORY_KIND_FORCE_INT = 0x7fffffff

enum CUpti_ActivityObjectKind

See also:

CUpti_ActivityObjectKindId

Values

CUPTI_ACTIVITY_OBJECT_UNKNOWN = 0: The object kind is not known.
CUPTI_ACTIVITY_OBJECT_PROCESS = 1: A process.
CUPTI_ACTIVITY_OBJECT_THREAD = 2: A thread.
CUPTI_ACTIVITY_OBJECT_DEVICE = 3: A device.
CUPTI_ACTIVITY_OBJECT_CONTEXT = 4: A context.
CUPTI_ACTIVITY_OBJECT_STREAM = 5: A stream.
CUPTI_ACTIVITY_OBJECT_FORCE_INT = 0x7fffffff

enum CUpti_ActivityOverheadKind

Values

CUPTI_ACTIVITY_OVERHEAD_UNKNOWN = 0: The overhead kind is not known.
CUPTI_ACTIVITY_OVERHEAD_DRIVER_COMPILER = 1: Compiler(JIT) overhead.
CUPTI_ACTIVITY_OVERHEAD_CUPTI_BUFFER_FLUSH = 1<<16: Activity buffer flush overhead.
CUPTI_ACTIVITY_OVERHEAD_CUPTI_INSTRUMENTATION = 2<<16: CUPTI instrumentation overhead.
CUPTI_ACTIVITY_OVERHEAD_CUPTI_RESOURCE = 3<<16: CUPTI resource creation and destruction overhead.
CUPTI_ACTIVITY_OVERHEAD_FORCE_INT = 0x7fffffff

enum CUpti_ActivityPreemptionKind

Values

CUPTI_ACTIVITY_PREEMPTION_KIND_UNKNOWN = 0: The preemption kind is not known.
CUPTI_ACTIVITY_PREEMPTION_KIND_SAVE = 1: Preemption to save CDP block.
CUPTI_ACTIVITY_PREEMPTION_KIND_RESTORE = 2: Preemption to restore CDP block.
CUPTI_ACTIVITY_PREEMPTION_KIND_FORCE_INT = 0x7fffffff

enum CUpti_EnvironmentClocksThrottleReason

The possible reasons that a clock can be throttled. There can be more than one reason that a clock is being throttled so these types can be combined by bitwise OR. These are used in the clocksThrottleReason field in the Environment Activity Record.

Values

CUPTI_CLOCKS_THROTTLE_REASON_GPU_IDLE = 0x00000001: Nothing is running on the GPU and the clocks are dropping to idle state.
CUPTI_CLOCKS_THROTTLE_REASON_USER_DEFINED_CLOCKS = 0x00000002: The GPU clocks are limited by a user specified limit.
CUPTI_CLOCKS_THROTTLE_REASON_SW_POWER_CAP = 0x00000004: A software power scaling algorithm is reducing the clocks below requested clocks.
CUPTI_CLOCKS_THROTTLE_REASON_HW_SLOWDOWN = 0x00000008: Hardware slowdown to reduce the clock by a factor of two or more is engaged. This is an indicator of one of the following: 1) Temperature is too high, 2) External power brake assertion is being triggered (e.g. by the system power supply), 3) Change in power state.
CUPTI_CLOCKS_THROTTLE_REASON_UNKNOWN = 0x80000000: Some unspecified factor is reducing the clocks.
CUPTI_CLOCKS_THROTTLE_REASON_UNSUPPORTED = 0x40000000: Throttle reason is not supported for this GPU.
CUPTI_CLOCKS_THROTTLE_REASON_NONE = 0x00000000: No clock throttling.
CUPTI_CLOCKS_THROTTLE_REASON_FORCE_INT = 0x7fffffff

Functions

CUptiResult cuptiActivityDequeueBuffer ( CUcontext context, uint32_t streamId, uint8_t** buffer, size_t* validBufferSizeBytes )

Dequeue a buffer containing activity records.

Parameters

context: The context, or NULL to dequeue from the global queue
streamId: The stream ID
buffer: Returns the dequeued buffer
validBufferSizeBytes: Returns the number of bytes in the buffer that contain activity records

Returns

CUPTI_SUCCESS
CUPTI_ERROR_NOT_INITIALIZED
CUPTI_ERROR_INVALID_OPERATION
if preceeded by a successful call to cuptiActivityRegisterCallbacks
CUPTI_ERROR_INVALID_PARAMETER
if buffer or validBufferSizeBytes are NULL
CUPTI_ERROR_QUEUE_EMPTY
the queue is empty, buffer returns NULL and validBufferSizeBytes returns 0

Description

Remove the buffer from the head of the specified queue. See cuptiActivityEnqueueBuffer() for description of queues. Calling this function transfers ownership of the buffer from CUPTI. CUPTI will no add any activity records to the buffer after it is dequeued.

**DEPRECATED** This method is deprecated and will be removed in a future release. The new asynchronous API implemented by cuptiActivityRegisterCallbacks(), cuptiActivityFlush(), and cuptiActivityFlushAll() should be adopted.

CUptiResult cuptiActivityDisable ( CUpti_ActivityKind kind )

Disable collection of a specific kind of activity record.

Parameters

kind: The kind of activity record to stop collecting

Returns

CUPTI_SUCCESS
CUPTI_ERROR_NOT_INITIALIZED
CUPTI_ERROR_INVALID_KIND
if the activity kind is not supported

Description

Disable collection of a specific kind of activity record. Multiple kinds can be disabled by calling this function multiple times. By default all activity kinds are disabled for collection.

CUptiResult cuptiActivityDisableContext ( CUcontext context, CUpti_ActivityKind kind )

Disable collection of a specific kind of activity record for a context.

Parameters

context: The context for which activity is to be disabled
kind: The kind of activity record to stop collecting

Returns

CUPTI_SUCCESS
CUPTI_ERROR_NOT_INITIALIZED
CUPTI_ERROR_INVALID_KIND
if the activity kind is not supported

Description

Disable collection of a specific kind of activity record for a context. This setting done by this API will supersede the global settings for activity records. Multiple kinds can be enabled by calling this function multiple times.

CUptiResult cuptiActivityEnable ( CUpti_ActivityKind kind )

Enable collection of a specific kind of activity record.

Parameters

kind: The kind of activity record to collect

Returns

CUPTI_SUCCESS
CUPTI_ERROR_NOT_INITIALIZED
CUPTI_ERROR_NOT_COMPATIBLE
if the activity kind cannot be enabled
CUPTI_ERROR_INVALID_KIND
if the activity kind is not supported

Description

Enable collection of a specific kind of activity record. Multiple kinds can be enabled by calling this function multiple times. By default all activity kinds are disabled for collection.

CUptiResult cuptiActivityEnableContext ( CUcontext context, CUpti_ActivityKind kind )

Enable collection of a specific kind of activity record for a context.

Parameters

context: The context for which activity is to be enabled
kind: The kind of activity record to collect

Returns

CUPTI_SUCCESS
CUPTI_ERROR_NOT_INITIALIZED
CUPTI_ERROR_NOT_COMPATIBLE
if the activity kind cannot be enabled
CUPTI_ERROR_INVALID_KIND
if the activity kind is not supported

Description

Enable collection of a specific kind of activity record for a context. This setting done by this API will supersede the global settings for activity records enabled by cuptiActivityEnable. Multiple kinds can be enabled by calling this function multiple times.

CUptiResult cuptiActivityEnqueueBuffer ( CUcontext context, uint32_t streamId, uint8_t* buffer, size_t bufferSizeBytes )

Queue a buffer for activity record collection.

Parameters

context: The context, or NULL to enqueue on the global queue
streamId: The stream ID
buffer: The pointer to user supplied buffer for storing activity records.The buffer must be at least 8 byte aligned, and the size of the buffer must be at least 1024 bytes.
bufferSizeBytes: The size of the buffer, in bytes. The size of the buffer must be at least 1024 bytes.

Returns

CUPTI_SUCCESS
CUPTI_ERROR_NOT_INITIALIZED
CUPTI_ERROR_INVALID_OPERATION
if preceeded by a successful call to cuptiActivityRegisterCallbacks
CUPTI_ERROR_INVALID_PARAMETER
if buffer is NULL, does not have alignment of at least 8 bytes, or is not at least 1024 bytes in size

Description

Queue a buffer for activity record collection. Calling this function transfers ownership of the buffer to CUPTI. The buffer should not be accessed or modified until ownership is regained by calling cuptiActivityDequeueBuffer().

There are three types of queues:

Global Queue: The global queue collects all activity records that are not associated with a valid context. All device and API activity records are collected in the global queue. A buffer is enqueued in the global queue by specifying context == NULL.

Context Queue: Each context queue collects activity records associated with that context that are not associated with a specific stream or that are associated with the default stream. A buffer is enqueued in a context queue by specifying the context and a streamId of 0.

Stream Queue: Each stream queue collects memcpy, memset, and kernel activity records associated with the stream. A buffer is enqueued in a stream queue by specifying a context and a non-zero stream ID.

Multiple buffers can be enqueued on each queue, and buffers can be enqueue on multiple queues.

When a new activity record needs to be recorded, CUPTI searches for a non-empty queue to hold the record in this order: 1) the appropriate stream queue, 2) the appropriate context queue. If the search does not find any queue with a buffer then the activity record is dropped. If the search finds a queue containing a buffer, but that buffer is full, then the activity record is dropped and the dropped record count for the queue is incremented. If the search finds a queue containing a buffer with space available to hold the record, then the record is recorded in the buffer.

At a minimum, one or more buffers must be queued in the global queue and context queue at all times to avoid dropping activity records. Global queue will not store any activity records for gpu activity(kernel, memcpy, memset). It is also necessary to enqueue at least one buffer in the context queue of each context as it is created. The stream queues are optional and can be used to reduce or eliminate application perturbations caused by the need to process or save the activity records returned in the buffers. For example, if a stream queue is used, that queue can be flushed when the stream is synchronized.

CUptiResult cuptiActivityFlush ( CUcontext context, uint32_t streamId, uint32_t flag )

Wait for all activity records are delivered via the completion callback.

Parameters

context: A valid CUcontext or NULL.
streamId: The stream ID.
flag: Reserved, must be 0.

Returns

CUPTI_SUCCESS
CUPTI_ERROR_NOT_INITIALIZED
CUPTI_ERROR_CUPTI_ERROR_INVALID_OPERATION
if not preceeded by a successful call to cuptiActivityRegisterCallbacks
CUPTI_ERROR_UNKNOWN
an internal error occurred

Description

This function does not return until all activity records associated with the specified context/stream are returned to the CUPTI client using the callback registered in cuptiActivityRegisterCallbacks. To ensure that all activity records are complete, the requested stream(s), if any, are synchronized.

If context is NULL, the global activity records (i.e. those not associated with a particular stream) are flushed (in this case no streams are synchonized). If context is a valid CUcontext and streamId is 0, the buffers of all streams of this context are flushed. Otherwise, the buffers of the specified stream in this context is flushed.

Before calling this function, the buffer handling callback api must be activated by calling cuptiActivityRegisterCallbacks.

CUptiResult cuptiActivityFlushAll ( uint32_t flag )

Wait for all activity records are delivered via the completion callback.

Parameters

flag: Reserved, must be 0.

Returns

CUPTI_SUCCESS
CUPTI_ERROR_NOT_INITIALIZED
CUPTI_ERROR_INVALID_OPERATION
if not preceeded by a successful call to cuptiActivityRegisterCallbacks
CUPTI_ERROR_UNKNOWN
an internal error occurred

Description

This function does not return until all activity records associated with all contexts/streams (and the global buffers not associated with any stream) are returned to the CUPTI client using the callback registered in cuptiActivityRegisterCallbacks. To ensure that all activity records are complete, the requested stream(s), if any, are synchronized.

Before calling this function, the buffer handling callback api must be activated by calling cuptiActivityRegisterCallbacks.

CUptiResult cuptiActivityGetAttribute ( CUpti_ActivityAttribute attr, size_t* valueSize, void* value )

Read an activity API attribute.

Parameters

attr: 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 attr is not an activity attribute
CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT
Indicates that the value buffer is too small to hold the attribute value.

Description

Read an activity API attribute and return it in *value.

CUptiResult cuptiActivityGetNextRecord ( uint8_t* buffer, size_t validBufferSizeBytes, CUpti_Activity** record )

Iterate over the activity records in a buffer.

Parameters

buffer: The buffer containing activity records
validBufferSizeBytes: The number of valid bytes in the buffer.
record: Inputs the previous record returned by cuptiActivityGetNextRecord and returns the next activity record from the buffer. If input value is NULL, returns the first activity record in the buffer. Records of kind CUPTI_ACTIVITY_KIND_CONCURRENT_KERNEL may contain invalid (0) timestamps, indicating that no timing information could be collected for lack of device memory.

Returns

CUPTI_SUCCESS
CUPTI_ERROR_NOT_INITIALIZED
CUPTI_ERROR_MAX_LIMIT_REACHED
if no more records in the buffer
CUPTI_ERROR_INVALID_PARAMETER
if buffer is NULL.

Description

This is a helper function to iterate over the activity records in a buffer. A buffer of activity records is typically obtained by using the cuptiActivityDequeueBuffer() function or by receiving a CUpti_BuffersCallbackCompleteFunc callback.

An example of typical usage:

‎ CUpti_Activity *record = NULL;
       CUptiResult status = CUPTI_SUCCESS;
         do {
            status = cuptiActivityGetNextRecord(buffer, validSize, &record);
            if(status == CUPTI_SUCCESS) {
                 // Use record here...
            }
            else if (status == CUPTI_ERROR_MAX_LIMIT_REACHED)
                break;
            else {
                goto Error;
            }
          } while (1);

CUptiResult cuptiActivityGetNumDroppedRecords ( CUcontext context, uint32_t streamId, size_t* dropped )

Get the number of activity records that were dropped of insufficient buffer space.

Parameters

context: The context, or NULL to get dropped count from global queue
streamId: The stream ID
dropped: The number of records that were dropped since the last call to this function.

Returns

CUPTI_SUCCESS
CUPTI_ERROR_NOT_INITIALIZED
CUPTI_ERROR_INVALID_PARAMETER
if dropped is NULL

Description

Get the number of records that were dropped because of insufficient buffer space. The dropped count includes records that could not be recorded because CUPTI did not have activity buffer space available for the record (because the CUpti_BuffersCallbackRequestFunc callback did not return an empty buffer of sufficient size) and also CDP records that could not be record because the device-size buffer was full (size is controlled by the CUPTI_ACTIVITY_ATTR_DEVICE_BUFFER_SIZE_CDP attribute). The dropped count maintained for the queue is reset to zero when this function is called.

CUptiResult cuptiActivityQueryBuffer ( CUcontext context, uint32_t streamId, size_t* validBufferSizeBytes )

Query the status of the buffer at the head of a queue.

Parameters

context: The context, or NULL to query the global queue
streamId: The stream ID
validBufferSizeBytes: Returns the number of bytes in the buffer that contain activity records

Returns

CUPTI_SUCCESS
CUPTI_ERROR_NOT_INITIALIZED
CUPTI_ERROR_INVALID_PARAMETER
if buffer or validBufferSizeBytes are NULL
CUPTI_ERROR_MAX_LIMIT_REACHED
if buffer is full
CUPTI_ERROR_QUEUE_EMPTY
the queue is empty, validBufferSizeBytes returns 0

Description

Query the status of buffer at the head in the queue. See cuptiActivityEnqueueBuffer() for description of queues. Calling this function does not transfer ownership of the buffer.

CUptiResult cuptiActivityRegisterCallbacks ( CUpti_BuffersCallbackRequestFunc funcBufferRequested, CUpti_BuffersCallbackCompleteFunc funcBufferCompleted )

Registers callback functions with CUPTI for activity buffer handling.

Parameters

funcBufferRequested: callback which is invoked when an empty buffer is requested by CUPTI
funcBufferCompleted: callback which is invoked when a buffer containing activity records is available from CUPTI

Returns

CUPTI_SUCCESS
CUPTI_ERROR_INVALID_PARAMETER
if either funcBufferRequested or funcBufferCompleted is NULL

Description

This function registers two callback functions to be used in asynchronous buffer handling. If registered, activity record buffers are handled using asynchronous requested/completed callbacks from CUPTI.

Registering these callbacks prevents the client from using CUPTI's blocking enqueue/dequeue functions.

CUptiResult cuptiActivitySetAttribute ( CUpti_ActivityAttribute attr, size_t* valueSize, void* value )

Write an activity API attribute.

Parameters

attr: 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 attr is not an activity attribute
CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT
Indicates that the value buffer is too small to hold the attribute value.

Description

Write an activity API attribute.

CUptiResult cuptiGetDeviceId ( CUcontext context, uint32_t* deviceId )

Get the ID of a device.

Parameters

context: The context, or NULL to indicate the current context.
deviceId: Returns the ID of the device that is current for the calling thread.

Returns

CUPTI_SUCCESS
CUPTI_ERROR_NOT_INITIALIZED
CUPTI_ERROR_INVALID_DEVICE
if unable to get device ID
CUPTI_ERROR_INVALID_PARAMETER
if deviceId is NULL

Description

If context is NULL, returns the ID of the device that contains the currently active context. If context is non-NULL, returns the ID of the device which contains that context. Operates in a similar manner to cudaGetDevice() or cuCtxGetDevice() but may be called from within callback functions.

CUptiResult cuptiGetStreamId ( CUcontext context, CUstream stream, uint32_t* streamId )

Get the ID of a stream.

Parameters

context: If non-NULL then the stream is checked to ensure that it belongs to this context. Typically this parameter should be null.
stream: The stream
streamId: Returns a context-unique ID for the stream

Returns

CUPTI_SUCCESS
CUPTI_ERROR_NOT_INITIALIZED
CUPTI_ERROR_INVALID_STREAM
if unable to get stream ID, or if context is non-NULL and stream does not belong to the context
CUPTI_ERROR_INVALID_PARAMETER
if streamId is NULL

Description

Get the ID of a stream. The stream ID is unique within a context (i.e. all streams within a context will have unique stream IDs).

See also:

cuptiActivityEnqueueBuffer

cuptiActivityDequeueBuffer

CUptiResult cuptiGetTimestamp ( uint64_t* timestamp )

Get the CUPTI timestamp.

Parameters

timestamp: Returns the CUPTI timestamp

Returns

CUPTI_SUCCESS
CUPTI_ERROR_INVALID_PARAMETER
if timestamp is NULL

Description

Returns a timestamp normalized to correspond with the start and end timestamps reported in the CUPTI activity records. The timestamp is reported in nanoseconds.

< Previous | Next >

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