mx-mft 用户手册

概述

MOFFETT SPU 上的固件分为板载固件和动态加载的固件两个部分，其中板载固件又分为板载设备固件和板载 MCU 固件。

mx-mft 是用于管理 MOFFETT SPU 设备固件工具，管理员可使用 mx-mft 查询设备固件版本，给设备加载动态固件，重启设备，更新板载设备固件和 MCU 固件。

boot 加载动态固件，不更新板载 Bootloader；板载设备固件通过 update 更新。

组件和固件版本请参见 MACS 1.1.3 发布日志。

子命令 status

列出计算卡的设备，并显示设备的状态和版本信息。

mx-mft status [<device_id>]

device_id（可选）: 指定设备索引（device index）或索引范围，例如 0、0-2（表示设备 0、1、2）。省略或设置为 all 时查询全部设备。设备索引必须为非负整数，小于当前设备数量，且不超过 31。输入负数或超出当前设备数量的索引会失败。

示例

mx-mft status 0

# 未加载动态固件
Device 0 info:
    SN: 9002348s21
    PN: 00S30-00A
    PCI bus: 0000:04:00.0
    Mode: Bootloader # 表示卡处于 Bootloader 模式。
    Bootloader version info:
        version: V1.0.**
        type: Release
        build date: Nov 27 2023
        active slot: A

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

输出字段	说明
`SN`	设备序列号
`PN`	产品标识
`PCI bus`	设备的 PCI 总线地址
`Mode`	设备模式，示例中分别为 Bootloader 和 Kernel UMD
`Firmware version`	Kernel UMD 状态下设备报告的固件版本
`Bootloader version info`	Bootloader 状态下的版本信息，包括 version、type、build date 和 active slot

子命令 boot

为设备加载动态固件。

mx-mft boot <device_id> <firmware_package>

device_id: 指定设备索引（device index）或索引范围，例如 0、0-2（表示设备 0、1、2）。设置为 all 时，选择所有设备。设备索引必须为非负整数，小于当前设备数量，且不超过 31。
firmware_package: 指定 moffett 发布的固件包压缩文件路径，例如 /usr/local/sola/driver/firmware/moffett-antoum-V3.52.14-20240416.tar.gz。

示例

mx-mft boot all /usr/local/sola/driver/firmware/moffett-antoum-V3.52.14-20240416.tar.gz

加载完成后，使用 mx-mft status all 查询设备，确认 Mode: Kernel UMD。

子命令 reboot

重启设备，使设备进入 Bootloader 状态。执行该命令需要 root 权限。

mx-mft reboot <device_id>

device_id: 指定设备索引（device index）或索引范围，例如 0、0-2（表示设备 0、1、2）。设置为 all 时，选择所有设备。设备索引必须为非负整数，小于当前设备数量，且不超过 31。

示例

sudo mx-mft reboot all

重启完成后，使用 mx-mft status all 查询设备，确认 Mode: Bootloader。

子命令 mcu-ota

更新板卡上 MCU 的固件。使用该命令的限制如下：

确认 S30 的 MCU version 是否为 V4X05 或以上版本，其他版本和 S4 计算卡不支持此功能。
卡已经加载动态固件后才能更新 MCU 固件，如果卡未加载动态固件，使用 mx-mft boot 命令加载卡的固件。
SOLA 3.5.3 包含 ota-test/DMS-BC404X0007.bin（4X07 测试镜像）；配套正式 MCU 版本为 4X08。

mx-mft mcu-ota <device_id> [<fw_file_path>]

device_id: 指定设备索引（device index）或索引范围，例如 0、0-2（表示设备 0、1、2）。设置为 all 时，选择所有设备。设备索引必须为非负整数，小于当前设备数量，且不超过 31。
fw_file_path（可选）: 指定主机上的 MCU 固件文件路径。省略时使用默认 MCU 固件。

示例

mx-mft mcu-ota all /usr/local/sola/driver/firmware/ota-test/DMS-BC404X0007.bin

指定测试镜像降级的操作步骤见MCU 固件降级测试示例；使用默认 MCU 固件更新的操作步骤见MCU 固件更新测试示例。

子命令 update

更新板卡的固件。使用该命令的限制如下：

执行该命令需要 root 权限。
卡处于 Bootloader 模式时才能更新卡的固件，如果卡已经加载动态固件，使用 mx-mft reboot 命令使卡重新启动到 Bootloader 模式。

mx-mft update <device_id> <firmware_package> [-f]

device_id: 指定设备索引（device index）或索引范围，例如 0、0-2（表示设备 0、1、2）。设置为 all 时，选择所有设备。设备索引必须为非负整数，小于当前设备数量，且不超过 31。
firmware_package: 指定 moffett 发布的固件包压缩文件路径，例如 /usr/local/sola/driver/firmware/moffett-antoum-V3.52.14-20240416.tar.gz。
-f（可选）: 该参数在固件升级时无需指定，降级和平级更新时必须指定。降级或平级更新时，若提示 no need to be updated，请确认已指定 -f。

示例

sudo mx-mft update all /usr/local/sola/driver/firmware/moffett-antoum-V3.52.14-20240416.tar.gz -f

等待命令结束，并检查各设备的更新结果及汇总。100% downloaded 仅表示传输完成，仍需等待后续写入结束。若提示 Please power off this server，关闭服务器后重新开机，再查询设备状态和版本。

升级、降级、平级更新和正式版本恢复的操作步骤见工具应用。

工具应用

以下示例使用 MACS 1.1.3 配套 SOLA 3.5.3 / mx-mft 1.08 及包内固件。安装步骤见 SOLA Toolkit 安装指南。执行前确认所有设备均无工作负载。

以下板载设备固件示例按升级、降级、平级和正式版本恢复的顺序组织，可依次执行：1.0.14 → 1.0.15 → 1.0.13 → 1.0.13 → 1.0.14。单独执行时，先确认对应示例的起始版本。

固件包路径（相对于 `/usr/local/sola/driver/firmware/`）	板载设备固件版本	类型与示例用途
`moffett-antoum-V3.52.14-20240416.tar.gz`	1.0.14	Release，MACS 1.1.3 配套正式版本，用于正式版本恢复
`ota-test/moffett-antoum-V3.52.15-20240327.tar.gz`	1.0.15	OTA TEST，用于升级测试
`ota-test/moffett-antoum-V3.52.13-20240327.tar.gz`	1.0.13	OTA TEST，用于降级和平级测试

所有 mx-mft 示例均使用 all 对全部设备操作，各设备均须满足示例的起始版本和使用条件；查询时逐一确认各设备的模式和版本。

固件升级测试示例

本示例从正式板载设备固件版本 1.0.14 升级到 1.0.15，步骤如下：

查询所有设备当前状态和版本。
```
mx-mft status all
```
确认所有设备的板载设备固件版本均为 V1.0.14；若版本不一致，先完成固件恢复测试示例。
若有设备处于 Kernel UMD 模式，重启进入 Bootloader 模式；所有设备均处于 Bootloader 模式时跳过重启命令。更新前确认 Mode: Bootloader。
```
sudo mx-mft reboot all
mx-mft status all
```

使用升级测试包更新板载设备固件。

sudo mx-mft update all /usr/local/sola/driver/firmware/ota-test/moffett-antoum-V3.52.15-20240327.tar.gz

等待工具完成设备重启；若提示需要关闭服务器，则执行以下命令关机后重新开机，再继续验证。
```
sudo shutdown -P now
```
完成工具要求的生效步骤后，逐一查询并确认所有设备的板载设备固件版本为 V1.0.15。Bootloader 模式下读取 version 和 type: OTA TEST；Kernel UMD 模式下读取 Firmware version。
```
mx-mft status all
```
继续执行固件降级测试示例；若测试到此结束，执行固件恢复测试示例恢复到 1.0.14。

固件降级测试示例

本示例从板载设备固件版本 1.0.15 降级到 1.0.13，步骤如下：

查询所有设备当前状态和版本。
```
mx-mft status all
```
确认所有设备的板载设备固件版本均为 V1.0.15，可通过固件升级测试示例准备。
若有设备处于 Kernel UMD 模式，重启进入 Bootloader 模式；所有设备均处于 Bootloader 模式时跳过重启命令。更新前确认 Mode: Bootloader。
```
sudo mx-mft reboot all
mx-mft status all
```

使用降级测试包更新板载设备固件。

sudo mx-mft update all /usr/local/sola/driver/firmware/ota-test/moffett-antoum-V3.52.13-20240327.tar.gz -f

按工具提示完成生效操作。若工具提示 Please power off this server to use device new firmware，关闭服务器后重新开机，使新的板载设备固件生效。
```
sudo shutdown -P now
```
若未提示关机，等待工具完成设备重启后再继续验证。
完成工具要求的生效步骤后，逐一查询并确认所有设备的板载设备固件版本为 V1.0.13。Bootloader 模式下读取 version；Kernel UMD 模式下确认 Mode: Kernel UMD 和 Firmware version: V1.0.13。
```
mx-mft status all
```
继续执行固件平级测试示例；若测试到此结束，执行固件恢复测试示例恢复到 1.0.14。

固件平级测试示例

本示例使用 1.0.13 测试包重新更新同一板载设备固件版本，即 1.0.13 → 1.0.13，步骤如下：

查询所有设备当前状态和版本。
```
mx-mft status all
```
确认所有设备的板载设备固件版本均为 V1.0.13，可通过固件降级测试示例准备。
若有设备处于 Kernel UMD 模式，重启进入 Bootloader 模式；所有设备均处于 Bootloader 模式时跳过重启命令。更新前确认 Mode: Bootloader。
```
sudo mx-mft reboot all
mx-mft status all
```

使用 1.0.13 测试包进行平级更新。

sudo mx-mft update all /usr/local/sola/driver/firmware/ota-test/moffett-antoum-V3.52.13-20240327.tar.gz -f

等待工具完成设备重启；若提示需要关闭服务器，则执行以下命令关机后重新开机，再继续验证。
```
sudo shutdown -P now
```
完成工具要求的生效步骤后，逐一查询并确认所有设备的板载设备固件版本仍为 V1.0.13。Bootloader 模式下读取 version；Kernel UMD 模式下读取 Firmware version。
```
mx-mft status all
```
完成固件恢复测试示例，将板载设备固件恢复到 1.0.14。

固件恢复测试示例

本示例将设备的板载设备固件更新或恢复到 1.0.14，用于上述测试结束后的正式版本恢复，步骤如下：

查询所有设备当前状态和版本。
```
mx-mft status all
```
设备处于 Bootloader 模式时，查看 Bootloader version info 中的 version；处于 Kernel UMD 模式时，查看 Firmware version。
若有设备处于 Kernel UMD 模式，重启设备进入 Bootloader 模式；所有设备均处于 Bootloader 模式时跳过重启命令。更新前查询确认 Mode: Bootloader。
```
sudo mx-mft reboot all
mx-mft status all
```
使用正式固件包更新板载设备固件。以下命令添加 -f，适用于从较高版本恢复或平级更新。1.0.15 → 1.0.14 属于降级，必须保留 -f；1.0.13 → 1.0.14 属于升级，可以省略 -f。
```
sudo mx-mft update all /usr/local/sola/driver/firmware/moffett-antoum-V3.52.14-20240416.tar.gz -f
```
按工具提示完成生效操作。若工具提示 Please power off this server to use device new firmware，关闭服务器后重新开机：
```
sudo shutdown -P now
```
若未提示关机，等待工具完成设备重启。
完成工具要求的生效步骤后，逐一查询并确认所有设备的板载设备固件版本为 V1.0.14。
```
mx-mft status all
```
完成工具要求的生效步骤后，若仍有设备处于 Bootloader 模式，执行以下命令加载正式动态固件；已处于 Kernel UMD 模式的设备会跳过加载。若所有设备均已处于 Kernel UMD 模式，跳过该命令。
```
sudo mx-mft boot all /usr/local/sola/driver/firmware/moffett-antoum-V3.52.14-20240416.tar.gz
```
再次查询所有设备，逐一确认 Mode: Kernel UMD，且 Firmware version: V1.0.14。版本与模式均符合预期后，恢复完成。
```
mx-mft status all
```

MCU 固件降级测试示例

本示例使用 SOLA 3.5.3 中的 4X07 测试镜像对所有设备进行降级。执行前，请确认所有设备均满足子命令 mcu-ota中的使用条件。

查询并记录所有设备更新前的 MCU 版本，确认所有设备的当前版本均高于目标版本 4X07。
```
mx-smi select -f mcu_version
```

指定包内的 4X07 测试镜像更新 MCU 固件。

mx-mft mcu-ota all /usr/local/sola/driver/firmware/ota-test/DMS-BC404X0007.bin

再次查询所有设备的 MCU 版本，逐一与更新前的结果对比，并结合更新命令的实际结果确认是否降至目标版本 4X07。
```
mx-smi select -f mcu_version
```
测试完成后，参见MCU 固件更新测试示例，使用默认 MCU 固件更新并再次查询版本。更新后的版本以设备实际查询结果为准。

MCU 固件更新测试示例

本示例使用默认 MCU 固件更新所有设备。执行前，请确认所有设备均满足子命令 mcu-ota中的使用条件。

查询并记录所有设备更新前的 MCU 版本。
```
mx-smi select -f mcu_version
```
更新 MCU 固件。
```
mx-mft mcu-ota all
```
再次查询所有设备的 MCU 版本，逐一与更新前的结果对比，并结合更新命令的实际结果确认更新情况。
```
mx-smi select -f mcu_version
```