API 参考手册

数据中心GPU管理器 (MTDCMG)

API 参考

版本：v1.1.5

2025-09-19

模块

以下是所有模块的介绍

管理

DCGMAPI_Admin组

本节描述了MTDCGM的管理接口。用户在调用任何其他接口之前必须调用dcgmInit()进行初始化，并在不再使用MTDCGM时调用dcgmShutdown()进行资源释放。以下是管理模块中的API介绍：

初始化和关闭

DCGMAPI_Admin_InitShut 组

描述初始化和关闭MTDCGM引擎的API

dcgmReturn_t dcgmInit (void)

返回值

• DCGM_ST_OK：如果MTDCGM已正确初始化
• DCGM_ST_INIT_ERROR：如果初始化MTDCGM动态库时发生错误

接口描述

此函数用于在进程中初始化MTDCGM。必须在调用dcgmStartEmbedded()或dcgmConnect()之前调用

dcgmReturn_t dcgmShutdown (void)

返回值

• DCGM_ST_OK：如果MTDCGM已正确关闭
• DCGM_ST_UNINITIALIZED：如果MTDCGM动态库未正确关闭

接口描述

此接口用于关闭MTDCGM。任何以嵌入hostengines或远程连接的方式也将自动关闭

dcgmReturn_t dcgmStartEmbedded (dcgmOperationMode_t opMode, dcgmHandle_t *pDcgmHandle)

参数：

opMode

IN: 指定使用MTDCGM的操作模式，自动或手动收集数据

pDcgmHandle

OUT : MTDCGM Handle用于API调用

返回值

• DCGM_ST_OK：如果MTDCGM在进程中成功启动
• DCGM_ST_UNINITIALIZED：如果尚未使用dcgmInit初始化MTDCGM

接口描述

在进程中以embedded的方式启动Hostengine，这种方式以加载MTDCGM动态库的形式使用。在这种模式下，用户必须定期调用dcgmUpdateAllFields API接口，让代理服务执行数据收集操作

dcgmReturn_t dcgmStartEmbedded_v2 (dcgmStartEmbeddedV2Params_v1 *params)

参数：

params

IN/OUT : 指向dcgmStartEmbeddedV2Params_v1 or dcgmStartEmbeddedV2Params_v2的指针

返回值

• DCGM_ST_OK：如果MTDCGM在进程中成功启动
• DCGM_ST_UNINITIALIZED：如果尚未使用dcgmInit初始化MTDCGM或者Hostengine服务未运行

接口描述

在进程中启动嵌入Hostengine代理

代理模式需要将MTDCGM作为共享库加载，此模式与自主代理需要管理的额外操作不同，嵌入代理不需要任何额外操作。在这种模式下，用户必须定期调用dcgmUpdateAllFields来执行数据收集

注意：调用时通过传入params->version的版本号来决定实际的调用类型

dcgmReturn_t dcgmStopEmbedded (dcgmHandle_t pDcgmHandle)

参数：

pDcgmHandle

IN: 从dcgmStartEmbedded获取的MTDCGM Handle

返回值

• DCGM_ST_OK：如果MTDCGM在进程中成功停止
• DCGM_ST_UNINITIALIZED：如果尚未使用dcgmInit初始化MTDCGM或嵌入主机代理服务未运行
• DCGM_ST_BADPARAM：如果提供了无效参数
• DCGM_ST_INIT_ERROR：如果尝试启动代理服务时发生错误

接口描述

停止当前进程中由dcgmStartEmbedded启动的嵌入代理服务

dcgmReturn_t dcgmConnect(const char *ipAddress, dcgmHandle_t *pDcgmHandle)

参数：

ipAddress

IN: 用于连接Hostengine的有效IP地址。如果ipAddress指定为x.x.x.x，它将尝试连接到由DCGM_HE_PORT_NUMBER指定的默认端口。如果ipAddress指定为x.x.x.x:yyyy，它将尝试连接到由yyyy指定的端口

pDcgmHandle

OUT : Hostengine的MTDCGM句柄

返回值

• DCGM_ST_OK：成功连接hostengine
• DCGM_ST_CONNECTION_NOT_VALID：hostengine不可达
• DCGM_ST_UNINITIALIZED：MTDCGM未被dcgmInit初始化
• DCGM_ST_BADPARAM：pDcgmHandle是空指针或者ipAddress无效
• DCGM_ST_INIT_ERROR：MTDCGM在初始化客户端库时遇到错误

接口描述

此函数用于连接到独立的mt-hostengine，Hostengine是通过运行mt-hostengine命令启动 注意：dcgmConnect_v2提供了额外的连接选项

dcgmReturn_t dcgmConnect_v2 (const char *ipAddress, dcgmConnectV2Params_t *connectParams, dcgmHandle_t *pDcgmHandle)

参数：

ipAddress

IN: 用于连接Hostengine的有效IP地址。如果ipAddress指定为x.x.x.x，它将尝试连接到由DCGM_HE_PORT_NUMBER指定的默认端口。如果ipAddress指定为x.x.x.x:yyyy，它将尝试连接到由yyyy指定的端口

connectParams

IN:额外的连接参数，详细请参考：dcgmConnectV2Params_t

pDcgmHandle

OUT : Hostengine的MTDCGM句柄

返回值

• DCGM_ST_OK：如果成功连接Hostengine
• DCGM_ST_CONNECTION_NOT_VALID：远程Hostengine不可达
• DCGM_ST_UNINITIALIZED：MTDCGM未被dcgmInit初始化过
• DCGM_ST_BADPARAM：pDcgmHandle是空指针或者ipAddress无效
• DCGM_ST_INIT_ERROR：MTDCGM在初始化客户端库时遇到错误

接口描述

此方法用于连接到独立的mt-hostengine，Hostengine是通过运行mt-hostengine命令启动

dcgmReturn_t dcgmDisconnect (dcgmHandle_t pDcgmHandle)

参数：

pDcgmHandle

IN: 来自dcgmConnect的MTDCGM句柄

返回值

• DCGM_ST_OK：成功从Hostengine断开连接
• DCGM_ST_UNINITIALIZED：MTDCGM未被dcgmInit初始化过
• DCGM_ST_BADPARAM：pDcgmHandle是空指针
• DCGM_ST_GENERIC_ERROR：未知内部错误发生

接口描述

此函数用于从独立的mt-hostengine中断开连接

DCGM Hostengine的辅助信息

DCGMAPI_Admin_Info组

本节的API用于描述如何获取MTDCGM Hostengine的基本信息

dcgmReturn_t dcgmVersionInfo (dcgmVersionInfo_t *pVersionInfo)

参数：

pVersionInfo

OUT : 返回编译版本信息

返回值

• DCGM_ST_OK：成功获取编译版本信息
• DCGM_ST_BADPARAM：pVersionInfo为空指针
• DCGM_ST_VER_MISMATCH：期望和提供的dcgmVersionInfo_t版本不匹配

接口描述 该函数用于获取MTDCGM编译时的编译版本信息

这一节的API描述获取MTDCGM引擎的基本信息

dcgmReturn_t dcgmHostengineVersionInfo (dcgmHandle_t pDcgmHandle, dcgmVersionInfo_t *pVersionInfo)

参数：

pDcgmHandle

IN: MTDCGM句柄

pVersionInfo

OUT : 编版本信息

返回值

• DCGM_ST_OK：成功获取编译版本信息
• DCGM_ST_BADPARAM：pVersionInfo为空指针
• DCGM_ST_VER_MISMATCH：期望和提供的dcgmVersionInfo_t版本不匹配

接口描述

该函数用于获取MTDCGM编译时的编译版本信息

dcgmReturn_t dcgmHostengineSetLoggingSeverity(dcgmHandle_t pDcgmHandle, dcgmSettingsSetLoggingSeverity_t *logging)

参数：

pDcgmHandle

IN: MTDCGM句柄

logging

IN: dcgmSettingsSetLoggingSeverity_t结构体包含目标logger和日志等级

返回值

• DCGM_ST_OK：日志等级设置成功
• DCGM_ST_BADPARAM：非法的logger或者日志等级
• DCGM_ST_VER_MISMATCH：期望和提供的dcgmSettingsSetLoggingSeverity_t版本不匹配

接口描述

此函数用于配置Hostengine上的日志信息

dcgmReturn_t dcgmHostengineIsHealthy(dcgmHandle_t pDcgmHandle, dcgmHostengineHealth_t *heHealth)

参数：

pDcgmHandle

IN: MTDCGM句柄

heHealth

OUT : Hostengine健康状况的结构体。如果heHealth.hostengineHealth为0，则Hostengine健康。非零值表示不健康，由返回的错误代码确定原因

返回值

• DCGM_ST_OK：成功获取主机代理的健康状态
• DCGM_ST_BADPARAM：isHealthy指针非法

接口描述

此函数用于返回Hostengine是否认为自身健康

const char *errorString(dcgmReturn_t result)

参数：

result

IN: MTDCGM其他API接口的返回结果

返回值

• 如果传入的错误码是有效的，结果返回带有错误码的可读字符串
• 如果是无效错误码，则返回空指针

接口描述

此函数将API接口的返回值转换为可读的MTDCGM错误信息

dcgmReturn_t dcgmModuleIdToName(dcgmModuleId_t id, char const **name)

参数：

id

IN: Module ID

name

OUT : Module Name

返回值

• DCGM_ST_OK：获取的模块名字有效
• DCGM_ST_BADPARAM：Module ID无效

接口描述

该接口将Module ID转换为Module Name

系统

DCGMAPI_SYS组

本章描述了用于识别Node节点上的GPU设备集合的API、可操作一组GPU设备的Grouping、以及从其他接口返回的Status管理API。系统模块中的API可以分为以下类别：

Discovery

Grouping

Field Group

Discovery

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

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

参数：

pDcgmHandle

IN: MTDCGM句柄

gpuIdList

OUT : Node节点上由GPU逻辑索引组成的数组

count

OUT : gpuIdList中的GPU数量

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_BADPARAM：gpuIdList或count无效

接口描述

此函数用于获取Node节点上所有设备的标识符。标识符表示系统上每个GPU的逻辑索引，这些标识在Hostengine的生命周期内保持不变。如果Hostengine重新启动，则需要重新查询此列表

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

参数：

pDcgmHandle

IN: MTDCGM句柄

gpuIdList

OUT : 由Node节点上支持的GPU逻辑索引组成的数组

count

OUT : gpuIdList中的GPU数量

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_BADPARAM：gpuIdList或count无效

接口描述

此方法用于获取系统上所有MTDCGM支持的设备的标识符。标识符代表系统上每个GPU的MTDCGM GPU逻辑索引，并且在引擎的生命周期内是不可变的。如果引擎重新启动，应重新查询此列表

当前dcgmGetAllSupportedDevices()接口和dcgmGetAllDevices()返回值一致

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

参数：

pDcgmHandle

IN: MTDCGM句柄

gpuId

IN: GPU逻辑索引

pDcgmAttr

IN/OUT : 对应gpuId的设备属性。在调用时需要将pDcgmAttr->version设置为dcgmDeviceAttributes_version

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_VER_MISMATCH：pDcgmAttr->version无效或者不匹配

接口描述

该函数用于获取指定gpuId的设备属性

如果某一个设备属性获取失败，则Field将被填充为DCGM_BLANK_VALUES（该值在dcgm_structs.h中定义）

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

参数：

dcgmHandle

IN: MTDCGM句柄

entityGroup

IN: 实体类型，信息类型请参考dcgm_field_entity_group_t中的定义

entities

OUT: entityGroup的实体数组

numEntities

IN/OUT: 作为入参时，表示entityList[]数组可以容纳的entity数量。作为出参时，表示entityList中实际存储的entity数量

flags

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

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_INSUFFICIENT_SIZE：numEntities不够容纳entityGroup中的实体数量。numEntities将包含完成此请求所需的容量
• DCGM_ST_NOT_SUPPORTED：给定的entityGroup是不支持的枚举类型
• DCGM_ST_BADPARAM：传入的参数无效

接口描述

获取给定实体组的实体列表

此API可用于替代dcgmGetAllDevices

Grouping

以下API用于实体分组管理

用户可以创建一个实体组，并对一组实体执行操作。如果不需要分组，并且用户希望对MTDCGM看到的所有GPU执行命令，那么用户可以使用DCGM_GROUP_ALL_GPUS代替分组ID

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

参数：

pDcgmHandle

IN: MTDCGM句柄

type

IN: 实体组的类型

groupName

IN: 指定为新GPU组的名称，为NULL终止的C字符串

pDcgmGrpId

OUT : group ID指针

返回值

• DCGM_ST_OK：组成功创建
• DCGM_ST_BADPARAM：type、groupName、长度或pDcgmGrpId无效
• DCGM_ST_MAX_LIMIT：系统上的组数量已达到最大限制DCGM_MAX_NUM_GROUPS
• DCGM_ST_INIT_ERROR:库初始化失败

接口描述

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

代替为每个实体单独执行操作，MTDCGM组允许用户对组中的所有实体作为一个单元执行相同的操作

要创建包含系统上所有实体的组，应将类型Field指定为DCGM_GROUP_DEFAULT；要创建一个空组，类型Field应指定为DCGM_GROUP_EMPTY。空组可以通过API dcgmGroupAddDevice、dcgmGroupAddEntity、dcgmGroupRemoveDevice和dcgmGroupRemoveEntity更新为所需的实体集

dcgmReturn_t dcgmGroupDestroy (dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId)

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: Group ID

返回值

• DCGM_ST_OK：组成功删除
• DCGM_ST_BADPARAM：groupId无效
• DCGM_ST_INIT_ERROR：库初始化失败
• DCGM_ST_NOT_CONFIGURED：对应组项不存在

接口描述

用于删除由groupId表示的Group

由于MTDCGM Group是实体的一种逻辑分组，即使Group组被删除后也不会对单个实体产生影响

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

参数：

pDcgmHandle

IN: MTDCGM Handle

groupId

IN: 应添加设备的组ID

gpuId

IN: GPU逻辑索引

返回值

• DCGM_ST_OK：GPU逻辑索引成功添加到组中
• DCGM_ST_INIT_ERROR：库未成功初始化
• DCGM_ST_NOT_CONFIGURED：对应组（groupId）项不存在
• DCGM_ST_BADPARAM：gpuId无效或已属于指定组

接口描述

该函数用于将指定的GPU逻辑索引添加到group组中

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

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 应添加设备的组ID

entityGroupId

IN: entityId所属的实体组

entityId

IN: MTDCGM entityId

返回值

• DCGM_ST_OK：实体已成功添加到组中
• DCGM_ST_INIT_ERROR：库未成功初始化
• DCGM_ST_NOT_CONFIGURED：对应组（groupId）项不存在
• DCGM_ST_BADPARAM：entityId无效或已属于指定组

接口描述

用于将指定的实体添加到由groupId组中

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

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN:需要移除设备的Group ID

gpuId

IN: GPU逻辑索引

返回值

• DCGM_ST_OK：GPU逻辑索引已成功从组中移除
• DCGM_ST_INIT_ERROR：库未成功初始化
• DCGM_ST_NOT_CONFIGURED：对应组（groupId）项不存在
• DCGM_ST_BADPARAM：gpuId无效或不属于指定组

接口描述

用于从由groupId表示的组中移除指定的GPU逻辑索引

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

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 需要从中移除设备的Group ID

entityGroupId

IN: entityId所属的实体组

entityId

IN: MTDCGM entityId

返回值

• DCGM_ST_OK：实体已成功从组中移除
• DCGM_ST_INIT_ERROR：库未成功初始化
• DCGM_ST_NOT_CONFIGURED：与组(groupId)对应的条目不存在
• DCGM_ST_BADPARAM：entityId无效或不在指定的组中

接口描述

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

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

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 需要获取信息的Group ID

pDcgmGroupInfo

OUT : Group信息

返回值

• DCGM_ST_OK：成功接收到组信息
• DCGM_ST_BADPARAM:groupId或pDcgmGroupInfo中的任何一个无效
• DCGM_ST_INIT_ERROR：库未成功初始化
• DCGM_ST_MAX_LIMIT：组中不包含GPU
• DCGM_ST_NOT_CONFIGURED：与组(groupId)对应的条目不存在

接口描述

用于获取与groupId表示的Group相对应的信息

pDcgmGroupInfo包括Group名，以及组中存在的Entity列表

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

参数：

pDcgmHandle

IN: MTDCGM句柄

groupIdList

OUT : Group ID列表

count

OUT : 列表中Group ID的数量

返回值

• DCGM_ST_OK：成功检索到组的ID
• DCGM_ST_BADPARAM：groupIdList或count为空
• DCGM_ST_GENERIC_ERROR：发生未知错误

接口描述

用于获取所有Entity Group的ID

返回的信息是groupIdList中的Group ID列表，以及count数量。需要为groupIdList分配足够的内存，groupIdList分配的最大为MAX_NUM_GROUPS

Field Group

以下API用于Field Group管理

用户可以创建一个Field Group，并一次性对一组Field执行操作

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

参数：

dcgmHandle

IN: MTDCGM句柄

numFieldIds

IN: 创建Field Group时需要添加的Field数量。必须在1和DCGM_MAX_FIELD_IDS_PER_FIELD_GROUP之间

fieldIds

IN: 要添加到新创建的field组中的Field Id

fieldGroupName

IN: fields group的唯一名称。不能与任何现有的Field Group相同

dcgmFieldGroupId

OUT: 新创建field group的ID

返回值

• DCGM_ST_OK：field group成功创建
• DCGM_ST_BADPARAM：发生任何入参错误
• DCGM_ST_INIT_ERROR：库未成功初始化
• DCGM_ST_MAX_LIMIT：已经存在太多的field group

接口描述

用于创建一个Field Group，并在dcgmFieldGroupId中返回句柄

dcgmReturn_t dcgmFieldGroupDestroy(dcgmHandle_t dcgmHandle, dcgmFieldGrp_t dcgmFieldGroupId)

参数：

dcgmHandle

IN: MTDCGM句柄

dcgmFieldGroupId

IN: 需要移除的Field group ID

返回值

• DCGM_ST_OK：field group成功移除
• DCGM_ST_BADPARAM：任何入参发生错误
• DCGM_ST_INIT_ERROR：库未成功初始化

接口描述

销毁创建的Field Group

dcgmReturn_t dcgmFieldGroupGetInfo(dcgmHandle_t dcgmHandle, dcgmFieldGroupInfo_t *fieldGroupInfo)

参数：

dcgmHandle

IN: MTDCGM句柄

fieldGroupInfo

IN/OUT: 输入：申请好内存的dcgmFieldGroupInfo_t结构体指针，输出：对应Field Group的信息。调用时.version应配置为dcgmFieldGroupInfo_version。fieldGroupId需要配置为要查询信息的fieldGroupId

返回值

• DCGM_ST_OK：field组信息成功返回
• DCGM_ST_BADPARAM：发生任何入参错误
• DCGM_ST_INIT_ERROR：库未成功初始化
• DCGM_ST_VER_MISMATCH：.version未设置或无效

接口描述

用于获取Field Group信息

dcgmReturn_t dcgmFieldGroupGetAll(dcgmHandle_t dcgmHandle, dcgmAllFieldGroup_t *allGroupInfo)

参数：

dcgmHandle

IN: MTDCGM句柄

allGroupInfo

IN/OUT: 输入：申请好内存的dcgmAllFieldGroup_t结构体指针，输出：所有Field Group的信息。在调用时.version应设置为dcgmAllFieldGroup_version

返回值

• DCGM_ST_OK：field组信息成功返回
• DCGM_ST_BADPARAM：发生任何入参错误
• DCGM_ST_INIT_ERROR：库未成功初始化
• DCGM_ST_VER_MISMATCH：.version未设置或无效

接口描述

用于获取系统中所有Field Group的信息

Field接口

DCGMAPI_FI 组

以下API负责监视、取消监视和更新由DCGM_FI_*定义的特定Field

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

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 表示一个或多个实体的Group ID。有关创建Group的详细信息，请参阅dcgmGroupCreate。或者传入DCGM_GROUP_ALL_GPUS作为Group ID，这样可以对所有GPU执行操作

fieldGroupId

IN: 要监视的Field Group ID

updateFreq

IN: 需要更新Filed Group中Field的时间间隔（单位：微秒）

maxKeepAge

IN: 保留Filed Group中Field数据的时间（单位：秒）

maxKeepSamples

IN: 保留的最大样本数。0表示无限制

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_BADPARAM：参数无效

接口描述

请求MTDCGM开始给Field Group的数据更新。注意，Field中的值将在下一更新周期时更新，如果要强制更新Field的值，需要调用dcgmUpdateAllFields(1)

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

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 表示一个或多个实体的Group ID

fieldGroupId

IN: 取消监视的Field

返回值

• DCGM_ST_OK：函数成功调用
• DCGM_ST_BADPARAM：参数无效

接口描述

请求MTDCGM停止更新Gield ID的值

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

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 表示一个或多个实体的Group ID

fieldGroupId

IN: 要返回数据的Field Group ID

sinceTimestamp

IN: 请求数据的时间戳（从1970年开始（微秒）），这将在后续调用中输出到参数nextSinceTimestamp，传入 0 表示请求所有数据

nextSinceTimestamp

OUT: 在下次调用此函数时用于sinceTimestamp的时间戳

enumCB

IN: 为每个Field值更新调用的回调。请注意，每次调用可能会返回多个更新

userData

IN: 要传递给enumCB的userDataField的用户数据指针

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_NOT_SUPPORTED：其中一个实体来自非GPU类型
• DCGM_ST_BADPARAM：参数无效

接口描述

请求自给定时间戳以来所有Field值，当前仅适用于GPU实体

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

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 表示一个或多个实体的Group ID

fieldGroupId

IN: 要返回数据的Field Group ID

sinceTimestamp

IN: 请求数据的时间戳（从1970年开始（微秒）），这将在后续调用中输出到参数nextSinceTimestamp，传入 0 表示请求所有数据

nextSinceTimestamp

OUT: 在下次调用此函数时用于sinceTimestamp的时间戳

enumCB

IN: 为每个Field值更新调用的回调，每次调用可能会返回多个更新

userData

IN: 要传递给enumCB的userData的用户数据指针

返回值

• DCGM_ST_OK：函数成功调用
• DCGM_ST_BADPARAM\：参数无效

接口描述

请求自给定时间戳以来所有filed值

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

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 表示一个或多个实体的Group ID

fieldGroupId

IN: 要返回数据的Field Group ID

enumCB

IN: 为每个Field值更新调用的回调，每次调用可能会返回多个更新

userData

IN: 要传递给enumCB的userData 的用户数据指针

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_NOT_SUPPORTED：其中一个实体来自非GPU类型
• DCGM_ST_BADPARAM：传入参数为无效参数

接口描述

请求Filed Group最新缓存Field 值。当前仅适用于GPU实体

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

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 表示一个或多个实体的Group ID

fieldGroupId

IN: 要返回数据的Field Group ID

enumCB

IN: 为每个Field 值更新调用的回调，每次调用可能会返回多个更新

userData

IN: 要传递给enumCB的userData 的用户数据指针

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_NOT_SUPPORTED：其中一个实体来自非GPU类型
• DCGM_ST_BADPARAM：传入参数为无效参数

接口描述

请求Field Group的最新缓存值

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

参数：

pDcgmHandle

IN: MTDCGM句柄

gpuId

IN: GPU逻辑索引

fields

IN: 要返回数据的Field ID。请参阅dcgm_fields.h中以DCGM_FI_开头的定义

count

IN: fields数组中Field ID的数量

values

OUT: fields[]中Field的最新值

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_NOT_SUPPORTED：其中一个实体来自非GPU类型
• DCGM_ST_BADPARAM：传入参数为无效参数

接口描述

请求GPU的最新缓存Field 值

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: MTDCGM句柄

entityGroup

IN: entity_group_t

entityId

IN: 表示请求Field所对应的Entity ID

fields

IN: 要返回数据的Field ID。请参阅dcgm_fields.h中以DCGM_FI_开头的定义

count

IN: fields[]数组中的Field ID数量

values

OUT: fields[]中Field的最新Field值

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_NOT_SUPPORTED：其中一个实体来自非GPU类型
• DCGM_ST_BADPARAM：传入参数为无效参数

接口描述

请求特定Entity的Field Group最新缓存的Field值

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

参数：

pDcgmHandle

IN: MTDCGM句柄

entities

IN: 要获取值的Entity列表

entityCount

IN: entities[]中的数量

fields

IN: 要返回数据的Field ID。请参阅dcgm_fields.h中以DCGM_FI_开头的定义

fieldCount

IN: fields[]数组中的Field ID数量

flags

IN: 影响此请求处理方式的可选标志。在此处传递DCGM_FV_FLAG_LIVE_DATA以获取实时值而不是缓存值。有关说明，请参阅flag的说明文档

values

OUT: 请求的Field的最新值。要求数组必须能够保存entityCount * fieldCount的数据

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_NOT_SUPPORTED：其中一个实体来自非GPU类型
• DCGM_ST_BADPARAM：传入参数为无效参数

接口描述

获取一组Entity的Field Group的最新缓存或实时值

注意：返回的Entity不保证任何顺序。为了优化对MUSA驱动的调用，可能会在内部进行重新排序

dcgmReturn_t dcgmGetFieldSummary(dcgmHandle_t pDcgmHandle, dcgmFieldSummaryRequest_t *request)

参数：

pDcgmHandle

IN: MTDCGM句柄

request

IN/OUT: 输入：传入指定的Field Id，Entity Id，结构体版本，Summary类型（详细参考DCGM_SUMMARY_*），开始和结束的统计时间；输出：Summary的结果

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_FIELD_UNSUPPORTED_BY_API：Field 值类型不是int64或double类型

接口描述

获取一段时间内Field 值汇总

健康监视

DCGMAPI_HM 组

本章描述处理GPU健康监控的接口

dcgmReturn_t dcgmHealthSet(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmHealthSystems_t systems)

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 表示一个或多个Entity Group ID

systems

IN: 枚举值，表示需要设置观测模块枚举值的逻辑与。详细信息请参考dcgmHealthSystems_t

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_BADPARAM：传入的参数非法

接口描述

用dcgmHealthSystems_t中定义的给定系统枚举，启动MTDCGM健康检查

dcgmReturn_t dcgmHealthSet_v2(dcgmHandle_t pDcgmHandle, dcgmHealthSetParams_v2 *params)

参数：

pDcgmHandle

IN: MTDCGM句柄

params

IN: 设置需要观测模块健康的参数。查看dcgmHealthSetParams_v2以获取每个参数的接口描述

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_BADPARAM：传入的参数非法

接口描述

用dcgmHealthSystems_t中定义的给定系统枚举，开启MTDCGM健康检查

dcgmReturn_t dcgmHealthGet(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmHealthSystems_t *systems)

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 表示一个或多个Entity Group ID

systems

OUT: 表示所有使能观测模块对应枚举的逻辑与值。参考dcgmHealthSystems_t以获取详细信息

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_BADPARAM：传入的参数非法

接口描述

查看MTDCGM健康检查模块的观测状态

dcgmReturn_t dcgmHealthCheck(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmHealthResponse_t *results)

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 表示一个或多个Entity Group ID

results

OUT: 返回有数据的dcgmHealthResponse_t结构体。使用时results->version必须设置为dcgmHealthResponse_version

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_BADPARAM：传入的参数非法
• DCGM_ST_VER_MISMATCH：传入的results->version不是dcgmHealthResponse_version

接口描述

检查自上次配置观测的模块是否发生了errors/failures/warnings错误

在第一次调用时，会创建关于组内所有启用观察的状态信息，但不会提供错误结果。在后续调用中，将返回错误信息

模块

本章描述了查询和配置MTDCGM模块的API

dcgmReturn_t dcgmModuleBlacklist(dcgmHandle_t pDcgmHandle, dcgmModuleId_t moduleId)

参数：

pDcgmHandle

IN: MTDCGM句柄

moduleId

IN: 要加入黑名单的模块ID。使用dcgmModuleGetStatuses获取有效的模块ID列表

返回值

• DCGM_ST_OK：模块成功加入黑名单
• DCGM_ST_IN_USE：模块已经被加载且不能被加入黑名单
• DCGM_ST_BADPARAM：入参缺失或错误

接口描述

将一个模块添加到黑名单列表，表示该模块不能被加载

如果该模块尚未加载，这将阻止它被加载。模块会在在MTDCGM API使用时延迟（lazy）加载，因此在使用后尽快调用此API非常重要。也可以将denylist-modules传递给mt-hostengine二进制文件，以确保在Hostengine启动后立即将模块添加到黑名单

dcgmReturn_t dcgmModuleGetStatuses(dcgmHandle_t pDcgmHandle, dcgmModuleGetStatuses_t *moduleStatuses)

参数：

pDcgmHandle

IN: MTDCGM句柄

moduleStatuses

OUT: 模块状态。调用时应将version设置为dcgmModuleStatuses_version

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_BADPARAM：入参非法

接口描述

获取所有MTDCGM模块的加载状态

策略

本章介绍策略管理和验证配置方法

dcgmReturn_t dcgmActionValidate(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmPolicyValidation_t validate, dcgmDiagResponse_t *response)

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 表示一个或多个Entity Group ID

validate

IN: 验证操作需要执行的诊断等级

response

OUT: 验证之后返回的结果，详细信息请参考dcgmDiagResponse_t

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_NOT_SUPPORTED：运行不支特的validate
• DCGM_ST_BADPARAM：groupId、validate或者statusHandle无效
• DCGM_ST_GENERIC_ERROR：发生未指定的 MTDCGM 错误
• DCGM_ST_GROUP_INCOMPATIBLE：同一组GPU不是同一个sku

接口描述

在系统上手动执行一组GPU的验证功能

dcgmReturn_t dcgmActionValidate_v2(dcgmHandle_t pDcgmHandle, dcgmRunDiag_v9 *drd, dcgmDiagResponse_t *response)

参数：

pDcgmHandle

IN: MTDCGM句柄

drd

IN: 包含group id、测试名称、测试参数、结构体版本以及应执行的验证

response

OUT: 验证之后返回的结果，详细信息请参考dcgmDiagResponse_t 注意：用户应该确保该结构体的初始化（不包含版本号）

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_NOT_SUPPORTED：运行不支特的validate
• DCGM_ST_BADPARAM：groupId、validate或者statusHandle无效
• DCGM_ST_GENERIC_ERROR：发生未指定的 MTDCGM 错误
• DCGM_ST_GROUP_INCOMPATIBLE：同一组GPU不是同一类型

接口描述

action管理器在系统上手动执行一组GPU的验证

注：如果dcgmRunDiag_v9结构体中传入同时传入了validate和testNames，则仅会以testNames为主

dcgmReturn_t dcgmRunDiagnostic(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmDiagnosticLevel_t diagLevel, dcgmDiagResponse_v11 *diagResponse)

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 表示一个或多个Entity Group ID

diagLevel

IN: 运行的诊断等级

diagResponse

IN/OUT:MTDCGM诊断结果。调用前需要将.version设置为dcgmDiagResponse_version

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_NOT_SUPPORTED：运行不支特的validate
• DCGM_ST_BADPARAM：groupId、validate或者statusHandle无效
• DCGM_ST_GENERIC_ERROR：发生未指定的 MTDCGM 错误
• DCGM_ST_GROUP_INCOMPATIBLE：同一组GPU不是同一类型
• DCGM_ST_VER_MISMATCH：.version没有赋值或者非法

接口描述

在一组GPU上运行诊断

拓扑

dcgmReturn_t dcgmGetDeviceTopology(dcgmHandle_t pDcgmHandle, unsigned int gpuId, dcgmDeviceTopology_t *pDcgmDeviceTopology)

参数：

pDcgmHandle

IN: MTDCGM句柄

gpuId

IN: 想要获取拓扑信息的GPU设备id

pDcgmDeviceTopology

IN/OUT: gpuId对应设备的拓扑信息，pDcgmDeviceTopology->version置为dcgmDeviceTopology_version，否则将会使用dcgmDeviceTopology_version1调用.

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_BADPARAM：运行不支特的validate
• DCGM_ST_VER_MISMATCH：pDcgmDeviceTopology->version传入的值不是dcgmDeviceTopology_version

接口描述

获取gpuId相对应的设备拓扑结构

dcgmReturn_t dcgmGetGroupTopology(dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmGroupTopology_t *pDcgmGroupTopology)

参数：

pDcgmHandle

IN: MTDCGM句柄

groupId

IN: 想要获取拓扑信息的Group组id

pDcgmGroupTopology

IN/OUT: groupId对应设备组的拓扑信息，pDcgmgroupTopology->version应置为dcgmGroupTopology_version，否则将会使用dcgmGroupTopology_version1调用.

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_BADPARAM：groupId或者pDcgmGroupTopology异常
• DCGM_ST_VER_MISMATCH：pDcgmgroupTopology->version传入的值不是dcgmGroupTopology_version

接口描述

获取groupId相对应的一组设备的拓扑结构

dcgmReturn_t dcgmActionValidateFormatInfo(dcgmHandle_t pDcgmHandle, dcgmRunDiag_v9 *drd, dcgmDiagResponse_t *response)

参数：

pDcgmHandle

IN: MTDCGM句柄

drd

IN: 包含group id、测试名称、测试参数、结构体版本以及应执行的验证

response

OUT: 验证之后返回的结果，详细信息请参考dcgmDiagResponse_t 注意：调用者应该确保该结构体的初始化（不包含版本号）

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_NOT_SUPPORTED：运行不支特的validate
• DCGM_ST_BADPARAM：groupId、validate或者statusHandle无效
• DCGM_ST_GENERIC_ERROR：发生未指定的 MTDCGM 错误
• DCGM_ST_GROUP_INCOMPATIBLE：同一组GPU不是同一类型

接口描述

action管理器在系统上手动执行一组GPU的验证，并将PCIe的Info信息格式化为JSON表示

注：如果dcgmRunDiag_v9结构体中传入同时传入了validate和testNames，则仅会以testNames为主

执行控制

dcgmReturn_t dcgmUpdateAllFields(dcgmHandle_t pDcgmHandle, int waitForUpdate)

参数：

pDcgmHandle

IN: MTDCGM句柄

waitForUpdate

IN: 在返回给调用者之前是否等待更新循环完成， 1表示等待， 0表示不等待

返回值

• DCGM_ST_OK：函数调用成功
• DCGM_ST_BADPARAM：waitForUpdate 无效
• DCGM_ST_GENERIC_ERROR：发生未指定的 MTDCGM 错误

接口描述

此方法用于告诉 MTDCGM 模块更新所有被监视的Fields

注意：如果在初始化（dcgmInit）期间将操作模式设置为手动模式（DCGM_OPERATION_MODE_MANUAL），则必须定期调用此函数，以允许Field监视采集样本

枚举和宏定义

dcgmReturnEnums组

MAKE_DCGM_VERSION(typeName, ver)(unsignedint)(sizeof(typeName)|

((unsignedlong)(ver)<<24U))

为每个结构体创建唯一版本号

DCGM_BLANK_VALUES

表示空值，如果Hostengine操作不成功，则可能返回该值

DCGM_INT32_BLANK 0x7ffffff0

32位整数空值，可以用作未指定的空白

DCGM_INT64_BLANK 0x7ffffffffffffff0

64位整数空值，可以用作未指定的空白

DCGM_FP64_BLANK 140737488355328.0

双精度空值，2^47。FP64有52位的尾数，所以47位仍然可以加1，并表示从0-15的每个值

DCGM_STR_BLANK "<<<NULL>>>"

字符串空值

DCGM_INT32_NOT_FOUND (DCGM_INT32_BLANK+1)

表示找不到INT32数据的错误

DCGM_INT64_NOT_FOUND (DCGM_INT64_BLANK+1)

表示找不到INT64数据的错误

DCGM_FP64_NOT_FOUND (DCGM_FP64_BLANK+1.0)

表示找不到FP64数据的错误

DCGM_STR_NOT_FOUND "<<<NOT_FOUND>>>"

表示找不到STR数据的错误

DCGM_INT32_NOT_SUPPORTED (DCGM_INT32_BLANK+2)

表示不支持获取INT32值的错误

DCGM_INT64_NOT_SUPPORTED (DCGM_INT64_BLANK+2)

表示不支持获取INT64值的错误

DCGM_FP64_NOT_SUPPORTED (DCGM_FP64_BLANK+2.0)

表示不支持获取FP64值的错误

DCGM_STR_NOT_SUPPORTED "<<<NOT_SUPPORTED>>>"

表示不支持获取STR值的错误

DCGM_INT32_NOT_PERMISSIONED (DCGM_INT32_BLANK+3)

表示不允许使用当前凭据获取INT32值的错误

DCGM_INT64_NOT_PERMISSIONED (DCGM_INT64_BLANK+3)

表示不允许使用当前凭据获取INT64值的错误

DCGM_FP64_NOT_PERMISSIONED (DCGM_FP64_BLANK+3.0)

表示不允许使用当前凭据获取FP64值的错误

DCGM_STR_NOT_PERMISSIONED "<<<NOT_PERM>>>"

表示不允许使用当前凭据获取STR值的错误

DCGM_INT32_IS_BLANK (val)(((val)>=DCGM_INT32_BLANK)?1:0)

用于检查INT32值是否为空

DCGM_INT64_IS_BLANK (val)(((val)>=DCGM_INT64_BLANK)?1:0)

用于检查INT64值是否为空

DCGM_FP64_IS_BLANK (val)(((val)>=DCGM_FP64_BLANK?1:0))

用于检查FP64值是否为空

DCGM_STR_IS_BLANK (val)(val==strstr(val,"<<<")&&strstr(val,">>>"))

用于检查STR值是否为空，适用于(char *)

查找第一个位置是否有"<<<"，并在字符串中查找">>>"

DCGM_MAX_NUM_DEVICES 32

DCGM支持的最大GPU数量

DCGM_MTLINK_MAX_LINKS_PER_GPU 16

DCGM支持的每个GPU的MtLink链接数量。对于S4000为4

DCGM_MAX_XID_INFO 10

要存储的XID信息的最大数量

DCGM_MAX_STR_LENGTH 256

DCGM字符串的最大长度

DCGM_MAX_AGE_USEC_DEFAULT 30000000

保留的样本的最大时长(微秒)的默认值

DCGM_MAX_CLOCKS 256

支持的设备最大时钟数量，当前设备不支持

DCGM_MAX_NUM_GROUPS 64

DCGM支持的最大group数限制

DCGM_HE_PORT_NUMBER 5555

MTDCGM Hostengine的默认端口号

DCGM_GROUP_ALL_GPUS 0x7fffffff

用于标识特殊的GPU组，表示所有的GPU

DCGM_GROUP_ALL_ENTITIES 0x7ffffffb

用于标识特殊的Entity组，表示所有的Entity

DCGM_GROUP_MAX_ENTITIES 64

每个实体组中实体的最大数量

enum dcgmOperationMode_t

MTDCGM的操作模式

MTDCGM可以使用自动模式运行，需要在后台运行额外的线程来收集需要的数据，这种模式下会自动管理策略相关的操作

MTDCGM也可以使用手动模式运行，这种模式需要用户自己控制。在这种模式下，用户必须定期调用如dcgmPolicyTrigger和dcgmUpdateAllFields等API，用于唤醒执行数据收集和策略管理操作

Values:

enumerator DCGM_OPERATION_MODE_AUTO

enumerator DCGM_OPERATION_MODE_MANUAL

enum dcgmOrder_t

当查询返回多个值时，应该按什么顺序返回

Values:

enumerator DCGM_ORDER_ASCENDING

按照最早获取的数据顺序

enumerator DCGM_ORDER_DESCENDING

按照最新获取的数据顺序

enum dcgmReturn_t

MTDCGM API调用返回的结果

Values:

enumerator DCGM_ST_OK

返回成功

enumerator DCGM_ST_BADPARAM

传递给函数的参数错误

enumerator DCGM_ST_GENERIC_ERROR

一般未指定的错误

enumerator DCGM_ST_MEMORY

发生内存不足错误

enumerator DCGM_ST_NOT_CONFIGURED

未配置错误

enumerator DCGM_ST_NOT_SUPPORTED

接口功能不支持

enumerator DCGM_ST_INIT_ERROR

MTDCGM 初始化错误

enumerator DCGM_ST_MTML_ERROR

由于MTML接口返回的错误

enumerator DCGM_ST_PENDING

对象处于其他事物的待定状态

enumerator DCGM_ST_UNINITIALIZED

对象处于未定义状态

enumerator DCGM_ST_TIMEOUT

请求的操作超时

enumerator DCGM_ST_VER_MISMATCH

接收到的 API 与传入的 API 版本不匹配

enumerator DCGM_ST_UNKNOWN_FIELD

未知的Field id

enumerator DCGM_ST_NO_DATA

没有可用数据

enumerator DCGM_ST_STALE_DATA

数据被认为过时

enumerator DCGM_ST_NOT_WATCHED

给定的Field id 没有被缓存管理器更新

enumerator DCGM_ST_NO_PERMISSION

没有权限执行所需操作

enumerator DCGM_ST_GPU_IS_LOST

GPU不可访问

enumerator DCGM_ST_RESET_REQUIRED

GPU需要重置

enumerator DCGM_ST_FUNCTION_NOT_FOUND

请求的函数未找到（仅绑定错误）

enumerator DCGM_ST_CONNECTION_NOT_VALID

与Hostengine的连接无效

enumerator DCGM_ST_GPU_NOT_SUPPORTED

MTDCGM 不支持此GPU

enumerator DCGM_ST_GROUP_INCOMPATIBLE

提供的 GPU 组对于请求的操作彼此不兼容

enumerator DCGM_ST_MAX_LIMIT

对象达到最大限制

enumerator DCGM_ST_LIBRARY_NOT_FOUND

找不到 MTDCGM 库

enumerator DCGM_ST_DUPLICATE_KEY

向函数传递了重复的键

enumerator DCGM_ST_GPU_IN_SYNC_BOOST_GROUP

GPU 已经是同步加速组的一部分，当前不支持该枚举值

enumerator DCGM_ST_GPU_NOT_IN_SYNC_BOOST_GROUP

GPU 不是同步加速组的一部分，当前不支持该枚举值

enumerator DCGM_ST_REQUIRES_ROOT

当Hostengine以非根用户运行时，无法执行此操作

enumerator DCGM_ST_MTVS_ERROR

MTDCGM GPU 诊断成功执行，但报告了错误

enumerator DCGM_ST_INSUFFICIENT_SIZE

输入参数给的内存不够大

enumerator DCGM_ST_FIELD_UNSUPPORTED_BY_API

定的Field ID不支持

enumerator DCGM_ST_MODULE_NOT_LOADED

MTDCGM 的模块未加载

enumerator DCGM_ST_IN_USE

无法完成请求的操作，因为受影响的资源正在使用中

enumerator DCGM_ST_GROUP_IS_EMPTY

此组为空，请求的操作在空组上无效

enumerator DCGM_ST_PROFILING_NOT_SUPPORTED

不支持对此组 GPU 或 GPU 进行分析

enumerator DCGM_ST_PROFILING_LIBRARY_ERROR

第三方分析模块返回了无法恢复的错误

enumerator DCGM_ST_PROFILING_MULTI_PASS

请求的分析指标无法在一次传递中收集

enumerator DCGM_ST_DIAG_ALREADY_RUNNING

已有一个诊断实例正在运行，无法在当前实例完成前运行新的诊断

enumerator DCGM_ST_DIAG_BAD_JSON

MTDCGM GPU 诊断返回的 JSON 无法解析

enumerator DCGM_ST_DIAG_BAD_LAUNCH

启动 MTDCGM GPU 诊断时出错

enumerator DCGM_ST_DIAG_UNUSED

预留字段

enumerator DCGM_ST_DIAG_THRESHOLD_EXCEEDED

Field值达到或超过错误阈值

enumerator DCGM_ST_INSUFFICIENT_DRIVER_VERSION

安装的驱动程序版本不足以支持此 API

enumerator DCGM_ST_INSTANCE_NOT_FOUND

指定的 GPU 实例不存在

enumerator DCGM_ST_COMPUTE_INSTANCE_NOT_FOUND

指定的 GPU 计算实例不存在，当前不支持该枚举值

enumerator DCGM_ST_CHILD_NOT_KILLED

在重试次数内无法杀死子进程

enumerator DCGM_ST_3RD_PARTY_LIBRARY_ERROR

检测到第三方库中的错误

enumerator DCGM_ST_INSUFFICIENT_RESOURCES

资源不足

enumerator DCGM_ST_PLUGIN_EXCEPTION

诊断插件抛出异常

enumerator DCGM_ST_MTVS_ISOLATE_ERROR

诊断返回的错误表明需要进行隔离

enumerator DCGM_ST_MTVS_BINARY_NOT_FOUND

在指定位置未找到 MTVS 二进制文件

enumerator DCGM_ST_MTVS_KILLED

MTVS 进程被信号杀死

enumerator DCGM_ST_PAUSED

Hostengine和所有模块已暂停

enumerator DCGM_ST_ALREADY_INITIALIZED

对象已初始化

enumerator DCGM_ST_MTML_NOT_LOADED

无法执行操作，因为 MTML 未加载

enum dcgmGroupType_t

GPU组的类型

Values:

enumerator DCGM_GROUP_DEFAULT

节点上的所有 GPU 都被添加到该组

enumerator DCGM_GROUP_EMPTY

创建一个空组

enumerator DCGM_GROUP_DEFAULT_MTSWITCHES

节点上的所有 MtSwitches 都被添加到该组，当前不支持

Field类型

Field类型是一个字节

#define DCGM_FT_BINARY 'b'

表示结构的二进制数据块

#define DCGM_FT_DOUBLE 'd'

8字节双精度

#define DCGM_FT_INT64 'i'

8字节有符号整数

#define DCGM_FT_STRING 's'

以 null 结尾的 ASCII 字符串

#define DCGM_FT_TIMESTAMP 't'

8字节有符号整数，表示自1970年以来的微秒数

#define DCGM_FT_INT64_HEX 'x'

8字节有符号整数，表示以十六进制形式显示

Field 域

表示和Field相关连的设备实体域或全局域

#define DCGM_FS_GLOBAL 0

全局Field (比如: driver version)

#define DCGM_FS_ENTITY 1

和Field相关连的设备实例 (GPU...等)

#define DCGM_FS_DEVICE DCGM_FS_ENTITY

和Field ID相关连的device

Field实体

表示与特定实体关联的Field

Typedefs

typedef enum dcgm_field_entity_group_t dcgm_field_entity_group_t

可能Field实体组的枚举

typedef unsigned int dcgm_field_eid_t

• 表示Field实体内的实体标识符。例如，这是DCGM_FE_GPU的gpuId

Enums

enum dcgm_field_entity_group_t

可能Field实体组的枚举

Values:

enumerator DCGM_FE_NONE

Field不与任何实体关联。Field范围应该是DCGM_FS_GLOBAL

enumerator DCGM_FE_GPU

Field与GPU实体关联

enumerator DCGM_FE_COUNT

枚举中的元素数量。保持此项为最后一个

Field标识符

Field标识符

Functions

dcgm_field_meta_p DcgmFieldGetById (unsigned short fieldId)

参数：

fieldId

IN: Field ID之一 (DCGM_FI_?)

返回值

如果是0则表示获取失败，如果大于0，则表示指向Field元数据结构的指针

接口描述

通过Field ID获取指向Field元数据

请参阅 DCGM_FI_? 以获取Field ID列表

dcgm_field_meta_p DcgmFieldGetByTag (char *tag)

参数：

tag

IN: Field的标签

返回值

返回0表示失败或未找到，返回大于0表示指向Field元数据结构的指针

接口描述

通过Field标签获取指向Field元数据的指针

int DcgmFieldsInit (void)

返回值

返回0则表示成功， 小于0则表示初始化失败

接口描述

初始化 DcgmFields 模块。在程序内部调用一次

int DcgmFieldsTerm (void)

返回值

返回0则表示成功， 小于0则表示结束失败

接口描述

终止 DcgmFields 模块，在程序内部调用一次

const char *DcgmFieldsGetEntityGroupString(dcgm_field_entity_group_t entityGroupId)

接口描述

获取entityGroupId对应的字符串Entity Group名字

返回值

指向如GPU的字符串

错误时为空

Defines

#define DCGM_FI_UNKNOWN 0

空Field，未定义

#define DCGM_FI_DRIVER_VERSION 1

驱动程序版本号

#define DCGM_FI_MTML_VERSION 2

MTDCGM 当前使用的MTML版本号

#define DCGM_FI_PROCESS_NAME 3

当前使用libdcgm.so的进程名字

#define DCGM_FI_DEV_COUNT 4

Node节点上的设备数量

#define DCGM_FI_DEV_NAME 50

GPU 设备的名称

#define DCGM_FI_DEV_BRAND 51

设备品牌

#define DCGM_FI_DEV_MTML_INDEX 52

GPU在MTML中使用的逻辑索引

#define DCGM_FI_DEV_SERIAL 53

设备序列号SN

#define DCGM_FI_DEV_UUID 54

与设备对应的 UUID

#define DCGM_FI_DEV_PCI_BUSID 57

设备的 PCI 属性

#define DCGM_FI_DEV_PCI_COMBINED_ID 58

16位device id 和 16位vender id 的组合

#define DCGM_FI_DEV_PCI_SUBSYS_ID 59

32位Sub System Device ID

#define DCGM_FI_GPU_TOPOLOGY_PCI 60

系统中通过PCIe连接的所有GPU拓扑（静态）

#define DCGM_FI_GPU_TOPOLOGY_MTLINK 61

系统中通过MTlink连接的所有GPU拓扑（静态）

#define DCGM_FI_DEV_MIG_MODE 67

设备的 MPC 模式 布尔值：0 表示禁用，1 表示启用

#define DCGM_FI_DEV_CPU_AFFINITY_0 70

设备 CPU 亲和性。第1/8部分 = cpus 0 – 63

#define DCGM_FI_DEV_CPU_AFFINITY_1 71

设备 CPU 亲和性。第1/8部分 = cpus 64 – 127

#define DCGM_FI_DEV_CPU_AFFINITY_2 72

设备 CPU 亲和性。第2/8部分 = cpus 128 - 191

#define DCGM_FI_DEV_CPU_AFFINITY_3 73

设备 CPU 亲和性。第3/8部分 = cpus 192 - 255

#define DCGM_FI_DEV_MTBIOS_VERSION 85

设备的 MTBIOS 版本号

#define DCGM_FI_DEV_MEM_AFFINITY_0 86

NUMA节点亲和性, 0-63

#define DCGM_FI_DEV_MEM_AFFINITY_1 87

NUMA节点亲和性, 64-127

#define DCGM_FI_DEV_MEM_AFFINITY_2 88

NUMA节点亲和性, 128-191

#define DCGM_FI_DEV_MEM_AFFINITY_3 89

NUMA节点亲和性, 192-255

#define DCGM_FI_DEV_GPU_CLOCK 100

设备的 GPU 时钟频率

#define DCGM_FI_DEV_MEM_CLOCK 101

设备的内存时钟频率

#define DCGM_FI_DEV_VIDEO_CLOCK 102

设备的视频编码器/解码器时钟频率

#define DCGM_FI_DEV_MAX_GPU_CLOCK 113

设备支持的最大 GPU 时钟频率

#define DCGM_FI_DEV_MAX_MEM_CLOCK 114

设备支持的最大内存时钟频率

#define DCGM_FI_DEV_MAX_VIDEO_CLOCK 115

设备支持的最大视频编码器/解码器时钟频率

#define DCGM_FI_DEV_MEMORY_TEMP 140

设备的Memory温度,单位为摄氏度 C

#define DCGM_FI_DEV_GPU_TEMP 150

设备的当前温度读数，单位为摄氏度 C

#define DCGM_FI_DEV_POWER_USAGE 155

GPU的功率使用情况，单位为瓦特

#define DCGM_FI_DEV_SLOWDOWN_TEMP 158

GPU设备Slowdown温度的阈值

#define DCGM_FI_DEV_SHUTDOWN_TEMP 159

GPU设备Shutdown温度的阈值

#define DCGM_FI_DEV_POWER_MGMT_LIMIT 160

设备的当前功率限制

#define DCGM_FI_DEV_POWER_MGMT_LIMIT_MIN 161

设备功率的最小限制

#define DCGM_FI_DEV_POWER_MGMT_LIMIT_MAX 162

设备功率的最大限制

#define DCGM_FI_DEV_POWER_MGMT_LIMIT_DEF 163

设备功率的默认限制

#define DCGM_FI_DEV_ENFORCED_POWER_LIMIT 164

设备的有效功率限制

#define DCGM_FI_DEV_FAN_SPEED 191

设备的风扇速度，以百分比表示，范围是0-100

#define DCGM_FI_DEV_PCIE_TX_THROUGHPUT 200

PCIe传输吞吐，每秒传输字节数

#define DCGM_FI_DEV_PCIE_RX_THROUGHPUT 201

PCIe 接收吞吐，每秒接收字节数

#define DCGM_FI_DEV_PCIE_REPLAY_COUNTER 202

PCIe重播计数器

#define DCGM_FI_DEV_GPU_UTIL 203

GPU利用率

#define DCGM_FI_DEV_ENC_UTIL 206

编码利用率

#define DCGM_FI_DEV_DEC_UTIL 207

解码利用率

#define DCGM_FI_DEV_XID_ERRORS 230

GPU上发生的XID错误，不同的value表示不同的XID错误类型

#define DCGM_FI_DEV_PCIE_MAX_LINK_GEN 235

当前PCIe链路的最大generation

#define DCGM_FI_DEV_PCIE_MAX_LINK_WIDTH 236

当前PCIe链路的最大宽度

#define DCGM_FI_DEV_PCIE_LINK_GEN 237

当前PCIe链路的generation

#define DCGM_FI_DEV_PCIE_LINK_WIDTH 238

当前PCIe链路的宽度

#define DCGM_FI_DEV_FB_TOTAL 250

GPU的总显存大小，以MB为单位

#define DCGM_FI_DEV_FB_FREE 251

当前可申请的最大剩余显存大小，以MB为单位

#define DCGM_FI_DEV_FB_USED 252

已使用的显存大小，以MB为单位

#define DCGM_FI_DEV_FB_USED_PERCENT 254

显存使用百分比：算公式为'已用/(总数)'，取值范围为0.0-1.0

#define DCGM_FI_DEV_ECC_CURRENT 300

当前设备的ECC模式开启或者关闭

#define DCGM_FI_DEV_ECC_SBE_VOL_TOTAL 310

当前设备DDR上单bit ECC错误volatile计数

#define DCGM_FI_DEV_ECC_DBE_VOL_TOTAL 311

当前设备DDR上双bit ECC错误volatile计数

#define DCGM_FI_DEV_ECC_SBE_AGG_TOTAL 312

当前设备DDR上单bit ECC错误aggregate计数

#define DCGM_FI_DEV_ECC_DBE_AGG_TOTAL 313

当前设备DDR上双bit ECC错误aggregate计数

#define DCGM_FI_DEV_RETIRED_SBE 390

由DDR单bit错误导致的retired page错误计数

#define DCGM_FI_DEV_RETIRED_DBE 391

由DDR双bit错误导致的retired page错误计数

#define DCGM_FI_DEV_MTLINK_CRC_DATA_ERROR_COUNT_TOTAL 419

所有的MTLink发生CRC错误的累计总数

#define DCGM_FI_DEV_MTLINK_REPLAY_ERROR_COUNT_TOTAL 429

所有MTLink发生Replay错误的累计总数

#define DCGM_FI_DEV_MTLINK_RECOVERY_ERROR_COUNT_TOTAL 439

所有MTLink发生Recovery错误累计总数

#define DCGM_FI_DEV_VIRTUAL_MODE 500

当前GPU的虚拟化模式

#define DCGM_FI_PROF_ENGINE_ACTIVE 2001

GPU Engine活动的时间比

GPU设备memory读写接口的活跃比率

#define DCGM_FI_PROF_MTLINK_TX_BYTES 2100

所有MtLink发送（传输）数据的总字节数，包括头部和有效载荷

#define DCGM_FI_PROF_MTLINK_RX_BYTES 2150

所有MtLink接收（读取）数据的总字节数，包括头部和有效载荷

#define DCGM_FI_DEV_THERMAL_SLOWDOWN_COUNTER 2201

温度发生slowdown的次数

#define DCGM_FI_DEV_GPU_TEMP_SENSOR1 2202

Sensor1的当前温度，单位摄氏度

#define DCGM_FI_DEV_GPU_TEMP_SENSOR2 2203

Sensor2的当前温度，单位摄氏度

#define DCGM_FI_DEV_ON_DIE_ECC_MODE_CURRENT 2204

ON DIE ECC开启状态，0表示OFF，1表示ON

#define DCGM_FI_DEV_EDC_MODE_CURRENT 2205

EDC开启状态，0表示OFF，1表示ON

#define DCGM_FI_DEV_HWR_COUNTER 3000

GPU发生Hardware Recovery硬件恢复的次数

#define DCGM_FI_DEV_MEM_EDC_UNCORRECTABLE_COUNTER_TOTAL 3100

Memory EDC检测出不可纠正错误计数

#define DCGM_FI_DEV_MEM_EDC_CORRECTABLE_COUNTER_TOTAL 3101

Memory EDC检测出可纠正错误计数

#define DCGMI_FI_DEV_MTLINK_UNCORRECTABLE_COUNTER_TOTAL 3200

当前Device的所有MTLink发生不可纠正错误计数

#define DCGMI_FI_DEV_MTLINK_CORRECTABLE_COUNTER_TOTAL 3201

当前Device的所有MTLink发生可纠正错误计数

#define DCGM_FI_DEV_MTLINK_FRAMING_ERROR_COUNT_TOTAL 3202

当前Device的所有MTLink发生帧错误计数，仅支持QY2

#define DCGMI_FI_DEV_MTLINK_BER_L0 3203

Mtlink Link0的BER

#define DCGMI_FI_DEV_MTLINK_BER_L1 3204

Mtlink Link1的BER

#define DCGMI_FI_DEV_MTLINK_BER_L2 3205

Mtlink Link2的BER

#define DCGMI_FI_DEV_MTLINK_BER_L3 3206

Mtlink Link3的BER

#define DCGMI_FI_DEV_MTLINK_BER_L4 3207

Mtlink Link4的BER

#define DCGMI_FI_DEV_MTLINK_BER_L5 3208

Mtlink Link5的BER

#define DCGMI_FI_DEV_MTLINK_BER_L6 3209

Mtlink Link6的BER

#define DCGMI_FI_DEV_MTLINK_BER_L7 3210

Mtlink Link7的BER

#define DCGMI_FI_DEV_MTLINK_BER_L8 3211

Mtlink Link8的BER

#define DCGMI_FI_DEV_MTLINK_BER_L9 3212

Mtlink Link9的BER

#define DCGMI_FI_DEV_MTLINK_BER_L10 3213

Mtlink Link10的BER

#define DCGMI_FI_DEV_MTLINK_BER_L11 3214

Mtlink Link11的BER

#define DCGMI_FI_DEV_MTLINK_BER_L12 3215

Mtlink Link12的BER

#define DCGMI_FI_DEV_MTLINK_BER_L13 3216

Mtlink Link13的BER

#define DCGM_FI_MAX_FIELDS 3217

表示最大Field ID，用来检测Field Id是否超过最大值

数据结构

dcgmStructs 组

DCGM_HOME_DIR_VAR_NAME "DCGM_HOME_DIR"

运行GPU诊断的标志选项，表示DCGM的安装路径

DCGM_RUN_FLAGS_VERBOSE 0x0001

以详细模式输出；包括信息以及警告

DCGM_RUN_FLAGS_STATSONFAIL 0x0002

仅在失败时输出统计信息

DCGM_RUN_FLAGS_FAIL_EARLY 0x0010

启用针对Targeted Stress、 Targeted Power诊断测试的早期失败检查

Defines

dcgmConnectV2Params_version1 MAKE_DCGM_VERSION(dcgmConnectV2Params_v1,1)

dcgmConnectV2Params_v1的v1版本

dcgmConnectV2Params_version2 MAKE_DCGM_VERSION(dcgmConnectV2Params_v2,2)

dcgmConnectV2Params_v2的v2版本

dcgmConnectV2Params_version dcgmConnectV2Params_version2

dcgmConnectV2Params_t的最新版本

dcgmHostengineHealth_version1 MAKE_DCGM_VERSION(dcgmHostengineHealth_v1,1)

dcgmHostengineHealth_version dcgmHostengineHealth_version1

dcgmHostengineHealth_t的最新版本

dcgmGroupInfo_version2 MAKE_DCGM_VERSION(dcgmGroupInfo_v2,2)

dcgmGroupInfo_v2的v2版本

dcgmGroupInfo_versiondcgmGroupInfo_version2

dcgmGroupInfo_t的最新版本

DCGM_MAX_NUM_FIELD_GROUPS 64

可以存在的Field Group最大数量

DCGM_MAX_FIELD_IDS_PER_FIELD_GROUP 128

单个Field Group中可以存在的FieldID的最大数量

dcgmFieldGroupInfo_version1 MAKE_DCGM_VERSION(dcgmFieldGroupInfo_v1,1)

dcgmFieldGroupInfo_v1的v1版本

dcgmFieldGroupInfo_version dcgmFieldGroupInfo_version1

dcgmFieldGroupInfo_t的最新版本

dcgmAllFieldGroup_version1 MAKE_DCGM_VERSION(dcgmAllFieldGroup_v1,1)

dcgmAllFieldGroup_v1的v1版本

dcgmAllFieldGroup_version dcgmAllFieldGroup_version1

dcgmAllFieldGroup_v1的最新版本

dcgmDeviceIdentifiers_version1 MAKE_DCGM_VERSION(dcgmDeviceIdentifiers_v1,1)

dcgmDeviceIdentifiers_v1的v1版本

dcgmDeviceIdentifiers_version dcgmDeviceIdentifiers_version1

dcgmDeviceIdentifiers_v1的最新版本

dcgmDeviceAttributes_version3 MAKE_DCGM_VERSION(dcgmDeviceAttributes_v3,3)

dcgmDeviceAttributes_v3的v3版本

dcgmDeviceAttributes_version dcgmDeviceAttributes_version3

dcgmDeviceAttributes_t的最新版本

DCGM_DEVICE_UUID_BUFFER_SIZE 80

设备UUID缓冲区大小

DCGM_MAX_BLOB_LENGTH 4096

设置最大blob条目的大小

dcgmFieldValue_version1 MAKE_DCGM_VERSION(dcgmFieldValue_v1,1)

dcgmFieldValue_v1的v1版本

dcgmFieldValue_version2 MAKE_DCGM_VERSION(dcgmFieldValue_v2,2)

dcgmFieldValue_v2的v2版本

DCGM_FV_FLAG_LIVE_DATA 0x00000001

dcgmEntitiesGetLatestValues使用的Field值标志

从驱动程序检索实时数据，而不是缓存数据 警告： 设置此标志将导致多次调用MUSA驱动程序，这将比检索缓存值慢得多

DCGM_HEALTH_WATCH_COUNT_V1 10

用于遍历dcgmHealthSystems_v1枚举

DCGM_HEALTH_WATCH_COUNT_V2 12

用于遍历dcgmHealthSystems_v2枚举

DCGM_ERR_MSG_LENGTH 512

DCGM_HEALTH_WATCH_MAX_INCIDENTS DCGM_GROUP_MAX_ENTITIES

dcgmHealthResponse_version4 MAKE_DCGM_VERSION(dcgmHealthResponse_v4,4)

dcgmHealthResponse_v4的v4版本

dcgmHealthResponse_version dcgmHealthResponse_version4

dcgmHealthResponse_t的最新版本

dcgmHealthSetParams_version2 MAKE_DCGM_VERSION(dcgmHealthSetParams_v2,2)

dcgmHealthSet_v2的v2版本

DCGM_MAX_ERRORS 5

DCGM_PER_GPU_TEST_COUNT_V8 13

DCGM_PER_GPU_TEST_COUNT_V7 9

DCGM_DIAG_AUX_DATA_LEN 2048

dcgmDiagTestAuxData_version1 MAKE_DCGM_VERSION(dcgmDiagTestAuxData_v1,1)

dcgmDiagTestAuxData_v1的v1版本

dcgmDiagTestAuxData_version dcgmDiagTestAuxData_version1

DCGM_SWTEST_COUNT 10

LEVEL_ONE_MAX_RESULTS 16

DCGM_DEVICE_ID_LEN 5

DCGM_VERSION_LEN 12

dcgmDiagResponse_version10 MAKE_DCGM_VERSION(dcgmDiagResponse_v10,10)

dcgmDiagResponse_v10的v10版本

dcgmDiagResponse_version9 MAKE_DCGM_VERSION(dcgmDiagResponse_v9,9)

dcgmDiagResponse_v9的v9版本

dcgmDiagResponse_version8 MAKE_DCGM_VERSION(dcgmDiagResponse_v8,8)

dcgmDiagResponse_v8的v8版本

dcgmDiagResponse_version7 MAKE_DCGM_VERSION(dcgmDiagResponse_v7,7)

dcgmDiagResponse_v7的v7版本

DCGM_MAX_CONFIG_FILE_LEN 10000

DCGM_MAX_TEST_NAMES 20

DCGM_MAX_TEST_NAMES_LEN 50

DCGM_MAX_TEST_PARMS 100

DCGM_MAX_TEST_PARMS_LEN 100

DCGM_GPU_LIST_LEN 50

DCGM_FILE_LEN 30

DCGM_PATH_LEN 128

DCGM_THROTTLE_MASK_LEN 50

dcgmRunDiag_version7 MAKE_DCGM_VERSION(dcgmRunDiag_v7,7)

dcgmRunDiag_t的v7版本

DCGM_GEGE_FLAG_ONLY_SUPPORTED 0x00000001

dcgmGetEntityGroupEntities的标志参数的标志

仅返回MTDCGM支持的实体。这模仿了dcgmGetAllSupportedDevices()的行为

DCGM_SUMMARY_MIN 0x00000001

DCGM_SUMMARY_MAX 0x00000002

DCGM_SUMMARY_AVG 0x00000004

DCGM_SUMMARY_SUM 0x00000008

DCGM_SUMMARY_COUNT 0x00000010

DCGM_SUMMARY_INTEGRAL 0x00000020

DCGM_SUMMARY_DIFF 0x00000040

DCGM_SUMMARY_SIZE 7

dcgmFieldSummaryRequest_version1 MAKE_DCGM_VERSION(dcgmFieldSummaryRequest_v1,1)

DCGM_MODULE_STATUSES_CAPACITY 16

dcgmModuleGetStatuses_version1 MAKE_DCGM_VERSION(dcgmModuleGetStatuses_v1,1)

dcgmModuleGetStatuses的v1版本

dcgmModuleGetStatuses_versiondcgmModuleGetStatuses_version1

dcgmStartEmbeddedV2Params_version1MAKE_DCGM_VERSION(dcgmStartEmbeddedV2Params_v1,1)

dcgmStartEmbeddedV2Params_v1的v1版本

dcgmStartEmbeddedV2Params_version2MAKE_DCGM_VERSION(dcgmStartEmbeddedV2Params_v2,2)

dcgmStartEmbeddedV2Params的v2版本

dcgmSettingsSetLoggingSeverity_version1 MAKE_DCGM_VERSION(dcgmSettingsSetLoggingSeverity_v1,1)

dcgmSettingsSetLoggingSeverity_version dcgmSettingsSetLoggingSeverity_version1

dcgmVersionInfo_version2 MAKE_DCGM_VERSION(dcgmVersionInfo_v2,2)

dcgmVersionInfo_v2的v2版本

dcgmVersionInfo_version dcgmVersionInfo_version2

类型定义

typedef uintptr_t dcgmHandle_t

MTDCGM句柄的标识符

typedef uintptr_t dcgmGpuGrp_t

GPU组的标识符，一个组可以有一个或多个GPU

typedef uintptr_t dcgmFieldGrp_t

Field Group的标识符

typedef uintptr_t dcgmStatus_t

状态代码列表的标识符

typedef struct dcgm_link_s dcgm_link_t

表示一个mtlink对象

typedef dcgmConnectV2 Params_v2 dcgmConnectV2Params_t

dcgmConnectV2Params_v2的类型定义

typedef dcgmHostengineHealth_v1 dcgmHostengineHealth_t

dcgmHostengineHealth_t的类型定义

typedef dcgmGroupInfo_v2 dcgmGroupInfo_t

dcgmGroupInfo_v2的类型定义

typedef dcgmFieldGroupInfo_v1 dcgmFieldGroupInfo_t

typedef dcgmAllFieldGroup_v1 dcgmAllFieldGroup_t

typedef dcgmDeviceIdentifiers_v1 dcgmDeviceIdentifiers_t

dcgmDeviceIdentifiers_v1的类型定义

typedef dcgmDeviceAttributes_v3 dcgmDeviceAttributes_t

dcgmDeviceAttributes_v3的类型定义

typedef int (*dcgmFieldValueEnumeration_f)(unsigned int gpuId, dcgmFieldValue_v1 *values, int numValues, void *userData)

用户回调函数，用于处理一个或多个Field更新

• 这个回调函数将针对每个Field被调用一次或多次，直到所有预期的Field值都被枚举。由被调用者来检测Field ID何时发生变化

Param gpuId:

IN: GPU逻辑索引

Param values:

IN: Field的值，一旦获取到Field值，则必须及时将这些值拷贝回来，因为调用结束，数据将会被销毁

Param numValues:

IN: values[]中有效的数量

Param userData:

IN: 传递给生成此回调的更新函数的用户数据指针

Return:

• 如果OK则返回0，如果失败返回值小于0的值，允许调用者提前终止Field遍历

typedef int (*dcgmFieldValueEntityEnumeration_f)(dcgm_field_entity_group_t entityGroupId, dcgm_field_eid_t entityId, dcgmFieldValue_v1 *values, int numValues, void *userData)

用户回调函数，用于处理一个或多个Field更新

这个回调函数将对每个Field调用一次或多次，直到所有预期的Field值都被调用

Param entityGroupId:

IN: Entity Group Id

Param entityId:

IN: Entity ID

Param values:

IN: Field的值，一旦获取到Field值，则必须及时将这些值拷贝回来，因为调用结束，数据将会被销毁

Param numValues:

IN: values[]中有效的数量

Param userData:

IN: 传递给生成此回调的更新函数的用户数据指针

Return:

如果OK则返回0，如果失败则返回小于0的值，允许调用者提前终止Field遍历

typedef enum dcgmHealthSystems_enum dcgmHealthSystems_t

系统模块枚举

typedef enum dcgmHealthWatchResult_enum dcgmHealthWatchResults_t

健康监控结果结构体

typedef dcgmHealthResponse_v4 dcgmHealthResponse_t

dcgmHealthResponse_v4的类型定义

typedef enum dcgmDiagResult_enum dcgmDiagResult_t

Diagnostic测试结果枚举值

typedef enum dcgmPerGpuTestIndices_enum dcgmPerGpuTestIndices_t

每个GPU的Diagnostic测试结果枚举 - dcgmDiagResponsePerGpu_t.results[]的固定索引

typedef enum dcgmSoftwareTest_enum dcgmSoftwareTest_t**

typedef dcgmFieldSummaryRequest_v1 dcgmFieldSummaryRequest_t

typedef dcgmModuleGetStatuses_v1 dcgmModuleGetStatuses_t

typedef dcgmSettingsSetLoggingSeverity_v1 dcgmSettingsSetLoggingSeverity_t

typedef dcgmVersionInfo_v2 dcgmVersionInfo_t

枚举

enum DcgmLoggingSeverity_t

MTDCGM日志严重性等级

这些与Severity.h中定义的plog严重性相匹配。每个级别包括所有高于它的级别。例如，级别4包括3、2和1

Values:

enumerator DcgmLoggingSeverityUnspecified

不关心/从环境继承

enumerator DcgmLoggingSeverityNone

无日志

enumerator DcgmLoggingSeverityFatal

致命错误级

enumerator DcgmLoggingSeverityError

错误级

enumerator DcgmLoggingSeverityWarning

警告级

enumerator DcgmLoggingSeverityInfo

信息级

enumerator DcgmLoggingSeverityDebug

调试信息（将生成大量日志）

enumerator DcgmLoggingSeverityVerbose

详细调试信息

enum dcgmHealthSystems_enum

用于启用或禁用健康监控系统的系统结构

Values:

enumerator DCGM_HEALTH_WATCH_PCIE

PCIe系统模块（查询前必须要有1分钟的数据）

enumerator DCGM_HEALTH_WATCH_MTLINK

MTLINK系统模块

enumerator DCGM_HEALTH_WATCH_ALL

所有系统模块

enum dcgmHealthWatchResult_enum

健康监控测试结果

Values:

enumerator DCGM_HEALTH_RESULT_PASS

此系统中的所有结果都报告正常

enumerator DCGM_HEALTH_RESULT_WARN

已发出警告

enumerator DCGM_HEALTH_RESULT_FAIL

已发出的失败

enum dcgmDiagnosticLevel_t

诊断级别的枚举

枚举值:

enumerator DCGM_DIAG_LVL_INVALID

未初始化

enumerator DCGM_DIAG_LVL_SHORT

对系统进行非常基础的健康检查

enumerator DCGM_DIAG_LVL_MED

运行中等长度的诊断（几分钟）

enumerator DCGM_DIAG_LVL_LONG

运行全面诊断（几分钟）

enumerator DCGM_DIAG_LVL_XLONG

运行非常全面的诊断（几十分钟）

enum dcgmDiagResult_enum

诊断测试结果

Values:

enumerator DCGM_DIAG_RESULT_PASS

诊断结果通过

enumerator DCGM_DIAG_RESULT_SKIP

诊断插件跳过测试

enumerator DCGM_DIAG_RESULT_WARN

诊断结果有警告信息，结果通过

enumerator DCGM_DIAG_RESULT_FAIL

诊断结果未能通过

enumerator DCGM_DIAG_RESULT_NOT_RUN

诊断插件未运行

enum dcgmPerGpuTestIndices_enum

每GPU诊断测试 - dcgmDiagResponsePerGpu_t.results[]的固定索引

枚举值:

enumerator DCGM_PCI_INDEX

PCIe测试索引

enumerator DCGM_MEMORY_BANDWIDTH_INDEX

内存带宽测试索引

enumerator DCGM_MEMTEST_INDEX

Memtest测试索引

enumerator DCGM_SOFTWARE_INDEX

软件测试索引

enumerator DCGM_UNKNOWN_INDEX

未知测试索引，用于判断测试是否越界

enum dcgmSoftwareTest_enum

枚举值:

enumerator DCGM_SWTEST_MTML_LIBRARY

检查MTML库的存在

enumerator DCGM_SWTEST_MUSA_MAIN_LIBRARY

检查MUSA库的存在

enumerator DCGM_SWTEST_MUSA_RUNTIME_LIBRARY

检查MUSA运行时库的存在

enumerator DCGM_SWTEST_PERMISSIONS

检查字符设备权限

enum dcgmModuleId_t

模块ID

Values:

enumerator DcgmModuleIdCore

核心MTDCGM模块 - 始终加载

enumerator DcgmModuleIdIntrospect

Introspect模块

enumerator DcgmModuleIdHealth

Health模块

enumerator DcgmModuleIdDiag

GPU诊断模块

enumerator DcgmModuleIdCount

用于标记最后一个模块，无实际意义

enum dcgmModuleStatus_t

模块状态

模块是延迟加载的，因此它们将处于状态DcgmModuleStatusNotLoaded，直到它们被使用。一旦模块被使用，它们将转移到另一个状态

枚举值:

enumerator DcgmModuleStatusNotLoaded

模块尚未加载

enumerator DcgmModuleStatusDenylisted

模块在黑名单上，无法加载

enumerator DcgmModuleStatusFailed

加载模块失败

enumerator DcgmModuleStatusLoaded

模块已加载

enumerator DcgmModuleStatusUnloaded

模块已卸载，发生在关机期间

enumerator DcgmModuleStatusPaused

模块已被暂停。这是一个临时状态，一旦模块恢复，它将转移到DcgmModuleStatusLoaded，这个状态意味着模块已加载

struct dcgmConnectV2Params_v1

#include <dcgm_structs.h>

dcgmConnect_v2（v1）的连接选项

注意：此版本已过时。请使用dcgmConnectV2Params_v2

公共成员

unsigned int version

版本号，使用dcgmConnectV2Params_version

unsigned int persistAfterDisconnect

一旦连接终止，是否保留此连接修改的状态，一旦取消连接，由之前连接创建的所有Field监控都会被移除。1表示在此断开连接后不清理；0表示断开连接后清理

struct dcgmConnectV2Params_v2

#include <dcgm_structs.h>

dcgmConnect_v2（v2）的连接选项

公共成员

unsigned int version

版本号，使用dcgmConnectV2Params_version

unsigned int persistAfterDisconnect

一旦连接终止，是否保留此连接修改的状态。通常，一旦取消连接，由之前连接创建的所有Field监控都会被移除。1表示在此断开连接后不清理；0表示断开连接后清理

unsigned int timeoutMs

尝试连接到指定Hostengine时，在放弃连接之前应等待多长时间（以毫秒为单位）

unsigned int addressIsUnixSocket

传递的地址是否为unix套接字文件名，1表示是，0表示TCP/IP地址

struct dcgmHostengineHealth_v1

#include <dcgm_structs.h>

dcgmHostengineHealth_v1的类型定义

公共成员

unsigned int version

结构体的版本

unsigned int overallHealth

0表示健康，其他表示不健康

struct dcgmGroupEntityPair_t

#include <dcgm_structs.h>

表示一个entityGroupId + entityId的peer对，唯一标识一个Entity Group

公共成员

dcgm_field_entity_group_t entityGroupId

Entity Group ID

dcgm_field_eid_t entityId

Entity ID

struct dcgmGroupInfo_v2

#include <dcgm_structs.h>

存储MTDCGM Group 信息的结构

公共成员

unsigned int version

Group 信息的版本号（使用dcgmGroupInfo_version2）

unsigned int count

entityList中的Entity数量

char groupName[256]

Group名称

dcgmGroupEntityPair_t entityList[64]

Entity列表

struct dcgmFieldGroupInfo_v1

#include <dcgm_structs.h>

表示Field Group信息的结构体

公共成员

unsigned int version

结构体的版本号（dcgmFieldGroupInfo_version）

unsigned int numFieldIds

fieldIds[]中有效数量

dcgmFieldGrp_t fieldGroupId

Field Group ID

char fieldGroupName[256]

Field Group名称

unsigned short fieldIds[128]

Field ID数组

struct dcgmAllFieldGroup_v1

公共成员

unsigned int version

结构体版本号（dcgmAllFieldGroupInfo_version）

unsigned int numFieldGroups

fieldGroups[]中的成员数量

dcgmFieldGroupInfo_t fieldGroups[64]

Field Group信息数组

struct dcgmErrorInfo_t

#include <dcgm_structs.h>

表示错误属性的结构体

公共成员

unsigned int gpuId

GPU逻辑索引

short fieldId

Field Id，是DCGM_FI_?中的一个

int status

Field Value的状态，是DCGM_ST_?中的一个

struct dcgmDeviceThermals_v1

#include <dcgm_structs.h>

表示GPU设备温度信息

公共成员

unsigned int version

结构体版本号

unsigned int slowdownTemp

GPU的Slowdown温度

unsigned int shutdownTemp

GPU的Shutdown温度

struct dcgmDeviceIdentifiers_v1

#include <dcgm_structs.h>

表示设备标识符结构体

公共成员

unsigned int version

结构体版本号（dcgmDeviceIdentifiers_version）

char brandName[256]

设备品牌名字

char deviceName[256]

设备名字

char pciBusId[256]

PCI总线ID

char serial[256]

设备的序列号

char uuid[256]

设备的UUID

char mtbios[256]

MTBIOS版本号

char inforomImageVersion[256]

Inforom Image版本号

unsigned int pciDeviceId

16-bit 设备ID和16-bit供应商ID组合

unsigned int pciSubSystemId

32位子系统设备ID

char driverVersion[256]

驱动程序版本号

unsigned int virtualizationMode

虚拟化模式

struct dcgmDeviceMemoryUsage_v1

#include <dcgm_structs.h>

表示设备内存和使用情况结构体

公共成员

unsigned int version

结构体版本号（dcgmDeviceMemoryUsage_version）

unsigned int bar1Total

BAR1总大小（兆字节），当前不支持

unsigned int fbTotal

GPU Memory总大小（兆字节）

unsigned int fbUsed

已使用的Memory大小（兆字节）

unsigned int fbFree

空闲Memory大小（兆字节）

struct dcgmDeviceAttributes_v3

公共成员

unsigned int version

结构体版本号（dcgmDeviceAttributes_version）

dcgmDeviceSupportedClockSets_t clockSets

设备的支持时钟频率列表

dcgmDeviceThermals_t thermalSettings

设备的当前的温度结构体

dcgmDevicePowerLimits_t powerLimits

设备的各种功率阈值结构体

dcgmDeviceIdentifiers_t identifiers

设备的标识结构体

dcgmDeviceMemoryUsage_t memoryUsage

设备的内存使用信息结构体

dcgmDeviceSettings_v2 settings

基本设备设置信息结构体

struct dcgmFieldValue_v1

#include <dcgm_structs.h>

此结构用于表示要查询的Field的值

公共成员

unsigned int version

结构体版本号（dcgmFieldValue_version1）

unsigned short fieldId

FIeld Id，是DCGM_FI_?中的一个

unsigned short fieldType

Field Value类型，是DCGM_FT_?中的一个

int status

查询Field value的状态，是DCGM_ST_OK或DCGM_ST_? 中的一个

int64_t ts

自1970年以来以微秒为单位的计时戳

int64_t i64

Int64类型的值

double dbl

Double类型的值

char str[256]

字符类型的值，以NULL结束

char blob[4096]

二进制blob类型的值

union dcgmFieldValue_v1::[anonymous] value

Field Value的数值，以联合体表示，实际Value与\ref fieldType相关

struct dcgmFieldValue_v2

#include <dcgm_structs.h>

此结构用于表示要查询的Field的值

公共成员

unsigned int version

结构体版本号（dcgmFieldValue_version2）

dcgm_field_entity_group_t entityGroupId

Field值的实体所属Entity Group的ID

dcgm_field_eid_t entityId

Field值所属Entity的ID

unsigned short fieldId

FIeld Id，是DCGM_FI_?中的一个

unsigned short fieldType

Field Value类型，是DCGM_FT_?中的一个

int status

查询Field value的状态，是DCGM_ST_OK或DCGM_ST_? 中的一个

unsigned int unused

预留字段，用于将ts对齐到8字节边界

int64_t ts

自1970年以来以微秒为单位的计时戳

int64_t i64

Int64类型的值

double dbl

Double类型的值

char str[256]

字符串类型的值，以NULL结束

char blob[4096]

二进制blob类型的值

union dcgmFieldValue_v2::[anonymous] value

Field Value的数值，以联合体表示，实际Value与\ref fieldType相关

struct dcgmStatSummaryInt64_t

#include <dcgm_structs.h>

int64格式的时间序列数据Summary

每个值要么被设置，要么是一个空白值。使用DCGM_INT64_IS_BLANK()宏检查空白值

详细见dcgm_structs.h中空白值的实际解释

公共成员

long long minValue

样本中的最小值

long long maxValue

样本中的最大值

long long average

样本中的简单平均值，在计算时会忽略空白值

struct dcgmStatSummaryInt32_t

#include <dcgm_structs.h>

与dcgmStatSummaryInt64_t相同，但使用32位整数值

公共成员

int minValue

样本中的最小值

int maxValue

样本中的最大值

int average

样本中的简单平均值，在计算时会忽略空白值

struct dcgmStatSummaryFp64_t

#include <dcgm_structs.h>

双精度时间序列数据的Summary

每个值要么被设置，要么是一个空值。使用DCGM_FP64_IS_BLANK()宏来检查空值

见dcgm_structs.h以获取空值的实际值

公共成员

double minValue

样本中的最小值

double maxValue

样本中的最大值

double average

样本中的简单平均值，在计算时会忽略空白值

struct dcgmDiagErrorDetail_v2

#include <dcgm_structs.h>

诊断的错误详细描述

公共成员

msg 诊断错误的详细信息

gpuId GPU逻辑索引

code 诊断错误时的错误码

unsigned int category

见dcgmErrorCategory_t枚举

unsigned int severity

见dcgmErrorSeverity_t枚举

struct dcgmIncidentInfo_t

公共成员

dcgmHealthSystems_t system

此信息所属的系统模块

dcgmHealthWatchResults_t health

此事件的健康监视结果

dcgmDiagErrorDetail_t error

有关错误及其错误代码的信息

dcgmGroupEntityPair_t entityInfo

Entity peer

struct dcgmHealthResponse_v4

#include <dcgm_structs.h>

健康响应结构v4版本 - 简单列出事件，而不是按实体报告列出

公共成员

unsigned int version

此结构体的版本号

dcgmHealthWatchResults_t overallHealth

整个主机的整体健康状况

unsigned int incidentCount

此结构中报告的健康事件数量

dcgmIncidentInfo_t incidents[64]

错误检测报告

struct dcgmHealthSetParams_v2

#include <dcgm_structs.h>

用于通过dcgmHealthSet_v2 API设置健康监控的结构

公共成员

unsigned int version

此结构的版本号，应为dcgmHealthSet_version2

dcgmGpuGrp_t groupId

标识Group的唯一Id

dcgmHealthSystems_t systems

启用系统模块的掩码，使用逻辑或组合的一个值，支持的系统模块请参阅dcgmHealthSystems_t

long long updateInterval

多久检查一次系统模块的健康（以微秒为单位），这应该与调用dcgmHealthCheck接口的频率相同

double maxKeepAge

保留观测系统模块健康的Field数据缓存的时长（以秒为单位），这应该至少与调用dcgmHealthCheck之间的最大时长相等

struct dcgmDiagTestResult_v2

公共成员

dcgmDiagResult_t status

诊断结果

dcgmDiagErrorDetail_t error

如果有错误信息的话，则返回错误信息和错误代码

char info[1024]

如果有信息的话，测试返回的详细信息

struct dcgmDiagTestResult_v3

公共成员

dcgmDiagResult_t status

诊断测试结果

dcgmDiagErrorDetail_v2 error[5]

如果有错误信息的话，则返回错误信息和错误代码

char info[1024]

如果有信息的话，测试返回的详细信息

struct dcgmDiagResponsePerGpu_v3

#include <dcgm_structs.h>

每个GPU响应结构体v3版本

公共成员

unsigned int gpuId

此信息相关的GPU逻辑索引

unsigned int hwDiagnosticReturn

每个GPU硬件诊断测试的返回码

dcgmDiagTestResult_v2 results[9]

每个GPU测试的结果数组

struct dcgmDiagResponsePerGpu_v4

#include <dcgm_structs.h>

每个GPU诊断结果结构V4版本

公共成员

unsigned int gpuId

此信息相关的GPU逻辑索引

unsigned int hwDiagnosticReturn

每个GPU硬件诊断测试的返回码

dcgmDiagTestResult_v2 results[13]

每个GPU测试的结果数组

struct dcgmDiagResponsePerGpu_v5

公共成员

unsigned int gpuId

此信息相关的GPU逻辑索引

unsigned int hwDiagnosticReturn

每个GPU硬件诊断测试的返回码

dcgmDiagTestResult_v3 results[13]

每个GPU测试的结果数组

struct dcgmDiagResponse_v9

#include <dcgm_structs.h>

全局诊断结果结构体v9版本

自MTDCGM 3.3起

公共成员

unsigned int version

结构体版本号(dcgmDiagResult_version)

unsigned int gpuCount

诊断的GPU个数

unsigned int levelOneTestCount

有效的levelOne诊断结果的数量

dcgmDiagTestResult_v3 levelOneResults[3]

levelOne的测试结果

dcgmDiagResponsePerGpu_v5 perGpuResponses[32]

每个GPU的测试结果

dcgmDiagErrorDetail_v2 systemError

从MTVS报告的系统范围错误信息

char devIds[32][5]

每个GPU的SKU设备ID

char devSerials[32][256]

设备的序列号

char dcgmVersion[12]

MTDCGM使用的社区版本号

char driverVersion[256]

驱动版本号

char \mtVersion[12]

MTDCGM版本号

char _unused[584]

预留字段

struct dcgmDiagResponse_v8

#include <dcgm_structs.h>

全局诊断结果结构体v8版本

公共成员

unsigned int version

结构体版本号(dcgmDiagResult_version)

unsigned int gpuCount

诊断的GPU个数

unsigned int levelOneTestCount

levelOne诊断结果的数量

dcgmDiagTestResult_v2 levelOneResults[3]

levelOne诊断的结果

dcgmDiagResponsePerGpu_v4 perGpuResponses[32]

每个GPU的测试结果

dcgmDiagErrorDetail_t systemError

从MTVS报告的系统范围错误信息

char devIds[32][5]

每个GPU的SKU设备ID

char dcgmVersion[12]

MTDCGM社区版本号

char driverVersion[256]

驱动版本号

char \mtVersion[12]

MTDCGM版本号

char _unused[584]

预留

struct dcgmRunDiag_v7

公共成员

unsigned int version

当前结构体的版本号

unsigned int flags

指定运行时的二进制选项。参见DCGM_RUN_FLAGS_*？

unsigned int debugLevel

GPU诊断将用于记录的日志级别，范围为0-5

dcgmGpuGrp_t groupId

要验证的GPU Group的ID，不能与gpuList同时指定

dcgmPolicyValidation_t validate

要运行的测试，范围为0-3，可选

char testNames[20][50]

指定的测试名称列表。可选

char testParms[100][100]

为指定测试设置的诊断参数

格式：testName.parameterName=parameterValue

char fakeGpuList[50]

逗号分隔的假GPU列表，不能与groupId同时指定，当前版本未支持

char gpuList[50]

逗号分隔的GPU列表。不能与groupId同时指定

char debugLogFile[128]

应使用的调试日志文件名称

char statsPath[128]

插件统计文件应写入的路径

char configFileContents[10000]

mtvs配置文件的内容（可能是yaml），当前版本未支持

char throttleMask[50]

要忽略的节流原因，可以是整数掩码或原因的csv列表

char pluginPath[128]

诊断插件的自定义路径 - 从2.2.9社区版起不再支持

unsigned int currentIteration

将要执行的当前迭代次数

unsigned int totalIterations

将要执行的总迭代次数

unsigned int _unusedInt1

预留

char _unusedBuf[128]

预留

unsigned int failCheckInterval

启用时，早停检查失败发生的频率

struct dcgmDeviceTopology_v1

#include <dcgm_structs.h> 设备拓扑信息.

公共成员 unsigned int version dcgmDeviceTopology_version结构体的版本号

unsigned long cpuAffinityMask[8] GPU和CPU亲和性的掩码，1 表示与该 bit 位置对应的 CPU 具有亲和性，最多支持 256 个核心

unsigned int numGpus 表示gpuPaths中，有效的GPU数量

unsigned int gpuId 表示path中的GPU ID

dcgmGpuTopologyLevel_v1_t path 从当前 GPU 到 gpuId 的路径。

注意：这是一个由 DCGM_TOPOLOGY_* 值组成的位掩码；在适用情况下，它可以同时包含 PCIe 拓扑和 MtLink 拓扑。例如：0x210 = DCGM_TOPOLOGY_CPU | DCGM_TOPOLOGY_MTLINK2。可分别使用宏 DCGM_TOPOLOGY_PATH_MTLINK 和 DCGM_TOPOLOGY_PATH_PCI 来屏蔽/提取 MTLink 路径和 PCI 路径

unsigned int localMtLinkIds 表示连接到 gpuId 的本地链路的bit位。 例如：如果该字段等于 3，表示链路 0 和链路 1 已连接。 仅当 GPU 之间实际存在 MTLINK 时，该字段才有效

typedef dcgmDeviceTopology_v1 dcgmDeviceTopology_t;

#define dcgmDeviceTopology_version1 MAKE_DCGM_VERSION(dcgmDeviceTopology_v1, 1)

#define dcgmDeviceTopology_version dcgmDeviceTopology_version1

struct dcgmGroupTopology_v1

#include <dcgm_structs.h> Group组的拓扑信息

公共成员 unsigned int version dcgmGroupTopology_version结构体的版本号

unsigned long groupCpuAffinityMask[8] group中所有GPU和CPU亲和性的掩码，1 表示与该 bit 位置对应的 CPU 具有亲和性，最多支持 256 个核心

unsigned int numaOptimalFlag 值为 0 表示该组中有一个或多个 GPU 具有不同的 CPU 亲和性，因此对于某些算法来说可能不是最优配置

dcgmGpuTopologyLevel_v1_t slowestPath 表示path中的GPU ID

struct dcgmFieldSummaryRequest_v1

公共成员

unsigned int version

结构体dcgmFieldSummaryRequest_v1的版本号

unsigned short fieldId

要汇总的Field ID

dcgm_field_entity_group_t entityGroupId

Entity Group的唯一ID标识

dcgm_field_eid_t entityId

ENtity的唯一ID标识

uint32_t summaryTypeMask

DCGM_SUMMARY_*的位掩码，请求的汇总

uint64_t startTime

要汇总的时间段的开始时间

0表示使用之前的数据

uint64_t endTime

要汇总的时间段的结束时间

0表示使用之后的数据

dcgmSummaryResponse_t response

此请求的响应数据

struct dcgmModuleGetStatusesModule_t

#include <dcgm_structs.h>

Hostengine所有模块的状态

公共成员

dcgmModuleId_t id

此模块的ID

dcgmModuleStatus_t status

此模块的状态

struct dcgmModuleGetStatuses_v1

公共成员

unsigned int version

结构体dcgmModuleGetStatuses_version1的版本号

unsigned int numStatuses

statuses[]中个数

dcgmModuleGetStatusesModule_t statuses[16]

每个模块的状态信息

struct dcgmStartEmbeddedV2Params_v1

#include <dcgm_structs.h>

dcgmStartEmbedded_v2的选项

公共成员

unsigned int version

结构体版本号，使用dcgmStartEmbeddedV2Params_version1

dcgmOperationMode_t opMode

IN: 当用户请求时，指定操作模式，自动或手动收集数据

dcgmHandle_t dcgmHandle

OUT: 用于API调用的MTDCGM句柄

const char *logFile

IN: MTDCGM应记录到的文件，NULL表示不记录，‘-’表示使用stdout

DcgmLoggingSeverity_t severity

IN: MTDCGM应记录到logFile的日志等级

unsigned int denyListCount

IN: denyList[]中的模块个数

denyList[10]

IN：存储黑名单的模块ID

struct dcgmStartEmbeddedV2Params_v2

#include <dcgm_structs.h>

dcgmStartEmbeddedV2Params_v2的选项

在MTDCGM社区版的 2.4.0中添加，3.0.0中重命名成员

公共成员

unsigned int version

结构体版本号，使用dcgmStartEmbeddedV2Params_version2

dcgmOperationMode_t opMode

IN: 当用户请求时，指定操作模式，自动或手动收集数据

dcgmHandle_t dcgmHandle

OUT: 用于API调用的MTDCGM句柄

const char *logFile

IN: MTDCGM应记录到的文件，NULL表示不记录，‘-’表示使用stdout

DcgmLoggingSeverity_t severity

IN: MTDCGM应记录到logFile的日志等级

unsigned int denyListCount

IN: 应添加到黑名单中的模块个数

const char *serviceAccount

IN: 未特权进程的服务帐户

unsigned int denyList[10]

IN: 应添加到黑名单的模块ID

struct dcgmSettingsSetLoggingSeverity_v1

#include <dcgm_structs.h>

dcgmSettingsSetLoggingSeverity_t的v1版本

公共成员

targetLogger

目标logger对象

targetSeverity

目标日志等级

struct dcgmVersionInfo_v2

#include <dcgm_structs.h>

用于描述MTDCGM编译版本信息的v2版本

公共成员

version

结构体的版本号

char rawBuildInfoString[256 * 2]

MTDCGM编译信息的原始数据

可能有多个key-value键值对，由分号(;)分隔

每个对都由冒号字符(:)分隔。只考虑第一个冒号作为分隔符

值可以包含冒号字符，值和键不能包含分号字符

Key通常定义为：

• version: MTDCGM版本号
• arch: 目标MTDCGM架构
• buildid: 构建ID，通常是一个连续的数字
• commit: 提交ID（通常是git提交hash）
• author: 上述提交的作者
• branch: 分支（通常用于构建的git分支）
• buildtype: 构建类型
• builddate: 构建日期
• buildplatform: 构建的平台

注意：

Key值可能缺失

这些值仅作为参考，不应用于复杂的逻辑