5.2. CUPTI 回调 API

实现 CUPTI 回调 API 的函数、类型和枚举。

数据结构

CUpti_CallbackData

传递到运行时或驱动程序 API 回调函数中的数据。

CUpti_GraphData

传递到资源回调函数中的 CUDA 图形数据。

CUpti_ModuleResourceData

传递到资源回调函数中的模块数据。

CUpti_NvtxData

传递到 NVTX 回调函数中的数据。

CUpti_ResourceData

传递到资源回调函数中的数据。

CUpti_StateData

传递到状态回调函数中的数据。

CUpti_StreamAttrData

传递到资源回调函数中的流属性数据，用于 CUPTI_CBID_RESOURCE_STREAM_ATTRIBUTE_CHANGED 回调。

CUpti_SynchronizeData

传递到同步回调函数中的数据。

枚举

CUpti_ApiCallbackSite

指定 API 调用中发出回调的点。

CUpti_CallbackDomain

回调域。

CUpti_CallbackIdResource

资源域的回调 ID。

CUpti_CallbackIdState

状态域的回调 ID。

CUpti_CallbackIdSync

同步域的回调 ID。

函数

CUptiResult cuptiEnableAllDomains(uint32_t enable, CUpti_SubscriberHandle subscriber)

启用或禁用所有域中的所有回调。

CUptiResult cuptiEnableCallback(uint32_t enable, CUpti_SubscriberHandle subscriber, CUpti_CallbackDomain domain, CUpti_CallbackId cbid)

为特定域和回调 ID 启用或禁用回调。

CUptiResult cuptiEnableDomain(uint32_t enable, CUpti_SubscriberHandle subscriber, CUpti_CallbackDomain domain)

为特定域启用或禁用所有回调。

CUptiResult cuptiGetCallbackName(CUpti_CallbackDomain domain, uint32_t cbid, const char **name)

获取特定域和回调 ID 的回调名称。

CUptiResult cuptiGetCallbackState(uint32_t *enable, CUpti_SubscriberHandle subscriber, CUpti_CallbackDomain domain, CUpti_CallbackId cbid)

获取特定域和函数 ID 的回调的当前启用/禁用状态。

CUptiResult cuptiSubscribe(CUpti_SubscriberHandle *subscriber, CUpti_CallbackFunc callback, void *userdata)

使用回调函数和用户数据初始化回调订阅者。

CUptiResult cuptiSupportedDomains(size_t *domainCount, CUpti_DomainTable *domainTable)

获取可用的回调域。

CUptiResult cuptiUnsubscribe(CUpti_SubscriberHandle subscriber)

注销回调订阅者。

类型定义

CUpti_CallbackFunc

回调的函数类型。

CUpti_CallbackId

驱动程序 API、运行时 API、资源或同步回调的 ID。

CUpti_DomainTable

回调域数组的指针。

CUpti_SubscriberHandle

回调订阅者。

5.2.1. 枚举

enum CUpti_ApiCallbackSite

指定 API 调用中发出回调的点。

指定 API 调用中发出回调的点。此值通过 CUpti_CallbackData::callbackSite 传递给回调函数。

值

enumerator CUPTI_API_ENTER

回调位于 API 调用的入口处。

enumerator CUPTI_API_EXIT

回调位于 API 调用的出口处。

enumerator CUPTI_API_CBSITE_FORCE_INT
enum CUpti_CallbackDomain

回调域。

回调域。每个域代表一组相关 API 函数或 CUDA 驱动程序活动的回调点。

值

enumerator CUPTI_CB_DOMAIN_INVALID

无效域。

enumerator CUPTI_CB_DOMAIN_DRIVER_API

包含所有驱动程序 API 函数的回调点的域。

enumerator CUPTI_CB_DOMAIN_RUNTIME_API

包含所有运行时 API 函数的回调点的域。

enumerator CUPTI_CB_DOMAIN_RESOURCE

包含 CUDA 资源跟踪的回调点的域。

enumerator CUPTI_CB_DOMAIN_SYNCHRONIZE

包含 CUDA 同步的回调点的域。

enumerator CUPTI_CB_DOMAIN_NVTX

包含 NVTX API 函数的回调点的域。

enumerator CUPTI_CB_DOMAIN_STATE

包含各种状态的回调点的域。

enumerator CUPTI_CB_DOMAIN_SIZE
enumerator CUPTI_CB_DOMAIN_FORCE_INT
enum CUpti_CallbackIdResource

资源域的回调 ID。

资源域的回调 ID，CUPTI_CB_DOMAIN_RESOURCE。此值通过 cbid 参数传递给回调函数。

值

enumerator CUPTI_CBID_RESOURCE_INVALID

无效的资源回调 ID。

enumerator CUPTI_CBID_RESOURCE_CONTEXT_CREATED

已创建新上下文。

enumerator CUPTI_CBID_RESOURCE_CONTEXT_DESTROY_STARTING

上下文即将被销毁。

enumerator CUPTI_CBID_RESOURCE_STREAM_CREATED

已创建新流。

enumerator CUPTI_CBID_RESOURCE_STREAM_DESTROY_STARTING

流即将被销毁。

enumerator CUPTI_CBID_RESOURCE_CU_INIT_FINISHED

驱动程序已完成初始化。

enumerator CUPTI_CBID_RESOURCE_MODULE_LOADED

已加载模块。

enumerator CUPTI_CBID_RESOURCE_MODULE_UNLOAD_STARTING

模块即将被卸载。

enumerator CUPTI_CBID_RESOURCE_MODULE_PROFILED

当前正在分析的模块。

enumerator CUPTI_CBID_RESOURCE_GRAPH_CREATED

已创建 CUDA 图形。

enumerator CUPTI_CBID_RESOURCE_GRAPH_DESTROY_STARTING

CUDA 图形即将被销毁。

enumerator CUPTI_CBID_RESOURCE_GRAPH_CLONED

CUDA 图形已克隆。

enumerator CUPTI_CBID_RESOURCE_GRAPHNODE_CREATE_STARTING

CUDA 图形节点即将被创建。

enumerator CUPTI_CBID_RESOURCE_GRAPHNODE_CREATED

CUDA 图形节点已创建。

enumerator CUPTI_CBID_RESOURCE_GRAPHNODE_DESTROY_STARTING

CUDA 图形节点即将被销毁。

enumerator CUPTI_CBID_RESOURCE_GRAPHNODE_DEPENDENCY_CREATED

已创建 CUDA 图形节点的依赖项。

enumerator CUPTI_CBID_RESOURCE_GRAPHNODE_DEPENDENCY_DESTROY_STARTING

CUDA 图形节点的依赖项已被销毁。

enumerator CUPTI_CBID_RESOURCE_GRAPHEXEC_CREATE_STARTING

可执行 CUDA 图形即将被创建。

enumerator CUPTI_CBID_RESOURCE_GRAPHEXEC_CREATED

已创建可执行 CUDA 图形。

enumerator CUPTI_CBID_RESOURCE_GRAPHEXEC_DESTROY_STARTING

可执行 CUDA 图形即将被销毁。

enumerator CUPTI_CBID_RESOURCE_GRAPHNODE_CLONED

CUDA 图形节点已克隆。

enumerator CUPTI_CBID_RESOURCE_STREAM_ATTRIBUTE_CHANGED

CUDA 流属性已更改。

enumerator CUPTI_CBID_RESOURCE_SIZE
enumerator CUPTI_CBID_RESOURCE_FORCE_INT
enum CUpti_CallbackIdState

状态域的回调 ID。

状态域的回调 ID，CUPTI_CB_DOMAIN_STATE。此值通过 cbid 参数传递给回调函数。

值

enumerator CUPTI_CBID_STATE_INVALID

无效的状态回调 ID。

enumerator CUPTI_CBID_STATE_FATAL_ERROR

致命错误通知 - 高影响，不可恢复。当遇到时，CUPTI 会自动调用 cuptiFinalize()。用户可以从接收此回调来控制应用程序未来的行为 - 例如，继续但不进行分析，或终止整个应用程序。

enumerator CUPTI_CBID_STATE_ERROR

非致命错误通知 - 高影响，但可恢复。当前版本中未发出此通知。

enumerator CUPTI_CBID_STATE_WARNING

警告通知 - 低影响，可恢复。

enumerator CUPTI_CBID_STATE_SIZE
enumerator CUPTI_CBID_STATE_FORCE_INT
enum CUpti_CallbackIdSync

同步域的回调 ID。

同步域的回调 ID，CUPTI_CB_DOMAIN_SYNCHRONIZE。此值通过 cbid 参数传递给回调函数。

值

enumerator CUPTI_CBID_SYNCHRONIZE_INVALID

无效的同步回调 ID。

enumerator CUPTI_CBID_SYNCHRONIZE_STREAM_SYNCHRONIZED

流同步已完成。

enumerator CUPTI_CBID_SYNCHRONIZE_CONTEXT_SYNCHRONIZED

上下文同步已完成。

enumerator CUPTI_CBID_SYNCHRONIZE_SIZE
enumerator CUPTI_CBID_SYNCHRONIZE_FORCE_INT

5.2.2. 函数

CUptiResult cuptiEnableAllDomains(uint32_t enable, CUpti_SubscriberHandle subscriber)

启用或禁用所有域中的所有回调。

启用或禁用所有域中的所有回调。

注意

线程安全

：订阅者必须序列化对 cuptiGetCallbackState、cuptiEnableCallback、cuptiEnableDomain 和 cuptiEnableAllDomains 的访问。 例如，如果并发调用 cuptiGetCallbackState(sub,

d, *) 和 cuptiEnableAllDomains(sub)，则结果未定义。

参数

  • enable – 所有域中所有回调的新启用状态。 零禁用所有回调，非零启用所有回调。

  • subscriber – - 回调订阅的句柄

返回值

  • CUPTI_SUCCESS – 成功时

  • CUPTI_ERROR_NOT_INITIALIZED – 如果无法初始化 CUPTI

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 subscriber 无效

CUptiResult cuptiEnableCallback(uint32_t enable, CUpti_SubscriberHandle subscriber, CUpti_CallbackDomain domain, CUpti_CallbackId cbid)

为特定域和回调 ID 启用或禁用回调。

为订阅者为特定域和回调 ID 启用或禁用回调。

注意

线程安全

：订阅者必须序列化对 cuptiGetCallbackState、cuptiEnableCallback、cuptiEnableDomain 和 cuptiEnableAllDomains 的访问。 例如，如果并发调用 cuptiGetCallbackState(sub,

d, c) 和 cuptiEnableCallback(sub, d, c) 并发调用时，结果未定义。

参数

  • enable – 回调的新启用状态。 零禁用回调，非零启用回调。

  • subscriber – - 回调订阅的句柄

  • domain – 回调的域

  • cbid – 回调的 ID

返回值

  • CUPTI_SUCCESS – 成功时

  • CUPTI_ERROR_NOT_INITIALIZED – 如果无法初始化 CUPTI

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 subscriber、domain 或 cbid 无效。

CUptiResult cuptiEnableDomain(uint32_t enable, CUpti_SubscriberHandle subscriber, CUpti_CallbackDomain domain)

为特定域启用或禁用所有回调。

为特定域启用或禁用所有回调。

注意

线程安全

：订阅者必须序列化对 cuptiGetCallbackState、cuptiEnableCallback、cuptiEnableDomain 和 cuptiEnableAllDomains 的访问。 例如，如果并发调用 cuptiGetCallbackEnabled(sub,

d, *) 和 cuptiEnableDomain(sub, d)，则结果未定义。

参数

  • enable – 域中所有回调的新启用状态。零禁用所有回调，非零启用所有回调。

  • subscriber – - 回调订阅的句柄

  • domain – 回调的域

返回值

  • CUPTI_SUCCESS – 成功时

  • CUPTI_ERROR_NOT_INITIALIZED – 如果无法初始化 CUPTI

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 subscriber 或 domain 无效

CUptiResult cuptiGetCallbackName(CUpti_CallbackDomain domain, uint32_t cbid, const char **name)

获取特定域和回调 ID 的回调名称。

返回指向 **name 中名称 c 字符串的指针。

注意

Names 仅适用于 DRIVER 和 RUNTIME 域。

参数

  • domain – 回调的域

  • cbid – 回调的 ID

  • name – 成功时返回指向名称字符串的指针，否则返回 NULL

返回值

  • CUPTI_SUCCESS – 成功时

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 name 为 NULL，或者如果 domain 或 cbid 无效。

CUptiResult cuptiGetCallbackState(uint32_t *enable, CUpti_SubscriberHandle subscriber, CUpti_CallbackDomain domain, CUpti_CallbackId cbid)

获取特定域和函数 ID 的回调的当前启用/禁用状态。

如果域和回调 ID 的回调已启用，则在 *enable 中返回非零值；如果未启用，则返回零。

注意

线程安全

：订阅者必须序列化对 cuptiGetCallbackState、cuptiEnableCallback、cuptiEnableDomain 和 cuptiEnableAllDomains 的访问。 例如，如果并发调用 cuptiGetCallbackState(sub,

d, c) 和 cuptiEnableCallback(sub, d, c) 并发调用时，结果未定义。

参数

  • enable – 如果回调已启用，则返回非零值；如果未启用，则返回零

  • subscriber – 指向已初始化的订阅者的句柄

  • domain – 回调的域

  • cbid – 回调的 ID

返回值

  • CUPTI_SUCCESS – 成功时

  • CUPTI_ERROR_NOT_INITIALIZED – 如果无法初始化 CUPTI

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 enabled 为 NULL，或者如果 subscriber、domain 或 cbid 无效。

CUptiResult cuptiSubscribe(CUpti_SubscriberHandle *subscriber, CUpti_CallbackFunc callback, void *userdata)

使用回调函数和用户数据初始化回调订阅者。

使用回调函数和（可选的）指向用户数据的指针初始化回调订阅者。返回的订阅者句柄可用于为特定域和回调 ID 启用和禁用回调。

注意

一次只能注册一个订阅者。为了确保没有其他 CUPTI 客户端中断性能分析会话，所有 CUPTI 客户端都有责任在启动性能分析会话之前调用此函数。如果性能分析会话已由另一个 CUPTI 客户端启动，则此函数返回错误代码 CUPTI_ERROR_MULTIPLE_SUBSCRIBERS_NOT_SUPPORTED。请注意，当使用 NVIDIA 工具（如 nvprof、Visual Profiler、Nsight Systems、Nsight Compute、cuda-gdb 和 cuda-memcheck）启动应用程序时，此函数也会返回相同的错误。

注意

此函数不启用任何回调。

注意

Thread-safety: 此函数是线程安全的。

参数

  • subscriber – 返回指向已初始化订阅者的句柄

  • callback – 回调函数

  • userdata – 指向用户数据的指针。此数据将通过 userdata 参数传递给回调函数。

返回值

  • CUPTI_SUCCESS – 成功时

  • CUPTI_ERROR_NOT_INITIALIZED – 如果无法初始化 CUPTI

  • CUPTI_ERROR_MULTIPLE_SUBSCRIBERS_NOT_SUPPORTED – 如果已存在 CUPTI 订阅者

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 subscriber 为 NULL

CUptiResult cuptiSupportedDomains(size_t *domainCount, CUpti_DomainTable *domainTable)

获取可用的回调域。

在 *domainTable 中返回大小为 *domainCount 的所有可用回调域的数组。

注意

Thread-safety: 此函数是线程安全的。

参数

  • domainCount – 返回回调域的数量

  • domainTable – 返回指向可用回调域数组的指针

返回值

  • CUPTI_SUCCESS – 成功时

  • CUPTI_ERROR_NOT_INITIALIZED – 如果无法初始化 CUPTI

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 domainCount 或 domainTable 为 NULL

CUptiResult cuptiUnsubscribe(CUpti_SubscriberHandle subscriber)

注销回调订阅者。

移除回调订阅者，以便将来不会向该订阅者发出任何回调。

注意

Thread-safety: 此函数是线程安全的。

参数

subscriber – 指向已初始化的订阅者的句柄

返回值

  • CUPTI_SUCCESS – 成功时

  • CUPTI_ERROR_NOT_INITIALIZED – 如果无法初始化 CUPTI

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 subscriber 为 NULL 或未初始化

5.2.3. 类型定义

typedef void (*CUpti_CallbackFunc)(void *userdata, CUpti_CallbackDomain domain, CUpti_CallbackId cbid, const void *cbdata)

回调的函数类型。

回调的函数类型。传递给 cbdata 中回调的数据类型取决于 domain。如果 domain 是 CUPTI_CB_DOMAIN_DRIVER_API 或 CUPTI_CB_DOMAIN_RUNTIME_API，则 cbdata 的类型将为 CUpti_CallbackData。如果 domain 是 CUPTI_CB_DOMAIN_RESOURCE，则 cbdata 的类型将为 CUpti_ResourceData。如果 domain 是 CUPTI_CB_DOMAIN_SYNCHRONIZE，则 cbdata 的类型将为 CUpti_SynchronizeData。如果 domain 是 CUPTI_CB_DOMAIN_NVTX，则 cbdata 的类型将为 CUpti_NvtxData。

Param userdata

在回调订阅时提供的用户数据

Param domain

回调的域

Param cbid

回调的 ID

Param cbdata

传递给回调的数据。

typedef uint32_t CUpti_CallbackId

驱动程序 API、运行时 API、资源或同步回调的 ID。

驱动程序 API、运行时 API、资源或同步回调的 ID。在驱动程序 API 回调中，这应解释为 CUpti_driver_api_trace_cbid 值（这些值在 cupti_driver_cbid.h 中定义）。在运行时 API 回调中，这应解释为 CUpti_runtime_api_trace_cbid 值（这些值在 cupti_runtime_cbid.h 中定义）。在资源 API 回调中，这应解释为 CUpti_CallbackIdResource 值。在同步 API 回调中，这应解释为 CUpti_CallbackIdSync 值。

typedef CUpti_CallbackDomain *CUpti_DomainTable

回调域数组的指针。

typedef struct CUpti_Subscriber_st *CUpti_SubscriberHandle

回调订阅者。