5.11. CUPTI Range Profiling API

Functions, types, and enums that implement the CUPTI Range Profiling API.

Data Structures

CUpti_RangeProfiler_CounterDataImage_Initialize_Params: Params for cuptiRangeProfilerCounterDataImageInitialize.
CUpti_RangeProfiler_CounterData_GetRangeInfo_Params: Params for cuptiRangeProfilerCounterDataGetRangeInfo.
CUpti_RangeProfiler_DecodeData_Params: Params for cuptiRangeProfilerDecodeData.
CUpti_RangeProfiler_Disable_Params: Params for cuptiRangeProfilerDisable.
CUpti_RangeProfiler_Enable_Params: Params for cuptiRangeProfilerEnable.
CUpti_RangeProfiler_GetCounterDataInfo_Params: Params for cuptiRangeProfilerGetCounterDataInfo.
CUpti_RangeProfiler_GetCounterDataSize_Params: Params for cuptiRangeProfilerGetCounterDataSize.
CUpti_RangeProfiler_PopRange_Params: Params for cuptiRangeProfilerPopRange.
CUpti_RangeProfiler_PushRange_Params: Params for cuptiRangeProfilerPushRange.
CUpti_RangeProfiler_SetConfig_Params: Params for cuptiRangeProfilerSetConfig.
CUpti_RangeProfiler_Start_Params: Params for cuptiRangeProfilerStart.
CUpti_RangeProfiler_Stop_Params: Params for cuptiRangeProfilerStop.

Macros

CUpti_RangeProfiler_CounterDataImage_Initialize_Params_STRUCT_SIZE
CUpti_RangeProfiler_CounterData_GetRangeInfo_Params_STRUCT_SIZE
CUpti_RangeProfiler_DecodeData_Params_STRUCT_SIZE
CUpti_RangeProfiler_Disable_Params_STRUCT_SIZE
CUpti_RangeProfiler_Enable_Params_STRUCT_SIZE
CUpti_RangeProfiler_GetCounterDataInfo_Params_STRUCT_SIZE
CUpti_RangeProfiler_GetCounterDataSize_Params_STRUCT_SIZE
CUpti_RangeProfiler_PopRange_Params_STRUCT_SIZE
CUpti_RangeProfiler_PushRange_Params_STRUCT_SIZE
CUpti_RangeProfiler_SetConfig_Params_STRUCT_SIZE
CUpti_RangeProfiler_Start_Params_STRUCT_SIZE
CUpti_RangeProfiler_Stop_Params_STRUCT_SIZE

Functions

CUptiResult cuptiRangeProfilerCounterDataGetRangeInfo(CUpti_RangeProfiler_CounterData_GetRangeInfo_Params *pParams): Get the range name for the given range index.
CUptiResult cuptiRangeProfilerCounterDataImageInitialize(CUpti_RangeProfiler_CounterDataImage_Initialize_Params *pParams): Initialize the counter data image with the profiling data for the ranges profiled.
CUptiResult cuptiRangeProfilerDecodeData(CUpti_RangeProfiler_DecodeData_Params *pParams): Decode the profiling data stored in the hardware to the counter data image passed in the SetConfig API.
CUptiResult cuptiRangeProfilerDisable(CUpti_RangeProfiler_Disable_Params *pParams): Disable the range profiler on the CUDA context and destroy the range profiler object.
CUptiResult cuptiRangeProfilerEnable(CUpti_RangeProfiler_Enable_Params *pParams): Create a range profiler object and enable range profiling on the CUDA context.
CUptiResult cuptiRangeProfilerGetCounterDataInfo(CUpti_RangeProfiler_GetCounterDataInfo_Params *pParams): Get the number of ranges stored in the counter data image.
CUptiResult cuptiRangeProfilerGetCounterDataSize(CUpti_RangeProfiler_GetCounterDataSize_Params *pParams): Get the size of the counter data image required to store the profiling data for the ranges profiled.
CUptiResult cuptiRangeProfilerPopRange(CUpti_RangeProfiler_PopRange_Params *pParams): pop the current range to the Range Profiler.
CUptiResult cuptiRangeProfilerPushRange(CUpti_RangeProfiler_PushRange_Params *pParams): Add a new range to the Range Profiler with a given range name.
CUptiResult cuptiRangeProfilerSetConfig(CUpti_RangeProfiler_SetConfig_Params *pParams): Set the configuration for range profiler like maximum number of ranges per pass, number of nesting levels, range and replay mode and the config image which has scheduling info for metric collection.
CUptiResult cuptiRangeProfilerStart(CUpti_RangeProfiler_Start_Params *pParams): Start the range profiler.
CUptiResult cuptiRangeProfilerStop(CUpti_RangeProfiler_Stop_Params *pParams): Stop the range profiler.

Typedefs

CUpti_RangeProfiler_Object

Variables

size_t CUpti_RangeProfiler_CounterDataImage_Initialize_Params::counterDataSize: [in] Size of the counter data image.
uint8_t * CUpti_RangeProfiler_CounterDataImage_Initialize_Params::pCounterData: [in] Counter data image.
void * CUpti_RangeProfiler_CounterDataImage_Initialize_Params::pPriv: [in] Set to NULL.
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_CounterDataImage_Initialize_Params::pRangeProfilerObject: [in] Periodic sampler object.
size_t CUpti_RangeProfiler_CounterDataImage_Initialize_Params::structSize: [in] Size of the data structure.
size_t CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::counterDataImageSize: [in] Size of the counter data image.
const uint8_t * CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::pCounterDataImage: [in] Counter data image.
void * CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::pPriv: [in] Set to NULL.
const char * CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::rangeDelimiter: [in] range delimiter.
size_t CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::rangeIndex: [in] Index of the sample.
const char * CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::rangeName: [out] RangeName;
size_t CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::structSize: [in] Size of the data structure.
size_t CUpti_RangeProfiler_DecodeData_Params::numOfRangeDropped: [out] Number of ranges dropped in the processed passes.
void * CUpti_RangeProfiler_DecodeData_Params::pPriv: [in] Set to NULL.
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_DecodeData_Params::pRangeProfilerObject: [in] Range Profiler Object.
size_t CUpti_RangeProfiler_DecodeData_Params::structSize: [in] Size of the data structure.
void * CUpti_RangeProfiler_Disable_Params::pPriv: [in] Set to NULL.
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_Disable_Params::pRangeProfilerObject: [in] Range Profiler Object.
size_t CUpti_RangeProfiler_Disable_Params::structSize: [in] Size of the data structure.
CUcontext CUpti_RangeProfiler_Enable_Params::ctx: [in] Context to be used for profiling.
void * CUpti_RangeProfiler_Enable_Params::pPriv: [in] Set to NULL.
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_Enable_Params::pRangeProfilerObject: [out] Range Profiler Object.
size_t CUpti_RangeProfiler_Enable_Params::structSize: [in] Size of the data structure.
size_t CUpti_RangeProfiler_GetCounterDataInfo_Params::counterDataImageSize: [in] Size of the counter data image.
size_t CUpti_RangeProfiler_GetCounterDataInfo_Params::numTotalRanges: [out] Number of ranges in the counter data image.
const uint8_t * CUpti_RangeProfiler_GetCounterDataInfo_Params::pCounterDataImage: [in] Counter data image.
void * CUpti_RangeProfiler_GetCounterDataInfo_Params::pPriv: [in] Set to NULL.
size_t CUpti_RangeProfiler_GetCounterDataInfo_Params::structSize: [in] Size of the data structure.
size_t CUpti_RangeProfiler_GetCounterDataSize_Params::counterDataSize: [out] Size of the counter data image.
size_t CUpti_RangeProfiler_GetCounterDataSize_Params::maxNumOfRanges: [in] Maximum number of ranges to be stored in the counter data image.
uint32_t CUpti_RangeProfiler_GetCounterDataSize_Params::maxNumRangeTreeNodes: [in] Maximum number of RangeTree nodes; must be >= maxNumOfRanges
size_t CUpti_RangeProfiler_GetCounterDataSize_Params::numMetrics: [in] Number of metrics to be collected.
const char ** CUpti_RangeProfiler_GetCounterDataSize_Params::pMetricNames: [in] Names of the metrics to be collected.
void * CUpti_RangeProfiler_GetCounterDataSize_Params::pPriv: [in] Set to NULL.
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_GetCounterDataSize_Params::pRangeProfilerObject: [in] Periodic sampler object.
size_t CUpti_RangeProfiler_GetCounterDataSize_Params::structSize: [in] Size of the data structure.
void * CUpti_RangeProfiler_PopRange_Params::pPriv: [in] Set to NULL.
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_PopRange_Params::pRangeProfilerObject: [in] Range Profiler Object.
size_t CUpti_RangeProfiler_PopRange_Params::structSize: [in] Size of the data structure.
void * CUpti_RangeProfiler_PushRange_Params::pPriv: [in] Set to NULL.
const char * CUpti_RangeProfiler_PushRange_Params::pRangeName: [in] Name of the range to be profiled (only valid for User range mode).
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_PushRange_Params::pRangeProfilerObject: [in] Range Profiler Object.
size_t CUpti_RangeProfiler_PushRange_Params::structSize: [in] Size of the data structure.
size_t CUpti_RangeProfiler_SetConfig_Params::configSize: [in] Size of the config image.
size_t CUpti_RangeProfiler_SetConfig_Params::counterDataImageSize: [in] Size of the counter data image.
size_t CUpti_RangeProfiler_SetConfig_Params::maxRangesPerPass: [in] Maximum number of ranges that can be profiled in a pass.
uint16_t CUpti_RangeProfiler_SetConfig_Params::minNestingLevel: [in] minimum nesting level to be profiled.
uint16_t CUpti_RangeProfiler_SetConfig_Params::numNestingLevels: [in] number of nesting level to be profiled. For Auto range mode, this should be set to 1.
const uint8_t * CUpti_RangeProfiler_SetConfig_Params::pConfig: [in] Config image.
uint8_t * CUpti_RangeProfiler_SetConfig_Params::pCounterDataImage: [in] Counter data image.
void * CUpti_RangeProfiler_SetConfig_Params::pPriv: [in] Set to NULL.
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_SetConfig_Params::pRangeProfilerObject: [in] Range Profiler Object.
size_t CUpti_RangeProfiler_SetConfig_Params::passIndex: [in] Pass index for the replay session.
CUpti_ProfilerRange CUpti_RangeProfiler_SetConfig_Params::range: [in] Profiling Range mode.
CUpti_ProfilerReplayMode CUpti_RangeProfiler_SetConfig_Params::replayMode: [in] Replay mode.
size_t CUpti_RangeProfiler_SetConfig_Params::structSize: [in] Size of the data structure.
uint16_t CUpti_RangeProfiler_SetConfig_Params::targetNestingLevel: [in] Target nesting level for the replay session.
void * CUpti_RangeProfiler_Start_Params::pPriv: [in] Set to NULL.
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_Start_Params::pRangeProfilerObject: [in] Range Profiler Object.
size_t CUpti_RangeProfiler_Start_Params::structSize: [in] Size of the data structure.
uint8_t CUpti_RangeProfiler_Stop_Params::isAllPassSubmitted: [out] 1 if all passes are submitted to GPU for collection, 0 otherwise.
void * CUpti_RangeProfiler_Stop_Params::pPriv: [in] Set to NULL.
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_Stop_Params::pRangeProfilerObject: [in] Range Profiler Object.
size_t CUpti_RangeProfiler_Stop_Params::passIndex: [out] pass index for the replay session.
size_t CUpti_RangeProfiler_Stop_Params::structSize: [in] Size of the data structure.
size_t CUpti_RangeProfiler_Stop_Params::targetNestingLevel: [out] target nesting level for the replay session.

5.11.1. Macros

CUpti_RangeProfiler_CounterDataImage_Initialize_Params_STRUCT_SIZE

CUpti_RangeProfiler_CounterData_GetRangeInfo_Params_STRUCT_SIZE

CUpti_RangeProfiler_DecodeData_Params_STRUCT_SIZE

CUpti_RangeProfiler_Disable_Params_STRUCT_SIZE

CUpti_RangeProfiler_Enable_Params_STRUCT_SIZE

CUpti_RangeProfiler_GetCounterDataInfo_Params_STRUCT_SIZE

CUpti_RangeProfiler_GetCounterDataSize_Params_STRUCT_SIZE

CUpti_RangeProfiler_PopRange_Params_STRUCT_SIZE

CUpti_RangeProfiler_PushRange_Params_STRUCT_SIZE

CUpti_RangeProfiler_SetConfig_Params_STRUCT_SIZE

CUpti_RangeProfiler_Start_Params_STRUCT_SIZE

CUpti_RangeProfiler_Stop_Params_STRUCT_SIZE

5.11.2. Functions

CUptiResult cuptiRangeProfilerCounterDataGetRangeInfo(CUpti_RangeProfiler_CounterData_GetRangeInfo_Params *pParams)

Get the range name for the given range index.

Parameters

pParams – A pointer to CUpti_RangeProfiler_CounterData_GetRangeInfo_Params

Return values

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – if any pParams is not valid
CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiRangeProfilerCounterDataImageInitialize(CUpti_RangeProfiler_CounterDataImage_Initialize_Params *pParams)

Initialize the counter data image with the profiling data for the ranges profiled.

Parameters

pParams – A pointer to CUpti_RangeProfiler_CounterDataImage_Initialize_Params

Return values

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – if any pParams is not valid
CUPTI_ERROR_INVALID_OPERATION – if range profiler CounterDataImageInitialize is called without enabling range profiler
CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiRangeProfilerDecodeData(CUpti_RangeProfiler_DecodeData_Params *pParams)

Decode the profiling data stored in the hardware to the counter data image passed in the SetConfig API.

This API should be called after cuptiRangeProfilerStop. The counter data image will be updated with the profiling data for the ranges profiled.

For the cases where the number of ranges counter data image can store is less than the number of ranges profiled (= maxRangesPerPass in SetConfig API), the counter data image will report dropped ranges.

Parameters

pParams – A pointer to CUpti_RangeProfiler_DecodeData_Params

Return values

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – if any pParams is not valid
CUPTI_ERROR_INVALID_OPERATION – if range profiler DecodeData is called without enabling range profiler
CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiRangeProfilerDisable(CUpti_RangeProfiler_Disable_Params *pParams)

Disable the range profiler on the CUDA context and destroy the range profiler object.

Parameters

pParams – A pointer to CUpti_RangeProfiler_Disable_Params

Return values

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – if any pParams is not valid

CUptiResult cuptiRangeProfilerEnable(CUpti_RangeProfiler_Enable_Params *pParams)

Create a range profiler object and enable range profiling on the CUDA context.

Parameters

pParams – A pointer to CUpti_RangeProfiler_Enable_Params

Return values

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – if any pParams is not valid
CUPTI_ERROR_OUT_OF_MEMORY – if memory allocation fails while creating the PM sampling object
CUPTI_ERROR_INSUFFICIENT_PRIVILEGES – if the user does not have sufficient privileges to perform the operation
CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiRangeProfilerGetCounterDataInfo(CUpti_RangeProfiler_GetCounterDataInfo_Params *pParams)

Get the number of ranges stored in the counter data image.

Parameters

pParams – A pointer to CUpti_RangeProfiler_GetCounterDataInfo_Params

Return values

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – if any pParams is not valid
CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiRangeProfilerGetCounterDataSize(CUpti_RangeProfiler_GetCounterDataSize_Params *pParams)

Get the size of the counter data image required to store the profiling data for the ranges profiled.

Parameters

pParams – A pointer to CUpti_RangeProfiler_GetCounterDataSize_Params

Return values

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – if any pParams is not valid
CUPTI_ERROR_INVALID_OPERATION – if range profiler GetCounterDataSize is called without enabling range profiler
CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiRangeProfilerPopRange(CUpti_RangeProfiler_PopRange_Params *pParams)

pop the current range to the Range Profiler.

The number of pop range API call should be same as number of push ranges in the same order.

Parameters

pParams – A pointer to CUpti_RangeProfiler_PopRange_Params

Return values

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – if any pParams is not valid
CUPTI_ERROR_INVALID_OPERATION – if range profiler PopRange is called without enabling range profiler
CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiRangeProfilerPushRange(CUpti_RangeProfiler_PushRange_Params *pParams)

Add a new range to the Range Profiler with a given range name.

For nested ranges, this API should be called again for the innermost range. For profiling the nested range, users need to set the values for minNestingLevel and numNestingLevels in the SetConfig API.

Parameters

pParams – A pointer to CUpti_RangeProfiler_PushRange_Params

Return values

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – if any pParams is not valid
CUPTI_ERROR_INVALID_OPERATION – if range profiler PushRange is called without enabling range profiler
CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiRangeProfilerSetConfig(CUpti_RangeProfiler_SetConfig_Params *pParams)

Set the configuration for range profiler like maximum number of ranges per pass, number of nesting levels, range and replay mode and the config image which has scheduling info for metric collection.

Parameters

pParams – A pointer to CUpti_RangeProfiler_SetConfig_Params

Return values

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – if any pParams is not valid

CUptiResult cuptiRangeProfilerStart(CUpti_RangeProfiler_Start_Params *pParams)

Start the range profiler.

Parameters

pParams – A pointer to CUpti_RangeProfiler_Start_Params

Return values

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – if any pParams is not valid
CUPTI_ERROR_INVALID_OPERATION – if range profiler Start is called without enabling range profiler
CUPTI_ERROR_UNKNOWN – for any internal error

CUptiResult cuptiRangeProfilerStop(CUpti_RangeProfiler_Stop_Params *pParams)

Stop the range profiler.

Parameters

pParams – A pointer to CUpti_RangeProfiler_Stop_Params

Return values

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – if any pParams is not valid
CUPTI_ERROR_INVALID_OPERATION – if range profiler Stop is called without enabling range profiler
CUPTI_ERROR_UNKNOWN – for any internal error

5.11.3. Typedefs

typedef struct CUpti_RangeProfiler_Object CUpti_RangeProfiler_Object