2. 安装与维护

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

2.1. 用户须知

2.1.1. 系统支持范围

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

表 2.1 软硬件平台兼容列表
CPU架构	操作系统	内核版本	状态
x86_64	Ubuntu 18.04	5.4.0-42-generic	支持
x86_64	Ubuntu 18.04	5.4.0-131-generic	支持
x86_64	Ubuntu 20.04	5.4.0-144-generic	支持
x86_64	Ubuntu 20.04	5.15.0-58-generic	支持
x86_64	Ubuntu 22.04	5.15.0-72-generic	支持
x86_64	Ubuntu 22.04	5.15.0-112-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形式
x86_64	CentOS 7	5.14.0	支持加载Docker Container形式
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	Kylin V10 SP2	4.19.90-24.4.v2101.ky10.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	支持

2.1.2. 安装包说明

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

表 2.2 Driver软件包内容清单
文件名	说明
metax-linux_x.x.x-xxx_amd64.deb	曦云系列GPU KMD驱动、工具及相关配置文件
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 所示。

备注

首次安装场景：服务器上从未安装过驱动，板卡出厂时默认已安装好固件。
覆盖安装场景：服务器上安装过驱动且未卸载，当前要再次安装驱动。

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

../_images/image2.png — 图 2.2 确认服务器架构，操作系统和内核版本

操作步骤

执行以下命令，查询服务器CPU架构，操作系统和内核版本。
```
uname -m && uname -r && lsb_release -a
```
对照表 2.1 软硬件平台兼容列表，确认CPU架构，操作系统以及内核版本是否在列表中。若有任何一项不匹配，需按照列表升级软硬件系统。

备注

目前驱动安装只支持二进制安装，因此需严格匹配软硬件系统。

2.2.2. 创建运行用户

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

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

操作步骤

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

创建运行用户。
```
sudo adduser [user]
```
将运行用户加入video组。
```
sudo usermod -a -G video [user]
```

备注

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

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

sudo ./metax-driver-xxx.run -- [other-options] -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，空间大小分别为1 MB，8 MB和64 GB。

环境检查

表 2.3 环境检查（如无特别说明，以Ubuntu 18.04为例）
序号	检查项目	检查命令	说明
1	服务器CPU架构	`uname -m`	对照表 2.1 软硬件平台兼容列表，确认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	虚拟化	`dmesg \| grep "no space"`	支持SRIOV功能的曦云系列GPU板卡需要分配额外的PCI BAR空间给VF，VF所需BAR空间的大小是PF的8倍，如果系统无法分配地址空间，对应的设备将无法正常工作。
8	IOMMU配置	`vim /etc/default/grub`	在 `GRUB_CMDLINE_LINUX=""` 里面添加 `iommu.passthrough=1` 更新GRUB菜单 Ubuntu上执行 `sudo update-grub` CentOS上执行 `sudo grub2-mkconfig -o /boot/efi/EFI/centos/grub.cfg` 重启系统，查看/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. 二进制文件直接安装

操作步骤

将驱动的run安装文件下载到目标机器上，进入文件所在目录，执行以下命令安装驱动：
```
sudo ./metax-driver-mxc500-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。
- 针对C550X-DF16CubeDC-32这种拓扑类型，需要执行以下命令安装驱动：
  sudo ./metax-driver-mxc500-x.x.x.x-deb-x86_64.run -- -f -p topo_df=1
- 驱动默认支持省电模式，空闲状态时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
（可选）对于RHEL/CentOS/Rocky Linux及其延伸版本（ALINUX3等），在安装完驱动后需要执行以下命令，将驱动集成到initramfs中，以确保驱动的加载顺序：
```
sudo dracut -f
```
重启服务器。
```
sudo reboot
```
执行以下命令，查询驱动安装信息。
```
lsmod | grep metax
```
定义环境变量并执行以下命令，若回显信息列出所有曦云GPU的信息，则metax驱动工作正常。
```
export PATH=$PATH:/opt/mxdriver/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/mxdriver/lib
mx-smi
```

2.2.4. 更新固件

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

操作步骤

确认已经成功加载设备内核驱动。详细内容请参见 2.2.3 安装驱动。
检查更新的VBIOS固件文件mxvbios-xxx.bin（例如mxvbios-1.1.1.0-17-C500.bin）已安装到Linux的/lib/firmware/metax/mxc500目录下。

备注

若需要使用SRIOV功能，应安装带-VF后缀的VBIOS固件文件，例如mxvbios-1.4.0.0-200-C500-VF.bin。
确保板卡所有任务已经停止。如果有任务在进行中，需要停止其进程。
使用mx-smi工具执行以下命令，升级VBIOS固件（需要Root权限）。
```
sudo mx-smi -u /lib/firmware/metax/mxc500/mxvbios-xxx.bin -t 600
```
默认对所有板卡进行升级。若屏幕显示以下信息，则表示固件下载成功。
```
vbios-upgrade Done
```
若上述升级VBIOS固件中出现 Bar0Size mismatch 字样，使用以下命令升级（需要Root权限）。
```
sudo mx-smi -U /lib/firmware/metax/mxc500/mxvbios-xxx.bin -t 600 -i ID
```
ID 是板卡序列号，可以通过 mx-smi -L 查询获取相应板卡的ID。
重启服务器，以使更新的固件生效。
重启成功并加载驱动后，用mx-smi工具执行以下命令查询VBIOS固件版本。若与目标版本一致，说明升级安装成功。以曦云C500为例，VBIOS固件版本如下图所示。
```
mx-smi --show-version
```
图 2.3 VBIOS固件版本

2.2.5. 卸载驱动

操作步骤

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

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

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