5.6. CUPTI PC 采样 API

实现 CUPTI PC 采样 API 的函数、类型和枚举。

数据结构

CUpti_GetCubinCrcParams: cuptiGetCubinCrc 的参数。
CUpti_GetSassToSourceCorrelationParams: cuptiGetSassToSourceCorrelation 的参数。
CUpti_PCSamplingConfigurationInfo: PC 采样配置信息结构。
CUpti_PCSamplingConfigurationInfoParams: PC 采样配置结构。
CUpti_PCSamplingData: 收集的 PC 采样数据。
CUpti_PCSamplingDisableParams: cuptiPCSamplingDisable 的参数。
CUpti_PCSamplingEnableParams: cuptiPCSamplingEnable 的参数。
CUpti_PCSamplingGetDataParams: cuptiPCSamplingEnable 的参数。
CUpti_PCSamplingGetNumStallReasonsParams: cuptiPCSamplingGetNumStallReasons 的参数。
CUpti_PCSamplingGetStallReasonsParams: cuptiPCSamplingGetStallReasons 的参数。
CUpti_PCSamplingPCData: PC 采样数据。
CUpti_PCSamplingStallReason: PC 采样停顿原因。
CUpti_PCSamplingStartParams: cuptiPCSamplingStart 的参数。
CUpti_PCSamplingStopParams: cuptiPCSamplingStop 的参数。

宏

CUPTI_STALL_REASON_STRING_SIZE
CUpti_GetCubinCrcParamsSize
CUpti_GetSassToSourceCorrelationParamsSize
CUpti_PCSamplingConfigurationInfoParamsSize
CUpti_PCSamplingDisableParamsSize
CUpti_PCSamplingEnableParamsSize
CUpti_PCSamplingGetDataParamsSize
CUpti_PCSamplingGetNumStallReasonsParamsSize
CUpti_PCSamplingGetStallReasonsParamsSize
CUpti_PCSamplingStartParamsSize
CUpti_PCSamplingStopParamsSize

枚举

CUpti_PCSamplingCollectionMode: PC 采样收集模式。
CUpti_PCSamplingConfigurationAttributeType: PC 采样配置属性。
CUpti_PCSamplingOutputDataFormat: PC 采样输出数据格式。

函数

CUptiResult cuptiGetCubinCrc(CUpti_GetCubinCrcParams *pParams): 获取 cubin 的 CRC。
CUptiResult cuptiGetSassToSourceCorrelation(CUpti_GetSassToSourceCorrelationParams *pParams): SASS 到源代码关联。
CUptiResult cuptiPCSamplingDisable(CUpti_PCSamplingDisableParams *pParams): 禁用 PC 采样。
CUptiResult cuptiPCSamplingEnable(CUpti_PCSamplingEnableParams *pParams): 启用 PC 采样。
CUptiResult cuptiPCSamplingGetConfigurationAttribute(CUpti_PCSamplingConfigurationInfoParams *pParams): 读取 PC 采样配置属性。
CUptiResult cuptiPCSamplingGetData(CUpti_PCSamplingGetDataParams *pParams): 定期刷新 GPU PC 采样数据。
CUptiResult cuptiPCSamplingGetNumStallReasons(CUpti_PCSamplingGetNumStallReasonsParams *pParams): 获取 PC 采样停顿原因计数。
CUptiResult cuptiPCSamplingGetStallReasons(CUpti_PCSamplingGetStallReasonsParams *pParams): 获取 PC 采样停顿原因。
CUptiResult cuptiPCSamplingSetConfigurationAttribute(CUpti_PCSamplingConfigurationInfoParams *pParams): 写入 PC 采样配置属性。
CUptiResult cuptiPCSamplingStart(CUpti_PCSamplingStartParams *pParams): 启动 PC 采样。
CUptiResult cuptiPCSamplingStop(CUpti_PCSamplingStopParams *pParams): 停止 PC 采样。
CUptiResult cuptiRegisterComputeCrcCallback(CUpti_ComputeCrcCallbackFunc funcComputeCubinCrc): 向 CUPTI 注册回调函数，以使用您自己的算法来计算 cubin crc。

类型定义

CUpti_ComputeCrcCallbackFunc: CUPTI 使用的回调函数类型，用于请求已加载模块的 crc。

5.6.1. 宏

CUPTI_STALL_REASON_STRING_SIZE

CUpti_GetCubinCrcParamsSize

CUpti_GetSassToSourceCorrelationParamsSize

CUpti_PCSamplingConfigurationInfoParamsSize

CUpti_PCSamplingDisableParamsSize

CUpti_PCSamplingEnableParamsSize

CUpti_PCSamplingGetDataParamsSize

CUpti_PCSamplingGetNumStallReasonsParamsSize

CUpti_PCSamplingGetStallReasonsParamsSize

CUpti_PCSamplingStartParamsSize

CUpti_PCSamplingStopParamsSize

5.6.2. 枚举

enum CUpti_PCSamplingCollectionMode

PC 采样收集模式。

值

enumerator CUPTI_PC_SAMPLING_COLLECTION_MODE_INVALID: 无效值。

enumerator CUPTI_PC_SAMPLING_COLLECTION_MODE_CONTINUOUS

连续模式。

在此模式下，内核不会被序列化。

enumerator CUPTI_PC_SAMPLING_COLLECTION_MODE_KERNEL_SERIALIZED

序列化模式。

在此模式下，内核会被序列化。

enum CUpti_PCSamplingConfigurationAttributeType

PC 采样配置属性。

PC 采样配置属性类型。这些属性可以使用 cuptiPCSamplingGetConfigurationAttribute 读取，并且可以使用 cuptiPCSamplingSetConfigurationAttribute 写入。标记为 [r] 的属性只能使用 cuptiPCSamplingGetConfigurationAttribute 读取，[w] 只能使用 cuptiPCSamplingSetConfigurationAttribute 写入，[rw] 可以使用 cuptiPCSamplingGetConfigurationAttribute 读取，并使用 cuptiPCSamplingSetConfigurationAttribute 写入

值

enumerator CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_INVALID

enumerator CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_SAMPLING_PERIOD

[rw] PC 采样的采样周期。

默认值 - CUPTI 基于 SM 数量定义的数值。有效采样周期值在 5 到 31 之间（包括 5 和 31）。这将采样周期设置为 (2^samplingPeriod) 个周期。例如，对于采样周期 = 5 到 31，周期 = 32, 64, 128,…, 2^31。值类型为 uint32_t。

enumerator CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_STALL_REASON

[w] 要收集的停顿原因数量。

默认值 - 将收集所有停顿原因。值类型为 size_t。[w] 要收集的停顿原因。默认值 - 将收集所有停顿原因。输入值应是指向停顿原因索引数组的指针，该数组包含要收集的所有停顿原因索引。

enumerator CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_SCRATCH_BUFFER_SIZE

[rw] 用于从 HW 缓冲区下载的原始 PC 计数器数据的 SW 缓冲区大小。默认值 - 1 MB，大约可容纳 5500 个 PC 和所有停顿原因。大致需要 16 字节（以及一些固定大小的内存）来容纳一个 PC 和一个停顿原因。例如：

1 个 PC 和 1 个停顿原因 = 32 字节，1 个 PC 和 2 个停顿原因 = 48 字节，1 个 PC 和 4 个停顿原因 = 96 字节。值类型为 size_t。

enumerator CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_HARDWARE_BUFFER_SIZE: [rw] HW 缓冲区大小，以字节为单位。默认值 - 512 MB。如果采样周期太短，HW 缓冲区可能会溢出并丢弃 PC 数据。值类型为 size_t。

enumerator CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_COLLECTION_MODE: [rw] PC 采样收集模式。默认值 - CUPTI_PC_SAMPLING_COLLECTION_MODE_CONTINUOUS。输入值应为 CUpti_PCSamplingCollectionMode 类型。

enumerator CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_ENABLE_START_STOP_CONTROL: [rw] PC 采样数据收集范围的控制。默认值 - 0。1 - 允许用户使用 API 启动和停止 PC 采样 - cuptiPCSamplingStart() - 启动 PC 采样，cuptiPCSamplingStop() - 停止 PC 采样。值类型为 uint32_t。

enumerator CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_OUTPUT_DATA_FORMAT: [w] 输出数据格式的值。默认值 - CUPTI_PC_SAMPLING_OUTPUT_DATA_FORMAT_PARSED。输入值应为 CUpti_PCSamplingOutputDataFormat 类型。

enumerator CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_SAMPLING_DATA_BUFFER

[w] 用于保存收集的 PC 采样数据 PARSED_DATA 的数据缓冲区。默认值 - 无。

缓冲区类型为 void *，可以指向 PARSED_DATA。有关 PARSED_DATA 的缓冲区格式，请参阅 CUpti_PCSamplingData。

enumerator CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_WORKER_THREAD_PERIODIC_SLEEP_SPAN

[rw] 控制 CUPTI 为各种 PC 采样操作创建的工作线程的睡眠时间。

CUPTI 创建多个工作线程，以将某些操作卸载到这些线程。这包括将 HW 数据解码为 CUPTI PC 采样数据，以及将 PC 数据与 SASS 指令关联。CUPTI 定期唤醒这些线程。默认值 - 100 毫秒。值类型为 uint32_t。

enumerator CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_FORCE_INT

enum CUpti_PCSamplingOutputDataFormat

PC 采样输出数据格式。

值

enumerator CUPTI_PC_SAMPLING_OUTPUT_DATA_FORMAT_INVALID

enumerator CUPTI_PC_SAMPLING_OUTPUT_DATA_FORMAT_PARSED: HW 缓冲区数据将在数据收集期间进行解析。

5.6.3. 函数

CUptiResult cuptiGetCubinCrc(CUpti_GetCubinCrcParams *pParams)

获取 cubin 的 CRC。

此函数返回提供的 cubin 二进制文件的 CRC。

参数

pParams – 指向 CUpti_GetCubinCrcParams 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果参数 cubin 为 NULL 或提供的 cubinSize 为零或 size 字段未设置。

CUptiResult cuptiGetSassToSourceCorrelation(CUpti_GetSassToSourceCorrelationParams *pParams)

SASS 到源代码关联。

用户需要在使用后释放为 fileName 和 dirName 分配的内存。

参数

pParams – 指向 CUpti_GetSassToSourceCorrelationParams 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果参数 cubin 或 functionName 之一为 NULL，或者 cubinSize 为零，或者 size 字段设置不正确。
CUPTI_ERROR_INVALID_MODULE – 提供的 cubin 无效。
CUPTI_ERROR_UNKNOWN – 发生内部错误。当模块中不存在该函数时，也会使用此错误代码。未来版本中将返回更好的错误代码。

CUptiResult cuptiPCSamplingDisable(CUpti_PCSamplingDisableParams *pParams)

禁用 PC 采样。

对于不显式销毁 CUDA 上下文的应用程序，此 API 执行 PC 采样终止操作，加入线程，并将 PC 记录复制到 PC 采样配置期间提供的缓冲区中。无法容纳在缓冲区中的 PC 记录将被丢弃。

参数

pParams – 指向 CUpti_PCSamplingDisableParams 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_NOT_SUPPORTED – 表示系统/设备不支持此 API

CUptiResult cuptiPCSamplingEnable(CUpti_PCSamplingEnableParams *pParams)

启用 PC 采样。

参数

pParams – 指向 CUpti_PCSamplingEnableParams 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_NOT_SUPPORTED – 表示系统/设备不支持此 API

CUptiResult cuptiPCSamplingGetConfigurationAttribute(CUpti_PCSamplingConfigurationInfoParams *pParams)

读取 PC 采样配置属性。

参数

pParams – 指向 CUpti_PCSamplingConfigurationInfoParams 的指针，其中包含 PC 采样配置。

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_OPERATION – 如果使用某些无效属性调用此 API。
CUPTI_ERROR_INVALID_PARAMETER – 如果 attrib 无效或任何 pParams 无效
CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT – 表示 value 缓冲区太小，无法容纳属性值
CUPTI_ERROR_NOT_SUPPORTED – 表示系统/设备不支持此 API

CUptiResult cuptiPCSamplingGetData(CUpti_PCSamplingGetDataParams *pParams)

定期刷新 GPU PC 采样数据。

在以下时间点需要刷新 GPU PC 采样数据，以保持 PC 的唯一性：对于 CUPTI_PC_SAMPLING_COLLECTION_MODE_CONTINUOUS，在每次模块加载-卸载-加载之后；对于 CUPTI_PC_SAMPLING_COLLECTION_MODE_KERNEL_SERIALIZED，在每个内核结束后；如果配置选项 CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_ENABLE_START_STOP_CONTROL 已启用，则在每个范围结束后，即 cuptiPCSamplingStop()。

如果应用程序在 CUPTI_PC_SAMPLING_COLLECTION_MODE_CONTINUOUS 中进行分析，并且禁用了

CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_ENABLE_START_STOP_CONTROL，并且没有模块卸载，则用户可以通过两种方式收集数据：定期使用 cuptiPCSamplingGetData() API；在应用程序退出时使用 cuptiPCSamplingDisable()，并从配置期间传递的采样数据缓冲区中读取 GPU PC 采样数据。注意：如果未定期调用 cuptiPCSamplingGetData() API，则配置期间传递的采样数据缓冲区应足够大以容纳所有 PC 数据。

cuptiPCSamplingGetData() API 永远不会执行设备同步。当调用此 API 时，硬件缓冲区中可能存在一些未消耗的数据。在这种情况下，CUPTI 仅提供当时可用的数据。

参数

pParams – 指向 CUpti_PCSamplingGetDataParams 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_OPERATION – 如果在未启用 PC 采样的情况下调用此 API。
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_NOT_SUPPORTED – 表示系统/设备
CUPTI_ERROR_OUT_OF_MEMORY – 表示硬件缓冲区已满，不支持此 API

CUptiResult cuptiPCSamplingGetNumStallReasons(CUpti_PCSamplingGetNumStallReasonsParams *pParams)

获取 PC 采样停顿原因计数。

参数

pParams – 指向 CUpti_PCSamplingGetNumStallReasonsParams 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_NOT_SUPPORTED – 表示系统/设备不支持此 API

CUptiResult cuptiPCSamplingGetStallReasons(CUpti_PCSamplingGetStallReasonsParams *pParams)

获取 PC 采样停顿原因。

参数

pParams – 指向 CUpti_PCSamplingGetStallReasonsParams 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_NOT_SUPPORTED – 表示系统/设备不支持此 API

CUptiResult cuptiPCSamplingSetConfigurationAttribute(CUpti_PCSamplingConfigurationInfoParams *pParams)

写入 PC 采样配置属性。

参数

pParams – 指向 CUpti_PCSamplingConfigurationInfoParams 的指针，其中包含 PC 采样配置。

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_OPERATION – 如果使用一些无效的 attrib 调用此 API。
CUPTI_ERROR_INVALID_PARAMETER – 如果属性 value 无效或任何 pParams 无效
CUPTI_ERROR_NOT_SUPPORTED – 表示系统/设备不支持此 API

CUptiResult cuptiPCSamplingStart(CUpti_PCSamplingStartParams *pParams)

启动 PC 采样。

用户可以为 Start/Stop API 指定的用户定义范围收集 PC 采样数据。此 API 可用于标记范围的开始。设置配置选项

CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_ENABLE_START_STOP_CONTROL 以使用此 API。

参数

pParams – 指向 CUpti_PCSamplingStartParams 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_OPERATION – 如果使用不正确的 PC 采样配置调用此 API。
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_NOT_SUPPORTED – 表示系统/设备不支持此 API

CUptiResult cuptiPCSamplingStop(CUpti_PCSamplingStopParams *pParams)

停止 PC 采样。

用户可以为 Start/Stop API 指定的用户定义范围收集 PC 采样数据。此 API 可用于标记范围的结束。设置配置选项

CUPTI_PC_SAMPLING_CONFIGURATION_ATTR_TYPE_ENABLE_START_STOP_CONTROL 以使用此 API。

参数

pParams – 指向 CUpti_PCSamplingStopParams 的指针

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_OPERATION – 如果使用不正确的 PC 采样配置调用此 API。
CUPTI_ERROR_INVALID_PARAMETER – 如果任何 pParams 无效
CUPTI_ERROR_NOT_SUPPORTED – 表示系统/设备不支持此 API

CUptiResult cuptiRegisterComputeCrcCallback(CUpti_ComputeCrcCallbackFunc funcComputeCubinCrc)

向 CUPTI 注册回调函数，以使用您自己的算法来计算 cubin crc。

此函数注册一个回调函数，并在加载 CUDA 模块时从 CUPTI 调用该函数。

参数

funcComputeCubinCrc – 当加载 CUDA 模块时调用此回调。

返回值

CUPTI_SUCCESS –
CUPTI_ERROR_INVALID_PARAMETER – 如果 funcComputeCubinCrc 为 NULL。

5.6.4. 类型定义

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

CUPTI 使用的回调函数类型，用于请求已加载模块的 crc。

此回调函数请求函数中提供的模块的 CRC。提供的 CRC 将存储在 PC 采样记录中，即 PC 采样结构 CUpti_PCSamplingPCData 的 ‘cubinCrc’ 字段中。CRC 在离线源关联期间使用，以唯一标识模块。

参数 cubin: 指向 cubin 二进制文件的指针
参数 cubinSize: cubin 二进制文件的大小。
参数 cubinCrc: 返回 cubin 的计算出的 CRC。