5.7. CUPTI PC Sampling Utility API

实现 CUPTI PC Sampling Utility API 的函数、类型和枚举。

数据结构

CUPTI::PcSamplingUtil::BufferInfo: BufferInfo 将为每个缓冲区存储在文件中，即对于 UtilDumpPcSamplingBufferInFile() API 的每次调用。
CUPTI::PcSamplingUtil::CUptiUtil_GetBufferInfoParams: CuptiUtilGetBufferInfo 的参数。
CUPTI::PcSamplingUtil::CUptiUtil_GetHeaderDataParams: CuptiUtilGetHeaderData 的参数。
CUPTI::PcSamplingUtil::CUptiUtil_GetPcSampDataParams: CuptiUtilGetPcSampData 的参数。
CUPTI::PcSamplingUtil::CUptiUtil_MergePcSampDataParams: CuptiUtilMergePcSampData 的参数。
CUPTI::PcSamplingUtil::CUptiUtil_PutPcSampDataParams: CuptiUtilPutPcSampData 的参数。
CUPTI::PcSamplingUtil::Header: Header 信息将存储在文件中。
CUPTI::PcSamplingUtil::PcSamplingStallReasons: 所有可用的停顿原因名称和相应的索引将存储在其中。

宏

CUptiUtil_GetBufferInfoParamsSize
CUptiUtil_GetHeaderDataParamsSize
CUptiUtil_GetPcSampDataParamsSize
CUptiUtil_MergePcSampDataParamsSize
CUptiUtil_PutPcSampDataParamsSize

枚举

CUPTI::PcSamplingUtil::CUptiUtilResult: CUPTI PC 采样实用程序 API 结果代码。
CUPTI::PcSamplingUtil::PcSamplingBufferType: CUPTI PC 采样缓冲区类型。

函数

CUptiUtilResult CUPTI::PcSamplingUtil::CuptiUtilGetBufferInfo(CUptiUtil_GetBufferInfoParams *pParams): 获取文件的缓冲区信息数据。
CUptiUtilResult CUPTI::PcSamplingUtil::CuptiUtilGetHeaderData(CUptiUtil_GetHeaderDataParams *pParams): 获取文件的标头数据。
CUptiUtilResult CUPTI::PcSamplingUtil::CuptiUtilGetPcSampData(CUptiUtil_GetPcSampDataParams *pParams): 从文件检索 PC 采样数据到已分配的缓冲区中。
CUptiUtilResult CUPTI::PcSamplingUtil::CuptiUtilMergePcSampData(CUptiUtil_MergePcSampDataParams *pParams): 按范围 ID 合并 PC 采样数据。
CUptiUtilResult CUPTI::PcSamplingUtil::CuptiUtilPutPcSampData(CUptiUtil_PutPcSampDataParams *pParams): 将 PC 采样数据转储到文件中。

5.7.1. 宏

CUptiUtil_GetBufferInfoParamsSize

CUptiUtil_GetHeaderDataParamsSize

CUptiUtil_GetPcSampDataParamsSize

CUptiUtil_MergePcSampDataParamsSize

CUptiUtil_PutPcSampDataParamsSize

5.7.2. 枚举

enum CUPTI::PcSamplingUtil::CUptiUtilResult

CUPTI PC 采样实用程序 API 结果代码。

CUPTI PC 采样实用程序 API 返回的错误和结果代码。

值

enumerator CUPTI_UTIL_SUCCESS: 没有错误。

enumerator CUPTI_UTIL_ERROR_INVALID_PARAMETER: 一个或多个参数无效。

enumerator CUPTI_UTIL_ERROR_UNABLE_TO_CREATE_FILE: 无法创建新文件。

enumerator CUPTI_UTIL_ERROR_UNABLE_TO_OPEN_FILE: 无法打开文件。

enumerator CUPTI_UTIL_ERROR_READ_WRITE_OPERATION_FAILED: 读取或写入操作失败。

enumerator CUPTI_UTIL_ERROR_FILE_HANDLE_CORRUPTED: 提供的文件句柄已损坏。

enumerator CUPTI_UTIL_ERROR_SEEK_OPERATION_FAILED: seek 操作失败。

enumerator CUPTI_UTIL_ERROR_OUT_OF_MEMORY: 无法分配足够的内存来执行请求的操作。

enumerator CUPTI_UTIL_ERROR_UNKNOWN: 发生未知内部错误。

enumerator CUPTI_UTIL_ERROR_FORCE_INT

enum CUPTI::PcSamplingUtil::PcSamplingBufferType

CUPTI PC 采样缓冲区类型。

值

enumerator PC_SAMPLING_BUFFER_INVALID: 无效的缓冲区类型。

enumerator PC_SAMPLING_BUFFER_PC_TO_COUNTER_DATA: 指 CUpti_PCSamplingData 缓冲区。

5.7.3. 函数

CUptiUtilResult CUPTI::PcSamplingUtil::CuptiUtilGetBufferInfo(CUptiUtil_GetBufferInfoParams *pParams)

获取文件的缓冲区信息数据。

每次调用 CuptiUtilGetPcSampData API 之前都必须调用此 API。BufferInfo 结构，它提供有关缓冲区中每个记录的 recordCount 和 stallReasonCount 的信息。这将有助于分配确切的缓冲区以在其中检索数据。

返回值

CUPTI_UTIL_SUCCESS –
CUPTI_UTIL_ERROR_INVALID_PARAMETER – 如果 pParam 或 fileHandle 为 NULL，或者参数结构大小不正确，则会报错。
CUPTI_UTIL_ERROR_FILE_HANDLE_CORRUPTED – 文件句柄状态不佳，无法从文件中读取数据。
CUPTI_UTIL_ERROR_READ_WRITE_OPERATION_FAILED – 无法从文件中读取数据。

CUptiUtilResult CUPTI::PcSamplingUtil::CuptiUtilGetHeaderData(CUptiUtil_GetHeaderDataParams *pParams)

获取文件的标头数据。

从文件检索数据时，最初必须调用此 API 一次。Header 结构，它提供有关文件中存在的缓冲区总数的信息。

返回值

CUPTI_UTIL_SUCCESS –
CUPTI_UTIL_ERROR_INVALID_PARAMETER – 如果 pParam 或 fileHandle 为 NULL，或者参数结构大小不正确，则会报错。
CUPTI_UTIL_ERROR_FILE_HANDLE_CORRUPTED – 文件句柄状态不佳，无法从文件中读取数据
CUPTI_UTIL_ERROR_READ_WRITE_OPERATION_FAILED – 无法从文件中读取数据。

CUptiUtilResult CUPTI::PcSamplingUtil::CuptiUtilGetPcSampData(CUptiUtil_GetPcSampDataParams *pParams)

从文件检索 PC 采样数据到已分配的缓冲区中。

必须在 CuptiUtilGetBufferInfo API 之后调用此 API。它将从文件检索数据到已分配的缓冲区中。

返回值

CUPTI_UTIL_SUCCESS –
CUPTI_UTIL_ERROR_INVALID_PARAMETER – 如果缓冲区类型无效，或者 pSampData、pParams 之一为 NULL，则会报错。如果 pPcSamplingStallReasons 不为 NULL，则如果 stallReasonIndex、stallReasons 或 stallReasons 数组元素指针之一为 NULL，或者文件名为空，则会报错。
CUPTI_UTIL_ERROR_READ_WRITE_OPERATION_FAILED –
CUPTI_UTIL_ERROR_FILE_HANDLE_CORRUPTED – 文件句柄状态不佳，无法从文件中读取数据。

CUptiUtilResult CUPTI::PcSamplingUtil::CuptiUtilMergePcSampData(CUptiUtil_MergePcSampDataParams *pParams)

按范围 ID 合并 PC 采样数据。

此 API 按范围 ID 合并 PC 采样数据。它为合并的数据分配内存，并在其中填充数据，并在 MergedPcSampDataBuffers 字段中提供缓冲区指针。用户应在使用后释放合并的数据缓冲区。

返回值

CUPTI_UTIL_SUCCESS –
CUPTI_UTIL_ERROR_INVALID_PARAMETER – 如果参数结构大小无效，或者要合并的缓冲区计数无效（即小于 1），或者 PcSampDataBuffer、MergedPcSampDataBuffers、numMergedBuffer 之一为 NULL，则会报错
CUPTI_UTIL_ERROR_OUT_OF_MEMORY – 无法为合并的缓冲区分配内存。

CUptiUtilResult CUPTI::PcSamplingUtil::CuptiUtilPutPcSampData(CUptiUtil_PutPcSampDataParams *pParams)

将 PC 采样数据转储到文件中。

此 API 可以多次调用。它将在文件中附加缓冲区。对于每个缓冲区，它将存储 BufferInfo，以便在检索数据之前，它将帮助分配缓冲区以存储检索到的数据。如果文件不存在，此 API 将创建文件。如果 CUptiUtil_PutPcSampDataParams 的 stallReasonIndex 或 stallReasons 指针为 NULL，则停顿原因数据将不会存储在文件中。预计至少存储一次所有可用的停顿原因数据，以便在离线关联期间引用它。

返回值

CUPTI_UTIL_SUCCESS –
CUPTI_UTIL_ERROR_INVALID_PARAMETER – 如果缓冲区类型无效，或者 pSamplingData、pParams 指针之一为 NULL，或者未提供停顿原因配置详细信息，或者文件名为空，则会报错。
CUPTI_UTIL_ERROR_UNABLE_TO_CREATE_FILE –
CUPTI_UTIL_ERROR_UNABLE_TO_OPEN_FILE –
CUPTI_UTIL_ERROR_READ_WRITE_OPERATION_FAILED –