MUSA SDK rc3.1.0 安装使用说明
1.下载软件包
# 软件包中应含包含以下文件
├── Installation_guide_for_MUSA_SDK_rc3.1.0.pdf
├── MUSA SDK rc3.1.0 发布说明.pdf
├── MUSA_Programming_Guide_v0.9.4.pdf
├── MCCL_rc1.7.0
│ ├── MCCL_API_Reference_rc1.7.0.pdf
│ └── mccl_rc1.7.0.tar.gz
├── MT_Linux_Driver_2.7.0
│ └── musa_2.7.0-rc3-0822_Ubuntu_amd64.deb
├── muTriton_rc1.0.0
│ └── triton_rc1.0.0.tar.gz
├── muDNN_rc2.7.0
│ └── mudnn_rc2.7.0.tar.gz
├── MUSA_Toolkits_rc3.1.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_rc3.1.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
- 将显示器连接到主板上，并断开电源重新启动计算机。 在启动过程中，按下 delete 键 以进入 BIOS 设置界面。
- 在 BIOS 设置界面中，找到并开启 above 4G 选项。
- 查找并将 resize bar 开关置为 ON。请注意，大部分主板在首次开机时此选项默认为 OFF，并且通常显示在 BIOS 菜单的右上角。
- 如果使用的是内存 >=256G 的服务器，则必须开启 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能看到图形界面。另外，请务必选择软重启，硬重启不能保证所有写入行为同步到文件。
- 按 F10 键保存 BIOS 配置并退出。
2.3 安装 MT 驱动 Deb 包
2.3.1 环境依赖
# 查看 pci 是否识别到显卡
lspci -nn | grep 1ed5
#安装依赖包（若已安装请忽略）
sudo apt install lightdm (安装时，default display manager 选择 lightdm)
sudo apt install dkms (如果为非 dkms deb 包，可忽略该步骤)
sudo apt install libgbm1 libglapi-mesa
2.3.2 卸载驱动
#卸载 old musa deb
sudo dpkg -P musa
#如果报错 mtgpu is inuse，直接重启即可
sudo rmmod mtgpu
#查询是否仍有 mtgpu ko 残留
lsmod |grep mtgpu
2.3.3 安装驱动
#安装 MT DDK 驱动，以 musa_2.7.0-rc3-0822_Ubuntu_amd64.deb包为例
sudo dpkg -i musa_2.7.0-rc3-0822_Ubuntu_amd64.deb
# 重启电脑来更换驱动（强烈建议）
sudo reboot
#如果特殊情况下希望不重启更换驱动，可以手动重新加载驱动
modprobe -rv mtgpu && modprobe mtgpu
2.3.4 设置用户组
非 Root 用户如需获取设备使用权限，可参考以下方式设置：
# 把普通用户账号，加进 render group。
sudo usermod -aG render ${USER}
sudo usermod -aG video ${USER}
# 重新登入账户
2.4 验证安装 && 版本查询
2.4.1 clinfo && mthreads-gmi
# 通过 clinfo 校验 DDK 安装。
clinfo |grep "Platform Name"
输出 Moore Threads OpenCL 即安装成功。
# 通过 mthreads-gmi 校验 DDK 安装。
mthreads-gmi
2.4.2 查看版本信息
#查看 UMD 版本信息
sed -i "1i /usr/lib/uname -m-linux-gnu/musa" /etc/ld.so.conf.d/uname -m-linux-gnu.conf
ldconfig /usr/lib/x86_64-linux-gnu/musa/
clinfo |grep "Driver Version"
#查看 KMD 版本信息
方式一 ：dmesg |grep "Driver Version"
方式二 ：cat /var/log/dmesg | grep "Driver Version"
2.5 其他
-
多卡环境，配置用户可见设备 通过设置 MUSA_VISIBLE_DEVICES 环境变量来指定。
-
如何开启显示桌面 Ubuntu 22.04 默认使用 gdm3，参考如下命令安装 lightdm:
apt install lightdmdpkg-reconfigure lightdm -
安装 video firmware
#解压 video_firmware 包unzip video_firmware.zipcd video_firmware/sudo cp -rf * /lib/firmware/ -
设置 DISPLAY 输出选项
# DP输出echo "options mtgpu display=dp" > /etc/modprobe.d/mtgpu.conf# HDMI输出echo "options mtgpu display=hdmi" > /etc/modprobe.d/mtgpu.conf# Dummy输出echo "options mtgpu display=dummy" > /etc/modprobe.d/mtgpu.conf -
关闭开机自动加载 mtgpu.ko
#在 /etc/modprobe.d/mtgpu.conf 中设置 blacklist。echo "blacklist mtgpu" >> /etc/modprobe.d/mtgpu.conf -
重新加载 ko 后需要重启 lightdm 来获取显示
systemctl stop lightdmsystemctl start lightdm -
删除 Xorg 配置文件
sed -i "s/lib\/xorg/local\/bin/" /usr/bin/Xldconfig /usr/local/lib
3.MUSA Toolkit 安装指南
本章主要描述了 MUSA Toolkit 的详细安装步骤。
前提条件
已安装兼容版本 MT GPU 驱动。
3.1 准备工作
- 检查 MT GPU 驱动版本。
mthreads-gmi
- 若未安装或未安装适配版本 MT GPU 驱 动，请参考上一节驱动安装。
3.2 安装 MUSA Toolkit
MUSA Toolkit 支持安装到主机（host）或 docker 环境中。
说明：
- 运行环境在 docker 上，建议在 docker 中安装 musa toolkit。
- 运行环境在 host 上，且需要安装 container toolkit 时。安装顺序为 musa toolkit > container toolkit，否则会和 container tookit 发生冲突。
3.2.1 安装
先进入到安装包的下载目录下，然后依次执行：
# 以musa_toolkits_rc3.1.0.tar.gz为例
tar -zxvf musa_toolkits_rc3.1.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
将输出如下结果：
说明：
这里仅展示重要信息，实际运行可能有其他详细信息
# 这里以1.5.0版本为例
musa_toolkits:
{
"version": "1.5.0"
}
mcc:
{
"version": "1.5.0"
}
mublas:
{
"version": "1.1.0",
"build archs": "21"
}
mufft:
{
"version": "1.2.0",
"build archs": "21"
}
muPP:
{
"version": "1.3.0",
"build archs": "21"
}
murand:
{
"version": "0.9.0",
"build archs": "21"
}
musify:
{
"version": "0.2.0"
}
musa_runtime:
{
"version": "1.5.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_rc2.7.0.tar.gz为例
tar -zxvf mudnn_rc2.7.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 网卡
- 已安装 Linux 操作系统的服务器
5.2 检查项目
确认以下开关、组件及其版本号，以便安装 MCCL 后能顺利运行。
# System BIOS & OS IOMMU enabled
# ib devices & ib driver
# DDK version
# KMD enable_rdma
# Smart IO with mt_peermem
# MUSA Toolkit version
5.3 配置IOMMU
5.3.1 确认内存容量
# check system physical memory size
sudo dmidecode -t memory | grep Size: | grep -v "No Module Installed" | awk '{sum+=$2}END{print sum}'
如果内存总量>256 GB，则请开启 IOMMU 以使能 GPU Direct peer-to-peer，否则 MCCL 的传输路径默认为 /dev/shm，该路径的通信带宽较低。
5.3.2 确认grub配置
sudo cat /var/log/dmesg | grep -e "AMD-Vi: Interrupt remapping enabled" -e "IOMMU enabled"
如出现 kernel: DMAR: IOMMU enabled 或者 kernel: AMD-Vi: Interrupt remapping enabled，则说明 IOMMU 已经打开并使能。
如不出现，则需要在grub中使能IOMMU并重启
# if IOMMU is off, perf the following steps
sudo sed -i 's/GRUB_CMDLINE_LINUX_DEFAULT="\(.*\)"/GRUB_CMDLINE_LINUX_DEFAULT="intel_iommu=on iommu.passthrough=0 pci=disable_acs_redir=pci:1000:c030"/' /etc/default/grub
# If your CPU is AMD/HG, please use amd_iommu=on, not intel_iommu=on
sudo update-grub
sudo reboot
注意：
第二行会清除系统上原有的 quiet，以保证重启后 BMC 能看到图形界面。另外，请务必选择软重启，硬重启不能保证所有写入行为同步到文件。
pci=disable_acs_redir=pci:1000:c030中的1000:c030是GPU上游PCIe switch或者root complex设备的vendor:device号，默认为S4000 MCCX2.0中的1000:c030。不同服务器的upstream设备不同，可以按照如下脚本查询将终端得到的vendor:device字段，如下列的
1000:c030填到pci=disable_acs_redir=pci:后即可
5.3.3 确认BIOS配置
如果 BMC 有 BIOS checking 功能，可以先检查 VT-d (Intel) / IOMMU (AMD or HG) 是否已被打开。
如果当前处于 IOMMU disabled 状态，则需要在 BIOS 以及 grub 中手动开启 IOMMU：
- Intel 平台：使能（enable） **Intel VT for Directed I/O (VT-d)**选项。
- AMD 或海光平台：使能 IOMMU选项。
5.4. 配置网络
如果没有 IB 网卡，只有以太网，则无需配置 IB。
5.4.1 安装 IB 驱动
如果 有 IB 网卡，但是 IB 驱动未安装，请先安装 IB 驱动。
5.4.2 配置 OpenSM 服务(可选)
如果没有 IB 交换机，2 台服务器间 IB 端口通过 IB 光纤直连，可配置 OpenSM 服务。
5.4.2.1 配置 OpenSM
两台服务器都需要做以下配置：
opensm --create-config /etc/opensm/opensm.conf
编辑修改 /etc/opensm/opensm.conf 以下内容：
routing_engine updn
sm_priority 13 # 范围为 0-15，这里两台服务器sm_priority要不一样，数值大的为 master，另一台即为 back。
如果一台服务器有多个 IB 端口，需要同时运行 OpenSM 服务，可进行以下配置：
-
手动，对每个 IB 端口启动 opensm 服务。
opensm -B -g <port guid> # 如 opensm -B -g 0xb83fd203005686b2 -
自动，在
/etc/opensm/opensm.conf中，guid 项添加多个 IB 端口 guid，以逗号隔开，如：# DEVICE ATTRIBUTES OPTIONS## The port GUID on which the OpenSM is running.# Multiple port GUIDs can be specified separated by comasguid 0xb83fd2030056874a,0xb83fd203005686b2
5.4.2.2 启动 OpenSM
手动启动：
systemctl start opensm # 或 /etc/init.d/opensmd start
设置开机启动：
systemctl enable opensm
5.4.2.3 检查 OpenSM 是否正常工作
sudo mst status
5.4.3 验证 IB 是否工作
通过 ibstat 命令查看 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.5 安装 MT GPU 驱动
请确保 MT GPU 驱动正确安装，参考前面的驱动安装章节。
如果使用容器环境工作，更新驱动后，请务必重启容器，以便在容器中使能新驱动。
5.6 安装 MT SmartIO
如果已安装旧版本，请先卸载：
sudo rmmod mt_peermem
安装 MT SmartIO, 以 smartio_rc1.2 为例：
sudo dpkg -i mt-peermem_1.2_amd64.deb
5.7 安装 MUSA Toolkit
请确保安装正确版本的 MUSA Toolkit，参考前面MUSA Toolkit安装指南章节。
重要提示：
MUSA Toolkit 需要安装在运行环境中：
- 运行环境在 host 端，则需要先安装 MUSA Toolkit，再安装 MT container toolkits，否则 MUSA Toolkit 会和 MT container toolkits发生文件冲突。
- 运行环境在 docker 容器中，直接在 docker 容器中安装 MUSA Toolkit。
完装完毕后，请根据提示，配置相关环境变量。
5.8 检查驱动及 MUSA Toolkit 是否安装 成功
/usr/local/musa/bin/driver_version_query
/usr/local/musa/bin/musa_version_query
/usr/local/musa/bin/musaInfo
5.9 安装 MCCL
安装 MCCL 包，以 mccl_rc1.7.0.tar.gz 为例：
sudo tar -zxvf mccl_rc1.7.0.tar.gz
cd ./mccl
sudo ./install.sh -id /usr/local
5.10 环境优化
除了 IOMMU 特性，系统中的其他特性也会对通信性能造成一定影响，如：处理器的动态调频技术，UPI 总线的能效管理功能等。
为了获取最佳性能，建议您在不同服务器上为 MCCL 设置如下对应的优化选项。
- MCCX 1.0 (Lenovo D800)
| OPTION | VALUE |
|---|---|
| OPTION | VALUE |
| Devices and I/O Ports->MM Config Base | 3GB |
| Operation Mode | Maximum Performance |
| Power->Workload Configuration | I/O sensitive |
| Memoy->Patrol Scrub | Disabled |
| Processor->SNC | Enabled |
- MCCX 2.0 (H3C)
| OPTION | VALUE |
|---|---|
| Socket Configuration→Advance Power Management Configuration→Workload Profile Configuration | Low Latency |
| Socket Configuration→Common RefCode Configuration→Virtual Numa | Enabled |
| Socket Configuration→Advance Power Management Configuration→CPU-Advanced PM Tuning→Energy Perf BIAS→Workload Configuration | I/O sensitive |
注意：
在 MCCX 2.0 上，部分 BIOS 优化选项不会生效，如：CPU Power Management 的 governor 配置。所以进入系统后，您可以执行以下命令来使 CPU 进入 performance 模式。
sudo cpupower -c all frequency-set -g performance
如果出现以下日志，则说明当前平台不支持 Linux OS 下配置 CPU 运行频率。
Setting cpu: 0
Error setting new values. Common errors:
- Do you have proper administration rights? (super-user?)
- Is the governor you requested available and modprobed?
- Trying to set an invalid policy?
- Trying to set a specific frequency, but userspace governor is not available,
for example because of hardware which cannot be set to a specific frequency
or because the userspace governor isn't loaded?
