5.11. CUPTI 范围分析 API

实现 CUPTI 范围分析 API 的函数、类型和枚举。

数据结构

CUpti_RangeProfiler_CounterDataImage_Initialize_Params: cuptiRangeProfilerCounterDataImageInitialize 的参数。
CUpti_RangeProfiler_CounterData_GetRangeInfo_Params: cuptiRangeProfilerCounterDataGetRangeInfo 的参数。
CUpti_RangeProfiler_DecodeData_Params: cuptiRangeProfilerDecodeData 的参数。
CUpti_RangeProfiler_Disable_Params: cuptiRangeProfilerDisable 的参数。
CUpti_RangeProfiler_Enable_Params: cuptiRangeProfilerEnable 的参数。
CUpti_RangeProfiler_GetCounterDataInfo_Params: cuptiRangeProfilerGetCounterDataInfo 的参数。
CUpti_RangeProfiler_GetCounterDataSize_Params: cuptiRangeProfilerGetCounterDataSize 的参数。
CUpti_RangeProfiler_PopRange_Params: cuptiRangeProfilerPopRange 的参数。
CUpti_RangeProfiler_PushRange_Params: cuptiRangeProfilerPushRange 的参数。
CUpti_RangeProfiler_SetConfig_Params: cuptiRangeProfilerSetConfig 的参数。
CUpti_RangeProfiler_Start_Params: cuptiRangeProfilerStart 的参数。
CUpti_RangeProfiler_Stop_Params: cuptiRangeProfilerStop 的参数。

宏

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

函数

CUptiResult cuptiRangeProfilerCounterDataGetRangeInfo(CUpti_RangeProfiler_CounterData_GetRangeInfo_Params *pParams): 获取给定范围索引的范围名称。
CUptiResult cuptiRangeProfilerCounterDataImageInitialize(CUpti_RangeProfiler_CounterDataImage_Initialize_Params *pParams): 使用已分析范围的分析数据初始化计数器数据镜像。
CUptiResult cuptiRangeProfilerDecodeData(CUpti_RangeProfiler_DecodeData_Params *pParams): 将硬件中存储的分析数据解码到 SetConfig API 中传递的计数器数据镜像。
CUptiResult cuptiRangeProfilerDisable(CUpti_RangeProfiler_Disable_Params *pParams): 在 CUDA 上下文中禁用范围分析器并销毁范围分析器对象。
CUptiResult cuptiRangeProfilerEnable(CUpti_RangeProfiler_Enable_Params *pParams): 创建范围分析器对象并在 CUDA 上下文中启用范围分析。
CUptiResult cuptiRangeProfilerGetCounterDataInfo(CUpti_RangeProfiler_GetCounterDataInfo_Params *pParams): 获取计数器数据镜像中存储的范围数量。
CUptiResult cuptiRangeProfilerGetCounterDataSize(CUpti_RangeProfiler_GetCounterDataSize_Params *pParams): 获取存储已分析范围的分析数据所需的计数器数据镜像的大小。
CUptiResult cuptiRangeProfilerPopRange(CUpti_RangeProfiler_PopRange_Params *pParams): 将当前范围弹出到范围分析器。
CUptiResult cuptiRangeProfilerPushRange(CUpti_RangeProfiler_PushRange_Params *pParams): 使用给定的范围名称向范围分析器添加新范围。
CUptiResult cuptiRangeProfilerSetConfig(CUpti_RangeProfiler_SetConfig_Params *pParams): 设置范围分析器的配置，例如每次 Pass 的最大范围数、嵌套级别数、范围和重放模式，以及具有指标收集调度信息的配置镜像。
CUptiResult cuptiRangeProfilerStart(CUpti_RangeProfiler_Start_Params *pParams): 启动范围分析器。
CUptiResult cuptiRangeProfilerStop(CUpti_RangeProfiler_Stop_Params *pParams): 停止范围分析器。

类型定义

CUpti_RangeProfiler_Object

变量

size_t CUpti_RangeProfiler_CounterDataImage_Initialize_Params::counterDataSize: [in] 计数器数据镜像的大小。
uint8_t * CUpti_RangeProfiler_CounterDataImage_Initialize_Params::pCounterData: [in] 计数器数据镜像。
void * CUpti_RangeProfiler_CounterDataImage_Initialize_Params::pPriv: [in] 设置为 NULL。
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_CounterDataImage_Initialize_Params::pRangeProfilerObject: [in] 周期采样器对象。
size_t CUpti_RangeProfiler_CounterDataImage_Initialize_Params::structSize: [in] 数据结构的大小。
size_t CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::counterDataImageSize: [in] 计数器数据镜像的大小。
const uint8_t * CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::pCounterDataImage: [in] 计数器数据镜像。
void * CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::pPriv: [in] 设置为 NULL。
const char * CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::rangeDelimiter: [in] 范围分隔符。
size_t CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::rangeIndex: [in] 采样的索引。
const char * CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::rangeName: [out] 范围名称;
size_t CUpti_RangeProfiler_CounterData_GetRangeInfo_Params::structSize: [in] 数据结构的大小。
size_t CUpti_RangeProfiler_DecodeData_Params::numOfRangeDropped: [out] 在已处理的 Pass 中丢弃的范围数量。
void * CUpti_RangeProfiler_DecodeData_Params::pPriv: [in] 设置为 NULL。
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_DecodeData_Params::pRangeProfilerObject: [in] 范围分析器对象。
size_t CUpti_RangeProfiler_DecodeData_Params::structSize: [in] 数据结构的大小。
void * CUpti_RangeProfiler_Disable_Params::pPriv: [in] 设置为 NULL。
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_Disable_Params::pRangeProfilerObject: [in] 范围分析器对象。
size_t CUpti_RangeProfiler_Disable_Params::structSize: [in] 数据结构的大小。
CUcontext CUpti_RangeProfiler_Enable_Params::ctx: [in] 用于分析的上下文。
void * CUpti_RangeProfiler_Enable_Params::pPriv: [in] 设置为 NULL。
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_Enable_Params::pRangeProfilerObject: [out] 范围分析器对象。
size_t CUpti_RangeProfiler_Enable_Params::structSize: [in] 数据结构的大小。
size_t CUpti_RangeProfiler_GetCounterDataInfo_Params::counterDataImageSize: [in] 计数器数据镜像的大小。
size_t CUpti_RangeProfiler_GetCounterDataInfo_Params::numTotalRanges: [out] 计数器数据镜像中的范围数量。
const uint8_t * CUpti_RangeProfiler_GetCounterDataInfo_Params::pCounterDataImage: [in] 计数器数据镜像。
void * CUpti_RangeProfiler_GetCounterDataInfo_Params::pPriv: [in] 设置为 NULL。
size_t CUpti_RangeProfiler_GetCounterDataInfo_Params::structSize: [in] 数据结构的大小。
size_t CUpti_RangeProfiler_GetCounterDataSize_Params::counterDataSize: [out] 计数器数据镜像的大小。
size_t CUpti_RangeProfiler_GetCounterDataSize_Params::maxNumOfRanges: [in] 要存储在计数器数据镜像中的最大范围数。
uint32_t CUpti_RangeProfiler_GetCounterDataSize_Params::maxNumRangeTreeNodes: [in] RangeTree 节点的最大数量；必须 >= maxNumOfRanges
size_t CUpti_RangeProfiler_GetCounterDataSize_Params::numMetrics: [in] 要收集的指标数量。
const char ** CUpti_RangeProfiler_GetCounterDataSize_Params::pMetricNames: [in] 要收集的指标的名称。
void * CUpti_RangeProfiler_GetCounterDataSize_Params::pPriv: [in] 设置为 NULL。
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_GetCounterDataSize_Params::pRangeProfilerObject: [in] 周期采样器对象。
size_t CUpti_RangeProfiler_GetCounterDataSize_Params::structSize: [in] 数据结构的大小。
void * CUpti_RangeProfiler_PopRange_Params::pPriv: [in] 设置为 NULL。
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_PopRange_Params::pRangeProfilerObject: [in] 范围分析器对象。
size_t CUpti_RangeProfiler_PopRange_Params::structSize: [in] 数据结构的大小。
void * CUpti_RangeProfiler_PushRange_Params::pPriv: [in] 设置为 NULL。
const char * CUpti_RangeProfiler_PushRange_Params::pRangeName: [in] 要分析的范围的名称（仅对用户范围模式有效）。
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_PushRange_Params::pRangeProfilerObject: [in] 范围分析器对象。
size_t CUpti_RangeProfiler_PushRange_Params::structSize: [in] 数据结构的大小。
size_t CUpti_RangeProfiler_SetConfig_Params::configSize: [in] 配置镜像的大小。
size_t CUpti_RangeProfiler_SetConfig_Params::counterDataImageSize: [in] 计数器数据镜像的大小。
size_t CUpti_RangeProfiler_SetConfig_Params::maxRangesPerPass: [in] 一次 Pass 中可以分析的最大范围数。
uint16_t CUpti_RangeProfiler_SetConfig_Params::minNestingLevel: [in] 要分析的最小嵌套级别。
uint16_t CUpti_RangeProfiler_SetConfig_Params::numNestingLevels: [in] 要分析的嵌套级别数。对于自动范围模式，应设置为 1。
const uint8_t * CUpti_RangeProfiler_SetConfig_Params::pConfig: [in] 配置镜像。
uint8_t * CUpti_RangeProfiler_SetConfig_Params::pCounterDataImage: [in] 计数器数据镜像。
void * CUpti_RangeProfiler_SetConfig_Params::pPriv: [in] 设置为 NULL。
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_SetConfig_Params::pRangeProfilerObject: [in] 范围分析器对象。
size_t CUpti_RangeProfiler_SetConfig_Params::passIndex: [in] 重放会话的 Pass 索引。
CUpti_ProfilerRange CUpti_RangeProfiler_SetConfig_Params::range: [in] 分析范围模式。
CUpti_ProfilerReplayMode CUpti_RangeProfiler_SetConfig_Params::replayMode: [in] 重放模式。
size_t CUpti_RangeProfiler_SetConfig_Params::structSize: [in] 数据结构的大小。
uint16_t CUpti_RangeProfiler_SetConfig_Params::targetNestingLevel: [in] 重放会话的目标嵌套级别。
void * CUpti_RangeProfiler_Start_Params::pPriv: [in] 设置为 NULL。
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_Start_Params::pRangeProfilerObject: [in] 范围分析器对象。
size_t CUpti_RangeProfiler_Start_Params::structSize: [in] 数据结构的大小。
uint8_t CUpti_RangeProfiler_Stop_Params::isAllPassSubmitted: [out] 如果所有 pass 都已提交到 GPU 进行收集，则为 1，否则为 0。
void * CUpti_RangeProfiler_Stop_Params::pPriv: [in] 设置为 NULL。
CUpti_RangeProfiler_Object * CUpti_RangeProfiler_Stop_Params::pRangeProfilerObject: [in] 范围分析器对象。
size_t CUpti_RangeProfiler_Stop_Params::passIndex: [out] 重放会话的 pass 索引。
size_t CUpti_RangeProfiler_Stop_Params::structSize: [in] 数据结构的大小。
size_t CUpti_RangeProfiler_Stop_Params::targetNestingLevel: [out] 重放会话的目标嵌套级别。

5.11.1. 宏

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. 函数

CUptiResult cuptiRangeProfilerCounterDataGetRangeInfo(CUpti_RangeProfiler_CounterData_GetRangeInfo_Params *pParams)

获取给定范围索引的范围名称。

参数

pParams – 指向 CUpti_RangeProfiler_CounterData_GetRangeInfo_Params 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_UNKNOWN – 对于任何内部错误

CUptiResult cuptiRangeProfilerCounterDataImageInitialize(CUpti_RangeProfiler_CounterDataImage_Initialize_Params *pParams)

使用已分析范围的分析数据初始化计数器数据镜像。

参数

pParams – 指向 CUpti_RangeProfiler_CounterDataImage_Initialize_Params 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_INVALID_OPERATION – 如果在未启用范围分析器的情况下调用范围分析器 CounterDataImageInitialize
CUPTI_ERROR_UNKNOWN – 对于任何内部错误

CUptiResult cuptiRangeProfilerDecodeData(CUpti_RangeProfiler_DecodeData_Params *pParams)

将硬件中存储的分析数据解码到 SetConfig API 中传递的计数器数据镜像。

此 API 应在 cuptiRangeProfilerStop 之后调用。计数器数据镜像将使用已分析范围的分析数据进行更新。

对于计数器数据镜像可以存储的范围数量少于已分析范围数量（= SetConfig API 中的 maxRangesPerPass）的情况，计数器数据镜像将报告丢弃的范围。

参数

pParams – 指向 CUpti_RangeProfiler_DecodeData_Params 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_INVALID_OPERATION – 如果在未启用范围分析器的情况下调用范围分析器 DecodeData
CUPTI_ERROR_UNKNOWN – 对于任何内部错误

CUptiResult cuptiRangeProfilerDisable(CUpti_RangeProfiler_Disable_Params *pParams)

在 CUDA 上下文中禁用范围分析器并销毁范围分析器对象。

参数

pParams – 指向 CUpti_RangeProfiler_Disable_Params 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效

CUptiResult cuptiRangeProfilerEnable(CUpti_RangeProfiler_Enable_Params *pParams)

创建范围分析器对象并在 CUDA 上下文中启用范围分析。

参数

pParams – 指向 CUpti_RangeProfiler_Enable_Params 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_OUT_OF_MEMORY – 如果在创建 PM 采样对象时内存分配失败
CUPTI_ERROR_INSUFFICIENT_PRIVILEGES – 如果用户没有足够的权限来执行操作
CUPTI_ERROR_UNKNOWN – 对于任何内部错误

CUptiResult cuptiRangeProfilerGetCounterDataInfo(CUpti_RangeProfiler_GetCounterDataInfo_Params *pParams)

获取计数器数据镜像中存储的范围数量。

参数

pParams – 指向 CUpti_RangeProfiler_GetCounterDataInfo_Params 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_UNKNOWN – 对于任何内部错误

CUptiResult cuptiRangeProfilerGetCounterDataSize(CUpti_RangeProfiler_GetCounterDataSize_Params *pParams)

获取存储已分析范围的分析数据所需的计数器数据镜像的大小。

参数

pParams – 指向 CUpti_RangeProfiler_GetCounterDataSize_Params 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_INVALID_OPERATION – 如果在未启用范围分析器的情况下调用范围分析器 GetCounterDataSize
CUPTI_ERROR_UNKNOWN – 对于任何内部错误

CUptiResult cuptiRangeProfilerPopRange(CUpti_RangeProfiler_PopRange_Params *pParams)

将当前范围弹出到范围分析器。

弹出范围 API 调用的次数应与推送范围的次数相同，且顺序相同。

参数

pParams – 指向 CUpti_RangeProfiler_PopRange_Params 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_INVALID_OPERATION – 如果在未启用范围分析器的情况下调用范围分析器 PopRange
CUPTI_ERROR_UNKNOWN – 对于任何内部错误

CUptiResult cuptiRangeProfilerPushRange(CUpti_RangeProfiler_PushRange_Params *pParams)

使用给定的范围名称向范围分析器添加新范围。

对于嵌套范围，应再次为最内层范围调用此 API。为了分析嵌套范围，用户需要在 SetConfig API 中设置 minNestingLevel 和 numNestingLevels 的值。

参数

pParams – 指向 CUpti_RangeProfiler_PushRange_Params 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_INVALID_OPERATION – 如果在未启用范围分析器的情况下调用 PushRange，则会发生此错误
CUPTI_ERROR_UNKNOWN – 对于任何内部错误

CUptiResult cuptiRangeProfilerSetConfig(CUpti_RangeProfiler_SetConfig_Params *pParams)

设置范围分析器的配置，例如每次 Pass 的最大范围数、嵌套级别数、范围和重放模式，以及具有指标收集调度信息的配置镜像。

参数

pParams – 指向 CUpti_RangeProfiler_SetConfig_Params 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效

CUptiResult cuptiRangeProfilerStart(CUpti_RangeProfiler_Start_Params *pParams)

启动范围分析器。

参数

pParams – 指向 CUpti_RangeProfiler_Start_Params 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_INVALID_OPERATION – 如果在未启用范围分析器的情况下调用 Start，则会发生此错误
CUPTI_ERROR_UNKNOWN – 对于任何内部错误

CUptiResult cuptiRangeProfilerStop(CUpti_RangeProfiler_Stop_Params *pParams)

停止范围分析器。

参数

pParams – 指向 CUpti_RangeProfiler_Stop_Params 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_INVALID_OPERATION – 如果在未启用范围分析器的情况下调用 Stop，则会发生此错误
CUPTI_ERROR_UNKNOWN – 对于任何内部错误

5.11.3. 类型定义

typedef struct CUpti_RangeProfiler_Object CUpti_RangeProfiler_Object