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?
