mx-mft 用户手册

概述

墨芯 AI 计算卡上的固件分为板载固件和动态加载的固件两个部分。板载固件是存储在计算卡 Flash 上的固件，又分为板卡设备固件和板卡上的 MCU 固件。mx-mft 是用于管理墨芯 AI 计算卡设备固件的工具，您可使用 mx-mft 查询设备固件版本、给设备加载动态固件、重启设备、更新板载设备固件和 MCU 固件。

前提条件

在主机上安装 SOLA。具体的步骤，请参见《SOLA Toolkit 安装指南》。安装 SOLA 后，mx-mft 的二进制文件位于/usr/bin 目录下。

命令说明

执行 mx-mft --help 命令获取 mx-mft 的使用方法：

$ mx-mft --help
mx-mft(V1.11) avaliable commands:
    mx-mft status <id> : show device status
    mx-mft boot <id> <firmware package>: load bootimage for devices
    mx-mft reboot <id> : reboot device
    mx-mft mcu-ota <S30_id> [<fw_file_path>]: ota S30 mcu fw
    mx-mft update <id> <firmware package> <-f>: update bootloader for devices

for command detail help, use "mx-mft -h <command>"
for mx-mft version information, use "mx-mft -v"

mx-mft 命令支持以下选项：

选项	说明
-v	查看 mx-mft 的版本信息。
status	显示设备的状态和版本信息。如不指定设备 id，则显示所有设备的状态和版本信息。
boot	对设备加载固件。
update -f	更新板卡设备固件。注意：您需要获取 root 权限后才能更新板卡固件。卡处于 bootloader 模式时才能更新卡的固件，如果卡已经加载动态固件，请使用`mx-mft reboot`命令使卡重新启动到 bootloader 模式。固件升级可以不加 `-f` 参数，固件降级和平级更新则需要增加`-f`参数。
reboot	重启设备，使设备进入 bootloader 模式。
mcu-ota []	更新板卡上 MCU 的固件。注意：仅 S30 计算卡支持此功能，墨芯其他计算卡不支持此功能。

说明：

device_id：设备的 ID，参数可以类似是 0 或者 0-2（表示 0，1，2 这 3 个设备），或者是 all（表示所有的设备）
firmware package：墨芯发布的固件包压缩文件，例如 moffett-antoum-V3.52.14-20240327.tar.gz
fw_file_path：墨芯发布的 MCU 固件文件的路径，例如 /usr/local/sola/driver/firmware/ota-test/mcu_fw.tar.gz

命令示例

下文以更新设备 0 为例，如需更新所有的设备，请将命令中的 0 改为 all。

查看设备状态

$ mx-mft status 0

回显信息示例如下：

卡尚未加载动态固件状态下

#其中Mode: Bootloader表示卡处于bootloader模式
Device 0 info:
    SN: 9002348s21
    PN: 00S30-00A
    PCI bus: 0000:04:00.0
    Mode: Bootloader
    Bootloader version info:
        version: V12
        type: Release
        build date: Nov 27 2023
        active slot: A

卡已经加载动态固件状态下

#其中Mode: Kernel UMD表示卡已经加载完成动态固件
Device 0 info:
    SN: 9002348s21
    PN: 00S30-00A
    PCI bus: 0000:04:00.0
    Mode: Kernel UMD
    Firmware version: V1.0.14

加载设备的动态固件

#以实际文件路径和文件名为准
$ mx-mft boot 0-0 /usr/local/sola/driver/firmware/moffett-antoum*.tar.gz 
Extracting boot image...
package boot image version info:
    version: Vxx
    build time: Nov 27 2023 15:42:06
boot image check OK, image size: 65.21MB

Device 0 info:
    SN: 9002348s21
    PN: 00S30-00A
    PCI bus: 0000:04:00.0
    Mode: Bootloader
    Bootloader version info:
        version: Vxx
        type: Release
        build date: Nov 27 2023
        active slot: B

start loading boot image for device 0-0:
    device  0 (00S30-00A - 9002348s21): Boot image load success

total 1 device loading boot image, all success

重启设备

重启设备，使设备进入 bootloader 状态。

注意： 您需要获取 root 权限后才能重启计算卡设备。

$ sudo mx-mft reboot 0
request device 0(pci bus:0:04:00.0) reboot success
wait devices rebooting...
remove devices from pci bus...
rescan all devices...
device 0 reboot success

更新板卡固件

$ sudo mx-mft update 0-0 /usr/local/sola/driver/firmware/moffett-antoum* -f 

关机并重启服务器

固件升级完成后可能需要关闭服务器电源，请根据执行 mx-mft 命令后最后回显的提示信息进行操作，如提示需要关机，则关闭服务器，然后再启动服务器以使用设备新的固件。

查看固件版本

$ mx-qual list | grep "Firmware version"

使用示例

目前发布包 /usr/local/sola/driver/firmware/ota-test 目录下的压缩包是用来做固件更新测试的固件，仅用于测试目的。如果您烧录了该测试固件，请在测试完成后烧录回/usr/local/sola/driver/firmware/目录下的固件压缩包。

更新板载设备固件

查询当前的固件版本。

$ mx-qual list | grep "Firmware version"

重启设备，使设备进入 bootloader 状态。
```
$ sudo mx-mft reboot all
```
更新板载的设备固件到 v15 版本。
```
#以实际文件名为准
$ sudo mx-mft update all /usr/local/sola/driver/firmware/ota-test/moffett-antoum-*.15-*.tar.gz
```
- 如果出现类似下文需要关闭服务器的提示，则需要将服务器关机后重启以使用新的设备固件。
```
Important: Please power off this server to use device new firmware
```
- 如果未提示需要关闭服务器，则使用下面的命令重新启动 mx-daemon 服务，并等待 1 分钟左右后再查询新的固件版本。
```
$ sudo systemctl restart mx-daemon
```

查询新的固件版本。

   $ mx-qual list | grep "Firmware version"

完整流程示例如下：

### 参考结果：操作前后
$ mx-qual list | grep "Firmware version"  Firmware version:   1.0.14
  ...
  Firmware version:   1.0.14

$ sudo mx-mft update all /usr/local/sola/driver/firmware/ota-test/moffett-antoum-*.15-*.tar.gz
Package bootloader version info:
    version: V15
    type: V14 OTA TEST
    build time: Jan  6 2024 11:24:35

Device 0 info:
    SN: 2023513080278    PN: 00S30-00A
    PCI bus: 0000:51:00.0
    Mode: Bootloader
    Bootloader version info:
        version: V14
        type: Release
        build date: Dec 28 2023        active slot: A
...

Device 23 info:
    SN: 2023483080243    PN: 00S30-00A
    PCI bus: 0000:e6:00.0
    Mode: Bootloader
    Bootloader version info:
        version: V14
        type: Release
        build date: Dec 28 2023        active slot: B

Start updating bootloader for device 0-23:
    device  0 (00S30-00A - 2023513080278): bootloader update success, version is V0.15 now
    ...
    device 23 (00S30-00A - 2023483080243): bootloader update success, version is V0.15 now

Total 24 device update bootloader, all success

Important: Please power off this server to use device new firmware
$ mx-qual list | grep "Firmware version"  Firmware version:   1.0.15
  ...
  Firmware version:   1.0.15

降级板卡 MCU 固件

注意：

在 S30 板卡和 S40 板卡上均支持板卡 MCU 的升级和降级。
降级板卡固件时，S30 的 MCU version 必须在 4X05 及以上版本。
板卡需要在加载动态固件后才能更新 MCU 的固件，如果板卡尚未加载动态固件，请使用 mx-mft boot 命令加载卡的固件。

下文以降级 MCU 版本为例，演示了更新板卡 MCU 固件的流程：

查询设备 0 1 2 的 MCU 版本。

$ mx-smi select -f mcu_version -i 0 1 2
mcu_version
4X011
4X011
4X011

导入固件二进制文件，对设备 0 1 2 的 MCU 版本降级。

#以ota-test目录下的文件名为准
$ mx-mft mcu-ota 0-2 /usr/local/sola/driver/firmware/ota-test/mcu_fw.tar.gz
device 0 mcu ota updating... 
device 0 mcu ota success! 
device 1 mcu ota updating... 
deivce 1 mcu ota success! 
device 2 mcu ota updating... 
deivce 2 mcu ota success! 

降级流程结束后执行以下命令，查看当前 MCU 版本。
```
$ mx-smi select -f mcu_version -i 0 1 2
mcu_version
4X08
4X08
4X08
```
说明：
- 研华 S30 计算卡的 MCU 版本默认降级为 4x08。
- 云尖 S30 计算卡的 MCU 版本默认降级为 2V23。
- 云尖 S40 计算卡的 MCU 版本默认降级为 1V23。

升级板卡 MCU 固件