5.5. CUPTI Metric API

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

注意

头文件 cupti_metrics.h 中的 CUPTI 指标 API 不支持计算能力为 7.5 及更高版本（即 Turing 及更高版本的 GPU 架构）的设备。此 API 在 CUDA 12.8 版本中已弃用，并将在未来的 CUDA 版本中移除。它已被头文件 cupti_profiler_host.h 中的主机分析 API 和头文件 cupti_range_profiler.h 中的目标分析 API 取代，这些 API 在计算能力为 7.0 及更高版本（即 Volta 及更高版本的 GPU 架构）的设备上受支持。

数据结构

CUpti_MetricValue

一个指标值。

枚举

CUpti_MetricAttribute

指标属性。

CUpti_MetricCategory

一个指标类别。

CUpti_MetricEvaluationMode

一个指标评估模式。

CUpti_MetricPropertyDeviceClass

设备类别。

CUpti_MetricPropertyID

指标设备属性。

CUpti_MetricValueKind

指标值的种类。

CUpti_MetricValueUtilizationLevel

种类为 CUPTI_METRIC_VALUE_KIND_UTILIZATION_LEVEL 的指标值的利用率级别枚举。

函数

CUptiResult cuptiDeviceEnumMetrics(CUdevice device, size_t *arraySizeBytes, CUpti_MetricID *metricArray)

获取设备的指标。

CUptiResult cuptiDeviceGetNumMetrics(CUdevice device, uint32_t *numMetrics)

获取设备的指标数量。

CUptiResult cuptiEnumMetrics(size_t *arraySizeBytes, CUpti_MetricID *metricArray)

获取任何设备上可用的所有指标。

CUptiResult cuptiGetNumMetrics(uint32_t *numMetrics)

获取任何设备上可用的指标总数。

CUptiResult cuptiMetricCreateEventGroupSets(CUcontext context, size_t metricIdArraySizeBytes, CUpti_MetricID *metricIdArray, CUpti_EventGroupSets **eventGroupPasses)

对于一组指标，获取指示计算这些指标所需事件的必要传递次数和事件组的分组。

CUptiResult cuptiMetricEnumEvents(CUpti_MetricID metric, size_t *eventIdArraySizeBytes, CUpti_EventID *eventIdArray)

获取计算指标所需的事件。

CUptiResult cuptiMetricEnumProperties(CUpti_MetricID metric, size_t *propIdArraySizeBytes, CUpti_MetricPropertyID *propIdArray)

获取计算指标所需的属性。

CUptiResult cuptiMetricGetAttribute(CUpti_MetricID metric, CUpti_MetricAttribute attrib, size_t *valueSize, void *value)

获取指标属性。

CUptiResult cuptiMetricGetIdFromName(CUdevice device, const char *metricName, CUpti_MetricID *metric)

按名称查找指标。

CUptiResult cuptiMetricGetNumEvents(CUpti_MetricID metric, uint32_t *numEvents)

获取计算指标所需的事件数量。

CUptiResult cuptiMetricGetNumProperties(CUpti_MetricID metric, uint32_t *numProp)

获取计算指标所需的属性数量。

CUptiResult cuptiMetricGetRequiredEventGroupSets(CUcontext context, CUpti_MetricID metric, CUpti_EventGroupSets **eventGroupSets)

对于一个指标，获取必须在同一次传递中收集的事件组。

CUptiResult cuptiMetricGetValue(CUdevice device, CUpti_MetricID metric, size_t eventIdArraySizeBytes, CUpti_EventID *eventIdArray, size_t eventValueArraySizeBytes, uint64_t *eventValueArray, uint64_t timeDuration, CUpti_MetricValue *metricValue)

计算指标的值。

CUptiResult cuptiMetricGetValue2(CUpti_MetricID metric, size_t eventIdArraySizeBytes, CUpti_EventID *eventIdArray, size_t eventValueArraySizeBytes, uint64_t *eventValueArray, size_t propIdArraySizeBytes, CUpti_MetricPropertyID *propIdArray, size_t propValueArraySizeBytes, uint64_t *propValueArray, CUpti_MetricValue *metricValue)

计算指标的值。

类型定义

CUpti_MetricID

指标的 ID。

5.5.1. 枚举

enum CUpti_MetricAttribute

指标属性。

指标属性描述指标的属性。 这些属性可以使用 cuptiMetricGetAttribute 读取。

值

enumerator CUPTI_METRIC_ATTR_NAME

指标名称。

值是空终止的 const c 字符串。

enumerator CUPTI_METRIC_ATTR_SHORT_DESCRIPTION

指标的简短描述。

值是空终止的 const c 字符串。

enumerator CUPTI_METRIC_ATTR_LONG_DESCRIPTION

指标的详细描述。

值是空终止的 const c 字符串。

enumerator CUPTI_METRIC_ATTR_CATEGORY

指标的类别。

值类型为 CUpti_MetricCategory。

enumerator CUPTI_METRIC_ATTR_VALUE_KIND

指标的值类型。

值类型为 CUpti_MetricValueKind。

enumerator CUPTI_METRIC_ATTR_EVALUATION_MODE

指标评估模式。

值类型为 CUpti_MetricEvaluationMode。

enumerator CUPTI_METRIC_ATTR_FORCE_INT
enum CUpti_MetricCategory

一个指标类别。

每个指标都分配到一个类别，该类别表示指标的一般类型。 指标的类别可以使用 cuptiMetricGetAttribute 和 CUPTI_METRIC_ATTR_CATEGORY 属性访问。

值

enumerator CUPTI_METRIC_CATEGORY_MEMORY

与内存相关的指标。

enumerator CUPTI_METRIC_CATEGORY_INSTRUCTION

与指令相关的指标。

enumerator CUPTI_METRIC_CATEGORY_MULTIPROCESSOR

与多处理器相关的指标。

enumerator CUPTI_METRIC_CATEGORY_CACHE

与缓存相关的指标。

enumerator CUPTI_METRIC_CATEGORY_TEXTURE

与纹理相关的指标。

enumerator CUPTI_METRIC_CATEGORY_NVLINK

与 Nvlink 相关的指标。

enumerator CUPTI_METRIC_CATEGORY_PCIE

与 PCIe 相关的指标。

enumerator CUPTI_METRIC_CATEGORY_FORCE_INT
enum CUpti_MetricEvaluationMode

一个指标评估模式。

指标可以按硬件实例评估，以了解跨域实例的负载平衡，或者当指标评估中涉及的事件来自不同的事件域时，指标可以在聚合模式下评估。为了方便起见，某些指标可能可以在两种模式下评估。 指标的评估模式可以使用 CUpti_MetricEvaluationMode 和 CUPTI_METRIC_ATTR_EVALUATION_MODE 属性访问。

值

enumerator CUPTI_METRIC_EVALUATION_MODE_PER_INSTANCE

如果设置了此位，则可以为域的每个实例分析指标。

传递给 cuptiMetricGetValue 的事件值可以包含域的一个实例的值。 cuptiMetricGetValue 可以为每个实例调用。

enumerator CUPTI_METRIC_EVALUATION_MODE_AGGREGATE

如果设置了此位，则可以分析所有实例的指标。

传递给 cuptiMetricGetValue 的事件值可以是域的所有实例的事件的聚合值。

enumerator CUPTI_METRIC_EVALUATION_MODE_FORCE_INT
enum CUpti_MetricPropertyDeviceClass

设备类别。

指标属性 CUPTI_METRIC_PROPERTY_DEVICE_CLASS 的设备类别枚举。

值

enumerator CUPTI_METRIC_PROPERTY_DEVICE_CLASS_TESLA
enumerator CUPTI_METRIC_PROPERTY_DEVICE_CLASS_QUADRO
enumerator CUPTI_METRIC_PROPERTY_DEVICE_CLASS_GEFORCE
enumerator CUPTI_METRIC_PROPERTY_DEVICE_CLASS_TEGRA
enum CUpti_MetricPropertyID

指标设备属性。

指标设备属性描述指标所需的设备属性。 其中一些属性可以使用 cuDeviceGetAttribute 收集。

值

enumerator CUPTI_METRIC_PROPERTY_MULTIPROCESSOR_COUNT
enumerator CUPTI_METRIC_PROPERTY_WARPS_PER_MULTIPROCESSOR
enumerator CUPTI_METRIC_PROPERTY_KERNEL_GPU_TIME
enumerator CUPTI_METRIC_PROPERTY_CLOCK_RATE
enumerator CUPTI_METRIC_PROPERTY_FRAME_BUFFER_COUNT
enumerator CUPTI_METRIC_PROPERTY_GLOBAL_MEMORY_BANDWIDTH
enumerator CUPTI_METRIC_PROPERTY_PCIE_LINK_RATE
enumerator CUPTI_METRIC_PROPERTY_PCIE_LINK_WIDTH
enumerator CUPTI_METRIC_PROPERTY_PCIE_GEN
enumerator CUPTI_METRIC_PROPERTY_DEVICE_CLASS
enumerator CUPTI_METRIC_PROPERTY_FLOP_SP_PER_CYCLE
enumerator CUPTI_METRIC_PROPERTY_FLOP_DP_PER_CYCLE
enumerator CUPTI_METRIC_PROPERTY_L2_UNITS
enumerator CUPTI_METRIC_PROPERTY_ECC_ENABLED
enumerator CUPTI_METRIC_PROPERTY_FLOP_HP_PER_CYCLE
enumerator CUPTI_METRIC_PROPERTY_GPU_CPU_NVLINK_BANDWIDTH
enum CUpti_MetricValueKind

指标值的种类。

指标值可以是几种不同的类型之一。 每种类型都对应于 CUpti_MetricValue 联合的成员。 使用 cuptiMetricGetValue 返回的指标值应根据其值类型使用该联合的相应成员进行访问。

值

enumerator CUPTI_METRIC_VALUE_KIND_DOUBLE

指标值是 64 位双精度浮点数。

enumerator CUPTI_METRIC_VALUE_KIND_UINT64

指标值是 64 位无符号整数。

enumerator CUPTI_METRIC_VALUE_KIND_PERCENT

指标值是以 64 位双精度浮点数表示的百分比。

例如，57.5% 由值 57.5 表示。

enumerator CUPTI_METRIC_VALUE_KIND_THROUGHPUT

指标值是以 64 位整数表示的吞吐量。

吞吐量值的单位是字节/秒。

enumerator CUPTI_METRIC_VALUE_KIND_INT64

指标值是 64 位有符号整数。

enumerator CUPTI_METRIC_VALUE_KIND_UTILIZATION_LEVEL

指标值是一个利用率级别，由 CUpti_MetricValueUtilizationLevel 表示。

enumerator CUPTI_METRIC_VALUE_KIND_FORCE_INT
enum CUpti_MetricValueUtilizationLevel

种类为 CUPTI_METRIC_VALUE_KIND_UTILIZATION_LEVEL 的指标值的利用率级别枚举。

利用率值可以从 IDLE (0) 到 MAX (10) 不等，但枚举仅为少数几个值提供特定名称。

值

enumerator CUPTI_METRIC_VALUE_UTILIZATION_IDLE
enumerator CUPTI_METRIC_VALUE_UTILIZATION_LOW
enumerator CUPTI_METRIC_VALUE_UTILIZATION_MID
enumerator CUPTI_METRIC_VALUE_UTILIZATION_HIGH
enumerator CUPTI_METRIC_VALUE_UTILIZATION_MAX
enumerator CUPTI_METRIC_VALUE_UTILIZATION_FORCE_INT

5.5.2. 函数

CUptiResult cuptiDeviceEnumMetrics(CUdevice device, size_t *arraySizeBytes, CUpti_MetricID *metricArray)

获取设备的指标。

为设备返回 metricArray 中的指标 ID。 metricArray 缓冲区的大小由 *arraySizeBytes 给出。metricArray 缓冲区的大小必须至少为 numMetrics * sizeof(CUpti_MetricID)，否则将不会返回所有指标 ID。 *arraySizeBytes 中返回的值包含 metricArray 中返回的字节数。

参数

  • device – CUDA 设备

  • arraySizeBytes – metricArray 的大小（以字节为单位），并返回写入 metricArray 的字节数

  • metricArray – 返回设备的指标 ID

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_NOT_INITIALIZED –

  • CUPTI_ERROR_INVALID_DEVICE –

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 arraySizeBytes 或 metricArray 为 NULL

CUptiResult cuptiDeviceGetNumMetrics(CUdevice device, uint32_t *numMetrics)

获取设备的指标数量。

返回设备可用的指标数量。

参数

  • device – CUDA 设备

  • numMetrics – 返回设备可用的指标数量

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_NOT_INITIALIZED –

  • CUPTI_ERROR_INVALID_DEVICE –

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 numMetrics 为 NULL

CUptiResult cuptiEnumMetrics(size_t *arraySizeBytes, CUpti_MetricID *metricArray)

获取任何设备上可用的所有指标。

为所有支持 CUDA 的设备返回 metricArray 中的指标 ID。 metricArray 缓冲区的大小由 *arraySizeBytes 给出。metricArray 缓冲区的大小必须至少为 numMetrics * sizeof(CUpti_MetricID)，否则将不会返回所有指标 ID。 *arraySizeBytes 中返回的值包含 metricArray 中返回的字节数。

参数

  • arraySizeBytes – metricArray 的大小（以字节为单位），并返回写入 metricArray 的字节数

  • metricArray – 返回指标的 ID

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 arraySizeBytes 或 metricArray 为 NULL

CUptiResult cuptiGetNumMetrics(uint32_t *numMetrics)

获取任何设备上可用的指标总数。

返回任何支持 CUDA 的设备上可用的指标总数。

参数

numMetrics – 返回指标的数量

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 numMetrics 为 NULL

CUptiResult cuptiMetricCreateEventGroupSets(CUcontext context, size_t metricIdArraySizeBytes, CUpti_MetricID *metricIdArray, CUpti_EventGroupSets **eventGroupPasses)

对于一组指标，获取指示计算这些指标所需事件的必要传递次数和事件组的分组。

对于一组指标，获取指示计算这些指标所需事件的必要传递次数和事件组的分组。

另请参阅

cuptiEventGroupSetsCreate，了解有关事件组集创建的详细信息。

参数

  • context – 用于事件收集的上下文

  • metricIdArraySizeBytes – metricIdArray 的大小（以字节为单位）

  • metricIdArray – 指标 ID 数组

  • eventGroupPasses – 返回一个 CUpti_EventGroupSets 对象，该对象指示收集事件所需的趟数以及每趟要收集的事件

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_NOT_INITIALIZED –

  • CUPTI_ERROR_INVALID_CONTEXT –

  • CUPTI_ERROR_INVALID_METRIC_ID –

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 metricIdArray 或 eventGroupPasses 为 NULL

CUptiResult cuptiMetricEnumEvents(CUpti_MetricID metric, size_t *eventIdArraySizeBytes, CUpti_EventID *eventIdArray)

获取计算指标所需的事件。

获取计算 metric 所需的 eventIdArray 中的事件 ID。 eventIdArray 缓冲区的大小由 *eventIdArraySizeBytes 给出，并且必须至少为 numEvents * sizeof(CUpti_EventID)，否则将不会返回所有事件。 *eventIdArraySizeBytes 中返回的值包含 eventIdArray 中返回的字节数。

参数

  • metric – 指标的 ID

  • eventIdArraySizeBytes – eventIdArray 的大小（以字节为单位），并返回写入 eventIdArray 的字节数

  • eventIdArray – 返回计算 metric 所需的事件 ID

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_NOT_INITIALIZED –

  • CUPTI_ERROR_INVALID_METRIC_ID –

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 eventIdArraySizeBytes 或 eventIdArray 为 NULL。

CUptiResult cuptiMetricEnumProperties(CUpti_MetricID metric, size_t *propIdArraySizeBytes, CUpti_MetricPropertyID *propIdArray)

获取计算指标所需的属性。

获取计算 metric 所需的 propIdArray 中的属性 ID。 propIdArray 缓冲区的大小由 *propIdArraySizeBytes 给出，并且必须至少为 numProp * sizeof(CUpti_DeviceAttribute)，否则将不会返回所有属性。 *propIdArraySizeBytes 中返回的值包含 propIdArray 中返回的字节数。

参数

  • metric – 指标的 ID

  • propIdArraySizeBytes – propIdArray 的大小（以字节为单位），并返回写入 propIdArray 的字节数

  • propIdArray – 返回计算 metric 所需的属性 ID

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_NOT_INITIALIZED –

  • CUPTI_ERROR_INVALID_METRIC_ID –

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 propIdArraySizeBytes 或 propIdArray 为 NULL。

CUptiResult cuptiMetricGetAttribute(CUpti_MetricID metric, CUpti_MetricAttribute attrib, size_t *valueSize, void *value)

获取指标属性。

在 *value 中返回指标属性。 value 缓冲区的大小由 *valueSize 给出。 *valueSize 中返回的值包含 value 中返回的字节数。

如果属性值是长于 *valueSize 的 c 字符串，则只会返回前 *valueSize 个字符，并且不会有终止空字节。

参数

  • metric – 指标的 ID

  • attrib – 要读取的指标属性

  • valueSize – value 缓冲区的大小（以字节为单位），并返回写入 value 的字节数

  • value – 返回属性的值

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_NOT_INITIALIZED –

  • CUPTI_ERROR_INVALID_METRIC_ID –

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 valueSize 或 value 为 NULL，或者如果 attrib 不是指标属性

  • CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT – 对于非 c 字符串属性值，表示 value 缓冲区太小，无法容纳属性值。

CUptiResult cuptiMetricGetIdFromName(CUdevice device, const char *metricName, CUpti_MetricID *metric)

按名称查找指标。

按名称查找指标，并在 *metric 中返回指标 ID。

参数

  • device – CUDA 设备

  • metricName – 要查找的指标的名称

  • metric – 返回找到的指标的 ID；如果无法找到指标，则返回未定义

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_NOT_INITIALIZED –

  • CUPTI_ERROR_INVALID_DEVICE –

  • CUPTI_ERROR_INVALID_METRIC_NAME – 如果无法找到名称为 metricName 的指标。 在这种情况下，*metric 是未定义的

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 metricName 或 metric 为 NULL。

CUptiResult cuptiMetricGetNumEvents(CUpti_MetricID metric, uint32_t *numEvents)

获取计算指标所需的事件数量。

返回计算指标所需的 numEvents 中的事件数。

参数

  • metric – 指标的 ID

  • numEvents – 返回指标所需的事件数

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_NOT_INITIALIZED –

  • CUPTI_ERROR_INVALID_METRIC_ID –

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 numEvents 为 NULL

CUptiResult cuptiMetricGetNumProperties(CUpti_MetricID metric, uint32_t *numProp)

获取计算指标所需的属性数量。

返回计算指标所需的 numProp 中的属性数。

参数

  • metric – 指标的 ID

  • numProp – 返回指标所需的属性数

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_NOT_INITIALIZED –

  • CUPTI_ERROR_INVALID_METRIC_ID –

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 numProp 为 NULL

CUptiResult cuptiMetricGetRequiredEventGroupSets(CUcontext context, CUpti_MetricID metric, CUpti_EventGroupSets **eventGroupSets)

对于一个指标，获取必须在同一次传递中收集的事件组。

对于指标，获取必须在同一趟中收集的事件组，以确保正确计算指标。 如果未按指定方式收集事件，则指标值可能不准确。

如果指标没有任何必需的事件组，则该函数返回 NULL。 在这种情况下，指标所需的事件可以以任何方式分组以进行收集。

参数

  • context – 用于事件收集的上下文

  • metric – 指标 ID

  • eventGroupSets – 返回一个 CUpti_EventGroupSets 对象，该对象指示必须在同一趟中收集的事件，以确保正确计算指标。 如果指标不需要分组，则返回 NULL

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_NOT_INITIALIZED –

  • CUPTI_ERROR_INVALID_METRIC_ID –

CUptiResult cuptiMetricGetValue(CUdevice device, CUpti_MetricID metric, size_t eventIdArraySizeBytes, CUpti_EventID *eventIdArray, size_t eventValueArraySizeBytes, uint64_t *eventValueArray, uint64_t timeDuration, CUpti_MetricValue *metricValue)

计算指标的值。

使用为指标收集的事件来计算指标值。 指标值评估取决于指标支持的评估模式 CUpti_MetricEvaluationMode。 如果指标的评估模式为 CUPTI_METRIC_EVALUATION_MODE_PER_INSTANCE，则它假定输入事件值用于一个域实例。 如果指标的评估模式为 CUPTI_METRIC_EVALUATION_MODE_AGGREGATE，则它假定输入事件值已标准化以表示设备上的所有域实例。 为了获得最准确的指标收集，应为所有已分析的域实例收集指标所需的事件。 例如，要收集事件的所有实例，请将包含该事件的组上的 CUPTI_EVENT_GROUP_ATTR_PROFILE_ALL_DOMAIN_INSTANCES 属性设置为 1。 然后，事件的标准化值为：(sum_event_values * totalInstanceCount) / instanceCount，其中 sum_event_values 是所有已分析的域实例的事件值的总和，totalInstanceCount 是从查询 CUPTI_EVENT_DOMAIN_ATTR_TOTAL_INSTANCE_COUNT 获得的，而 instanceCount 是从查询 CUPTI_EVENT_GROUP_ATTR_INSTANCE_COUNT（或 CUPTI_EVENT_DOMAIN_ATTR_INSTANCE_COUNT）获得的。

参数

  • device – 要为其计算指标的 CUDA 设备

  • metric – 指标 ID

  • eventIdArraySizeBytes – eventIdArray 的大小（以字节为单位）

  • eventIdArray – 计算 metric 所需的事件 ID

  • eventValueArraySizeBytes – eventValueArray 的大小（以字节为单位）

  • eventValueArray – 计算 metric 所需的标准化事件值。 这些值的顺序必须与 eventIdArray 中事件的顺序匹配

  • timeDuration – 事件收集的持续时间，以纳秒为单位

  • metricValue – 返回指标的值

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_NOT_INITIALIZED –

  • CUPTI_ERROR_INVALID_METRIC_ID –

  • CUPTI_ERROR_INVALID_OPERATION –

  • CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT – 如果 eventIdArray 不包含指标所需的所有事件

  • CUPTI_ERROR_INVALID_EVENT_VALUE – 如果指标所需的任何事件值为 CUPTI_EVENT_OVERFLOW

  • CUPTI_ERROR_INVALID_METRIC_VALUE – 如果计算出的指标值无法以指标的值类型表示。 例如，如果指标值类型为无符号，而计算出的指标值为负数

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 metricValue、eventIdArray 或 eventValueArray 为 NULL

CUptiResult cuptiMetricGetValue2(CUpti_MetricID metric, size_t eventIdArraySizeBytes, CUpti_EventID *eventIdArray, size_t eventValueArraySizeBytes, uint64_t *eventValueArray, size_t propIdArraySizeBytes, CUpti_MetricPropertyID *propIdArray, size_t propValueArraySizeBytes, uint64_t *propValueArray, CUpti_MetricValue *metricValue)

计算指标的值。

使用为指标收集的事件和属性来计算指标值。指标值评估取决于指标支持的评估模式 CUpti_MetricEvaluationMode。如果指标的评估模式为 CUPTI_METRIC_EVALUATION_MODE_PER_INSTANCE，则它假定输入事件值是针对一个域实例的。如果指标的评估模式为 CUPTI_METRIC_EVALUATION_MODE_AGGREGATE，则它假定输入事件值已归一化，以表示设备上的所有域实例。为了最准确地收集指标，应该为所有已分析的域实例收集指标所需的事件。例如，要收集事件的所有实例，请将包含该事件的组的 CUPTI_EVENT_GROUP_ATTR_PROFILE_ALL_DOMAIN_INSTANCES 属性设置为 1。然后，事件的归一化值为：(sum_event_values * totalInstanceCount) / instanceCount，其中 sum_event_values 是跨所有已分析域实例的事件值的总和，totalInstanceCount 是从查询 CUPTI_EVENT_DOMAIN_ATTR_TOTAL_INSTANCE_COUNT 获得的，instanceCount 是从查询 CUPTI_EVENT_GROUP_ATTR_INSTANCE_COUNT (或 CUPTI_EVENT_DOMAIN_ATTR_INSTANCE_COUNT) 获得的。

参数

  • metric – 指标 ID

  • eventIdArraySizeBytes – eventIdArray 的大小（以字节为单位）

  • eventIdArray – 计算 metric 所需的事件 ID

  • eventValueArraySizeBytes – eventValueArray 的大小（以字节为单位）

  • eventValueArray – 计算 metric 所需的标准化事件值。 这些值的顺序必须与 eventIdArray 中事件的顺序匹配

  • propIdArraySizeBytes – propIdArray 的大小（以字节为单位）

  • propIdArray – 计算 metric 所需的指标属性 ID

  • propValueArraySizeBytes – propValueArray 的大小（以字节为单位）

  • propValueArray – 计算 metric 所需的指标属性值。这些值的顺序必须与 propIdArray 中指标属性的顺序匹配

  • metricValue – 返回指标的值

返回值

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_NOT_INITIALIZED –

  • CUPTI_ERROR_INVALID_METRIC_ID –

  • CUPTI_ERROR_INVALID_OPERATION –

  • CUPTI_ERROR_PARAMETER_SIZE_NOT_SUFFICIENT – 如果 eventIdArray 不包含指标所需的所有事件

  • CUPTI_ERROR_INVALID_EVENT_VALUE – 如果指标所需的任何事件值为 CUPTI_EVENT_OVERFLOW

  • CUPTI_ERROR_NOT_COMPATIBLE – 如果计算出的指标值无法用指标的值类型表示。例如，如果指标值类型是无符号的，而计算出的指标值是负数

  • CUPTI_ERROR_INVALID_PARAMETER – 如果 metricValue、eventIdArray 或 eventValueArray 为 NULL

5.5.3. Typedefs

typedef uint32_t CUpti_MetricID

指标的 ID。

指标提供了衡量设备某些方面的度量。