1. 概述

mx-smi（MetaX System Management Interface）是用于管理曦云® 系列GPU的命令行工具，可以实时查询GPU的信息，包括版本，温度，使用率，功耗，时钟频率等，并具有启用和禁用GPU配置选项，执行固件升降级等功能。

2. 安装及使用方法

2.1. 安装包安装与卸载

2.1.1. 安装

曦云系列GPU驱动包安装过程中会默认安装mx-smi工具。驱动包安装完成后，mx-smi工具放置在 /opt/mxdriver/bin/ 目录下，并会在 /usr/bin 目录下创建软链接。

2.1.2. 卸载

曦云系列GPU的驱动卸载后，mx-smi工具会自动卸载。驱动卸载参见《曦云® 系列通用计算GPU驱动安装指南》。

2.2. 在容器中使用

若需在容器中使用mx-smi，可在运行容器时传入以下参数：

docker run -v --device=/dev/dri -v /opt/mxdriver/bin/mx-smi:/opt/mxdriver/bin/mx-smi <image ID>

其中 --device=/dev/dri 将主机上的沐曦设备挂载到容器， -v /opt/mxdriver/bin/mx-smi:/opt/mxdriver/bin/mx-smi 将mx-smi工具挂载到容器。

以上方式仅可在容器中用 /opt/mxdriver/bin/mx-smi 执行一些查询类的命令，如需执行设置类的命令，需在启动容器时添加 --privileged=true。

2.3. 使用方法

mx-smi是一个Linux命令行工具，其调用遵守如下格式。

mx-smi [选项1 [参数1]] [参数2] …

2.4. 命令补全使用方法

驱动包安装后， /opt/mxdriver/share/mxsmi/mxsmi_completion.sh 为mx-smi命令补全脚本，可以实现mx-smi命令自动补全。

需确保系统已安装bash-completion包，以Ubuntu为例，执行以下命令安装：

dpkg -i bash-completion

若为当前用户临时使用：

source /opt/mxdriver/share/mxsmi/mxsmi_completion.sh

若对所有用户生效（需sudo权限），复制脚本到 /etc/bash_completion.d/ 目录并重新登录：

cp /opt/mxdriver/share/mxsmi/mxsmi_completion.sh /etc/bash_completion.d/

3. 命令介绍

mx-smi命令说明，可以通过在工作环境中执行 man mx-smi 获取。

3.1. 通用选项

-h, --help

打印使用帮助信息。

-v, --version

打印mx-smi的版本信息。

3.2. 归纳选项

./mx-smi （直接回车）

mx-smi命令不添加任何选项和参数，默认归纳并显示板卡的主要信息，显示信息包括功耗，内存，温度，版本，使用率，进程等。

3.3. 查询选项

--show-temperature

显示板卡上温度传感器读取的温度，单位是摄氏度。

--show-version

显示BIOS，驱动和Firmware的版本信息。

--show-hbm-bandwidth

显示显存的动态带宽信息。

--show-pcie-bandwidth

显示PCIe动态带宽信息。

--show-usage

显示GPU、VPU的使用率。使用率反应过去一段采样周期内硬件资源的使用情况。

--show-memory

显示存储资源的使用情况，包括板卡显存和板卡可以访问的系统内存。

--show-board-power

显示板卡当前的电压，电流和功耗信息。

--show-pmbus-power

显示芯片内的电压，电流和功耗信息。

--show-eeprom

显示EEPROM记录的信息，包括板卡版本，板卡序列号等。

--show-clocks all

显示板卡的时钟信息。

--show-dpm cur

显示当前的performance level设置。

--show-dpm all

显示支持的performance level及其对应的时钟和电压信息，为设置performance level做参考。

--show-dpm-max

显示支持的performance level的最高级别。

--show-pcie

显示PCIe当前及最大带宽和速率。

--show-sn

显示板卡序列号。

--show-process

显示当前运行的进程信息。

--show-power-mode

显示板卡的电源模式，未用 -i 指定板卡时，默认显示所有板卡的电源模式信息。

--show-event <aer_ue|aer_ce|synfld|dbe|mmio|all>

显示KMD关键事件信息，可指定显示相应pci错误类型或全部类型的关键事件信息，包括大小，次数，第一次发生时间，事件内容等。 未用 -i 指定板卡时，默认显示所有板卡的关键事件信息。详细信息参见表 1。

表 1 KMD关键事件信息

事件类型

说明

aer_ue

PCIe AER uncorrectable error，仅PF模式支持查询。

aer_ce

PCIe AER correctable error，仅PF模式支持查询。

synfld

PCIe syncflood error，仅PF模式支持查询，且曦云系列独有。

dbe

PCI device base error，仅PF模式支持查询。

mmio

PCI mmio invalid（disconnected），PF与VF模式均支持查询。

 
--show-clk-tr

显示板卡降频原因信息。 Active 表示对应项为降频原因；全为 Not Active 表示当前未降频。未用 -i 指定板卡时，默认显示所有板卡的降频原因信息。

--show-unavailable-reason

当使用 mx-smi -L 命令查看设备状态为not available时，可用以上命令查看具体不可用原因以及参考建议。

-i ID, --index ID

显示指定板卡的信息。如果没有指定，默认显示全部板卡的信息。 ID 是从0开始的自然数，可以通过 -L ， --list 获取板卡的ID信息。可指定一个或多个 ID ，多个ID用“,”分隔，如“0,1,5”，“0-2”，“0-4,6”，“all”等。

-o, fileName, --output fileName

可以将命令输出写入csv格式的文件中，支持显示的命令有：

  • --show-temperature

  • --show-board-power

  • --show-version

  • --show-usage

  • --show-memory

  • --show-pcie

  • --show-dpm cur

  • --show-pmbus-power

  • --show-vpu

-l ms, --loop ms

以特定的间隔周期持续显示板卡信息，单位是毫秒。执行 Ctrl+C 可退出持续查询。

示例 ：

以500ms周期持续显示所有卡的温度，功耗，使用率信息：

mx-smi --show-temperature --show-board-power --show-usage -l 500

以1s周期将GPU0 - GPU3的温度，功耗，使用率信息写文件：

mx-smi --show-temperature --show-board-power --show-usage -i 0-3 -l 1000 -o sample.csv

3.4. 控制选项

-u, --vbios-upgrade <vbios bin file>

默认对所有板卡进行BIOS固件升级。需要Root权限。在执行完固件升级命令后，需要对系统进行reboot或者warm reset以使新固件生效。

-r, --reset

对指定的卡执行warm reset。必须使用 -i ID , --index ID 选项以指定一个特定的板卡。 需要Root权限。如果warm reset失败（设备无法恢复），需要重启服务器，对同一组使用MetaXLink连接的卡，只需做一次warm reset，详情参见《曦云® 系列通用计算GPU Warm Reset使用指南》。

备注

warm reset功能目前仅在H3C UniServer R5300 G6服务器型号中经过验证，在未经验证的机型中使用warm reset功能可能会导致功能失效等不可预期的结果。

--set-power-mode <mode>

用 -i 指定板卡进行电源模式设置， 0 为 Normal， 1 为 High。

--set-dpm-max <IP,DpmLevel>

对指定的IP设置max performance level。必须使用 -i ID, --index ID 选项以指定一个特定的板卡。需要Root权限。

例如，执行以下命令，将板卡1的 xcore 模块的max performance level有效配置设置成level7：

mx-smi –set-dpm-max xcore,7 -i 1

3.5. RAS选项

mx-smi ras子命令用于显示与芯片可靠性，可用性，安全性相关的信息。

可显示IP的错误统计。例如，执行以下命令，显示板卡0相关的corrected error和uncorrected error统计数目：

mx-smi ras --show-count -i 0

可显示IP的错误状态。例如，执行以下命令，显示板卡0相关的错误状态：

mx-smi ras --show-status -i 0

3.6. 查询拓扑关系

mx-smi topo子命令用于查询主机上曦云GPU设备之间的拓扑关系。

-m, --matrix

显示曦云GPU设备之间的连接方式，以及CPU亲和性、NUMA node亲和性等信息。

-d, --distance

显示曦云GPU设备之间连接的相对距离信息。

-t, --tree

显示曦云GPU设备拓扑树。

-n, --nic

显示曦云GPU设备与网卡之间的连接方式。

--show-mxlk

显示曦云GPU设备之间MetaXLink带宽和速率。（N260系列不支持）

--show-mxlk-peer

显示通过MetaXLink与曦云GPU设备相连的设备信息。（N260系列不支持）

--show-mxlk-state

显示曦云GPU设备之间MetaXLink连接的状态（启用/禁用）和各端口的状态（ up/down ）。（N260系列不支持）

--set-mxlk-state <0|1>

启用/禁用MetaXLink连接，用于恢复因训练失败等导致端口状态为 down 的情况。操作为先禁用（ 0 ）再启用（ 1 ）。（N260系列不支持）

3.7. VM虚拟化管理

mx-smi vm子命令用于GPU卡虚拟化管理。注意：此命令仅支持在物理机中操作。

--enable-vf <1|2|4|8>

开启虚拟化，一张GPU卡可支持虚拟化的个数为1，2，4，8。

--disable-vf

关闭虚拟化功能。

--show-vf

显示虚拟化后的GPU信息。

3.8. 光模块信息（当前仅适用于C500X）

mx-smi om子命令用于显示光模块信息。

--show-status

显示光模块电压，温度，模块状态，通道状态及接收状态信息。

--show-info

显示光模块固件信息。

--show-rx-status

显示光模块接收的详细信息。

3.9. 轮询设备状态信息

mx-smi dmon子命令用于轮询显示设备状态信息，包括温度，功耗，VPUE，VPUD和GPU使用率，板卡显存及内存；时间间隔默认为1000ms。执行 Ctrl+C 可退出轮询。

例如，执行以下命令，可轮询100次板卡0的温度及功耗信息：

mx-smi dmon --show-temperature --show-board-power -i 0 -c 100

3.10. 强刷固件

仅当满足以下条件时可强刷固件：

  • 使用 mx-smi -L 命令查看设备状态为not available。

  • 无法通过《曦云® 系列通用计算GPU驱动安装指南》中“更新固件”章节方法来更新固件，即 mx-smi -u mxvbios-xxx.bin 及 mx-smi -U mxvbios-xxx.bin -i <ID> 均无法升级固件。

执行以下命令指定板卡强刷固件。注意，更新固件后需重启生效。

mx-smi --force-vbios-flash xxx.bin -i ID

3.11. sGPU切分选项

为了资源粒度可以灵活配置，sGPU（sliced GPU）功能可实现将一个父设备（物理设备）切分为多个子设备（sGPU），每个父设备最多可创建16个子设备（若按照默认配置显存 4GB,算力为父设备的5%创建，则由于显存大小的限制，无法创建出第16个子设备）。

注意：仅可在非虚拟化模式下使用sGPU功能。虚拟化模式暂不支持此功能。

sgpu -h

查看sGPU使用帮助信息。

sgpu --enable -i GPU-ID

启用设备sGPU功能，须用 -i 指定设备（需sudo权限）。默认为禁用。

sgpu --show-mode

查看设备sGPU功能是否启用，可用 -i 指定设备。

sgpu --disable

禁用设备sGPU功能，须用 -i 指定设备（需sudo权限），当子设备正在被使用时，则无法禁用sGPU功能。

sgpu -i GPU-ID --create

新建指定父设备的子设备，须用 -i 指定父设备。默认创建一个显存为4 GB，算力为父设备 5%的子设备，不创建别名。 若需创建多个可用 -n 传入数量；可用 --vram xxx --compute xxx --alias xxx 指定创建的子设备的显存大小、算力占比、别名等。具体资源设置方法参见表 2。

表 2 创建子设备时资源设置项说明

可设置项

说明

–vram

分配给子设备的显存，粒度为1M。例如，可设置为128M、8G或5%

–compute

分配给子设备的父设备算力百分比，粒度为1%，单位为%，例如，可设置为22

–alias

分配给子设备的别名，最大长度为31字节，超出部分会被截断

 
sgpu -i GPU-ID --set SGPU-ID --vram xxx --compute xxx --alias xxx

修改已建子设备的显存配额，算力配额及别名。

sgpu

可查看所有父设备下的子设备信息，包括父设备编号、时间片大小、调度策略、子设备 SGPU-ID 、 MinorID 、优先级、显存配额、算力配额以及别名等。可用 -i 指定父设备查看该父设备下所有子设备的信息。

sgpu --show-remain

查看父设备剩余可分配额度，可用 -i 指定父设备。

sgpu --show-usage

查看子设备使用率，可用 -i 仅指定父设备或用 -i 及 -s 指定父设备及子设备。

sgpu --show-memory

查看子设备显存使用情况，可用 -i 仅指定父设备或用 -i 及 -s 指定父设备及子设备。

sgpu --show-timeslice

查看父设备时间片大小，可用 -i 指定父设备。默认为10ms。

sgpu --set-timeslice xx -i GPU-ID

设置父设备时间片大小，单位为ms，须用 -i 指定父设备。

sgpu --show-schedclass

查看调度策略，可用 -i 指定父设备。

表 3 子设备调度策略说明

调度类型

说明

0：（Best Effort）争抢模式

默认调度策略。各子设备不限算力，父设备上有剩余算力即可使用

1：（Fixed Share）固定配额

各子设备有固定的算力配额，无法超过固定配额使用

2：（Burst Share）保证配额加弹性

各子设备有固定的算力配额，父设备上还有空闲算力可被使用

 
sgpu --set-sched-class [0-2] -i GPU-ID

设置调度策略（需sudo权限），须用 -i 指定设备。

sgpu --remove SGPU-ID -i GPU-ID

移除指定父设备的指定子设备（需sudo权限），须用 -i 指定设备。当子设备正在被使用时，则无法关闭sGPU功能。

4. MXSML使用说明

4.1. 简介

MXSML（MetaX System Management Library）是一套C API程序开发库。应用程序使用这套开发库，可以方便地对沐曦的设备进行状态查询和管理。MXSML提供的API可以被使用C/C++/PYTHON/GO等语言开发的程序使用。

4.2. 安装

MXSML动态链接库是随Driver软件包一起发布，同时在MXMACA SDK包中会包含头文件，stub库，示例代码，Python bindings等文件。

Driver软件包的安装参见《曦云® 系列通用计算GPU驱动安装指南》中“安装驱动”章节。Driver软件包安装后，MXSML动态链接库位于/opt/mxdriver/lib/libmxsml.so。

MXMACA SDK包的安装参见《曦云® 系列通用计算GPU快速上手指南》。SDK安装后的文件列表参见表 4。

表 4 MXSML安装文件列表

文件

说明

/opt/maca/include/mxsml/MxSml.h

MXSML头文件

/opt/maca/include/mxsml/MxSmlExtension.h

MXSML扩展头文件

/opt/maca/include/mxsml/mxsmlBindings.py

MXSML Python bindings

/opt/maca/lib/stub/libmxsml.so

MXSML stub库

/opt/maca/share/mxsml/pymxsml-xxx.whl

Pymxsml安装包

/opt/maca/share/mxsml/mxsmlDemo.c

C示例程序

/opt/maca/share/mxsml/mxsml_demo.py

Python示例程序

/opt/maca/share/mxsml/mxsmlDemo.go

Go示例程序

4.3. 编程指南

用C语言调用MXSML API读取所有卡的信息，示例如下：

 #include <stdio.h>
 #include "MxSml.h"

int main()
{
     // 调用任何MXSML API前都需要先调用mxSmlInit完成初始化
     mxSmlReturn_t ret = mxSmlInit();

     if(ret != MXSML_Success)
     {
         // 可通过mxSmlGetErrorString将错误号转换为错误信息
         printf("mxSmlInit failed: %u, %s\n", ret, mxSmlGetErrorString(ret));

         return 1;
     }

     // 获取可用设备总数，设备ID从0开始依次编号：0,1,2…deviceNum-1
     int deviceNum = mxSmlGetDeviceCount();
     for(int i = 0; i < deviceNum; i++)
     {
         mxSmlDeviceInfo_t deviceInfo;
         if(mxSmlGetDeviceInfo(i, &deviceInfo) == MXSML_Success)
         {
             printf("device id %d, bdf id: %s, type: %s\n", i, deviceInfo.bdfId, deviceInfo.deviceName);
         }
     }

     return 0;
 }

使用以下命令完成编译：

gcc example.c -I/opt/maca/include/mxsml -L/opt/maca/lib/stub -lmxsml -o example

运行example：

export LD_LIBRARY_PATH=/opt/mxdriver/lib:$ LD_LIBRARY_PATH
./example

5. Pymxsml使用说明

5.1. 简介

Pymxsml是基于MXSML封装的一套Python API程序开发库。使用这套开发库，可以方便地对沐曦GPU设备进行状态查询和管理。

5.2. 安装

操作步骤

  1. Pymxsml依赖MXSML动态链接库，确保驱动包已安装，相关信息参见 4.2 安装。

  2. Pymxsml以wheel包形式随MXMACA SDK包一起发布。MXMACA SDK包安装后，Pymxsml wheel包位于 /opt/maca/share/mxsml/pymxsml-*.whl。

  3. 确保系统已安装Python 3，使用以下命令安装Pymxsml wheel包。

pip3 install /opt/maca/share/mxsml/pymxsml-*.whl

5.3. 编程指南

用Python语言导入Pymxsml模块读取所有卡的信息，示例如下：

from pymxsml import *

# 调用任何Pymxsml API前都需要先调用mxSmlInit完成初始化
# 接口调用失败，会产生对应的python异常
mxSmlInit()

# 获取可用设备总数，设备ID从0开始依次编号：0,1,2…deviceNum-1
device_num = mxSmlGetDeviceCount()
for i in range(device_num):
    device_info = mxSmlGetDeviceInfo(i)
    print("device id", i, ", bdf id:", device_info.bdfId, ", type:", device_info.deviceName)

运行example：

python3 example.py

6. 附录

6.1. 术语/缩略语

术语/缩略语

全称

描述

RAS

Reliability, Availability, Serviceability

VM

Virtual Management

虚拟化管理