第5章精讲：开发环境搭建（驱动 / SDK / 容器 / 冒烟验证）

一、系统基础配置：硬件与系统合规是一切的前提

环境搭建的第一步不是装驱动，而是确认硬件与系统是否处于受支持状态。这一步跳过，后面装驱动、装 Toolkit 遇到的错误往往会被误判为软件问题，实际根源在 BIOS 或内核版本。

1. BIOS 核心配置

BIOS 配置直接影响 GPU 硬件资源的调用效率。标准操作步骤如下：

1. 将显示器连接到主板，断开电源、重新启动计算机；启动过程中按 Delete 键进入 BIOS 设置界面。
2. 在 BIOS 设置界面中开启 Above 4G Decoding 选项。
3. 开启 Resize Bar 选项。首次开机时，大部分主板该选项默认为 OFF，通常显示在 BIOS 设置界面右上角。

若使用 MTT S5000 服务器，必须关闭 IOMMU（VT-d）选项，操作命令如下：

# 如果 IOMMU 是打开的，可通过如下命令关闭
sudo cat /etc/default/grub | grep "iommu"
# 如果 amd_iommu=on 或 intel_iommu=on，则删除相关字段
sudo update-grub
sudo reboot
# 使用如下命令查看是否开启 IOMMU
sudo cat /var/log/dmesg | grep -e "AMD-Vi: Interrupt remapping enabled" -e "IOMMU enabled"

2. 操作系统与内核版本要求

MTT S5000 支持的操作系统基线为 Ubuntu 22.04，内核版本为 5.15.0-105-generic。这是本章后续所有命令验证过的组合，跨发行版或跨大版本内核安装前应先确认官方是否已支持。

3. 显卡安装验证

GPU 是 MUSA 开发的硬件核心，装驱动之前需先确认硬件是否被系统正常识别：

# 查看 PCI 是否识别到显卡
lspci -nn | grep led5

若命令无输出，需按顺序检查：

• 显卡是否已插入 PCIe 插槽；
• 显卡电源线是否已连接，风扇是否正常工作。

二、驱动安装：GPU 与操作系统通信的桥梁

只有正确安装与配置驱动，Toolkit 及扩展库才能正常调用硬件资源。这一节按"装依赖 → 装驱动 → 配组权限 → 验证"的顺序展开。

1. 环境依赖

dkms 编译需要依赖 Linux 内核头文件与内核模块，以 Ubuntu 为例：

apt install linux-headers-$(uname -r)
apt install linux-modules-$(uname -r)
apt install linux-modules-extra-$(uname -r)
apt install dkms

2. 安装驱动

以 MT DDK 驱动 3.3.0 版本为例：

sudo apt install ./musa_3.3.0-server_amd64.deb
# 重启计算机使驱动生效
sudo reboot
# 如果希望在不重启计算机的情况下更换驱动，可以手动重新加载驱动
modprobe -rv mtgpu && modprobe -v mtgpu

3. 设置用户组

非 root 用户需获取设备使用权限，需添加 render 和 video 组权限：

# 把普通用户账户加入 render 和 video 组
sudo usermod -aG render,video $USER
# 重新登录账户

4. 验证安装与版本查询

执行 mthreads-gmi 命令查看 gmi 版本号、Driver 版本号、显卡相关信息：

mt@mt:~$ mthreads-gmi
Wed May 14 14:26:15 2025
------------------------------------------------------------
mthreads-gmi:2.0.0 Driver Version:3.0.0
------------------------------------------------------------
ID Name |PCIe |%GPU Mem
Device Type |Pcie Lane Width |Temp MPC Capable | ECC Mode
--------------------------------------------------------------+
0 MTT S5000 |00000000:01:00.0 |1% 4MiB(65536MiB)
Physical |16x(16x) |58C YES | N/A
--------------------------------------------------------------
--------------------------------------------------------------
Processes:
ID PID Process name GPU Memory Usage
--------------------------------------------------------------+
No running processes found
--------------------------------------------------------------

也可通过 musa_version_query 命令检查所安装组件版本：

$ musa_version_query
# 以 4.3.0 版本为例，仅展示重要信息，实际运行时可能有其他详细信息输出
musa_toolkits:{"version": "4.3.0",}
MUPTI:{"version": "1.0.1",}
mcc:{"version": "4.3.0",}
mtjpeg:{"version": "1.0.0",}
muPP:{"version": "1.11.1",}
mublasLt:{"version": "1.10.1",}
mublas:{"version": "1.10.1",}
mufft:{"version": "1.10.1",}
murand:{"version": "1.1.0",}
musify:{"version": "1.1.1",}
musolver:{"version": "1.4.1",}
musparse:{"version": "1.5.0",}
musa_runtime:{"version": "4.3.0",}

三、MUSA Toolkit 安装：核心工具套件

MUSA Toolkit 是开发、编译、运行 MUSA 程序的核心工具套件，包含编译器、运行时库及各类开发工具。

1. MUSA Toolkit 安装

# 解压安装包
tar -zxvf musa_toolkit_4.3.0.tar.gz
# 进入安装目录
cd musa_toolkits_install
# 卸载环境中已安装的 musa toolkit
sudo ./install.sh -u
# 执行安装命令
sudo ./install.sh

2. 设置环境变量

安装成功后，会有如下信息输出：

Successfully installed MUSA in /usr/local/musa
Please export /usr/local/musa/bin to PATH in ~/.bashrc
export PATH=/usr/local/musa/bin:PATH
Please export /usr/local/musa/lib to LD_LIBRARY_PATH in ~/.bashrc
export LD_LIBRARY_PATH=/usr/local/musa/lib:LD_LIBRARY_PATH

根据提示依次设置环境变量：

Step-by-Step：配置 MUSA 环境变量

1. 打开用户终端配置文件：

   vim ~/.bashrc

2. 在配置文件末尾追加以下三行：

   export MUSA_INSTALL_PATH=/usr/local/musa
   export PATH=$MUSA_INSTALL_PATH/bin:$PATH
   export LD_LIBRARY_PATH=$MUSA_INSTALL_PATH/lib:$LD_LIBRARY_PATH

3. 使配置立即生效（无须等待下次开启终端）：

   source ~/.bashrc

配置文件会在下次启动终端时自动生效；若需要立即生效，执行 source ~/.bashrc 即可，无须重启系统。

3. 有效性验证

执行 musaInfo 命令验证 MUSA Toolkit 是否安装成功：

$ musaInfo
compiler: mcc
--------------------------------------------------------------------------------
device# 0
Name: MTT S5000
pciBusID: 1
pciDeviceID: 0
pciDomainID: 0
multiProcessorCount: 64
maxThreadsPerMultiProcessor: 3072
isMultiGpuBoard: 1
clockRate: 1500 Mhz
memoryClockRate: 20000 Mhz
memoryBusWidth: 640
totalGlobalMem: 63.92 GB
sharedMemPerMultiprocessor: 192.00 KB
totalConstMem: 8192
sharedMemPerBlock: 192.00 KB
canMapHostMemory: 1
regsPerBlock: 131072
warpSize: 32
l2CacheSize: 62914560
computeMode: 0
maxThreadsPerBlock: 1024
maxThreadsDim.x/y/z: 1024
maxGridSize.x/y/z: 2147483647
concurrentKernels: 1
cooperativeLaunch: 0
cooperativeMultiDeviceLaunch: 0
isIntegrated: 0
maxTexture1D: 32768
maxTexture2D.width/height: 32768
maxTexture3D.width: 16384 / height: 16384 / depth: 2048
peers: 无
non-peers: device#0
memInfo.total: 63.92 GB
memInfo.free: 63.34 GB (99%)

上述硬件参数（如 multiProcessorCount: 64、totalGlobalMem: 63.92 GB）为 MTT S5000 的实测/示例数值，本课第六课（m11-l8，第 6 章）将讲解如何用 Runtime API 编程读取这些字段。

四、在 MUSA 上输出 "Hello Musa"：第一个完整程序

"Hello World" 是学习任何编程语言的经典入门案例。下面这个例子完整展示了 MUSA 主机端/设备端协作的基本编程流程。

Step-by-Step：编写、编译、运行 Hello MUSA

1. 创建源文件，保存为 hello_musa.mu：

   #include <musa_runtime.h>
   #include <stdio.h>
   
   // 内核函数：设备端并行执行
   __global__ void helloMusa() {
       // 计算全局线程 ID
       int tid = blockIdx.x * blockDim.x + threadIdx.x;
       printf("GPU :: %2d :: Hello Musa!
   ", tid);
   }
   
   // 主机端函数：CPU 串行执行
   int bar() {
       printf("CPU :: Hello Musa!
   ");
       return 0;
   }
   
   int main() {
       // 主机端执行
       bar();
   
       // 启动内核
       // 配置：1 个线程网格、1 个线程块，每个线程块含 5 个线程
       helloMusa<<<1, 5>>>();
   
       // 主机等待设备执行完成
       musaDeviceSynchronize();
       return 1;
   }

2. 使用 mcc 编译：

   mcc hello_musa.mu -lmusart -L/usr/local/musa/lib -O2 -o hello_musa

3. 运行可执行文件：

   ./hello_musa

4. 核对输出结果是否与以下示例一致（顺序可能不同）：

   root@autodl-container-77de47b334-8b88d72b:~# mcc hello_musa.mu -lmusart -L/usr/local/musa/lib -o2 -o hello_musa
   root@autodl-container-77de47b334-8b88d72b:~# ./hello_musa
   GPU :: Hello_musa!
   GPU :: 0 :: Hello Musa!
   GPU :: 1 :: Hello Musa!
   GPU :: 2 :: Hello Musa!
   GPU :: 3 :: Hello Musa!
   GPU :: 4 :: Hello Musa!
   root@autodl-container-77de47b334-8b88d72b:~#

五、muDNN 加速库安装：深度学习算子支持

muDNN 是 MUSA 生态下的深度学习加速库，提供底层算子支持，其安装依赖已配置完成的 MUSA 驱动与 MUSA Toolkit。以 mudnn_rc3.1.0 版本为例：

tar -zxvf mudnn_rc3.1.0.tar.gz
cd mudnn && ./install_mudnn.sh -i

六、MCCL 安装：多卡通信库

MCCL 是 MUSA 生态中的多卡通信库，支持节点内/跨节点多卡协同计算。其安装依赖特定硬件（多 GPU、InfiniBand 网卡等）与软件环境。

1. 前置条件

1. 多 MT GPU（单节点/多节点）
2. 一块或多块 InfiniBand 网卡
3. 已安装 MUSA 驱动
4. 已安装 MUSA Toolkits
5. 已安装 mtml（容器内部直接安装 mtml，或通过主机端映射；若通过 container-toolkit 方式创建容器，会直接映射进去）

2. 配置网络

PH1 架构支持 RoCE 网络。若无 IB 网卡（仅以太网），需设置环境变量指定协议：

export MCCL_IB_GID_INDEX=3

若有 IB 网卡但未安装 IB 驱动，需先完成驱动安装；执行 ibstat 命令验证 IB 端口状态，若输出中某 network port 的 Physical state 为 LinkUp 且 Link layer 为 InfiniBand，则说明 IB 网络已正常启用：

$ibstat
CA 'mlx5_0'
	CA type: MT4123
	Number of ports: 1
	Firmware version: 20.31.1014
	Hardware version: 0
	Node GUID: 0xb83fd203005682a2
	System image GUID: 0xb83fd203005682a2
	Port 1:
		State: Active
		Physical state: LinkUp
		Rate: 200
		Base lid: 12
		LMC: 0
		SM lid: 5
		Capability mask: 0x2651e848
		Port GUID: 0xb83fd203005682a2
		Link layer: InfiniBand

3. 安装 MPI 工具

MPI 工具为 MCCL 提供跨节点的进程管理和通信基础，协调不同主机间的初始连接。多机场景下需要安装 MPI 工具（两种方式二选一）。

方式一：mpich（示例版本 4.2.0rc3）

wget https://www.mpich.org/static/downloads/4.2.0rc3/mpich-4.2.0rc3.tar.gz
tar -xzf mpich-4.2.0rc3.tar.gz
cd mpich-4.2.0rc3
# 若已经执行过 ./configure，需要执行 make clean 命令进行清除
make clean
./configure --with-device=ch3:sock
make -j64
sudo make install
# 验证，mpich 工具默认安装在 /usr/local/bin 路径中
export PATH=/usr/local/bin:$PATH
mpirun --version

方式二：openMPI（Ubuntu 22.04 + Linux 5.15.0-105-generic 版本与 AI 部门对齐统一安装 5.0.6 版本，以方便问题排查）

# 查看可用的 openmpi 版本
apt list -a openmpi-bin
wget https://oss.mthreads.com/tmp/torch_musa_build/openmpi-5.0.6.tar.bz2
tar -jxf openmpi-5.0.6.tar.bz2
cd openmpi-5.0.6
./configure --prefix=/usr/local/openmpi --without-hcoll --without-ucx
make -j4 all
make install
# 验证，手动安装 openMPI 工具，统一安装在 /usr/local/openmpi 路径中
export PATH=/usr/local/openmpi/bin/:$PATH
mpirun --version

4. 安装 MCCL

tar -zxvf mccl*.tar.gz
cd mccl && ./install.sh

5. 验证

确认 MCCL 的安装版本：

# 确认版本
export LD_LIBRARY_PATH=/usr/local/musa/lib:$LD_LIBRARY_PATH
/usr/local/musa/bin/mccl_version

多机 config 文件配置（以两个节点为例）：

# 1. mpich 配置文件：hostfile_with_mpich
node1_ip:process_num
node2_ip:process_num

# 2. openMPI 配置文件：hostfile_with_openmpi
node1_ip slots=process_num
node2_ip slots=process_num

Step-by-Step：单机与多机功能验证

1. 设置基础环境变量：

   export PATH=/usr/local/musa/bin:$PATH
   export LD_LIBRARY_PATH=/usr/local/musa/lib:$LD_LIBRARY_PATH
   cd mccl/mccl-test/

2. 单机验证：

   ./all_reduce_perf -b 1M -e 1024M -f 2 -g 1

3. 多节点验证（以 openMPI 为例）：

   mpirun --allow-run-as-root --mca btl_tcp_if_include bond0 -hostfile ./hostfile_with_openmpi   -x LD_LIBRARY_PATH=/usr/local/musa/lib:/usr/local/lib   -x MCCL_PROTOS=2 -x MCCL_NET_SHARED_BUFFERS=0 -x MCCL_ALGOS=1 -x MCCL_IB_GID_INDEX=3   ./all_reduce_perf -b 1M -e 1024M -f 2 -g 1

4. 多节点验证（以 mpich 为例）：

   mpirun -hostfile ./hostfile_with_mpich   -env LD_LIBRARY_PATH=/usr/local/musa/lib:/usr/local/lib   -env MCCL_PROTOS=2 -env MCCL_NET_SHARED_BUFFERS=0 -env MCCL_ALGOS=1 -env MCCL_IB_GID_INDEX=3   ./all_reduce_perf -b 1M -e 1024M -f 2 -g 1

5. 判定标准：命令执行不报错即说明 MCCL 正常工作；若报错，请优先检查 IB/RoCE 网络配置与 hostfile 路径。

七、常见问题排查

问题 1：执行 musaInfo、musa_version_query、musa_runtime_version 等命令后找不到可执行程序

mt@mt:~$ musaInfo
musaInfo: command not found
mt@mt:~$ musa_version_query
musa_version_query: command not found
mt@mt:~$ musa_runtime_version
musa_runtime_version: command not found

解决办法：在 PATH 环境变量中加入 /usr/local/musa/bin/，同时在 LD_LIBRARY_PATH 环境变量中加入 /usr/local/musa/lib/：

export PATH=/usr/local/musa/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/musa/lib/:$LD_LIBRARY_PATH
musaInfo

问题 2：安装驱动 deb 后 musaInfo 报 initialization error(3)

下载并安装 MUSA Driver deb，执行 dpkg -i musa_xxx.deb，重启后执行 musaInfo 出现如下错误信息：

compiler: mcc
CreatePlatform failed!
error:'initialization error'(3) at /home/jenkins/agent/workspace/build.linux-ddk/linux-ddk/MUSA-Runtime/src/tools/musaInfo.cpp:155
error: API returned error code
error: TEST FAILED

解决办法：检查计算机重启后是否加载 MT GPU 内核模块，若否，执行内核模块加载命令：

lsmod | grep mtgpu
sudo modprobe mtgpu
export PATH=/usr/local/musa/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/musa/lib/:$LD_LIBRARY_PATH
musaInfo

若需要开机自启动 mtgpu 内核模块以进行自动加载，则需查找并注释 /etc/modprobe.d/ 目录下与 blacklist mtgpu 相关的行：

grep -irn "blacklist mtgpu" /etc/modprobe.d/
# 输出示例：
# /etc/modprobe.d/blacklist.conf:54:blacklist mtgpu
# /etc/modprobe.d/blacklist.conf:55:blacklist mtgpu
sudo sed -i 's/blacklist mtgpu/# blacklist mtgpu/g' /etc/modprobe.d/blacklist.conf
grep -irn "blacklist mtgpu" /etc/modprobe.d/
# /etc/modprobe.d/blacklist.conf:54:# blacklist mtgpu
# /etc/modprobe.d/blacklist.conf:55:# blacklist mtgpu

问题 3：新建用户未添加组权限导致 initialization error(3)

在 Ubuntu 操作系统上新建用户，未添加组权限，导致执行 musaInfo 命令后输出错误信息 'initialization error'(3)。

解决办法：

groups
# mt adm cdrom sudo dip plugdev lxd  （缺少 render、video）
sudo usermod -aG render mt
sudo usermod -aG video mt

添加组权限后，需执行 exit 命令退出，重新使用该用户账户登录：

exit
su mt
# mt adm cdrom sudo dip video plugdev render lxd
export PATH=/usr/local/musa/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/musa/lib/:$LD_LIBRARY_PATH
musaInfo

版本与兼容性

本课小结

课后练习

1. 简述在 MTT S5000 服务器上为何要关闭 IOMMU（VT-d），如果不关闭可能会导致什么问题？
2. 写出验证 GPU 硬件被系统正确识别、驱动生效、MUSA Toolkit 安装成功的三条命令，并说明各自的判定标准。
3. 参照本课 Hello MUSA 示例，编写一个内核函数，用 10 个线程并行输出各自线程 ID 与来自主机端的一条问候消息，说明其中 musaDeviceSynchronize() 的作用；若省略该调用会有什么风险？
4. MCCL 安装为何依赖 MPI 工具？简述 mpich 与 openMPI 两种安装路径的主要差异。
5. 新建的 Ubuntu 用户执行 musaInfo 报错 initialization error(3)，请列出至少两种可能原因及排查步骤。

与其他课程的衔接

• m11-l3（第 3 章）：本课 Hello MUSA 示例中的 __global__、三重尖括号启动语法，在 m11-l3 有更系统的编程模型讲解
• m11-l4（第 4 章）：本课安装的 muDNN、MCCL 加速库，其软件架构定位与分层关系见 m11-l4
• m11-l8（第 6 章）：本课 musaInfo 输出的硬件参数字段，下一课会讲解如何用 Runtime API 编程读取