字段 API

group DCGMAPI_FI

这些 API 负责监视、取消监视和更新由 DCGM_FI_* 定义的特定字段。

函数

dcgmReturn_t dcgmWatchFields(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, long long updateFreq, double maxKeepAge, int maxKeepSamples)

请求 DCGM 开始记录给定字段集合的更新。

请注意，字段的首次更新将不会发生，直到下一个字段更新周期。要强制执行字段更新周期，请调用 dcgmUpdateAllFields(1)。

参数:

  • pDcgmHandle – IN: DCGM 句柄

  • groupId – IN: 组 ID，表示一个或多个实体的集合。有关创建组的详细信息，请查看 dcgmGroupCreate。或者，传入组 ID 作为 DCGM_GROUP_ALL_GPUS 以对所有 GPU 执行操作，或作为 DCGM_GROUP_ALL_NVSWITCHES 以对所有 NvSwitch 执行操作。

  • fieldGroupId – IN: 要监视的字段。

  • updateFreq – IN: 更新此字段的频率，单位为微秒

  • maxKeepAge – IN: 此字段的数据保留时间，单位为秒

  • maxKeepSamples – IN: 要保留的最大样本数。0=无限制

返回值:

dcgmReturn_t dcgmUnwatchFields(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId)

请求 DCGM 停止记录给定字段集合的更新。

参数:

  • pDcgmHandle – IN: DCGM 句柄

  • groupId – IN: 组 ID，表示一个或多个实体的集合。有关创建组的详细信息，请查看 dcgmGroupCreate。或者，传入组 ID 作为 DCGM_GROUP_ALL_GPUS 以对所有 GPU 执行操作，或作为 DCGM_GROUP_ALL_NVSWITCHES 以对所有 NvSwitch 执行操作。

  • fieldGroupId – IN: 要取消监视的字段。

返回值:

dcgmReturn_t dcgmGetValuesSince(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, long long sinceTimestamp, long long *nextSinceTimestamp, dcgmFieldValueEnumeration_f enumCB, void *userData)

请求自给定时间戳以来已更新的所有字段值的更新。

此版本仅适用于 GPU 实体。对于包含 NvSwitch 的实体组，请使用 dcgmGetValuesSince_v2。

参数:

  • pDcgmHandle – IN: DCGM 句柄

  • groupId – IN: 组 ID，表示一个或多个 GPU 的集合。有关创建组的详细信息，请查看 dcgmGroupCreate。或者，传入组 ID 作为 DCGM_GROUP_ALL_GPUS 以对所有 GPU 执行操作。

  • fieldGroupId – IN: 要为其返回数据的字段

  • sinceTimestamp – IN: 请求自那时起的值的时间戳，单位为自 1970 年以来的微秒数。这将会在 nextSinceTimestamp 中返回，用于后续调用。0 = 请求所有数据

  • nextSinceTimestamp – OUT: 时间戳，用于下次调用此函数时作为 sinceTimestamp

  • enumCB – IN: 为每个字段值更新调用的回调。请注意，每次调用中可以返回多个更新

  • userData – IN: 用户数据指针，用于传递到 enumCB 的 userData 字段。

返回值:

dcgmReturn_t dcgmGetValuesSince_v2(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, long long sinceTimestamp, long long *nextSinceTimestamp, dcgmFieldValueEntityEnumeration_f enumCB, void *userData)

请求自给定时间戳以来已更新的所有字段值的更新。

此版本适用于非 GPU 实体，如 NvSwitch

参数:

  • pDcgmHandle – IN: DCGM 句柄

  • groupId – IN: 组 ID，表示一个或多个实体的集合。有关创建组的详细信息，请查看 dcgmGroupCreate。或者，传入组 ID 作为 DCGM_GROUP_ALL_GPUS 以对所有 GPU 执行操作，或作为 DCGM_GROUP_ALL_NVSWITCHES 以对所有 NvSwitch 执行操作。

  • fieldGroupId – IN: 要为其返回数据的字段

  • sinceTimestamp – IN: 请求自那时起的值的时间戳，单位为自 1970 年以来的微秒数。这将会在 nextSinceTimestamp 中返回，用于后续调用。0 = 请求所有数据

  • nextSinceTimestamp – OUT: 时间戳，用于下次调用此函数时作为 sinceTimestamp

  • enumCB – IN: 为每个字段值更新调用的回调。请注意，每次调用中可以返回多个更新

  • userData – IN: 用户数据指针，用于传递到 enumCB 的 userData 字段。

返回值:

dcgmReturn_t dcgmGetLatestValues(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, dcgmFieldValueEnumeration_f enumCB, void *userData)

请求字段值集合的最新缓存字段值。

此版本仅适用于 GPU 实体。对于包含 NvSwitch 的实体组，请使用 dcgmGetLatestValues_v2。

参数:

  • pDcgmHandle – IN: DCGM 句柄

  • groupId – IN: 组 ID，表示一个或多个 GPU 的集合。有关创建组的详细信息，请查看 dcgmGroupCreate。或者，传入组 ID 作为 DCGM_GROUP_ALL_GPUS 以对所有 GPU 执行操作。

  • fieldGroupId – IN: 要为其返回数据的字段。

  • enumCB – IN: 为每个字段值更新调用的回调。请注意，每次调用中可以返回多个更新

  • userData – IN: 用户数据指针，用于传递到 enumCB 的 userData 字段。

返回值:

dcgmReturn_t dcgmGetLatestValues_v2(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, dcgmFieldValueEntityEnumeration_f enumCB, void *userData)

请求字段值集合的最新缓存字段值。

此版本适用于非 GPU 实体，如 NvSwitch

参数:

  • pDcgmHandle – IN: DCGM 句柄

  • groupId – IN: 组 ID，表示一个或多个实体的集合。有关创建组的详细信息，请查看 dcgmGroupCreate。或者，传入组 ID 作为 DCGM_GROUP_ALL_GPUS 以对所有 GPU 执行操作，或作为 DCGM_GROUP_ALL_NVSWITCHES 以对所有 NvSwitch 执行操作。

  • fieldGroupId – IN: 要为其返回数据的字段。

  • enumCB – IN: 为每个字段值更新调用的回调。请注意，每次调用中可以返回多个更新

  • userData – IN: 用户数据指针，用于传递到 enumCB 的 userData 字段。

返回值:

dcgmReturn_t dcgmGetLatestValuesForFields(dcgmHandle_t pDcgmHandle, int gpuId, unsigned short fields[], unsigned int count, dcgmFieldValue_v1 values[])

请求 GPU 的最新缓存字段值。

参数:

  • pDcgmHandle – IN: DCGM 句柄

  • gpuId – IN: Gpu ID，表示请求字段的 GPU。

  • fields – IN: 要返回数据的字段 ID。 请参阅 dcgm_fields.h 中以 DCGM_FI_ 开头的定义。

  • count – IN: fields[] 数组中的字段 ID 数量。

  • values – OUT: fields[] 中字段的最新字段值。

dcgmReturn_t dcgmEntityGetLatestValues(dcgmHandle_t pDcgmHandle, dcgm_field_entity_group_t entityGroup, int entityId, unsigned short fields[], unsigned int count, dcgmFieldValue_v1 values[])

请求特定实体的字段组的最新缓存字段值。

参数:

  • pDcgmHandle – IN: DCGM 句柄

  • entityGroup – IN: entity_group_t (例如 switch)

  • entityId – IN: 表示请求字段的实体的实体 ID。

  • fields – IN: 要返回数据的字段 ID。 请参阅 dcgm_fields.h 中以 DCGM_FI_ 开头的定义。

  • count – IN: fields[] 数组中的字段 ID 数量。

  • values – OUT: fields[] 中字段的最新字段值。

dcgmReturn_t dcgmEntitiesGetLatestValues(dcgmHandle_t pDcgmHandle, dcgmGroupEntityPair_t entities[], unsigned int entityCount, unsigned short fields[], unsigned int fieldCount, unsigned int flags, dcgmFieldValue_v2 values[])

请求一组实体的字段列表的最新缓存或实时字段值。

注意：不保证返回的实体的顺序。 为了优化对 NVIDIA 驱动程序的调用，可能会在内部重新排序。

参数:

  • pDcgmHandle – IN: DCGM 句柄

  • entities – IN: 要获取值的实体列表

  • entityCount – IN: entities[] 中的条目数

  • fields – IN: 要返回数据的字段 ID。 请参阅 dcgm_fields.h 中以 DCGM_FI_ 开头的定义。

  • fieldCount – IN: fields[] 数组中的字段 ID 数量。

  • flags – IN: 影响此请求处理方式的可选标志。 传递 DCGM_FV_FLAG_LIVE_DATA 以在此处检索实时驱动程序值，而不是缓存值。 有关注意事项，请参阅该标志的文档。

  • values – OUT: 请求的字段的最新字段值。 这必须能够容纳 entityCount * fieldCount 字段值记录。

dcgmReturn_t dcgmGetFieldSummary(dcgmHandle_t pDcgmHandle, dcgmFieldSummaryRequest_t *request)

获取一段时间内字段 ID 的值摘要。

参数:

  • pDcgmHandle – IN: DCGM 句柄

  • request – IN/OUT: 指向详细说明请求并包含响应的结构的指针

返回值: