CUPTI (PDF) - v6.0 (older) - Last updated February 13, 2014 - Send Feedback -

## 1. Usage

The CUDA Profiling Tools Interface (CUPTI) enables the creation of profiling and tracing tools that target CUDA applications. CUPTI provides four APIs: the Activity API, the Callback API, the Event API, and the Metric API. Using these APIs, you can develop profiling tools that give insight into the CPU and GPU behavior of CUDA applications. CUPTI is delivered as a dynamic library on all platforms supported by CUDA.

### 1.1. CUPTI Compatibility and Requirements

New versions of the CUDA driver are backwards compatible with older versions of CUPTI. For example, a developer using a profiling tool based on CUPTI 4.1 can update to a more recently released CUDA driver. However, new versions of CUPTI are not backwards compatible with older versions of the CUDA driver. For example, a developer using a profiling tool based on CUPTI 4.1 must have a version of the CUDA driver released with CUDA Toolkit 4.1 (or later) installed as well. CUPTI calls will fail with `CUPTI_ERROR_NOT_INITIALIZED` if the CUDA driver version is not compatible with the CUPTI version.

### 1.2. CUPTI Initialization

CUPTI initialization occurs lazily the first time you invoke any CUPTI function. For the Activity, Event, Metric, and Callback APIs there are no requirements on when this initialization must occur (i.e. you can invoke the first CUPTI function at any point). See the CUPTI Activity API section for more information on CUPTI initialization requirements for the activity API.

### 1.3. CUPTI Activity API

The CUPTI Activity API allows you to asynchronously collect a trace of an application's CPU and GPU CUDA activity. The following terminology is used by the activity API.

Activity Record
  CPU and GPU activity is reported in C data structures called activity records. There is a different C structure type for each activity kind (e.g. `CUpti_ActivityMemcpy`). Records are generically referred to using the `CUpti_Activity` type. This type contains only a kind field that indicates the kind of the activity record. Using this kind, the object can be cast from the generic `CUpti_Activity` type to the specific type representing the activity. See the `printActivity` function in the activity_trace_async sample for an example.
Activity Buffer
  An activity buffer is used to transfer one or more activity records from CUPTI to the client. CUPTI fills activity buffers with activity records as the corresponding activities occur on the CPU and GPU. The CUPTI client is responsible for providing empty activity buffers as necessary to ensure that no records are dropped.

An asynchronous buffering API is implemented by `cuptiActivityRegisterCallbacks`, `cuptiActivityFlush`, and `cuptiActivityFlushAll`.

It is not required that the activity API be initalized before CUDA, but if the activity API is not initialized before CUDA some activity records may not be collected. You can force initialization of the activity API by enabling one or more activity kinds using `cuptiActivityEnable` or `cuptiActivityEnableContext`, as shown in the `initTrace` function of the activity_trace_async sample. Some activity kinds cannot be directly enabled, see the API documentation for for `CUpti_ActivityKind` for details. Functions `cuptiActivityEnable` and `cuptiActivityEnableContext` will return `CUPTI_ERROR_NOT_COMPATIBLE` if the requested activity kind cannot be enabled.

The activity buffer API uses callbacks to request and return buffers of activity records. To use the asynchronous buffering API you must first register two callbacks using `cuptiActivityRegisterCallbacks`. One of these callbacks will be invoked whenever CUPTI needs an empty activity buffer. The other callback is used to deliver a buffer containing one or more activity records to the client. To minimize profiling overhead the client should return as quickly as possible from these callbacks. Functions `cuptiActivityFlush` and `cuptiActivityFlushAll` can be used to force CUPTI to deliver any activity buffers that contain completed activity records. Functions `cuptiActivityGetAttribute` and `cuptiActivitySetAttribute` can be used to read and write attributes that control how the buffering API behaves. See the API documentation for more information.

The activity_trace_async sample shows how to use the activity buffer API to collect a trace of CPU and GPU activity for a simple application.

#### 1.3.1. Context Activity Record

In 6.0 the context activity record, `CUpti_ActivityContext`, was changed in a manner that introduced a new field into the structure. This new field was introduced in a way that preserves backward compatibility with any persisted versions of this structure.

The 32-bit `computeApiKind` field was replaced with two 16 bit fields, `computeApiKind` and `defaultStreamId`. Because all valid `computeApiKind` values fit within 16 bits, and because all supported CUDA platforms are little-endian, persisted context record data read with the new structure will have the correct value for `computeApiKind` and have a value of zero for `defaultStreamId`. The CUPTI client is responsible for versioning the persisted context data to recognize when the `defaultStreamId` field is valid.

#### 1.3.2. Legacy Activity Records

In CUPTI 5.5 the `CUpti_ActivityKernel2` structure replaced `CUpti_ActivityKernel` as the activity record used for the CUPTI_ACTIVITY_KIND_KERNEL and CUPTI_ACTIVITY_KIND_CONCURRENT_KERNEL activity kinds. The `CUpti_ActivityKernel` definition is retained in CUPTI to enable newer versions of CUPTI to work with presisted activity record data.

The CUPTI client is responsible for versioning the persisted activity record data to recognize when the persisted data is stored using `CUpti_ActivityKernel` or `CUpti_ActivityKernel2`.

### 1.4. CUPTI Callback API

The CUPTI Callback API allows you to register a callback into your own code. Your callback will be invoked when the application being profiled calls a CUDA runtime or driver function, or when certain events occur in the CUDA driver. The following terminology is used by the callback API.

Callback Domain
  Callbacks are grouped into domains to make it easier to associate your callback functions with groups of related CUDA functions or events. There are currently four callback domains, as defined by `CUpti_CallbackDomain`: a domain for CUDA runtime functions, a domain for CUDA driver functions, a domain for CUDA resource tracking, and a domain for CUDA synchronization notification.
Callback ID
  Each callback is given a unique ID within the corresponding callback domain so that you can identify it within your callback function. The CUDA driver API IDs are defined in `cupti_driver_cbid.h` and the CUDA runtime API IDs are defined in `cupti_runtime_cbid.h`. Both of these headers are included for you when you include `cupti.h`. The CUDA resource callback IDs are defined by `CUpti_CallbackIdResource` and the CUDA synchronization callback IDs are defined by `CUpti_CallbackIdSync`.
Callback Function
  Your callback function must be of type `CUpti_CallbackFunc`. This function type has two arguments that specify the callback domain and ID so that you know why the callback is occurring. The type also has a `cbdata` argument that is used to pass data specific to the callback.
Subscriber
  A subscriber is used to associate each of your callback functions with one or more CUDA API functions. There can be at most one subscriber initialized with `cuptiSubscribe()` at any time. Before initializing a new subscriber, the existing subscriber must be finalized with `cuptiUnsubscribe()`.

Each callback domain is described in detail below. Unless explicitly stated, it is not supported to call any CUDA runtime or driver API from within a callback function. Doing so may cause the application to hang.

#### 1.4.1. Driver and Runtime API Callbacks

Using the callback API with the `CUPTI_CB_DOMAIN_DRIVER_API` or `CUPTI_CB_DOMAIN_RUNTIME_API` domains, you can associate a callback function with one or more CUDA API functions. When those CUDA functions are invoked in the application, your callback function is invoked as well. For these domains, the `cbdata` argument to your callback function will be of the type `CUpti_CallbackData`.

It is legal to call `cudaThreadSynchronize()`, `cudaDeviceSynchronize()`, `cudaStreamSynchronize()`, `cuCtxSynchronize()`, and `cuStreamSynchronize()` from within a driver or runtime API callback function.

The following code shows a typical sequence used to associate a callback function with one or more CUDA API functions. To simplify the presentation error checking code has been removed.

      CUpti_SubscriberHandle subscriber;
      MyDataStruct *my_data = ...;
      ...
      cuptiSubscribe(&subscriber,
                     (CUpti_CallbackFunc)my_callback , my_data);
      cuptiEnableDomain(1, subscriber,
                        CUPTI_CB_DOMAIN_RUNTIME_API);

First, `cuptiSubscribe` is used to initialize a subscriber with the `my_callback` callback function. Next, `cuptiEnableDomain` is used to associate that callback with all the CUDA runtime API functions. Using this code sequence will cause `my_callback` to be called twice each time any of the CUDA runtime API functions are invoked, once on entry to the CUDA function and once just before exit from the CUDA function. CUPTI callback API functions `cuptiEnableCallback` and `cuptiEnableAllDomains` can also be used to associate CUDA API functions with a callback (see reference below for more information).

The following code shows a typical callback function.

    void CUPTIAPI
    my_callback(void *userdata, CUpti_CallbackDomain domain,
                CUpti_CallbackId cbid, const void *cbdata)
    {
      const CUpti_CallbackData *cbInfo = (CUpti_CallbackData *)cbdata;
      MyDataStruct *my_data = (MyDataStruct *)userdata;

      if ((domain == CUPTI_CB_DOMAIN_RUNTIME_API) &&
          (cbid == CUPTI_RUNTIME_TRACE_CBID_cudaMemcpy_v3020))  {
        if (cbInfo->callbackSite == CUPTI_API_ENTER) {
            cudaMemcpy_v3020_params *funcParams =
                 (cudaMemcpy_v3020_params *)(cbInfo->
                     functionParams);

            size_t count = funcParams->count;
            enum cudaMemcpyKind kind = funcParams->kind;
            ...
          }
      ...

In your callback function, you use the `CUpti_CallbackDomain` and `CUpti_CallbackID` parameters to determine which CUDA API function invocation is causing this callback. In the example above, we are checking for the CUDA runtime `cudaMemcpy` function. The `cbdata` parameter holds a structure of useful information that can be used within the callback. In this case we use the `callbackSite` member of the structure to detect that the callback is occurring on entry to `cudaMemcpy`, and we use the `functionParams` member to access the parameters that were passed to `cudaMemcpy`. To access the parameters we first cast `functionParams` to a structure type corresponding to the `cudaMemcpy` function. These parameter structures are contained in `generated_cuda_runtime_api_meta.h`, `generated_cuda_meta.h`, and a number of other files. When possible these files are included for you by `cupti.h`.

The callback_event and callback_timestamp samples described on the samples page both show how to use the callback API for the driver and runtime API domains.

#### 1.4.2. Resource Callbacks

Using the callback API with the `CUPTI_CB_DOMAIN_RESOURCE` domain, you can associate a callback function with some CUDA resource creation and destruction events. For example, when a CUDA context is created, your callback function will be invoked with a callback ID equal to `CUPTI_CBID_RESOURCE_CONTEXT_CREATED`. For this domain, the `cbdata` argument to your callback function will be of the type `CUpti_ResourceData`.

#### 1.4.3. Synchronization Callbacks

Using the callback API with the `CUPTI_CB_DOMAIN_SYNCHRONIZE` domain, you can associate a callback function with CUDA context and stream synchronizations. For example, when a CUDA context is synchronized, your callback function will be invoked with a callback ID equal to `CUPTI_CBID_SYNCHRONIZE_CONTEXT_SYNCHRONIZED`. For this domain, the `cbdata` argument to your callback function will be of the type `CUpti_SynchronizeData`.

#### 1.4.4. NVIDIA Tools Extension Callbacks

Using the callback API with the `CUPTI_CB_DOMAIN_NVTX` domain, you can associate a callback function with NVIDIA Tools Extension (NVTX) API functions. When an NVTX function is invoked in the application, your callback function is invoked as well. For these domains, the `cbdata` argument to your callback function will be of the type `CUpti_NvtxData`.

The NVTX library has its own convention for discovering the profiling library that will provide the implementation of the NVTX callbacks. To receive callbacks you must set the NVTX environment variables appropriately so that when the application calls an NVTX function, your profiling library recieve the callbacks. The following code sequence shows a typical initialization sequence to enable NVTX callbacks and activity records.

    /* Set env so CUPTI-based profiling library loads on first nvtx call. */
    char *inj32_path = "/path/to/32-bit/version/of/cupti/based/profiling/library";
    char *inj64_path = "/path/to/64-bit/version/of/cupti/based/profiling/library";
    setenv("NVTX_INJECTION32_PATH", inj32_path, 1);
    setenv("NVTX_INJECTION64_PATH", inj64_path, 1);

The following code shows a typical sequence used to associate a callback function with one or more NVTX functions. To simplify the presentation error checking code has been removed.

    CUpti_SubscriberHandle subscriber;
    MyDataStruct *my_data = ...;
    ...
    cuptiSubscribe(&subscriber,
                   (CUpti_CallbackFunc)my_callback , my_data);
    cuptiEnableDomain(1, subscriber,
                      CUPTI_CB_DOMAIN_NVTX);

First, `cuptiSubscribe` is used to initialize a subscriber with the `my_callback` callback function. Next, `cuptiEnableDomain` is used to associate that callback with all the NVTX functions. Using this code sequence will cause `my_callback` to be called once each time any of the NVTX functions are invoked. CUPTI callback API functions `cuptiEnableCallback` and `cuptiEnableAllDomains` can also be used to associate NVTX API functions with a callback (see reference below for more information).

The following code shows a typical callback function.

    void CUPTIAPI
    my_callback(void *userdata, CUpti_CallbackDomain domain,
                CUpti_CallbackId cbid, const void *cbdata)
    {
      const CUpti_NvtxData *nvtxInfo = (CUpti_NvtxData *)cbdata;
      MyDataStruct *my_data = (MyDataStruct *)userdata;

      if ((domain == CUPTI_CB_DOMAIN_NVTX) &&
          (cbid == NVTX_CBID_CORE_NameOsThreadA))  {
        nvtxNameOsThreadA_params *params = (nvtxNameOsThreadA_params *)nvtxInfo->
                 functionParams;
        ...
      }
      ...

In your callback function, you use the `CUpti_CallbackDomain` and `CUpti_CallbackID` parameters to determine which NVTX API function invocation is causing this callback. In the example above, we are checking for the `nvtxNameOsThreadA` function. The `cbdata` parameter holds a structure of useful information that can be used within the callback. In this case, we use the `functionParams` member to access the parameters that were passed to `nvtxNameOsThreadA`. To access the parameters we first cast `functionParams` to a structure type corresponding to the `nvtxNameOsThreadA` function. These parameter structures are contained in `generated_nvtx_meta.h`.

### 1.5. CUPTI Event API

The CUPTI Event API allows you to query, configure, start, stop, and read the event counters on a CUDA-enabled device. The following terminology is used by the event API.

Event
  An event is a countable activity, action, or occurrence on a device.
Event ID
  Each event is assigned a unique identifier. A named event will represent the same activity, action, or occurrence on all device types. But the named event may have different IDs on different device families. Use `cuptiEventGetIdFromName` to get the ID for a named event on a particular device.
Event Category
  Each event is placed in one of the categories defined by `CUpti_EventCategory`. The category indicates the general type of activity, action, or occurrence measured by the event.
Event Domain
  A device exposes one or more event domains. Each event domain represents a group of related events available on that device. A device may have multiple instances of a domain, indicating that the device can simultaneously record multiple instances of each event within that domain.
Event Group
  An event group is a collection of events that are managed together. The number and type of events that can be added to an event group are subject to device-specific limits. At any given time, a device may be configured to count events from a limited number of event groups. All events in an event group must belong to the same event domain.
Event Group Set
  An event group set is a collection of event groups that can be enabled at the same time. Event group sets are created by `cuptiEventGroupSetsCreate` and `cuptiMetricCreateEventGroupSets`.

You can determine the events available on a device using the `cuptiDeviceEnumEventDomains` and `cuptiEventDomainEnumEvents` functions. The cupti_query sample described on the samples page shows how to use these functions. You can also enumerate all the CUPTI events available on any device using the `cuptiEnumEventDomains` function.

Configuring and reading event counts requires the following steps. First, select your event collection mode. If you want to count events that occur during the execution of a kernel, use `cuptiSetEventCollectionMode` to set mode `CUPTI_EVENT_COLLECTION_MODE_KERNEL`. If you want to continuously sample the event counts, use mode `CUPTI_EVENT_COLLECTION_MODE_CONTINUOUS`. Next determine the names of the events that you want to count, and then use the `cuptiEventGroupCreate`, `cuptiEventGetIdFromName`, and `cuptiEventGroupAddEvent` functions to create and initialize an event group with those events. If you are unable to add all the events to a single event group then you will need to create multiple event groups. Alternatively, you can use the `cuptiEventGroupSetsCreate` function to automatically create the event group(s) required for a set of events.

To begin counting a set of events, enable the event group or groups that contain those events by using the `cuptiEventGroupEnable` function. If your events are contained in multiple event groups you may be unable to enable all of the event groups at the same time, due to device limitations. In this case, you can gather the events across multiple executions of the application or you can enable kernel replay. If you enable kernel replay using `cuptiEnableKernelReplayMode` you will be able to enabled any number of event groups and all the contained events will be collect.

Use the `cuptiEventGroupReadEvent` and/or `cuptiEventGroupReadAllEvents` functions to read the event values. When you are done collecting events, use the `cuptiEventGroupDisable` function to stop counting of the events contained in an event group. The callback_event sample described on the samples page shows how to use these functions to create, enable, and disable event groups, and how to read event counts.

#### 1.5.1. Collecting Kernel Execution Events

A common use of the event API is to count a set of events during the execution of a kernel (as demonstrated by the callback_event sample). The following code shows a typical callback used for this purpose. Assume that the callback was enabled only for a kernel launch using the CUDA runtime (i.e. by `cuptiEnableCallback(1, subscriber, CUPTI_CB_DOMAIN_RUNTIME_API, CUPTI_RUNTIME_TRACE_CBID_cudaLaunch_v3020)`. To simplify the presentation error checking code has been removed.

    static void CUPTIAPI
    getEventValueCallback(void *userdata,
                          CUpti_CallbackDomain domain,
                          CUpti_CallbackId cbid,
                          const void *cbdata)
    {
      const CUpti_CallbackData *cbData =
                    (CUpti_CallbackData *)cbdata;

      if (cbData->callbackSite == CUPTI_API_ENTER) {
        cudaThreadSynchronize();
        cuptiSetEventCollectionMode(cbInfo->context,
                                    CUPTI_EVENT_COLLECTION_MODE_KERNEL);
        cuptiEventGroupEnable(eventGroup);
      }

      if (cbData->callbackSite == CUPTI_API_EXIT) {
        cudaThreadSynchronize();
        cuptiEventGroupReadEvent(eventGroup,
                                 CUPTI_EVENT_READ_FLAG_NONE,
                                 eventId,
                                 &bytesRead, &eventVal);

        cuptiEventGroupDisable(eventGroup);
      }
    }

Two synchronization points are used to ensure that events are counted only for the execution of the kernel. If the application contains other threads that launch kernels, then additional thread-level synchronization must also be introduced to ensure that those threads do not launch kernels while the callback is collecting events. When the cudaLaunch API is entered (that is, before the kernel is actually launched on the device), `cudaThreadSynchronize` is used to wait until the GPU is idle. The event collection mode is set to `CUPTI_EVENT_COLLECTION_MODE_KERNEL` so that the event counters are automatically started and stopped just before and after the kernel executes. Then event collection is enabled with `cuptiEventGroupEnable`.

When the cudaLaunch API is exited (that is, after the kernel is queued for execution on the GPU) another `cudaThreadSynchronize` is used to cause the CPU thread to wait for the kernel to finish execution. Finally, the event counts are read with `cuptiEventGroupReadEvent`.

#### 1.5.2. Sampling Events

The event API can also be used to sample event values while a kernel or kernels are executing (as demonstrated by the event_sampling sample). The sample shows one possible way to perform the sampling. The event collection mode is set to `CUPTI_EVENT_COLLECTION_MODE_CONTINUOUS` so that the event counters run continuously. Two threads are used in event_sampling: one thread schedules the kernels and memcpys that perform the computation, while another thread wakes periodically to sample an event counter. In this sample there is no correlation of the event samples with what is happening on the GPU. To get some coarse correlation, you can use `cuptiDeviceGetTimestamp` to collect the GPU timestamp at the time of the sample and also at other interesting points in your application.

### 1.6. CUPTI Metric API

The CUPTI Metric API allows you to collect application metrics calculated from one or more event values. The following terminology is used by the metric API.

Metric
  An characteristic of an application that is calculated from one or more event values.
Metric ID
  Each metric is assigned a unique identifier. A named metric will represent the same characteristic on all device types. But the named metric may have different IDs on different device families. Use `cuptiMetricGetIdFromName` to get the ID for a named metric on a particular device.
Metric Category
  Each metric is placed in one of the categories defined by `CUpti_MetricCategory`. The category indicates the general type of the characteristic measured by the metric.
Metric Property
  Each metric is calculated from input values. These input values can be events or properties of the device or system. The available properties are defined by `CUpti_MetricPropertyID`.
Metric Value
  Each metric has a value that represents one of the kinds defined by `CUpti_MetricValueKind`. For each value kind, there is a corresponding member of the `CUpti_MetricValue` union that is used to hold the metric's value.

The tables included in this section list the metrics available for each device, as determined by the device's compute capability. You can also determine the metrics available on a device using the `cuptiDeviceEnumMetrics` function. The cupti_query sample described on the samples page shows how to use this function. You can also enumerate all the CUPTI metrics available on any device using the `cuptiEnumMetrics` function.

CUPTI provides two functions for calculating a metric value. `cuptiMetricGetValue2` can be used to calculate a metric value when the device is not available. All required event values and metric properties must be provided by the caller. `cuptiMetricGetValue` can be used to calculate a metric value when the device is available (as a CUdevice object). All required event values must be provided by the caller but CUPTI will determine the appropriate property values from the CUdevice object.

Configuring and calculating metric values requires the following steps. First, determine the name of the metric that you want to collect, and then use the `cuptiMetricGetIdFromName` to get the metric ID. Use `cuptiMetricEnumEvents` to get the events required to calculate the metric and follow instructions in the CUPTI Event API section to create the event groups for those events. When creating event groups in this manner it is important to use the result of `cuptiMetricGetRequiredEventGroupSets` to properly group together events that must be collected in the same pass to ensure proper metric calculation.

Alternatively, you can use the `cuptiMetricCreateEventGroupSets` function to automatically create the event group(s) required for metric's events. When using this function events will be grouped as required to most accurately calculate the metric, as a result it is not necessary to use `cuptiMetricGetRequiredEventGroupSets`.

If you are using `cuptiMetricGetValue2` the you must also collect the required metric property values using `cuptiMetricEnumProperties`.

Collect event counts as described in the CUPTI Event API section, and then use either `cuptiMetricGetValue` or `cuptiMetricGetValue2` to calculate the metric value from the collected event and property values. The callback_metric sample described on the samples page shows how to use the functions to calculate event values and calculate a metric using `cuptiMetricGetValue`. Note that, as shown in the example, you should collect event counts from all domain instances and normalize the counts to get the most accurate metric values. It is necessary to normalize the event counts because the number of event counter instances varies by device and by the event being counted.

For example, a device might have 8 multiprocessors but only have event counters for 4 of the multiprocessors, and might have 3 memory units and only have events counters for one memory unit. When calculating a metric that requires a multiprocessor event and a memory unit event, the 4 multiprocessor counters should be summed and multiplied by 2 to normalize the event count across the entire device. Similarly, the one memory unit counter should be multiplied by 3 to normalize the event count across the entire device. The normalized values can then be passed to `cuptiMetricGetValue` or `cuptiMetricGetValue2` to calculate the metric value.

As described, the normalization assumes the kernel executes a sufficient number of blocks to completely load the device. If the kernel has only a small number of blocks, normalizing across the entire device may skew the result.

### Metric Reference - Compute Capability 1.x

Devices with compute capability less than 2.0 implement the metrics shown in the following table. A scope value of single-context indicates that the metric can only be accurately collected when a single context (CUDA or graphic) is executing on the GPU. A scope value of multi-context indicates that the metric can be accurately collected when multiple contexts are executing on the GPU.

Table 1. Capability 1.x Metrics
Metric Name | Description | Scope
--- | --- | ---
branch_efficiency | Ratio of non-divergent branches to total branches expressed as percentage | Single-context
gld_efficiency | Ratio of requested global memory load transactions to actual global memory load transactions expressed as percentage | Single-context
gst_efficiency | Ratio of requested global memory store transactions to actual global memory store transactions expressed as percentage | Single-context
gld_requested_throughput | Requested global memory load throughput | Single-context
gst_requested_throughput | Requested global memory store throughput | Single-context

### Metric Reference - Compute Capability 2.x

Devices with compute capability between 2.0, inclusive, and 3.0 implement the metrics shown in the following table. A scope value of single-context indicates that the metric can only be accurately collected when a single context (CUDA or graphic) is executing on the GPU. A scope value of multi-context indicates that the metric can be accurately collected when multiple contexts are executing on the GPU.

Table 2. Capability 2.x Metrics
Metric Name | Description | Scope
--- | --- | ---
sm_efficiency | The percentage of time at least one warp is active on a multiprocessor averaged over all multiprocessors on the GPU | Single-context
sm_efficiency_instance | The percentage of time at least one warp is active on a specific multiprocessor | Single-context
achieved_occupancy | Ratio of the average active warps per active cycle to the maximum number of warps supported on a multiprocessor | Multi-context
issue_slot_utilization | Percentage of issue slots that issued at least one instruction, averaged across all cycles | Multi-context
inst_executed | The number of instructions executed | Multi-context
inst_issued | The number of instructions issued | Multi-context
issue_slots | The number of issue slots used | Multi-context
executed_ipc | Instructions executed per cycle | Multi-context
issued_ipc | Instructions issued per cycle | Multi-context
ipc_instance | Instructions executed per cycle for a single multiprocessor | Multi-context
inst_per_warp | Average number of instructions executed by each warp | Multi-context
cf_issued | Number of issued control-flow instructions | Multi-context
cf_executed | Number of executed control-flow instructions | Multi-context
ldst_issued | Number of issued load and store instructions | Multi-context
ldst_executed | Number of executed load and store instructions | Multi-context
branch_efficiency | Ratio of non-divergent branches to total branches expressed as percentage | Multi-context
warp_execution_efficiency | Ratio of the average active threads per warp to the maximum number of threads per warp supported on a multiprocessor expressed as percentage | Multi-context
inst_replay_overhead | Average number of replays for each instruction executed | Multi-context
shared_replay_overhead | Average number of replays due to shared memory conflicts for each instruction executed | Single-context
global_cache_replay_overhead | Average number of replays due to global memory cache misses for each instruction executed | Single-context
local_replay_overhead | Average number of replays due to local memory accesses for each instruction executed | Single-context
gld_efficiency | Ratio of requested global memory load throughput to required global memory load throughput expressed as percentage | Single-context
gst_efficiency | Ratio of requested global memory store throughput to required global memory store throughput expressed as percentage | Single-context
gld_transactions | Number of global memory load transactions | Single-context
gst_transactions | Number of global memory store transactions | Single-context
gld_transactions_per_request | Average number of global memory load transactions performed for each global memory load | Single-context
gst_transactions_per_request | Average number of global memory store transactions performed for each global memory store | Single-context
gld_throughput | Global memory load throughput | Single-context
gst_throughput | Global memory store throughput | Single-context
gld_requested_throughput | Requested global memory load throughput | Multi-context
gst_requested_throughput | Requested global memory store throughput | Multi-context
local_load_transactions | Number of local memory load transactions | Single-context
local_store_transactions | Number of local memory store transactions | Single-context
local_load_transactions_per_ request | Average number of local memory load transactions performed for each local memory load | Single-context
local_store_transactions_per_ request | Average number of local memory store transactions performed for each local memory store | Single-context
local_load_throughput | Local memory load throughput | Single-context
local_store_throughput | Local memory store throughput | Single-context
shared_load_transactions | Number of shared memory load transactions | Single-context
shared_store_transactions | Number of shared memory store transactions | Single-context
shared_load_transactions_per_ request | Average number of shared memory load transactions performed for each shared memory load | Single-context
shared_store_transactions_per_ request | Average number of shared memory store transactions performed for each shared memory store | Single-context
shared_load_throughput | Shared memory load throughput | Single-context
shared_store_throughput | Shared memory store throughput | Single-context
shared_efficiency | Ratio of requested shared memory throughput to required shared memory throughput expressed as percentage | Single-context
dram_read_transactions | Device memory read transactions | Single-context
dram_write_transactions | Device memory write transactions | Single-context
dram_read_throughput | Device memory read throughput | Single-context
dram_write_throughput | Device memory write throughput | Single-context
sysmem_read_transactions | System memory read transactions | Single-context
sysmem_write_transactions | System memory write transactions | Single-context
sysmem_read_throughput | System memory read throughput | Single-context
sysmem_write_throughput | System memory write throughput | Single-context
l1_cache_global_hit_rate | Hit rate in L1 cache for global loads | Single-context
l1_cache_local_hit_rate | Hit rate in L1 cache for local loads and stores | Single-context
tex_cache_hit_rate | Texture cache hit rate | Single-context
tex_cache_transactions | Texture cache read transactions | Single-context
tex_cache_throughput | Texture cache throughput | Single-context
l2_read_transactions | Memory read transactions seen at L2 cache for all read requests | Single-context
l2_write_transactions | Memory write transactions seen at L2 cache for all write requests | Single-context
l2_read_throughput | Memory read throughput seen at L2 cache for all read requests | Single-context
l2_write_throughput | Memory write throughput seen at L2 cache for all write requests | Single-context
l2_l1_read_hit_rate | Hit rate at L2 cache for all read requests from L1 cache | Sinlge-context
l2_l1_read_throughput | Memory read throughput seen at L2 cache for read requests from L1 cache | Single-context
l2_texture_read_hit_rate | Hit rate at L2 cache for all read requests from texture cache | Single-context
l2_texure_read_throughput | Memory read throughput seen at L2 cache for read requests from the texture cache | Sinlge-context
local_memory_overhead | Ratio of local memory traffic to total memory traffic between the L1 and L2 caches expressed as percentage | Single-context
l1_shared_utilization | The utilization level of the L1/shared memory relative to peak utilization on a scale of 0 to 10 | Single-context
l2_utilization | The utilization level of the L2 cache relative to the peak utilization on a scale of 0 to 10 | Single-context
tex_utilization | The utilization level of the texture cache relative to the peak utilization on a scale of 0 to 10 | Single-context
dram_utilization | The utilization level of the device memory relative to the peak utilization on a scale of 0 to 10 | Single-context
sysmem_utilization | The utilization level of the system memory relative to the peak utilization on a scale of 0 to 10 | Single-context
ldst_fu_utilization | The utilization level of the multiprocessor function units that execute global, local and shared memory instructions on a scale of 0 to 10 | Multi-context
cf_fu_utilization | The utilization level of the multiprocessor function units that execute control-flow instructions on a scale of 0 to 10 | Multi-context
tex_fu_utilization | The utilization level of the multiprocessor function units that execute texture instructions on a scale of 0 to 10 | Multi-context
alu_fu_utilization | The utilization level of the multiprocessor function units that execute integer and floating-point arithmetic instructions on a scale of 0 to 10 | Multi-context
inst_fp_32 | Number of single-precision floating-point instructions executed by non-predicated threads (arithmetric, compare, etc.) | Multi-context
inst_fp_64 | Number of double-precision floating-point instructions executed by non-predicated threads (arithmetric, compare, etc.) | Multi-context
inst_integer | Number of integer instructions executed by non-predicated threads | Multi-context
inst_bit_convert | Number of bit-conversion instructions executed by non-predicated threads | Multi-context
inst_control | Number of control-flow instructions executed by non-predicated threads (jump, branch, etc.) | Multi-context
inst_compute_ld_st | Number of compute load/store instructions executed by non-predicated threads | Multi-context
inst_inter_thread_communication | Number of inter-thread communication instructions executed by non-predicated threads | Multi-context
inst_misc | Number of miscellaneous instructions executed by non-predicated threads | Multi-context
flops_sp | Single-precision floating point operations executed | Multi-context
flops_sp_add | Single-precision floating point add operations executed | Multi-context
flops_sp_mul | Single-precision floating point multiply operations executed | Multi-context
flops_sp_fma | Single-precision floating point multiply-accumulate operations executed | Multi-context
flops_dp | Double-precision floating point operations executed | Multi-context
flops_dp_add | Double-precision floating point add operations executed | Multi-context
flops_dp_mul | Double-precision floating point multiply operations executed | Multi-context
flops_dp_fma | Double-precision floating point multiply-accumulate operations executed | Multi-context
flops_sp_special | Single-precision floating point special operations executed | Multi-context
stall_inst_fetch | Percentage of stalls occurring because the next assembly instruction has not yet been fetched | Multi-context
stall_exec_dependency | Percentage of stalls occurring because an input required by the instruction is not yet available | Multi-context
stall_data_request | Percentage of stalls occurring because a memory operation cannot be performed due to the required resources not being available or fully utilized, or because too many requests of a given type are outstanding | Multi-context
stall_sync | Percentage of stalls occurring because the warp is blocked at a __syncthreads() call | Multi-context
stall_texture | Percentage of stalls occurring because the texture sub-system is fully utilized or has too many outstanding requests | Multi-context
stall_other | Percentage of stalls occurring due to miscellaneous reasons | Multi-context

### Metric Reference - Compute Capability 3.x

Devices with compute capability between 3.0, inclusive, and 4.0 implement the metrics shown in the following table. A scope value of single-context indicates that the metric can only be accurately collected when a single context (CUDA or graphic) is executing on the GPU. A scope value of multi-context indicates that the metric can be accurately collected when multiple contexts are executing on the GPU.

Table 3. Capability 3.x Metrics
Metric Name | Description | Scope
--- | --- | ---
sm_efficiency | The percentage of time at least one warp is active on a multiprocessor averaged over all multiprocessors on the GPU | Single-context
sm_efficiency_instance | The percentage of time at least one warp is active on a specific multiprocessor | Single-context
achieved_occupancy | Ratio of the average active warps per active cycle to the maximum number of warps supported on a multiprocessor | Multi-context
issue_slot_utilization | Percentage of issue slots that issued at least one instruction, averaged across all cycles | Multi-context
inst_executed | The number of instructions executed | Multi-context
inst_issued | The number of instructions issued | Multi-context
issue_slots | The number of issue slots used | Multi-context
ipc | Instructions executed per cycle | Multi-context
issued_ipc | Instructions issued per cycle | Multi-context
ipc_instance | Instructions executed per cycle for a single multiprocessor | Multi-context
inst_per_warp | Average number of instructions executed by each warp | Multi-context
cf_issued | Number of issued control-flow instructions | Multi-context
cf_executed | Number of executed control-flow instructions | Multi-context
ldst_issued | Number of issued load and store instructions | Multi-context
ldst_executed | Number of executed load and store instructions | Multi-context
branch_efficiency | Ratio of non-divergent branches to total branches expressed as percentage. This is available for compute capability 3.0. | Multi-context
warp_execution_efficiency | Ratio of the average active threads per warp to the maximum number of threads per warp supported on a multiprocessor expressed as percentage | Multi-context
warp_nonpred_execution_efficiency | Ratio of the average active threads per warp executing non-predicated instructions to the maximum number of threads per warp supported on a multiprocessor expressed as percentage | Multi-context
inst_replay_overhead | Average number of replays for each instruction executed | Multi-context
shared_replay_overhead | Average number of replays due to shared memory conflicts for each instruction executed | Multi-context
global_replay_overhead | Average number of replays due to global memory cache misses | Multi-context
global_cache_replay_overhead | Average number of replays due to global memory cache misses for each instruction executed | Multi-context
local_replay_overhead | Average number of replays due to local memory accesses for each instruction executed | Multi-context
gld_efficiency | Ratio of requested global memory load throughput to required global memory load throughput expressed as percentage | Single-context
gst_efficiency | Ratio of requested global memory store throughput to required global memory store throughput expressed as percentage | Single-context
gld_transactions | Number of global memory load transactions expressed as percentage | Single-context
gst_transactions | Number of global memory store transactions | Single-context
gld_transactions_per_request | Average number of global memory load transactions performed for each global memory load | Single-context
gst_transactions_per_request | Average number of global memory store transactions performed for each global memory store | Single-context
gld_throughput | Global memory load throughput | Single-context
gst_throughput | Global memory store throughput | Single-context
gld_requested_throughput | Requested global memory load throughput | Multi-context
gst_requested_throughput | Requested global memory store throughput | Multi-context
nc_l2_read_throughput | Memory read throughput for non coherent global read requests seen at L2 cache | Single-context
nc_l2_read_transactions | Memory read transactions seen at L2 cache for non coherent global read requests | Single-context
nc_cache_global_hit_rate | Hit rate in non coherent cache for global loads | Single-context
nc_gld_throughput | Non coherent global memory load throughput | Single-context
nc_gld_requested_throughput | Requested throughput for global memory loaded via non-coherent cache | Multi-context
nc_gld_efficiency | Ratio of requested non coherent global memory load throughput to required non coherent global memory load throughput expressed as percentage | Single-context
local_load_transactions | Number of local memory load transactions | Single-context
local_store_transactions | Number of local memory store transactions | Single-context
local_load_transactions_per_request | Average number of local memory load transactions performed for each local memory load | Single-context
local_store_transactions_per_request | Average number of local memory store transactions performed for each local memory store | Single-context
local_load_throughput | Local memory load throughput | Single-context
local_store_throughput | Local memory store throughput | Single-context
shared_load_transactions | Number of shared memory load transactions | Single-context
shared_store_transactions | Number of shared memory store transactions | Single-context
shared_load_transactions_per_request | Average number of shared memory load transactions performed for each shared memory load | Single-context
shared_store_transactions_per_request | Average number of shared memory store transactions performed for each shared memory store | Single-context
shared_load_throughput | Shared memory load throughput | Single-context
shared_store_throughput | Shared memory store throughput | Single-context
shared_efficiency | Ratio of requested shared memory throughput to required shared memory throughput expressed as percentage | Single-context
dram_read_transactions | Device memory read transactions | Single-context
dram_write_transactions | Device memory write transactions | Single-context
dram_read_throughput | Device memory read throughput | Single-context
dram_write_throughput | Device memory write throughput | Single-context
sysmem_read_transactions | System memory read transactions. This is available for compute capability 3.0 and 3.5. | Single-context
sysmem_write_transactions | System memory write transactions. This is available for compute capability 3.0 and 3.5. | Single-context
sysmem_read_throughput | System memory read throughput. This is available for compute capability 3.0 and 3.5. | Single-context
sysmem_write_throughput | System memory write throughput. This is available for compute capability 3.0 and 3.5. | Single-context
l1_cache_global_hit_rate | Hit rate in L1 cache for global loads | Single-context
l1_cache_local_hit_rate | Hit rate in L1 cache for local loads and stores | Single-context
tex_cache_hit_rate | Texture cache hit rate | Single-context
tex_cache_transactions | Texture cache read transactions | Single-context
tex_cache_throughput | Texture cache throughput | Single-context
l2_read_transactions | Memory read transactions seen at L2 cache for all read requests | Single-context
l2_write_transactions | Memory write transactions seen at L2 cache for all write requests | Single-context
l2_read_throughput | Memory read throughput seen at L2 cache for all read requests | Single-context
l2_write_throughput | Memory write throughput seen at L2 cache for all write requests | Single-context
l2_l1_read_hit_rate | Hit rate at L2 cache for all read requests from L1 cache. This is available for compute capability 3.0 and 3.5. | Sinlge-context
l2_l1_read_throughput | Memory read throughput seen at L2 cache for read requests from L1 cache. This is available for compute capability 3.0 and 3.5. | Single-context
l2_texture_read_hit_rate | Hit rate at L2 cache for all read requests from texture cache | Single-context
l2_texure_read_throughput | Memory read throughput seen at L2 cache for read requests from the texture cache | Sinlge-context
l2_atomic_throughput | Memory read throughput seen at L2 cache for atomic and reduction requests | Sinlge-context
local_memory_overhead | Ratio of local memory traffic to total memory traffic between the L1 and L2 caches expressed as percentage. This is available for compute capability 3.0 and 3.5. | Single-context
l1_shared_utilization | The utilization level of the L1/shared memory relative to peak utilization on a scale of 0 to 10. This is available for compute capability 3.0 and 3.5. | Single-context
l2_utilization | The utilization level of the L2 cache relative to the peak utilization on a scale of 0 to 10 | Single-context
tex_utilization | The utilization level of the texture cache relative to the peak utilization on a scale of 0 to 10 | Single-context
dram_utilization | The utilization level of the device memory relative to the peak utilization on a scale of 0 to 10 | Single-context
sysmem_utilization | The utilization level of the system memory relative to the peak utilization on a scale of 0 to 10. This is available for compute capability 3.0 and 3.5. | Single-context
ldst_fu_utilization | The utilization level of the multiprocessor function units that execute global, local and shared memory instructions on a scale of 0 to 10 | Multi-context
cf_fu_utilization | The utilization level of the multiprocessor function units that execute control-flow instructions on a scale of 0 to 10 | Multi-context
tex_fu_utilization | The utilization level of the multiprocessor function units that execute texture instructions on a scale of 0 to 10 | Multi-context
alu_fu_utilization | The utilization level of the multiprocessor function units that execute integer and floating-point arithmetic instructions on a scale of 0 to 10 | Multi-context
inst_fp_32 | Number of single-precision floating-point instructions executed by non-predicated threads (arithmetric, compare, etc.) | Multi-context
inst_fp_64 | Number of double-precision floating-point instructions executed by non-predicated threads (arithmetric, compare, etc.) | Multi-context
inst_integer | Number of integer instructions executed by non-predicated threads | Multi-context
inst_bit_convert | Number of bit-conversion instructions executed by non-predicated threads | Multi-context
inst_control | Number of control-flow instructions executed by non-predicated threads (jump, branch, etc.) | Multi-context
inst_compute_ld_st | Number of compute load/store instructions executed by non-predicated threads | Multi-context
inst_inter_thread_communication | Number of inter-thread communication instructions executed by non-predicated threads | Multi-context
inst_misc | Number of miscellaneous instructions executed by non-predicated threads | Multi-context
flops_sp | Single-precision floating point operations executed | Multi-context
flops_sp_add | Single-precision floating point add operations executed | Multi-context
flops_sp_mul | Single-precision floating point multiply operations executed | Multi-context
flops_sp_fma | Single-precision floating point multiply-accumulate operations executed | Multi-context
flops_dp | Double-precision floating point operations executed | Multi-context
flops_dp_add | Double-precision floating point add operations executed | Multi-context
flops_dp_mul | Double-precision floating point multiply operations executed | Multi-context
flops_dp_fma | Double-precision floating point multiply-accumulate operations executed | Multi-context
flops_sp_special | Single-precision floating point special operations executed | Multi-context
stall_inst_fetch | Percentage of stalls occurring because the next assembly instruction has not yet been fetched | Multi-context
stall_exec_dependency | Percentage of stalls occurring because an input required by the instruction is not yet available | Multi-context
stall_data_request | Percentage of stalls occurring because a memory operation cannot be performed due to the required resources not being available or fully utilized, or because too many requests of a given type are outstanding | Multi-context
stall_sync | Percentage of stalls occurring because the warp is blocked at a __syncthreads() call | Multi-context
stall_texture | Percentage of stalls occurring because the texture sub-system is fully utilized or has too many outstanding requests | Multi-context
stall_other | Percentage of stalls occurring due to miscellaneous reasons | Multi-context
atomic_replay_overhead | Average number of replays due to atomic and reduction bank conflicts for each instruction executed | Multi-context
atomic_transactions | Global memory atomic and reduction transactions | Multi-context
atomic_transactions_per_request | Average number of global memory atomic and reduction transactions performed for each atomic and reduction instruction | Multi-context

### 1.7. Samples

The CUPTI installation includes several samples that demonstrate the use of the CUPTI APIs. The samples are:

activity_trace_async
  This sample shows how to collect a trace of CPU and GPU activity using the new asynchronous activity buffer APIs.
callback_event
  This sample shows how to use both the callback and event APIs to record the events that occur during the execution of a simple kernel. The sample shows the required ordering for synchronization, and for event group enabling, disabling and reading.
callback_metric
  This sample shows how to use both the callback and metric APIs to record the metric's events during the execution of a simple kernel, and then use those events to calculate the metric value.
callback_timestamp
  This sample shows how to use the callback API to record a trace of API start and stop times.
cupti_query
  This sample shows how to query CUDA-enabled devices for their event domains, events, and metrics.
event_sampling
  This sample shows how to use the event API to sample events using a separate host thread.
unified_memory
  This sample shows how to collect various counters like page faults and page transfers for unified memory.