本课说明（2026-11-14 新编）
适用范围：MUSA SDK 5.2.0，重点为 MTT S5000/S4000 服务器；PC 卡只列出 BIOS 差异。本课只讲“装驱动之前”的准备工作，安装步骤见第 3 课，容器见第 4 课；m2-l1 已有总览，本课不重复。 本课依据官方文档与正式 Release 整理，未在真实 MUSA GPU 上实测；标注“官方”的命令与数值来自原文，标注“本站补充”的脚本由本站编写用于检查与教学，使用前请在自己的环境中验证。
一、为什么要单独做环境准备
驱动安装失败的多数原因不在驱动本身，而是操作系统/内核不在支持列表、BIOS 中 IOMMU 设置与卡型要求相反、缺少内核头文件或 DKMS，以及残留旧版本。MUSA SDK 5.2.0 安装指南 把这些都列为前置条件。先把检查做完，可以把问题挡在安装之前。
二、确认操作系统与内核在支持列表中
据 MUSA SDK v5.2.0 发布版本信息，MTT S5000 的 5.2.0 版本验证平台如下（节选）：
| CPU 平台 | 操作系统 | 内核 |
|---|---|---|
| Intel | Ubuntu 22.04.4 | 5.15.0-105-generic |
| Intel | Ubuntu 24.04.1 | 6.8.0-124 |
| Intel | Alinux3 | 5.10.134-13.al8 |
| Intel | VesselOS 2.0 | 见发布说明 |
| 海光（Hygon4）/ AMD | Ubuntu 22.04.4 | 5.15.0-105-generic |
| 海光（Hygon4） | Kylin V10 / V11、BCLinux | 见发布说明 |
APT 在线源的限制
官方 APT 在线源只面向全新安装的 Ubuntu 22.04 x86_64 Server。其他系统使用离线包：发布说明中 Ubuntu 平台对应 DEB 包，Alinux 3、VesselOS、Kylin、BCLinux 对应 RPM 包，请按平台下载。安装指南中 Ubuntu 的离线包示例为
musa_5.2.0-server_amd64.deb 与 musa_toolkits_5.2.0.tar.gz。关于 MTT S4000
SDK 5.2.0 发布说明的平台表只列出 MTT S5000；安装指南中给出了 S4000 的 IOMMU 设置和 mccl-s4000 包。S4000 在 5.2.0 上的支持范围请向厂商确认。
bash
# 按官方要求核对系统与内核（命令为本站补充）
cat /etc/os-release | grep -E "^(NAME|VERSION)="
uname -r # Ubuntu 22.04 期望 5.15.0-105-generic
uname -m # 期望 x86_64三、确认 GPU 已被 PCIe 识别
bash
# 1ed5 是官方文档用来筛选摩尔线程设备的 PCI 厂商编号
lspci -nn | grep 1ed5没有输出时，先检查供电、插槽和 BIOS，而不是继续装驱动。
四、BIOS 与 IOMMU：按卡型设置，方向相反
| 卡型 / 场景 | IOMMU 要求 | 内核启动参数（官方示例） |
|---|---|---|
| MTT S4000，主机内存 ≥ 256 GB | 必须开启 | Intel：intel_iommu=on iommu.passthrough=0；AMD/海光：amd_iommu=on |
| MTT S5000 | 必须关闭 | Intel：intel_iommu=off iommu=off iommu.passthrough=1 crashkernel=512M-:768M（官方只给出 Intel 示例；AMD/海光平台请以厂商说明为准） |
| PC 卡（如 MTT S80） | BIOS 打开 Above 4G Decoding 与 Resize BAR | — |
bash
# 查看当前 IOMMU 状态（官方命令）
sudo dmesg | grep -Ei "DMAR|IOMMU|VT-d|remapping"
cat /proc/cmdline
# 修改前先备份 GRUB 配置（本站补充）
sudo cp /etc/default/grub /etc/default/grub.bak.$(date +%Y%m%d)
# 编辑 GRUB_CMDLINE_LINUX_DEFAULT，按上表写入对应参数后：
sudo update-grub
sudo reboot # 官方建议软重启注意
官方示例用 sed 整行替换
GRUB_CMDLINE_LINUX_DEFAULT，会覆盖原有的全部参数。其中去掉 quiet 是官方有意为之，以便重启后 BMC 能看到启动画面。生产机若手工编辑，请按官方建议去掉 quiet，同时保留其他必要参数，重启后用 cat /proc/cmdline 确认。五、内核头文件与 DKMS
离线驱动包依赖与当前内核完全匹配的头文件和模块包，以及 DKMS：
bash
sudo apt update
sudo apt install -y linux-headers-$(uname -r) linux-modules-$(uname -r) \
linux-modules-extra-$(uname -r) dkms六、清理旧版本
机器上若装过旧版驱动或 Toolkit，先卸载再装新版本。官方步骤如下（详细说明见第 3 课）：
bash
# 旧版离线驱动包
sudo dpkg -P musa
sudo modprobe -rv mtgpu
lsmod | grep mtgpu # 无输出表示模块已卸载
# 旧版 Toolkit（tar 包安装）在解压目录中执行
sudo ./install.sh -u集群节点
在 Kubernetes 节点上，如果驱动由集群组件（如 Operator）管理，需要先按集群方案下线这些组件，再在宿主机上操作。具体顺序以集群方案文档为准。
七、一键预检脚本（本站补充）
下面的脚本只读取信息、不修改系统，用于在装机前快速汇总。它由本站编写，未在真实硬件上运行过。
bash
#!/usr/bin/env bash
# musa-precheck.sh — 只读预检，适用于 MUSA SDK 5.2.0 装机前
echo "== OS =="; grep -E "^(NAME|VERSION)=" /etc/os-release
echo "== Kernel =="; uname -r; uname -m
echo "== PCI (1ed5) =="; lspci -nn | grep 1ed5 || echo "未发现摩尔线程设备"
echo "== cmdline =="; cat /proc/cmdline
echo "== IOMMU =="; sudo dmesg | grep -Ei "DMAR|IOMMU|VT-d|remapping" | tail -n 5
echo "== headers/dkms =="
dpkg -l | grep -E "linux-headers-$(uname -r)|dkms" || echo "缺少 headers 或 dkms"
echo "== 旧版本残留 =="
dpkg -l | grep -E "^ii\s+(musa|mthreads-driver|musa-toolkit)" || echo "未发现已安装的 MUSA 包"
lsmod | grep mtgpu || echo "mtgpu 模块未加载"八、检查清单
| 检查项 | 通过标准 |
|---|---|
| 操作系统 / 内核 | 在发布说明的支持列表中 |
| PCIe 识别 | lspci -nn | grep 1ed5 有输出 |
| IOMMU | S5000 为关闭，S4000（≥256 GB 内存）为开启 |
| 依赖 | 与当前内核匹配的 headers / modules / modules-extra 以及 dkms 已安装 |
| 旧版本 | 已卸载，lsmod | grep mtgpu 无输出 |
九、回滚
本课唯一的系统改动是 GRUB 参数。若重启后异常，用备份恢复：sudo cp /etc/default/grub.bak.<日期> /etc/default/grub && sudo update-grub && sudo reboot。