MUSA SDK 4.3.0 安装使用说明
1.下载软件包
# 软件包中应含包含以下文件
├── Installation_guide_for_MUSA_SDK_rc4.3.0.pdf
├── MUSA SDK rc4.3.0 发布说明.pdf
├── MUSA_Programming_Guide_v0.9.4.pdf
├── MCCL_rc2.1.0
│ ├── MCCL_API_Reference_rc2.1.0.pdf
│ └── mccl_rc2.1.0.tar.gz
├── MT_Linux_Driver_3.1.0
│ └── musa_3.3.0-server_amd64.deb
├── muTriton_rc1.4.0
│ └── triton_rc1.4.0.tar.gz
├── muDNN_rc3.1.0
│ └── mudnn_rc3.1.0.tar.gz
├── MUSA_Toolkits_rc4.3.0
│ ├── docs
│ │ ├── muBLAS_API_Reference_rc1.6.0.pdf
│ │ ├── muDNN_API_Reference_rc2.7.0.pdf
│ │ ├── muFFT_API_Reference_rc1.6.0.pdf
│ │ ├── muSOLVER_API_rc1.0.0.pdf
│ │ ├── muSPARSE_API_Reference_rc1.1.0.pdf
│ │ ├── muPP_API_Reference_rc1.7.0.pdf
│ │ ├── muRAND_API_Reference_rtm1.0.1.pdf
│ │ ├── MUSA_Compiler_Collection_User_Manual_rc3.1.0.pdf
│ │ ├── MUSA_Driver_API_Reference_rc3.1.0.pdf
│ │ └── MUSA_Runtime_API_Reference_rc3.1.0.pdf
│ └── musa_toolkits_rc4.3.0.tar.gz
└── SmartIO_1.2
└── mt-peermem_1.2_amd64.deb
2.驱动安装
2.1 资源需求：
- MT GPU 卡
- 操作系统：Ubuntu 22.04
- 内核版本 5.15.0-105-generic
说明：
集群内部机器 无法直接在宿主机上安装 deb 包，请卸载 operator 相关组件后安装。
2.2 配置 Bios
- 如果使用的是内存 >=256G 的服务器，且显卡是S4000，则必须 开启 IOMMU（VT-d） 选项,
- 如果使用的显卡是S5000, 则必须 关闭 IOMMU (VT-d) 选项。
# 如果 IOMMU 是关闭的, 可通过如下步骤开启
sudo sed -i 's/GRUB_CMDLINE_LINUX_DEFAULT="\(.*\)"/GRUB_CMDLINE_LINUX_DEFAULT="intel_iommu=on iommu.passthrough=0"/' /etc/default/grub
# 如果你的 CPU 是 AMD/HG, 请改为 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"
#注意：第二行会清除系统上原有的quiet，以保证重启后BMC能看到图形界面。另外，请务必选择软重启 ，硬重启不能保证所有写入行为同步到文件。
- 如果是PC，需要将BIOS中的
resize bar选项设置为ON
- 将显示器连接到主板上，并断开电源重新启动计算机。 在启动过程中，按下 delete 键 以进入 BIOS 设置界面,
- 在 BIOS 设置界面中，找到并开启 above 4G 选项
- 查找并将 resize bar 开关置为 ON。请注意，大部分主板在首次开机时此选项默认为 OFF，并且通常显示在 BIOS 菜单的右上角
- 重启计算机，系统正常加载后，执行
lspci -nn | grep 1ed5确认显卡已识别
2.3 安装 MT 驱动 Deb 包
2.3.1 环境依赖
# 查看 pci 是否识别到显卡
lspci -nn | grep 1ed5
#安装依赖包（若已安装请忽略）
sudo apt install linux-headers-$(uname -r)
sudo apt install linux-modules-$(uname -r)
sudo apt install linux-modules-extra-$(uname -r)
sudo apt install dkms
2.3.2 卸载驱动
#卸载 old musa deb
sudo dpkg -P musa
#如果报错 mtgpu is inuse，直接重启即可
sudo modprobe -rv mtgpu
#查询是否仍有 mtgpu ko 残留
lsmod |grep mtgpu
2.3.3 安装驱动
#安装 MT DDK 驱动，以 musa_3.3.0-server_amd64.deb包为例
sudo apt install ./musa_3.3.0-server_amd64.deb
# 重启电脑来更换驱动（强烈建议）
sudo reboot
#如果特殊情况下希望不重启更换驱动，可以手动重新加载驱动
modprobe -rv mtgpu && modprobe -v mtgpu
2.3.4 设置用户组
非 Root 用户如需获取设备使用权限，可参考以下方式设置：
# 把普通用户账号，加进 render & video group。
sudo usermod -aG render,video ${USER}
# 重新登入账户
2.4 验证安装 && 版本查询
2.4.1 mthreads-gmi
# 通过 mthreads-gmi 校验 DDK 安装。
# 命令行执行mthreads-gmi，能够展示gmi版本号、Driver版本号、显卡相关主要信息等
mthreads-gmi
2.4.2 查看版本信息
# 可通过包管理器或者mthreads-gmi工具查看驱动的版本信息
dpkg -s musa
# 或者
mthreads-gmi
2.5 其他
-
多卡环境，配置用户可见设备 通过设置
MUSA_VISIBLE_DEVICES环境变量来指定使用的显卡，如export MUSA_VISIBLE_DEVICES=0,1,2,3指定前4张显卡可见。 -
关闭开机自动加载 mtgpu.ko
# 在 /etc/modprobe.d/blacklist.conf 中设置echo "blacklist mtgpu" >> /etc/modprobe.d/blacklist.conf
3.MUSA Toolkit 安装指南
本章主要描述了 MUSA Toolkit 的详细安装步骤。
前提条件
已安装兼容版本 MT GPU 驱动。
3.1 准备工作
- 检查 MT GPU 驱动版本。
mthreads-gmi
- 若未安装或未安装适配版本 MT GPU 驱动，请参考上一节驱动安装。
3.2 安装 MUSA Toolkit
MUSA Toolkit 支持安装到主机（host）或 docker 环境中。
说明：
运行环境在 docker 上，建议通过container-toolkit 创建容器, 否则需要手动映射host上的
/usr/lib/x86_64-linux-gnu/libmusa.so*到容器中。
3.2.1 安装
先进入到安装 包的下载目录下，然后依次执行：
# 以musa_toolkits_rc4.3.0.tar.gz为例
tar -zxvf musa_toolkits_rc4.3.0.tar.gz
cd musa_toolkits_install
bash ./install.sh -u # 先卸载环境已安装的musa
bash ./install.sh # 以上两条命令非root用户需要sudo提权执行
正常安装完毕后，终端会输出如下提示：
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}
3.2.2 设置环境变量
-
文本编辑器打开用户终端配置文件：
vim ~/.bashrc -
在打开的配置文件末尾追加如下命令：
export MUSA_INSTALL_PATH=/usr/local/musaexport PATH=$MUSA_INSTALL_PATH/bin:$PATHexport LD_LIBRARY_PATH=$MUSA_INSTALL_PATH/lib:$LD_LIBRARY_PATH -
配置文件会在下次启动终端时生效。如果想立即在当前终端生效，请执行：
source ~/.bashrc
3.2.3 验证
验证 MUSA Toolkit 是否安装成功，运行以下命令。
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是否能正常运行，运行一下命令musaInfo, 正常会有如下输出：
$ musaInfo
compiler: mcc
--------------------------------------------------------------------------------
device# 0
Name: MTT S80
pciBusID: 1
pciDeviceID: 0
pciDomainID: 0
multiProcessorCount: 32
maxThreadsPerMultiProcessor: 6144
isMultiGpuBoard: 1
clockRate: 1800.04 Mhz
memoryClockRate: 7000 Mhz
memoryBusWidth: 256
totalGlobalMem: 15.92 GB
sharedMemPerMultiprocessor: 28.00 KB
totalConstMem: 8192
sharedMemPerBlock: 28.00 KB
canMapHostMemory: 1
regsPerBlock: 262144
warpSize: 128
l2CacheSize: 25165824
computeMode: 0
maxThreadsPerBlock: 1024
maxThreadsDim.x: 1024
maxThreadsDim.y: 1024
maxThreadsDim.z: 1024
maxGridSize.x: 2147483647
maxGridSize.y: 2147483647
maxGridSize.z: 2147483647
major: 2
minor: 1
concurrentKernels: 1
cooperativeLaunch: 0
cooperativeMultiDeviceLaunch: 0
isIntegrated: 0
maxTexture1D: 32768
maxTexture2D.width: 32768
maxTexture2D.height: 32768
maxTexture3D.width: 16384
maxTexture3D.height: 16384
maxTexture3D.depth: 2048
peers:
non-peers: device#0
memInfo.total: 15.92 GB
memInfo.free: 15.79 GB (99%)
4.muDNN 安装指南
本章主要描述了 muDNN 的详细安装步骤。
4.1 准备工作
已安装兼容版本 MT GPU 驱动及MUSA Toolkit。
4.2 安装 muDNN
4.2.1 安装
# 以mudnn_rc3.1.0.tar.gz为例
tar -zxvf mudnn_rc3.1.0.tar.gz
cd mudnn && ./install_mudnn.sh -i
4.2.2 设置环境变量
DNN_PATH=$(realpath mudnn)
export LD_LIBRARY_PATH=${DNN_PATH}/lib:$LD_LIBRARY_PATH
安装完成后，您可以查看 muDNN 的所有 API。
5.MCCL 安装指南
本章主要描述了如何配置 MCCL 运行环境及其安装步骤。
5.1 前置条件：
- 多张 MT GPU 卡(单节点/多节点)
- 一块或多块 InfiniBand 网卡
- 已安装MUSA驱动
- 已安装MUSA Toolkits软件包
- 已安装mtml （容器内部直接安装mtml或者通过host端映射（若是通过container-toolkit方式起的容器，会直接映射进去））
5.2. 配置网络
如果没有 IB 网卡，只有以太网，则无需配置 IB。PH1架构走的RoCE网络，需要使用环境变量指定RoCE v2协议（MCCL_IB_GID_INDEX=3）
5.2.1 安装 IB 驱动
如果有 IB 网卡，但是 IB 驱动未安装，请先安装 IB 驱动。
5.2.2 验证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
如果其中一个 network port 的 physical state 是 LinkUp，而且 Link layer 标明为 InfiniBand，就说明已经使能了 IB 网络。
5.3 安装mpich或者openMPI（多机场景安装）
MPI工具为MCCL提供跨节点的进程管理和通信基础，协调不同机器间的初始连接。多机场景下需要安装MPI工具。
#以下两种工具二选一安装即可
#1. mpich工具安装，安装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
#2. openMPI工具安装
#查看可用openmpi版本
apt list -a openmpi-bin
#安装openMPI（Ubuntu 22.04 + Linux 5.15.0-105-generic版本与AI部门对齐统一安装5.0.6版本，方便问题排查）
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
5.4 安装 MCCL
安装 MCCL 包，以 mccl_rc1.7.0.tar.gz 为例：
sudo tar -zxvf mccl_rc1.7.0.tar.gz
cd ./mccl
sudo bash ./install.sh
5.5 验证
#确认版本
export LD_LIBRARY_PATH=/usr/local/musa/lib:$LD_LIBRARY_PATH
/usr/local/musa/bin/mccl_version
#多机config文件配置(2节点为例)
#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
#功能验证（单机+多机）
export PATH=/usr/local/musa/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/musa/lib:$LD_LIBRARY_PATH
cd mccl/mccl-test/
#单机验证
./all_reduce_perf -b 1M -e 1024M -f 2 -g 1
#multi cluster verify with 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
#multi cluster verify with 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
