2. 安装与维护

若无特殊说明，本章以曦云C500为例。

2.1. 用户须知

2.1.1. 支持的GPU系列

目前已支持的GPU系列主要规格参数，参见表 2.1。

表 2.1 GPU系列支持列表

GPU系列

MXMACA版本

VF数量

sGPU

ATS

MXC500系列

>= 2.23.0.23

1/2/4/8（仅C588和X206支持VF=8）

支持 （MXMACA >= 2.32.0.x）

支持 （MXMACA >= 2.25.2.9）

MXC600系列

>= 3.2.0.0

1/2/4

支持

支持

2.1.2. 系统支持范围

目前已支持的CPU架构和内核版本，参见表 2.2。

表 2.2 软硬件平台兼容列表

CPU架构

操作系统

内核版本

状态

x86_64

Ubuntu 18.04

5.4.0-42-generic

支持

5.4.0-131-generic

x86_64

Ubuntu 20.04

5.4.0-144-generic

支持

5.15.0-58-generic

x86_64

Ubuntu 22.04

5.15.0-72-generic

支持

5.15.0-112-generic

x86_64

Ubuntu 24.04

6.14.0-27-generic

支持

x86_64

CentOS 8

4.18.0-240.el8.x86_64

支持

x86_64

CentOS 7

4.19.0-1.el7.elrepo.x86_64

支持加载Docker Container形式

5.14.0

x86_64

BCLinux R8 U2

4.19.0-240.23.11.el8_2.bclinux.x86_64

支持

x86_64

CC Linux

5.15.131-2.cl9.x86_64

支持

x86_64

kylinv11

6.6.0-32.7.v2505.ky11.x86_64

支持

x86_64

ALinux3

5.10.134-13.1.al8.x86_64

支持

x86_64

CTYun 23.01

5.10.0-136.12.0.86.ctl3.x86_64

支持

x86_64

KeyarchOS 5.8

4.18.0-477.27.1.3.kos5.x86_64

支持

x86_64

RockyOS 9.2

5.14.0-284.11.1.el9_2.x86_64

支持

x86_64

Debian 10

5.10.0-0.deb10.28-amd64

支持

x86_64

TencentOS 3.1

5.4.119-19.0009.54

支持

x86_64

TencentOS 3.1

5.4.119-19.0009.44

支持

x86_64

TencentOS 3.3

5.4.241-24.0017.23

支持

x86_64

TencentOS 4.4

6.6.92-34.1.t14.x86_64

支持

x86_64

CULinux-3.0

5.10.0-60.67.0.116.ule3.x86_64

支持

x86_64

CULinux-4.0

6.6.0-72.0.0.95.ule.x86_64

支持

x86_64

RHEL 9.6

5.14.0-570.12.1.el9_6

支持

x86_64

RHEL 9.6

5.14.0-570.54.1.el9_6

支持

x86_64

RHEL 9.4

5.14.0-427.13.1.el9_4

支持

x86_64

RHEL 9.4

5.14.0-427.96.1.el9_4

支持

aarch64

KylinV10

5.15.0-1.10.6.v2307.ky10h.aarch64

支持

aarch64

kylinv11

6.6.0-32.0.v2025.ky11.aarch64

支持

2.1.3. 安装包说明

沐曦通用GPU所提供的驱动安装包通过run安装文件发布。以Ubuntu系统为例，Driver软件包所包含的内容参见表 2.3。

表 2.3 Driver软件包内容清单

文件名

说明

metax-linux_x.x.x-xxx_amd64.deb

沐曦通用GPU KMD驱动、工具及相关配置文件

metax-rdma_x.x.x-xxx.amd64.deb

RDMA驱动安装源码包（兼容OFED）

mxgvm_x.x.x-xxx_amd64.deb

沐曦通用GPU Virtualization Manager、工具及相关配置文件

mxfw_x.x.x.x.all.deb

沐曦通用GPU固件包

mxsmt_x.x.x.x.amd64.deb

mx-smi系统管理工具，MXSML系统管理库

2.2. 物理机上安装驱动和固件

在安装了Linux系统的物理机上，驱动和固件的安装流程如图 2.1 所示。

../_images/image1.png

图 2.1 软件包安装流程

备注

  • 首次安装场景：服务器上从未安装过驱动，板卡出厂时默认已安装好固件。

  • 覆盖安装场景：服务器上安装过驱动且未卸载，当前要再次安装驱动。

2.2.1. 确认服务器架构，操作系统和内核版本

../_images/image2.png

图 2.2 确认服务器架构，操作系统和内核版本

操作步骤

  1. 执行以下命令，查询服务器CPU架构，操作系统和内核版本。

    uname -m && uname -r && lsb_release -a

  2. 对照表 2.2 软硬件平台兼容列表，确认CPU架构，操作系统以及内核版本是否在列表中。若CPU架构不匹配，需按照列表升级硬件系统。

2.2.2. 创建运行用户

运行用户是软件包安装完成后，使用沐曦通用GPU的终端用户。安装用户是配置环境，安装软件包的用户，必须有sudo权限，一般为服务器管理员。

运行用户可以为root用户或者非root用户。如果服务器管理员对运行用户有用户权限控制或多用户隔离的需求，可创建非root用户作为运行用户。 将运行用户加入video组即可将其创建为非root用户（udev规则配置文件默认将沐曦通用GPU使用权限归属于video组内）。

操作步骤

例如，创建运行用户user并将其创建为非root用户。

  1. 创建运行用户。

    sudo adduser [user]

  2. 将运行用户加入video组。

    sudo usermod -a -G video [user]

备注

（可选）沐曦驱动安装包也支持自定义用户组和自定义权限。

比如指定用户组为 root，权限为0666，安装run文件时添加以下参数：

sudo bash ./metax-driver-xxx.run -- -G root -P 0666

自定义用户组和权限后，需要将运行用户添加到对应的用户组，确保运行用户能正常访问GPU。

2.2.3. 安装驱动

2.2.3.1. 安装环境确认

系统兼容性要求

  • 若沐曦通用GPU无法识别为PCIe设备（可通过 lspci | grep 9999 进行查看），需关闭BIOS里兼容性支持模块（CSM）选项。

  • 若PCIe BAR需要支持4GB以上地址空间，需打开BIOS里Large Bar选项。

  • 每张沐曦通用GPU板卡需要三个BAR，空间大小（以C500为例）分别为1 MB，8 MB和64 GB。

环境检查
表 2.4 环境检查（如无特别说明，以Ubuntu 22.04为例）

序号

检查项目

检查命令

说明

1

服务器CPU架构

uname -m

对照表 2.2 软硬件平台兼容列表，确认CPU架构，操作系统和内核版本是否在列表中。若CPU架构不匹配，则需更新硬件环境。详细信息参见 2.2.1 确认服务器架构，操作系统和内核版本。

2

操作系统

lsb_release -a

3

内核版本

uname -r

4

系统是否安装过驱动

lsmod | grep metax

  • 若无内容显示，则表示未安装过软件包。可以直接安装软件包。

  • 若有内容显示，则表示安装过软件包。需要先卸载驱动包，再安装新版本软件包。

    卸载驱动包，请参见 2.2.5 卸载驱动

5

板卡是否正常在位

（以曦云C500为例）

lspci | grep 9999

如果服务器上有N（N>0）张曦云C500板卡，回显中含 9999 字段的行数为N时，则表示曦云C500板卡正常在位。

例如，若服务器上有2张板卡且都正常在位，则回显信息如下所示：

01:00.0 Display controller: Device 9999:4001 (rev 01)

02:00.0 Display controller: Device 9999:4001 (rev 01)

6

udev配置

cat /etc/udev/rules.d/70-metax.rules

  • 若有群组管理需要，

    • 只允许video组的成员使用沐曦通用GPU，则配置文件有如下内容：

      KERNEL=="mxcd", GROUP="video", MODE="0660"

      KERNEL=="renderD[0-9]*", GROUP="video", MODE="0660"

    • 若没有以上内容，则表示只有root用户可以使用沐曦通用GPU。

  • 若无群组管理需要，可删除此配置文件。（deb包安装会自动创建此配置文件。）

7

MMIO空间

lspci -d9999: -v

确保每张GPU卡输出的 Memory at 字段都是有效值（非0）。

当系统有多张物理沐曦通用GPU板卡，或者有支持SRIOV功能的沐曦通用GPU板卡（需要分配额外的PCI BAR空间给VF）时，需要很大的PCI BAR空间，如果系统无法分配地址空间，对应的设备将无法正常工作。

8

IOMMU配置

vim /etc/default/grub

在透传场景下，需要使能IOMMU，如果想只让透传的PCI设备使用IOMMU，而宿主机其他设备绕过IOMMU，可以按如下步骤配置：

  1. 在 GRUB_CMDLINE_LINUX="" 里面添加 iommu.passthrough=1

  2. 更新GRUB菜单

  • Ubuntu上执行 sudo update-grub

  • CentOS上执行 sudo grub2-mkconfig -o /boot/efi/EFI/centos/grub.cfg

  1. 重启系统，查看 /proc/cmdline，确保改动生效

9

是否允许第三方驱动加载

（仅适用于SLES-15系统）

modprobe metax

对于SLES-15系统，如在加载metax驱动时提示 module metax is unsupported，则需使用 modprobe metax --allow-unsupported 命令加载。

如需开机自动加载metax驱动，则需添加/etc/modprobe.d/10-unsupported-modules.conf文件，并在该文件中填写 allow_unsupported_modules 1

2.2.3.2. 驱动文件安装

操作步骤

  1. 将驱动的run安装文件下载到目标机器上，进入文件所在目录，执行以下命令安装驱动：

    sudo bash ./metax-driver-x.x.x.x-deb-x86_64.run -- -f

    备注

    • 若VBIOS固件和驱动版本不兼容，安装 metax-linux/mxgvm 包时会出现如下回显信息：

      Notice: Please upgrade vbios first, otherwise normal business functions will not be supported

      此时驱动只提供升级VBIOS的功能，不支持正常的业务功能，请根据 2.2.4 更新固件升级VBIOS。

    • 驱动默认支持省电模式，空闲状态时GPU会进入低功耗，低功耗下GPU卡的PCIe link speed会降低到gen1（2.5GT/s）。如果用户不希望进入省电模式，可以通过下面两种方式进行关闭：

      • 通过修改模块参数重新加载驱动，手动临时关闭省电模式，该方式重启后不生效：

        sudo rmmod metax
sudo modprobe metax runpm=0

      • 通过增加配置文件方式永久生效，首次配置后需要重启生效：

        echo "options metax runpm=0" > /etc/modprobe.d/metax.conf

      • 如果软件平台不兼容，会自动进行源码编译安装，但可能存在无法编译和功能无法使用问题。

    默认情况下，驱动会自动识别GPU互连拓扑类型，以下拓扑类型需要在安装驱动时手动指定。

    • MXC500系列：

      sudo bash ./metax-driver-x.x.x.x-deb-x86_64.run -- -f -p topo_df=$topo_type

      其中，拓扑类型 $topo_type 定义参见表 2.5。

      表 2.5 MXC500系列拓扑配置参数

      拓扑类型

      说明

      1

      C550X-DF16CubeDC-32

    • MXC600系列：

      MXC600系列GPU内置了一个ETH端口，该端口支持P2P（类似MetaXLink点对点直连）和RDMA（接入RoCE交换机）两种模式二选一。

      默认情况下ETH端口不会使能，如果要使用，需要结合实际的物理拓扑类型，在安装驱动时手动指定ETH模式。

      • ETH P2P模式

        安装参数如下：

        sudo bash ./metax-driver-x.x.x.x-deb-x86_64.run -- -f -p topo_type=$topo_type

        其中，拓扑类型 $topo_type 用于指定ETH工作在P2P模式，定义参见表 2.6。

        表 2.6 MXC600系列ETH P2P模式拓扑配置参数

        拓扑类型

        说明

        5

        PCIe N300和X301 MetaXLink互连，ETH工作在P2P模式

        17

        OAM C600和X302 MetaXLink互连，ETH工作在P2P模式

      • ETH RDMA模式

        该模式仅支持RDMA RoCEv2功能，使用的前提条件如下：

        • 必须连接RoCE交换机

        • 必须先安装依赖的DOCA-OFED驱动，再安装MetaX的run安装文件

        目前适配的平台参见表 2.7。

        表 2.7 MXC600系列ETH RDMA模式硬件平台和操作系统支持列表

        CPU架构

        操作系统

        DOCA-OFED 版本

        状态

        x86_64

        Ubuntu 22.04

        3.1.0

        支持

        x86_64

        Kylin V11

        3.1.0，3.2.0

        支持

        安装参数如下：

        sudo bash ./metax-driver-x.x.x.x-deb-x86_64.run -- -f -m rdma

        其中，参数 -m rdma 指定ETH工作在RDMA模式，定义参见表 2.8。

        表 2.8 MXC600系列ETH RDMA模式配置参数

        安装模式

        说明

        rdma

        ETH工作在RDMA模式，编译并安装RDMA驱动

  2. （可选）对于RHEL/CentOS/Rocky Linux及其延伸版本（ALINUX3等），在安装完驱动后需要执行以下命令，将驱动集成到initramfs中，以确保驱动的加载顺序：

    sudo dracut -f

  3. 重启服务器。

    sudo reboot

  4. 执行以下命令，查询驱动安装信息。

    lsmod | grep metax

    备注

    若grep后没有输出，则请根据 2.2.1 确认服务器架构，操作系统和内核版本 重新确认安装环境和步骤。

  5. 定义环境变量并执行以下命令，若回显信息列出所有沐曦通用GPU的信息，则metax驱动工作正常。

    mx-smi

2.2.4. 更新固件

沐曦通用GPU采用沐曦带内管理工具mx-smi对固件进行升级。mx-smi工具自动安装在驱动安装包的 /opt/mxdriver/bin 目录下。关于mx-smi工具，参见《沐曦通用GPU mx-smi使用手册》。

驱动安装时，会将所支持GPU系列的固件分别安装到 /lib/firmware/metax/$chip_type 目录下， chip_type 具体定义参见表 2.9。

表 2.9 固件安装路径说明

GPU系列

chip_type

示例

MXC500系列

mxc500

例如，MXC500系列的固件安装路径为 /lib/firmware/metax/mxc500

MXC600系列

mxc600

操作步骤

  1. 确认已经成功加载设备内核驱动。详细内容请参见 2.2.3 安装驱动。

  2. 检查更新的VBIOS固件文件 mxvbios-xxx.bin 已安装到Linux的 /lib/firmware/metax/$chip_type 目录下。

    备注

    • 若需要使用SRIOV功能，应安装带 -VF 后缀的VBIOS固件文件，例如 mxvbios-1.4.0.0-200-C500-VF.bin。

    • 带 -ATS 后缀的VBIOS固件文件，例如 mxvbios-1.4.0.0-200-C500-ATS.bin，仅适用于受支持的特定场景，若您不清楚此文件的具体用途或操作流程，请勿尝试安装、刷写或操作此文件，否则可能导致非预期行为。如您确有PCIe ATS相关的功能需求，请联系沐曦FAE团队获取指导。

    • 除 -VF 和 -ATS 以外的其他后缀，包括但不限于 -E/-P/-PL，均为产品型号的组成部分。

  3. 确保板卡所有任务已经停止。如果有任务在进行中，需要停止其进程。

  4. 使用mx-smi工具执行以下命令，升级VBIOS固件（需要Root权限）。

    sudo mx-smi -u /lib/firmware/metax/$chip_type/mxvbios-xxx.bin -t 600

    默认对所有板卡进行升级。若屏幕显示以下信息，则表示固件下载成功。

    vbios-upgrade Done

    若上述升级VBIOS固件中出现 Bar0Size mismatch 字样，使用以下命令升级（需要Root权限）。

    sudo mx-smi -U /lib/firmware/metax/$chip_type/mxvbios-xxx.bin -t 600 -i ID

    ID 是板卡序列号，可以通过 mx-smi -L 查询获取相应板卡的ID。

  5. 重启服务器，以使更新的固件生效。

  6. 重启成功并加载驱动后，用mx-smi工具执行以下命令查询VBIOS固件版本。若与目标版本一致，说明升级安装成功。以曦云C500为例，VBIOS固件版本如下图所示。

    mx-smi --show-version
    ../_images/image3.png

    图 2.3 VBIOS固件版本

2.2.4.1. VBIOS升级开关（可选）

沐曦通用GPU支持VBIOS升级开关功能，用于限制在容器和虚拟机里升级VBIOS。使用步骤如下：

  1. 在宿主机上查看升级开关状态，命令及输出如下：

    sudo mx-smi misc --show-update-toggle
mx-smi  version: 2.3.1

=================== MetaX System Management Interface Log ===================
Timestamp                                         : Fri Mar 20 14:03:09 2026

Attached GPUs                                     : 1
GPU#0  MXC500  0000:0a:00.0
   Vbios update toggle
      state                                     : Enable

End of Log

    • state 为 Enable 表示升级开关打开，可以进行固件更新。

    • state 为 Disable 表示升级开关关闭，无法进行固件更新。

  2. 若要禁止在容器和虚拟机里更新固件，则在宿主机上关闭升级开关，命令如下：

    sudo mx-smi misc --set-update-toggle 0

    命令执行成功后，无论在宿主机、容器还是虚拟机里升级固件时会报错：

    sudo mx-smi -U /lib/firmware/metax/mxc500/mxvbios-1.33.1.0-1113-C500-VF.bin -i 0
mx-smi version: 2.3.1
GPU#0 vbios-upgrade Ioctl failed: Not Support

  3. 若要更新固件，则要在宿主机上打开升级开关，命令如下：

    sudo mx-smi misc --set-update-toggle 1

备注

  • 上述跟升级开关相关的命令只能在宿主机或拥有 CAP_SYS_ADMIN 权限的特权容器上执行，在普通容器或虚拟机无权限执行。

  • 当升级开关关闭时，在PF透传场景升级固件，需要先在宿主机上根据 2.2.3 安装驱动安装驱动，打开升级开关，更新固件，关闭升级开关。

  • 升级开关配置是永久生效的，即使设备掉电重启也会保留。

VBIOS升级开关对MXMACA和VBIOS版本都有依赖，见表 2.10。

表 2.10 VBIOS升级开关版本依赖列表

GPU型号

MXMACA版本

VBIOS版本

MXC500系列

>= 3.7.0.0

>= 1.32.0.0

MXC600系列

>= 2.1.0.0

2.2.5. 卸载驱动

操作步骤

  1. 执行以下命令，卸载驱动。

    sudo /opt/mxdriver/mxdriver-install.sh -U

  2. 根据系统提示信息决定是否重启服务器，若需要重启系统，请执行以下命令；否则，请跳过此步骤。

    reboot