系统

group DCGMAPI_SYS

本章介绍用于识别节点上实体的 API、用于提供对实体组进行操作的机制的分组函数，以及用于获取每个操作的单独状态的状态管理 API。

系统模块中的 API 可以分为以下几类

以下 API 用于发现 GPU 及其在节点上的属性。

函数

dcgmReturn_t dcgmGetAllDevices(dcgmHandle_t pDcgmHandle, unsigned int gpuIdList[32], int *count)

此方法用于获取与系统上所有设备对应的标识符。

该标识符表示与系统上每个 GPU 对应的 DCGM GPU ID，并且在引擎的生命周期内是不可变的。如果引擎重新启动，则应再次查询列表。

从此函数返回的 GPU 包括 DCGM 不支持的 GPU 的 gpuId。要仅获取 DCGM 支持的 GPU 的 gpuId，请使用 dcgmGetAllSupportedDevices()。

参数:

• pDcgmHandle – IN: DCGM 句柄

• gpuIdList – OUT: 用于填充系统上存在的 GPU ID 的数组引用。

• count – OUT: gpuIdList 中返回的 GPU 数量。

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果 gpuIdList 或 count 无效，则返回 DCGM_ST_BADPARAM。

dcgmReturn_t dcgmGetAllSupportedDevices(dcgmHandle_t pDcgmHandle, unsigned int gpuIdList[32], int *count)

此方法用于获取与系统上所有 DCGM 支持的设备对应的标识符。

该标识符表示与系统上每个 GPU 对应的 DCGM GPU ID，并且在引擎的生命周期内是不可变的。如果引擎重新启动，则应再次查询列表。

从此函数返回的 GPU 仅包括 DCGM 支持的 GPU 的 gpuId。要获取系统中所有 GPU 的 gpuId，请使用 dcgmGetAllDevices()。

参数:

• pDcgmHandle – IN: DCGM 句柄

• gpuIdList – OUT: 用于填充系统上存在的 GPU ID 的数组引用。

• count – OUT: gpuIdList 中返回的 GPU 数量。

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果 gpuIdList 或 count 无效，则返回 DCGM_ST_BADPARAM。

dcgmReturn_t dcgmGetDeviceAttributes(dcgmHandle_t pDcgmHandle, unsigned int gpuId, dcgmDeviceAttributes_t *pDcgmAttr)

获取与 gpuId 对应的设备属性。

如果任何请求的字段的操作不成功，则该字段将填充 dcgm_structs.h 中定义的 DCGM_BLANK_VALUES 之一。

参数:

• pDcgmHandle – IN: DCGM 句柄

• gpuId – IN: GPU ID，应针对该 ID 获取属性

• pDcgmAttr – IN/OUT: 与 gpuId 对应的设备属性

  .

  pDcgmAttr->version 应设置为

  调用此函数之前，请设置为 dcgmDeviceAttributes_version。

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果 pDcgmAttr->version 未设置或无效，则返回 DCGM_ST_VER_MISMATCH。

dcgmReturn_t dcgmGetEntityGroupEntities(dcgmHandle_t dcgmHandle, dcgm_field_entity_group_t entityGroup, dcgm_field_eid_t *entities, int *numEntities, unsigned int flags)

获取给定实体组存在的实体列表。

此 API 可以代替 dcgmGetAllDevices 使用。

参数:

• dcgmHandle – IN: DCGM 句柄

• entityGroup – IN: 要列出实体的实体组

• entities – OUT: entityGroup 的实体数组

• numEntities – IN/OUT: 调用时，这应该是 entityList[] 可以容纳的实体数量。 返回时，这将包含实际保存到 entityList 的实体数量。

• flags – IN: 用于修改此请求行为的标志。 请参阅 dcgm_structs.h 中的 DCGM_GEGE_FLAG_* #defines

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果 numEntities 不足以容纳 entityGroup 中的实体数量，则返回 DCGM_ST_INSUFFICIENT_SIZE。 numEntities 将包含成功完成此请求所需的能力。

• 如果给定的 entityGroup 不支持枚举，则返回 DCGM_ST_NOT_SUPPORTED。

• 如果任何参数无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGetGpuInstanceHierarchy(dcgmHandle_t dcgmHandle, dcgmMigHierarchy_v2 *hierarchy)

获取 GPU、GPU 实例和计算实例的层次结构。

参数:

• dcgmHandle – IN: DCGM 句柄

• hierarchy – OUT: GPU、GPU 实例和计算实例的层次结构

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果结构版本不正确，则返回 DCGM_ST_VER_MISMATCH

• 如果任何参数无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGetNvLinkLinkStatus(dcgmHandle_t dcgmHandle, dcgmNvLinkStatus_v4 *linkStatus)

获取此系统中每个 NvLink 的 NvLink 链接状态。

这包括 GPU 和 NvSwitch 的 NvLink。 请注意，此结构中仅返回当前环境可见的 NvSwitch 和 GPU。

参数:

• dcgmHandle – IN: DCGM 句柄

• linkStatus – OUT: 用于存储 NvLink 链接状态的结构。 在调用此函数之前，.version 应设置为 dcgmNvLinkStatus_version1。

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果给定的 entityGroup 不支持枚举，则返回 DCGM_ST_NOT_SUPPORTED。

• 如果任何参数无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGetCpuHierarchy(dcgmHandle_t dcgmHandle, dcgmCpuHierarchy_v1 *cpuHierarchy)

列出系统上受支持的 CPU 及其内核。

此 API 和其他 CPU API 仅支持数据中心 NVIDIA CPU。 使用 dcgmGetCpuHierarchy_v2 获取其他 CPU 信息。

参数:

• dcgmHandle – IN: DCGM 句柄

• cpuHierarchy – OUT: 将在其中枚举 CPU 及其关联内核的结构

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果设备不受支持，则返回 DCGM_ST_NOT_SUPPORTED

• 如果无法加载 sysmon 模块，则返回 DCGM_ST_MODULE_NOT_LOADED

• 如果任何参数无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGetCpuHierarchy_v2(dcgmHandle_t dcgmHandle, dcgmCpuHierarchy_v2 *cpuHierarchy)

列出系统上受支持的 CPU 及其内核。

此 API 和其他 CPU API 仅支持数据中心 NVIDIA CPU。

参数:

• dcgmHandle – IN: DCGM 句柄

• cpuHierarchy – OUT: 将在其中枚举 CPU 及其关联内核的结构

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果设备不受支持，则返回 DCGM_ST_NOT_SUPPORTED

• 如果无法加载 sysmon 模块，则返回 DCGM_ST_MODULE_NOT_LOADED

• 如果任何参数无效，则返回 DCGM_ST_BADPARAM

以下 API 用于组管理。

用户可以创建实体组，并对实体组执行操作。 如果不需要分组，并且用户希望在 DCGM 看到的所有 GPU 上运行命令，则在需要时，用户可以使用 DCGM_GROUP_ALL_GPUS 或 DCGM_GROUP_ALL_NVSWITCHES 代替组 ID。

函数

dcgmReturn_t dcgmGroupCreate(dcgmHandle_t pDcgmHandle, dcgmGroupType_t type, const char *groupName, dcgmGpuGrp_t *pDcgmGrpId)

用于创建实体组句柄，该句柄可以存储一个或多个实体 ID，作为 pDcgmGrpId 中返回的不透明句柄。

DCGM 组使用户能够对组中存在的所有实体执行相同的操作，只需一次 API 调用，而不是为每个实体单独执行操作。

要使用系统上存在的所有实体创建组，type 字段应指定为 DCGM_GROUP_DEFAULT 或 DCGM_GROUP_ALL_NVSWITCHES。 要创建空组，type 字段应指定为 DCGM_GROUP_EMPTY。 可以使用 API dcgmGroupAddDevice、dcgmGroupAddEntity、dcgmGroupRemoveDevice 和 dcgmGroupRemoveEntity 使用所需的实体集更新空组。

参数:

• pDcgmHandle – IN: DCGM 句柄

• type – IN: 要形成的实体组的类型

• groupName – IN: GPU 组的所需名称，指定为 NULL 终止的 C 字符串

• pDcgmGrpId – OUT: 组 ID 的引用

返回值:

• 如果已创建组，则返回 DCGM_ST_OK

• 如果 type、groupName、length 或 pDcgmGrpId 中的任何一个无效，则返回 DCGM_ST_BADPARAM

• 如果系统上的组数已达到最大限制 DCGM_MAX_NUM_GROUPS，则返回 DCGM_ST_MAX_LIMIT

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR

dcgmReturn_t dcgmGroupDestroy(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId)

用于销毁由 groupId 表示的组。

由于 DCGM 组是实体的逻辑分组，因此即使在组销毁后，应用于组的属性对于单个实体仍然保持不变。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupId – IN: 组 ID

返回值:

• 如果组已销毁，则返回 DCGM_ST_OK

• 如果 groupId 无效，则返回 DCGM_ST_BADPARAM

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR

• 如果与组对应的条目不存在，则返回 DCGM_ST_NOT_CONFIGURED

dcgmReturn_t dcgmGroupAddDevice(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, unsigned int gpuId)

用于将指定的 GPU ID 添加到由 groupId 表示的组。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupId – IN: 应向其添加设备的组 ID

• gpuId – IN: DCGM GPU ID

返回值:

• 如果 GPU ID 已成功添加到组，则返回 DCGM_ST_OK

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR

• 如果与组 (groupId) 对应的条目不存在，则返回 DCGM_ST_NOT_CONFIGURED

• 如果 gpuId 无效或已是指定组的一部分，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGroupAddEntity(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgm_field_entity_group_t entityGroupId, dcgm_field_eid_t entityId)

用于将指定的实体添加到由 groupId 代表的组。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupId – IN: 应向其添加设备的组 ID

• entityGroupId – 输入：实体 ID 所属的实体组

• entityId – 输入：DCGM 实体 ID

返回值:

• 如果实体已成功添加到组，则返回 DCGM_ST_OK

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR

• 如果与组 (groupId) 对应的条目不存在，则返回 DCGM_ST_NOT_CONFIGURED

• 如果 entityId 无效或已是指定组的一部分，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGroupRemoveDevice(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, unsigned int gpuId)

用于从由 groupId 代表的组中移除指定的 GPU ID。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupId – 输入：要从中移除设备的组 ID

• gpuId – IN: DCGM GPU ID

返回值:

• 如果 GPU ID 已成功从组中移除，则返回 DCGM_ST_OK

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR

• 如果与组 (groupId) 对应的条目不存在，则返回 DCGM_ST_NOT_CONFIGURED

• 如果 gpuId 无效或不是指定组的一部分，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGroupRemoveEntity(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgm_field_entity_group_t entityGroupId, dcgm_field_eid_t entityId)

用于从由 groupId 代表的组中移除指定的实体。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupId – 输入：要从中移除设备的组 ID

• entityGroupId – 输入：实体 ID 所属的实体组

• entityId – 输入：DCGM 实体 ID

返回值:

• 如果实体已成功从组中移除，则返回 DCGM_ST_OK

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR

• 如果与组 (groupId) 对应的条目不存在，则返回 DCGM_ST_NOT_CONFIGURED

• 如果 entityId 无效或不是指定组的一部分，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGroupGetInfo(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmGroupInfo_t *pDcgmGroupInfo)

用于获取与 groupId 代表的组相对应的信息。

在 pDcgmGroupInfo 中返回的信息包括组名称以及组中存在的实体列表。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupId – 输入：要获取信息的组 ID

• pDcgmGroupInfo – 输出：组信息

返回值:

• 如果成功接收到组信息，则返回 DCGM_ST_OK。

• 如果 groupId 或 pDcgmGroupInfo 中的任何一个无效，则返回 DCGM_ST_BADPARAM。

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR。

• 如果组不包含 GPU，则返回 DCGM_ST_MAX_LIMIT

• 如果与组 (groupId) 对应的条目不存在，则返回 DCGM_ST_NOT_CONFIGURED

dcgmReturn_t dcgmGroupGetAllIds(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupIdList[], unsigned int *count)

用于获取所有实体组的 ID。

返回的信息是 groupIdList 中的组 ID 列表以及 count 中的 ID 数量计数。请为 groupIdList 分配足够的内存。应为 groupIdList 分配 MAX_NUM_GROUPS 大小的内存。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupIdList – 输出：组 ID 列表

• count – 输出：列表中组 ID 的数量

返回值:

• 如果成功检索到组的 ID，则返回 DCGM_ST_OK

• 如果 groupIdList 或 count 中的任何一个为空，则返回 DCGM_ST_BADPARAM

• 如果发生未知错误，则返回 DCGM_ST_GENERIC_ERROR

以下 API 用于字段组管理。

用户可以创建一个字段组，并一次对一组字段执行操作。

函数

dcgmReturn_t dcgmFieldGroupCreate(dcgmHandle_t dcgmHandle, int numFieldIds, unsigned short *fieldIds, const char *fieldGroupName, dcgmFieldGrp_t *dcgmFieldGroupId)

用于创建字段组并在 dcgmFieldGroupId 中返回句柄。

参数:

• dcgmHandle – 输入：DCGM 句柄

• numFieldIds – 输入：在 fieldIds[] 中提供的字段 ID 的数量。必须介于 1 和 DCGM_MAX_FIELD_IDS_PER_FIELD_GROUP 之间。

• fieldIds – 输入：要添加到新创建的字段组的字段 ID

• fieldGroupName – 输入：此字段组的唯一名称。此名称不得与任何现有字段组相同。

• dcgmFieldGroupId – 输出：新创建的字段组的句柄

返回值:

• 如果字段组已成功创建，则返回 DCGM_ST_OK。

• 如果任何参数错误，则返回 DCGM_ST_BADPARAM

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR。

• 如果已存在太多字段组，则返回 DCGM_ST_MAX_LIMIT

dcgmReturn_t dcgmFieldGroupDestroy(dcgmHandle_t dcgmHandle, dcgmFieldGrp_t dcgmFieldGroupId)

用于移除使用 dcgmFieldGroupCreate 创建的字段组。

参数:

• dcgmHandle – 输入：DCGM 句柄

• dcgmFieldGroupId – 输入：要移除的字段组

返回值:

• 如果字段组已成功移除，则返回 DCGM_ST_OK

• 如果任何参数错误，则返回 DCGM_ST_BADPARAM

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR。

dcgmReturn_t dcgmFieldGroupGetInfo(dcgmHandle_t dcgmHandle, dcgmFieldGroupInfo_t *fieldGroupInfo)

用于获取有关使用 dcgmFieldGroupCreate 创建的字段组的信息。

参数:

• dcgmHandle – 输入：DCGM 句柄

• fieldGroupInfo –

  输入/输出：有关所有现有字段组的信息。

  在调用之前，.version 应设置为

  dcgmFieldGroupInfo_version

  .fieldGroupId 应包含您想要查询信息的 fieldGroupId。

返回值:

• 如果成功返回字段组信息，则返回 DCGM_ST_OK

• 如果任何参数错误，则返回 DCGM_ST_BADPARAM

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR。

• 如果 .version 未设置或无效，则返回 DCGM_ST_VER_MISMATCH。

dcgmReturn_t dcgmFieldGroupGetAll(dcgmHandle_t dcgmHandle, dcgmAllFieldGroup_t *allGroupInfo)

用于获取有关系统中所有字段组的信息。

参数:

• dcgmHandle – 输入：DCGM 句柄

• allGroupInfo –

  输入/输出：有关所有现有字段组的信息。

  在调用之前，.version 应设置为

  在调用之前，应设置为 dcgmAllFieldGroup_version。

返回值:

• 如果成功返回字段组信息，则返回 DCGM_ST_OK

• 如果任何参数错误，则返回 DCGM_ST_BADPARAM

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR。

• 如果 .version 未设置或无效，则返回 DCGM_ST_VER_MISMATCH。

以下 API 用于管理在一个或多个 GPU 上执行多个操作的状态。

函数

dcgmReturn_t dcgmStatusCreate(dcgmStatus_t *statusHandle)

创建对 DCGM 状态处理程序的引用，该引用可用于获取在一个或多个设备上执行多个操作的状态。

当操作在组级别执行时，多个状态非常有用。状态句柄提供了一种访问失败操作的错误属性的机制。

可以使用 API dcgmStatusGetCount 访问存储在不透明句柄后面的错误数量。可以使用 API dcgmStatusPopError 从不透明句柄 statusHandle 访问错误。用户可以调用 dcgmStatusPopError 来获取错误数量，或者直到获取所有错误。

当不再需要状态句柄时，应使用 API dcgmStatusDestroy 删除它。

参数:

statusHandle – 输出：状态列表的句柄引用

返回值:

• 如果状态句柄已成功创建，则返回 DCGM_ST_OK

• 如果 statusHandle 无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmStatusDestroy(dcgmStatus_t statusHandle)

用于销毁使用 dcgmStatusCreate 创建的状态句柄。

参数:

statusHandle – 输入：状态列表的句柄

返回值:

• 如果状态句柄已成功创建，则返回 DCGM_ST_OK

• 如果 statusHandle 无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmStatusGetCount(dcgmStatus_t statusHandle, unsigned int *count)

用于获取存储在不透明句柄 statusHandle 内的错误条目的计数。

参数:

• statusHandle – 输入：状态列表的句柄

• count – 输出：状态列表中存在的错误条目的数量

返回值:

• 如果成功接收到错误计数，则返回 DCGM_ST_OK

• 如果 statusHandle 或 count 中的任何一个无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmStatusPopError(dcgmStatus_t statusHandle, dcgmErrorInfo_t *pDcgmErrorInfo)

用于遍历在 statusHandle 后维护的错误列表。

该方法从 DCGM 状态列表中弹出第一个错误。为了遍历所有错误，用户可以调用此 API 来获取错误数量，或者直到获取所有错误。

参数:

• statusHandle – 输入：状态列表的句柄

• pDcgmErrorInfo – 输出：状态列表中的第一个错误

返回值:

• 如果成功获取错误条目，则返回 DCGM_ST_OK

• 如果 statusHandle 或 pDcgmErrorInfo 中的任何一个无效，则返回 DCGM_ST_BADPARAM

• 如果状态句柄列表为空，则返回 DCGM_ST_NO_DATA

dcgmReturn_t dcgmStatusClear(dcgmStatus_t statusHandle)

用于清除由 API dcgmStatusCreate 创建的状态句柄中的所有错误。

在一组操作之后，可以清除 *statusHandle* 并将其重新用于下一组操作。

参数:

statusHandle – 输入：状态列表的句柄

返回值:

• 如果错误已成功清除，则返回 DCGM_ST_OK

• 如果 statusHandle 无效，则返回 DCGM_ST_BADPARAM

发现

group DCGM_DISCOVERY

以下 API 用于发现 GPU 及其在节点上的属性。

函数

dcgmReturn_t dcgmGetAllDevices(dcgmHandle_t pDcgmHandle, unsigned int gpuIdList[32], int *count)

此方法用于获取与系统上所有设备对应的标识符。

该标识符表示与系统上每个 GPU 对应的 DCGM GPU ID，并且在引擎的生命周期内是不可变的。如果引擎重新启动，则应再次查询列表。

从此函数返回的 GPU 包括 DCGM 不支持的 GPU 的 gpuId。要仅获取 DCGM 支持的 GPU 的 gpuId，请使用 dcgmGetAllSupportedDevices()。

参数:

• pDcgmHandle – IN: DCGM 句柄

• gpuIdList – OUT: 用于填充系统上存在的 GPU ID 的数组引用。

• count – OUT: gpuIdList 中返回的 GPU 数量。

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果 gpuIdList 或 count 无效，则返回 DCGM_ST_BADPARAM。

dcgmReturn_t dcgmGetAllSupportedDevices(dcgmHandle_t pDcgmHandle, unsigned int gpuIdList[32], int *count)

此方法用于获取与系统上所有 DCGM 支持的设备对应的标识符。

该标识符表示与系统上每个 GPU 对应的 DCGM GPU ID，并且在引擎的生命周期内是不可变的。如果引擎重新启动，则应再次查询列表。

从此函数返回的 GPU 仅包括 DCGM 支持的 GPU 的 gpuId。要获取系统中所有 GPU 的 gpuId，请使用 dcgmGetAllDevices()。

参数:

• pDcgmHandle – IN: DCGM 句柄

• gpuIdList – OUT: 用于填充系统上存在的 GPU ID 的数组引用。

• count – OUT: gpuIdList 中返回的 GPU 数量。

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果 gpuIdList 或 count 无效，则返回 DCGM_ST_BADPARAM。

dcgmReturn_t dcgmGetDeviceAttributes(dcgmHandle_t pDcgmHandle, unsigned int gpuId, dcgmDeviceAttributes_t *pDcgmAttr)

获取与 gpuId 对应的设备属性。

如果任何请求的字段的操作不成功，则该字段将填充 dcgm_structs.h 中定义的 DCGM_BLANK_VALUES 之一。

参数:

• pDcgmHandle – IN: DCGM 句柄

• gpuId – IN: GPU ID，应针对该 ID 获取属性

• pDcgmAttr – IN/OUT: 与 gpuId 对应的设备属性

  .

  pDcgmAttr->version 应设置为

  调用此函数之前，请设置为 dcgmDeviceAttributes_version。

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果 pDcgmAttr->version 未设置或无效，则返回 DCGM_ST_VER_MISMATCH。

dcgmReturn_t dcgmGetEntityGroupEntities(dcgmHandle_t dcgmHandle, dcgm_field_entity_group_t entityGroup, dcgm_field_eid_t *entities, int *numEntities, unsigned int flags)

获取给定实体组存在的实体列表。

此 API 可以代替 dcgmGetAllDevices 使用。

参数:

• dcgmHandle – IN: DCGM 句柄

• entityGroup – IN: 要列出实体的实体组

• entities – OUT: entityGroup 的实体数组

• numEntities – IN/OUT: 调用时，这应该是 entityList[] 可以容纳的实体数量。 返回时，这将包含实际保存到 entityList 的实体数量。

• flags – IN: 用于修改此请求行为的标志。 请参阅 dcgm_structs.h 中的 DCGM_GEGE_FLAG_* #defines

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果 numEntities 不足以容纳 entityGroup 中的实体数量，则返回 DCGM_ST_INSUFFICIENT_SIZE。 numEntities 将包含成功完成此请求所需的能力。

• 如果给定的 entityGroup 不支持枚举，则返回 DCGM_ST_NOT_SUPPORTED。

• 如果任何参数无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGetGpuInstanceHierarchy(dcgmHandle_t dcgmHandle, dcgmMigHierarchy_v2 *hierarchy)

获取 GPU、GPU 实例和计算实例的层次结构。

参数:

• dcgmHandle – IN: DCGM 句柄

• hierarchy – OUT: GPU、GPU 实例和计算实例的层次结构

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果结构版本不正确，则返回 DCGM_ST_VER_MISMATCH

• 如果任何参数无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGetNvLinkLinkStatus(dcgmHandle_t dcgmHandle, dcgmNvLinkStatus_v4 *linkStatus)

获取此系统中每个 NvLink 的 NvLink 链接状态。

这包括 GPU 和 NvSwitch 的 NvLink。 请注意，此结构中仅返回当前环境可见的 NvSwitch 和 GPU。

参数:

• dcgmHandle – IN: DCGM 句柄

• linkStatus – OUT: 用于存储 NvLink 链接状态的结构。 在调用此函数之前，.version 应设置为 dcgmNvLinkStatus_version1。

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果给定的 entityGroup 不支持枚举，则返回 DCGM_ST_NOT_SUPPORTED。

• 如果任何参数无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGetCpuHierarchy(dcgmHandle_t dcgmHandle, dcgmCpuHierarchy_v1 *cpuHierarchy)

列出系统上受支持的 CPU 及其内核。

此 API 和其他 CPU API 仅支持数据中心 NVIDIA CPU。 使用 dcgmGetCpuHierarchy_v2 获取其他 CPU 信息。

参数:

• dcgmHandle – IN: DCGM 句柄

• cpuHierarchy – OUT: 将在其中枚举 CPU 及其关联内核的结构

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果设备不受支持，则返回 DCGM_ST_NOT_SUPPORTED

• 如果无法加载 sysmon 模块，则返回 DCGM_ST_MODULE_NOT_LOADED

• 如果任何参数无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGetCpuHierarchy_v2(dcgmHandle_t dcgmHandle, dcgmCpuHierarchy_v2 *cpuHierarchy)

列出系统上受支持的 CPU 及其内核。

此 API 和其他 CPU API 仅支持数据中心 NVIDIA CPU。

参数:

• dcgmHandle – IN: DCGM 句柄

• cpuHierarchy – OUT: 将在其中枚举 CPU 及其关联内核的结构

返回值:

• 如果调用成功，则返回 DCGM_ST_OK。

• 如果设备不受支持，则返回 DCGM_ST_NOT_SUPPORTED

• 如果无法加载 sysmon 模块，则返回 DCGM_ST_MODULE_NOT_LOADED

• 如果任何参数无效，则返回 DCGM_ST_BADPARAM

分组

group DCGM_GROUPING

以下 API 用于组管理。

用户可以创建实体组，并对实体组执行操作。 如果不需要分组，并且用户希望在 DCGM 看到的所有 GPU 上运行命令，则在需要时，用户可以使用 DCGM_GROUP_ALL_GPUS 或 DCGM_GROUP_ALL_NVSWITCHES 代替组 ID。

函数

dcgmReturn_t dcgmGroupCreate(dcgmHandle_t pDcgmHandle, dcgmGroupType_t type, const char *groupName, dcgmGpuGrp_t *pDcgmGrpId)

用于创建实体组句柄，该句柄可以存储一个或多个实体 ID，作为 pDcgmGrpId 中返回的不透明句柄。

DCGM 组使用户能够对组中存在的所有实体执行相同的操作，只需一次 API 调用，而不是为每个实体单独执行操作。

要使用系统上存在的所有实体创建组，type 字段应指定为 DCGM_GROUP_DEFAULT 或 DCGM_GROUP_ALL_NVSWITCHES。 要创建空组，type 字段应指定为 DCGM_GROUP_EMPTY。 可以使用 API dcgmGroupAddDevice、dcgmGroupAddEntity、dcgmGroupRemoveDevice 和 dcgmGroupRemoveEntity 使用所需的实体集更新空组。

参数:

• pDcgmHandle – IN: DCGM 句柄

• type – IN: 要形成的实体组的类型

• groupName – IN: GPU 组的所需名称，指定为 NULL 终止的 C 字符串

• pDcgmGrpId – OUT: 组 ID 的引用

返回值:

• 如果已创建组，则返回 DCGM_ST_OK

• 如果 type、groupName、length 或 pDcgmGrpId 中的任何一个无效，则返回 DCGM_ST_BADPARAM

• 如果系统上的组数已达到最大限制 DCGM_MAX_NUM_GROUPS，则返回 DCGM_ST_MAX_LIMIT

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR

dcgmReturn_t dcgmGroupDestroy(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId)

用于销毁由 groupId 表示的组。

由于 DCGM 组是实体的逻辑分组，因此即使在组销毁后，应用于组的属性对于单个实体仍然保持不变。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupId – IN: 组 ID

返回值:

• 如果组已销毁，则返回 DCGM_ST_OK

• 如果 groupId 无效，则返回 DCGM_ST_BADPARAM

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR

• 如果与组对应的条目不存在，则返回 DCGM_ST_NOT_CONFIGURED

dcgmReturn_t dcgmGroupAddDevice(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, unsigned int gpuId)

用于将指定的 GPU ID 添加到由 groupId 表示的组。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupId – IN: 应向其添加设备的组 ID

• gpuId – IN: DCGM GPU ID

返回值:

• 如果 GPU ID 已成功添加到组，则返回 DCGM_ST_OK

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR

• 如果与组 (groupId) 对应的条目不存在，则返回 DCGM_ST_NOT_CONFIGURED

• 如果 gpuId 无效或已是指定组的一部分，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGroupAddEntity(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgm_field_entity_group_t entityGroupId, dcgm_field_eid_t entityId)

用于将指定的实体添加到由 groupId 代表的组。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupId – IN: 应向其添加设备的组 ID

• entityGroupId – 输入：实体 ID 所属的实体组

• entityId – 输入：DCGM 实体 ID

返回值:

• 如果实体已成功添加到组，则返回 DCGM_ST_OK

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR

• 如果与组 (groupId) 对应的条目不存在，则返回 DCGM_ST_NOT_CONFIGURED

• 如果 entityId 无效或已是指定组的一部分，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGroupRemoveDevice(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, unsigned int gpuId)

用于从由 groupId 代表的组中移除指定的 GPU ID。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupId – 输入：要从中移除设备的组 ID

• gpuId – IN: DCGM GPU ID

返回值:

• 如果 GPU ID 已成功从组中移除，则返回 DCGM_ST_OK

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR

• 如果与组 (groupId) 对应的条目不存在，则返回 DCGM_ST_NOT_CONFIGURED

• 如果 gpuId 无效或不是指定组的一部分，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGroupRemoveEntity(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgm_field_entity_group_t entityGroupId, dcgm_field_eid_t entityId)

用于从由 groupId 代表的组中移除指定的实体。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupId – 输入：要从中移除设备的组 ID

• entityGroupId – 输入：实体 ID 所属的实体组

• entityId – 输入：DCGM 实体 ID

返回值:

• 如果实体已成功从组中移除，则返回 DCGM_ST_OK

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR

• 如果与组 (groupId) 对应的条目不存在，则返回 DCGM_ST_NOT_CONFIGURED

• 如果 entityId 无效或不是指定组的一部分，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmGroupGetInfo(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmGroupInfo_t *pDcgmGroupInfo)

用于获取与 groupId 代表的组相对应的信息。

在 pDcgmGroupInfo 中返回的信息包括组名称以及组中存在的实体列表。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupId – 输入：要获取信息的组 ID

• pDcgmGroupInfo – 输出：组信息

返回值:

• 如果成功接收到组信息，则返回 DCGM_ST_OK。

• 如果 groupId 或 pDcgmGroupInfo 中的任何一个无效，则返回 DCGM_ST_BADPARAM。

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR。

• 如果组不包含 GPU，则返回 DCGM_ST_MAX_LIMIT

• 如果与组 (groupId) 对应的条目不存在，则返回 DCGM_ST_NOT_CONFIGURED

dcgmReturn_t dcgmGroupGetAllIds(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupIdList[], unsigned int *count)

用于获取所有实体组的 ID。

返回的信息是 groupIdList 中的组 ID 列表以及 count 中的 ID 数量计数。请为 groupIdList 分配足够的内存。应为 groupIdList 分配 MAX_NUM_GROUPS 大小的内存。

参数:

• pDcgmHandle – IN: DCGM 句柄

• groupIdList – 输出：组 ID 列表

• count – 输出：列表中组 ID 的数量

返回值:

• 如果成功检索到组的 ID，则返回 DCGM_ST_OK

• 如果 groupIdList 或 count 中的任何一个为空，则返回 DCGM_ST_BADPARAM

• 如果发生未知错误，则返回 DCGM_ST_GENERIC_ERROR

字段分组

group DCGM_FIELD_GROUPING

以下 API 用于字段组管理。

用户可以创建一个字段组，并一次对一组字段执行操作。

函数

dcgmReturn_t dcgmFieldGroupCreate(dcgmHandle_t dcgmHandle, int numFieldIds, unsigned short *fieldIds, const char *fieldGroupName, dcgmFieldGrp_t *dcgmFieldGroupId)

用于创建字段组并在 dcgmFieldGroupId 中返回句柄。

参数:

• dcgmHandle – 输入：DCGM 句柄

• numFieldIds – 输入：在 fieldIds[] 中提供的字段 ID 的数量。必须介于 1 和 DCGM_MAX_FIELD_IDS_PER_FIELD_GROUP 之间。

• fieldIds – 输入：要添加到新创建的字段组的字段 ID

• fieldGroupName – 输入：此字段组的唯一名称。此名称不得与任何现有字段组相同。

• dcgmFieldGroupId – 输出：新创建的字段组的句柄

返回值:

• 如果字段组已成功创建，则返回 DCGM_ST_OK。

• 如果任何参数错误，则返回 DCGM_ST_BADPARAM

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR。

• 如果已存在太多字段组，则返回 DCGM_ST_MAX_LIMIT

dcgmReturn_t dcgmFieldGroupDestroy(dcgmHandle_t dcgmHandle, dcgmFieldGrp_t dcgmFieldGroupId)

用于移除使用 dcgmFieldGroupCreate 创建的字段组。

参数:

• dcgmHandle – 输入：DCGM 句柄

• dcgmFieldGroupId – 输入：要移除的字段组

返回值:

• 如果字段组已成功移除，则返回 DCGM_ST_OK

• 如果任何参数错误，则返回 DCGM_ST_BADPARAM

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR。

dcgmReturn_t dcgmFieldGroupGetInfo(dcgmHandle_t dcgmHandle, dcgmFieldGroupInfo_t *fieldGroupInfo)

用于获取有关使用 dcgmFieldGroupCreate 创建的字段组的信息。

参数:

• dcgmHandle – 输入：DCGM 句柄

• fieldGroupInfo –

  输入/输出：有关所有现有字段组的信息。

  在调用之前，.version 应设置为

  dcgmFieldGroupInfo_version

  .fieldGroupId 应包含您想要查询信息的 fieldGroupId。

返回值:

• 如果成功返回字段组信息，则返回 DCGM_ST_OK

• 如果任何参数错误，则返回 DCGM_ST_BADPARAM

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR。

• 如果 .version 未设置或无效，则返回 DCGM_ST_VER_MISMATCH。

dcgmReturn_t dcgmFieldGroupGetAll(dcgmHandle_t dcgmHandle, dcgmAllFieldGroup_t *allGroupInfo)

用于获取有关系统中所有字段组的信息。

参数:

• dcgmHandle – 输入：DCGM 句柄

• allGroupInfo –

  输入/输出：有关所有现有字段组的信息。

  在调用之前，.version 应设置为

  在调用之前，应设置为 dcgmAllFieldGroup_version。

返回值:

• 如果成功返回字段组信息，则返回 DCGM_ST_OK

• 如果任何参数错误，则返回 DCGM_ST_BADPARAM

• 如果库未成功初始化，则返回 DCGM_ST_INIT_ERROR。

• 如果 .version 未设置或无效，则返回 DCGM_ST_VER_MISMATCH。

状态处理

group DCGMAPI_ST

以下 API 用于管理在一个或多个 GPU 上执行多个操作的状态。

函数

dcgmReturn_t dcgmStatusCreate(dcgmStatus_t *statusHandle)

创建对 DCGM 状态处理程序的引用，该引用可用于获取在一个或多个设备上执行多个操作的状态。

当操作在组级别执行时，多个状态非常有用。状态句柄提供了一种访问失败操作的错误属性的机制。

可以使用 API dcgmStatusGetCount 访问存储在不透明句柄后面的错误数量。可以使用 API dcgmStatusPopError 从不透明句柄 statusHandle 访问错误。用户可以调用 dcgmStatusPopError 来获取错误数量，或者直到获取所有错误。

当不再需要状态句柄时，应使用 API dcgmStatusDestroy 删除它。

参数:

statusHandle – 输出：状态列表的句柄引用

返回值:

• 如果状态句柄已成功创建，则返回 DCGM_ST_OK

• 如果 statusHandle 无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmStatusDestroy(dcgmStatus_t statusHandle)

用于销毁使用 dcgmStatusCreate 创建的状态句柄。

参数:

statusHandle – 输入：状态列表的句柄

返回值:

• 如果状态句柄已成功创建，则返回 DCGM_ST_OK

• 如果 statusHandle 无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmStatusGetCount(dcgmStatus_t statusHandle, unsigned int *count)

用于获取存储在不透明句柄 statusHandle 内的错误条目的计数。

参数:

• statusHandle – 输入：状态列表的句柄

• count – 输出：状态列表中存在的错误条目的数量

返回值:

• 如果成功接收到错误计数，则返回 DCGM_ST_OK

• 如果 statusHandle 或 count 中的任何一个无效，则返回 DCGM_ST_BADPARAM

dcgmReturn_t dcgmStatusPopError(dcgmStatus_t statusHandle, dcgmErrorInfo_t *pDcgmErrorInfo)

用于遍历在 statusHandle 后维护的错误列表。

该方法从 DCGM 状态列表中弹出第一个错误。为了遍历所有错误，用户可以调用此 API 来获取错误数量，或者直到获取所有错误。

参数:

• statusHandle – 输入：状态列表的句柄

• pDcgmErrorInfo – 输出：状态列表中的第一个错误

返回值:

• 如果成功获取错误条目，则返回 DCGM_ST_OK

• 如果 statusHandle 或 pDcgmErrorInfo 中的任何一个无效，则返回 DCGM_ST_BADPARAM

• 如果状态句柄列表为空，则返回 DCGM_ST_NO_DATA

dcgmReturn_t dcgmStatusClear(dcgmStatus_t statusHandle)

用于清除由 API dcgmStatusCreate 创建的状态句柄中的所有错误。

在一组操作之后，可以清除 *statusHandle* 并将其重新用于下一组操作。

参数:

statusHandle – 输入：状态列表的句柄

返回值:

• 如果错误已成功清除，则返回 DCGM_ST_OK

• 如果 statusHandle 无效，则返回 DCGM_ST_BADPARAM