CUPTI PC Sampling API


Data Structures

struct  CUpti_GetCubinCrcParams
 Params for cuptiGetCubinCrc. More...
struct  CUpti_GetSassToSourceCorrelationParams
 Params for cuptiGetSassToSourceCorrelation. More...
struct  CUpti_PCSamplingConfigurationInfo
 PC sampling configuration information structure. More...
struct  CUpti_PCSamplingConfigurationInfoParams
 PC sampling configuration structure. More...
struct  CUpti_PCSamplingData
 Collected PC Sampling data. More...
struct  CUpti_PCSamplingDisableParams
 Params for cuptiPCSamplingDisable. More...
struct  CUpti_PCSamplingEnableParams
 Params for cuptiPCSamplingEnable. More...
struct  CUpti_PCSamplingGetDataParams
 Params for cuptiPCSamplingEnable. More...
struct  CUpti_PCSamplingGetNumStallReasonsParams
 Params for cuptiPCSamplingGetNumStallReasons. More...
struct  CUpti_PCSamplingGetStallReasonsParams
 Params for cuptiPCSamplingGetStallReasons. More...
struct  CUpti_PCSamplingPCData
 PC Sampling data. More...
struct  CUpti_PCSamplingStallReason
 PC Sampling stall reasons. More...
struct  CUpti_PCSamplingStartParams
 Params for cuptiPCSamplingStart. More...
struct  CUpti_PCSamplingStopParams
 Params for cuptiPCSamplingStop. More...

Typedefs

typedef void(* CUpti_ComputeCrcCallbackFunc )(const void *cubin, size_t cubinSize, uint64_t *cubinCrc)
 Function type for callback used by CUPTI to request crc of loaded module.

Enumerations

enum  CUpti_PCSamplingCollectionMode {
  CUPTI_PC_SAMPLING_COLLECTION_MODE_INVALID = 0,
  CUPTI_PC_SAMPLING_COLLECTION_MODE_CONTINUOUS = 1,
  CUPTI_PC_SAMPLING_COLLECTION_MODE_KERNEL_SERIALIZED = 2
}
 PC Sampling collection mode. More...
enum  CUpti_PCSamplingConfigurationAttributeType { ,
  CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_SAMPLING_PERIOD = 1,
  CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_STALL_REASON = 2,
  CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_SCRATCH_BUFFER_SIZE = 3,
  CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_HARDWARE_BUFFER_SIZE = 4,
  CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_COLLECTION_MODE = 5,
  CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_ENABLE_START_STOP_CONTROL = 6,
  CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_OUTPUT_DATA_FORMAT = 7,
  CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_SAMPLING_DATA_BUFFER = 8
}
 PC Sampling configuration attributes. More...
enum  CUpti_PCSamplingOutputDataFormat { , CUPTI_PC_SAMPLING_OUTPUT_DATA_FORMAT_PARSED = 1 }
 PC Sampling output data format. More...

Functions

CUptiResult cuptiGetCubinCrc (CUpti_GetCubinCrcParams *pParams)
 Get the CRC of cubin.
CUptiResult cuptiGetSassToSourceCorrelation (CUpti_GetSassToSourceCorrelationParams *pParams)
 SASS to Source correlation.
CUptiResult cuptiPCSamplingDisable (CUpti_PCSamplingDisableParams *pParams)
 Disable PC sampling.
CUptiResult cuptiPCSamplingEnable (CUpti_PCSamplingEnableParams *pParams)
 Enable PC sampling.
CUptiResult cuptiPCSamplingGetConfigurationAttribute (CUpti_PCSamplingConfigurationInfoParams *pParams)
 Read PC Sampling configuration attribute.
CUptiResult cuptiPCSamplingGetData (CUpti_PCSamplingGetDataParams *pParams)
 Flush GPU PC sampling data periodically.
CUptiResult cuptiPCSamplingGetNumStallReasons (CUpti_PCSamplingGetNumStallReasonsParams *pParams)
 Get PC sampling stall reason count.
CUptiResult cuptiPCSamplingGetStallReasons (CUpti_PCSamplingGetStallReasonsParams *pParams)
 Get PC sampling stall reasons.
CUptiResult cuptiPCSamplingSetConfigurationAttribute (CUpti_PCSamplingConfigurationInfoParams *pParams)
 Write PC Sampling configuration attribute.
CUptiResult cuptiPCSamplingStart (CUpti_PCSamplingStartParams *pParams)
 Start PC sampling.
CUptiResult cuptiPCSamplingStop (CUpti_PCSamplingStopParams *pParams)
 Stop PC sampling.
CUptiResult cuptiRegisterComputeCrcCallback (CUpti_ComputeCrcCallbackFunc funcComputeCubinCrc)
 Register callback function with CUPTI to use your own algorithm to compute cubin crc.

Detailed Description

Functions, types, and enums that implement the CUPTI PC Sampling API.

Typedef Documentation

typedef void( * CUpti_ComputeCrcCallbackFunc)(const void *cubin, size_t cubinSize, uint64_t *cubinCrc)

This callback function ask for crc of provided module in function. The provided crc will be stored in PC sampling records i.e. in the field 'cubinCrc' of the PC sampling struct CUpti_PCSamplingPCData. The CRC is uses during the offline source correlation to uniquely identify the module.

Parameters:
cubin The pointer to cubin binary
cubinSize The size of cubin binary.
cubinCrc Returns the computed crc of cubin.


Enumeration Type Documentation

Enumerator:
CUPTI_PC_SAMPLING_COLLECTION_MODE_INVALID  INVALID Value
CUPTI_PC_SAMPLING_COLLECTION_MODE_CONTINUOUS  Continuous mode. Kernels are not serialized in this mode.
CUPTI_PC_SAMPLING_COLLECTION_MODE_KERNEL_SERIALIZED  Serialized mode. Kernels are serialized in this mode.

PC Sampling configuration attribute types. These attributes can be read using cuptiPCSamplingGetConfigurationAttribute and can be written using cuptiPCSamplingSetConfigurationAttribute. Attributes marked [r] can only be read using cuptiPCSamplingGetConfigurationAttribute [w] can only be written using cuptiPCSamplingSetConfigurationAttribute [rw] can be read using cuptiPCSamplingGetConfigurationAttribute and written using cuptiPCSamplingSetConfigurationAttribute

Enumerator:
CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_SAMPLING_PERIOD  [rw] Sampling period for PC Sampling. DEFAULT - CUPTI defined value based on number of SMs Valid values for the sampling periods are between 5 to 31 both inclusive. This will set the sampling period to (2^samplingPeriod) cycles. For e.g. for sampling period = 5 to 31, cycles = 32, 64, 128,..., 2^31 Value is a uint32_t
CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_STALL_REASON  [w] Number of stall reasons to collect. DEFAULT - All stall reasons will be collected Value is a size_t [w] Stall reasons to collect DEFAULT - All stall reasons will be collected Input value should be a pointer pointing to array of stall reason indexes containing all the stall reason indexes to collect.
CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_SCRATCH_BUFFER_SIZE  [rw] Size of SW buffer for raw PC counter data downloaded from HW buffer DEFAULT - 1 MB, which can accommodate approximately 5500 PCs with all stall reasons Approximately it takes 16 Bytes (and some fixed size memory) to accommodate one PC with one stall reason For e.g. 1 PC with 1 stall reason = 32 Bytes 1 PC with 2 stall reason = 48 Bytes 1 PC with 4 stall reason = 96 Bytes Value is a size_t
CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_HARDWARE_BUFFER_SIZE  [rw] Size of HW buffer in bytes DEFAULT - 512 MB If sampling period is too less, HW buffer can overflow and drop PC data Value is a size_t
CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_COLLECTION_MODE  [rw] PC Sampling collection mode DEFAULT - CUPTI_PC_SAMPLING_COLLECTION_MODE_CONTINUOUS Input value should be of type CUpti_PCSamplingCollectionMode.
CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_ENABLE_START_STOP_CONTROL  [rw] Control over PC Sampling data collection range Default - 0 1 - Allows user to start and stop PC Sampling using APIs - cuptiPCSamplingStart() - Start PC Sampling cuptiPCSamplingStop() - Stop PC Sampling Value is a uint32_t
CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_OUTPUT_DATA_FORMAT  [w] Value for output data format Default - CUPTI_PC_SAMPLING_OUTPUT_DATA_FORMAT_PARSED Input value should be of type CUpti_PCSamplingOutputDataFormat.
CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_SAMPLING_DATA_BUFFER  [w] Data buffer to hold collected PC Sampling data PARSED_DATA Default - none. Buffer type is void * which can point to PARSED_DATA Refer CUpti_PCSamplingData for buffer format for PARSED_DATA

Enumerator:
CUPTI_PC_SAMPLING_OUTPUT_DATA_FORMAT_PARSED  HW buffer data will be parsed during collection of data


Function Documentation

CUptiResult cuptiGetCubinCrc ( CUpti_GetCubinCrcParams pParams  ) 

This function returns the CRC of provided cubin binary.

Parameters:
Refer CUpti_GetCubinCrcParams
Return values:
CUPTI_SUCCESS 
CUPTI_ERROR_INVALID_PARAMETER if parameter cubin is NULL or provided cubinSize is zero or size field is not set.

CUptiResult cuptiGetSassToSourceCorrelation ( CUpti_GetSassToSourceCorrelationParams pParams  ) 

Parameters:
Refer CUpti_GetSassToSourceCorrelationParams
It is expected from user to free allocated memory for fileName and dirName after use.

Return values:
CUPTI_SUCCESS 
CUPTI_ERROR_INVALID_PARAMETER if either of the parameters cubin or functionName is NULL or cubinSize is zero or size field is not set correctly.
CUPTI_ERROR_INVALID_MODULE provided cubin is invalid.
CUPTI_ERROR_UNKNOWN an internal error occurred. This error code is also used for cases when the function is not present in the module. A better error code will be returned in the future release.

CUptiResult cuptiPCSamplingDisable ( CUpti_PCSamplingDisableParams pParams  ) 

For application which doesn't destroy the CUDA context explicitly, this API does the PC Sampling tear-down, joins threads and copies PC records in the buffer provided during the PC sampling configuration. PC records which can't be accommodated in the buffer are discarded.

Parameters:
Refer CUpti_PCSamplingDisableParams
Return values:
CUPTI_SUCCESS 
CUPTI_ERROR_INVALID_PARAMETER if any pParams is not valid
CUPTI_ERROR_NOT_SUPPORTED indicates that the system/device does not support the API

CUptiResult cuptiPCSamplingEnable ( CUpti_PCSamplingEnableParams pParams  ) 

Parameters:
Refer CUpti_PCSamplingEnableParams
Return values:
CUPTI_SUCCESS 
CUPTI_ERROR_INVALID_PARAMETER if any pParams is not valid
CUPTI_ERROR_NOT_SUPPORTED indicates that the system/device does not support the API

CUptiResult cuptiPCSamplingGetConfigurationAttribute ( CUpti_PCSamplingConfigurationInfoParams pParams  ) 

Parameters:
pParams A pointer to CUpti_PCSamplingConfigurationInfoParams containing PC sampling configuration.
Return values:
CUPTI_SUCCESS 
CUPTI_ERROR_INVALID_OPERATION if this API is called with some invalid attribute.
CUPTI_ERROR_INVALID_PARAMETER if attrib is not valid or any pParams is not valid
CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT indicates that the value buffer is too small to hold the attribute value
CUPTI_ERROR_NOT_SUPPORTED indicates that the system/device does not support the API

CUptiResult cuptiPCSamplingGetData ( CUpti_PCSamplingGetDataParams pParams  ) 

Flushing of GPU PC Sampling data is required at following point to maintain uniqueness of PCs: For CUPTI_PC_SAMPLING_COLLECTION_MODE_CONTINUOUS, after every module load-unload-load For CUPTI_PC_SAMPLING_COLLECTION_MODE_KERNEL_SERIALIZED, after every kernel ends If configuration option CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_ENABLE_START_STOP_CONTROL is enabled, then after every range end i.e. cuptiPCSamplingStop() If application is profiled in CUPTI_PC_SAMPLING_COLLECTION_MODE_CONTINUOUS, with disabled CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_ENABLE_START_STOP_CONTROL, and there is no module unload, user can collect data in two ways: Use cuptiPCSamplingGetData() API periodically Use cuptiPCSamplingDisable() on application exit and read GPU PC sampling data from sampling data buffer passed during configuration. Note: In case, cuptiPCSamplingGetData() API is not called periodically, then sampling data buffer passed during configuration should be large enough to hold all PCs data. cuptiPCSamplingGetData() API never does device synchronization. It is possible that when the API is called there is some unconsumed data from the HW buffer. In this case CUPTI provides only the data available with it at that moment.

Parameters:
Refer CUpti_PCSamplingGetDataParams
Return values:
CUPTI_SUCCESS 
CUPTI_ERROR_INVALID_OPERATION if this API is called without enabling PC sampling.
CUPTI_ERROR_INVALID_PARAMETER if any pParams is not valid
CUPTI_ERROR_NOT_SUPPORTED indicates that the system/device does not support the API

CUptiResult cuptiPCSamplingGetNumStallReasons ( CUpti_PCSamplingGetNumStallReasonsParams pParams  ) 

Parameters:
Refer CUpti_PCSamplingGetNumStallReasonsParams
Return values:
CUPTI_SUCCESS 
CUPTI_ERROR_INVALID_PARAMETER if any pParams is not valid
CUPTI_ERROR_NOT_SUPPORTED indicates that the system/device does not support the API

CUptiResult cuptiPCSamplingGetStallReasons ( CUpti_PCSamplingGetStallReasonsParams pParams  ) 

Parameters:
Refer CUpti_PCSamplingGetStallReasonsParams
Return values:
CUPTI_SUCCESS 
CUPTI_ERROR_INVALID_PARAMETER if any pParams is not valid
CUPTI_ERROR_NOT_SUPPORTED indicates that the system/device does not support the API

CUptiResult cuptiPCSamplingSetConfigurationAttribute ( CUpti_PCSamplingConfigurationInfoParams pParams  ) 

Parameters:
pParams A pointer to CUpti_PCSamplingConfigurationInfoParams containing PC sampling configuration.
Return values:
CUPTI_SUCCESS 
CUPTI_ERROR_INVALID_OPERATION if this API is called with some invalid attrib.
CUPTI_ERROR_INVALID_PARAMETER if attribute value is not valid or any pParams is not valid
CUPTI_ERROR_NOT_SUPPORTED indicates that the system/device does not support the API

CUptiResult cuptiPCSamplingStart ( CUpti_PCSamplingStartParams pParams  ) 

User can collect PC Sampling data for user-defined range specified by Start/Stop APIs. This API can be used to mark starting of range. Set configuration option CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_ENABLE_START_STOP_CONTROL to use this API.

Parameters:
Refer CUpti_PCSamplingStartParams
Return values:
CUPTI_SUCCESS 
CUPTI_ERROR_INVALID_OPERATION if this API is called with incorrect PC Sampling configuration.
CUPTI_ERROR_INVALID_PARAMETER if any pParams is not valid
CUPTI_ERROR_NOT_SUPPORTED indicates that the system/device does not support the API

CUptiResult cuptiPCSamplingStop ( CUpti_PCSamplingStopParams pParams  ) 

User can collect PC Sampling data for user-defined range specified by Start/Stop APIs. This API can be used to mark end of range. Set configuration option CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_ENABLE_START_STOP_CONTROL to use this API.

Parameters:
Refer CUpti_PCSamplingStopParams
Return values:
CUPTI_SUCCESS 
CUPTI_ERROR_INVALID_OPERATION if this API is called with incorrect PC Sampling configuration.
CUPTI_ERROR_INVALID_PARAMETER if any pParams is not valid
CUPTI_ERROR_NOT_SUPPORTED indicates that the system/device does not support the API

CUptiResult cuptiRegisterComputeCrcCallback ( CUpti_ComputeCrcCallbackFunc  funcComputeCubinCrc  ) 

This function registers a callback function and it gets called from CUPTI when a CUDA module is loaded.

Parameters:
funcComputeCubinCrc callback is invoked when a CUDA module is loaded.
Return values:
CUPTI_SUCCESS 
CUPTI_ERROR_INVALID_PARAMETER if funcComputeCubinCrc is NULL.


Generated on Tue Jul 12 11:16:29 2022 for Cupti by  doxygen 1.5.8