Appearance
虚拟化配置
该章节是上层应用需要运行在虚拟化环境时才配置，直接运行在物理机上的应用环境配置可跳过该章节。
Docker
IB驱动安装
Docker中安装ib驱动有如下几种方式，安装完成后检查 ibv_devices 和 ibstat 命令，在容器和宿主机的打印是否一致，若一致说明安装正常。
用户态核心组件安装：
docker中只需ib的用户态驱动，安装RDMA-Core的相关软件包可满足要求：
bash
sudo apt-get install -y libibverbs1 librdmacm1 ibverbs-providers libibumad3 libibverbs-dev librdmacm-dev ibverbs-utils libibumad-dev opensmDockerfile自动安装安装包：
使用Dockerfile，预先下载ib驱动（参考2.3下载），放在dockerfile同一目录。
ubuntu系统的dockerfile示例如下：（其他操作系统的请参考内网通信库wiki）
#1)根据测试需要，设置基础镜像源
FROM mxcr.io/library/maca-c500@sha256:79dccb5aa62845827ce4c71ed6cc5fde09b316cbe354d3fb94835a87d8761e46
#FROM mxcr.io/library/maca-c500@sha256:c76ec4fa9b2eae1b8449c352c2e5ef406ec1cee5a67152ce1bc8de4820b5f493
#FROM mxcr.io/library/maca-c500@sha256:388af931eb88fcad5867e0e6216ca11d5fe3f5d1deca048f13de99037d5156cd
WORKDIR /opt
#2)可选，设置debian软件源：vdi内可参考如下配置，其他情况根据实际配置
RUN sed -e 's@http.*com/ubuntu@http://repo.metax-tech.com/r/ubuntu@g' -e 's@http.*cn/ubuntu@http://repo.metax-tech.com/r/ubuntu@g' -i.bak /etc/apt/sources.list
#3)安装依赖包
RUN apt-get update
RUN apt-get install -y libcap2
RUN apt-get install -y libperl-dev
RUN apt-get clean
#4)选择合适的ib驱动版本，根据镜像的系统(cat /etc/os-release)和cpu架构(lscpu)
ARG MOFED_VER=5.8-3.0.7.0
ARG OS_VER=ubuntu18.04
ARG PLATFORM=x86_64
ARG PACKAGE_NAME=MLNX_OFED_LINUX-${MOFED_VER}-${OS_VER}-${PLATFORM}
#ARG PACKAGE_NAME=MLNX_OFED_LINUX-5.8-3.0.7.0-ubuntu18.04-x86_64
#5)离线下载ib驱动包，将安装包放在与dockerfile同一目录下
COPY ${PACKAGE_NAME}.tgz /opt
#5)机器若能访问mellanox官网，也可以在线下载ib驱动
#RUN wget --quiet http://content.mellanox.com/ofed/MLNX_OFED-${MOFED_VER}/MLNX_OFED_LINUX-${MOFED_VER}-${OS_VER}-${PLATFORM}.tgz
#6)安装ib驱动，安装完成后，在容器检查ibstat和ibv_devinfo输出是否和宿主机一致，若一致说明安装正常
RUN tar -xvf ${PACKAGE_NAME}.tgz
RUN sed -i 's/\(my $installed_debs = `dpkg-query -l "\*\$name\*" 2> \/dev\/null\) |/\1 | grep -vE "mxucx|maca" |/' ./${PACKAGE_NAME}/mlnxofedinstall
RUN sed -i 's/\(my $installed_debs = `dpkg-query -l "\*\$name\*" 2> \/dev\/null\) |/\1 | grep -vE "mxucx|maca" |/' ./${PACKAGE_NAME}/uninstall.sh
RUN ./${PACKAGE_NAME}/mlnxofedinstall --force --user-space-only --without-neohost-backend --without-ucx
#7)可选，多docker mccl 测试参考如下配置:
#7.1 安装依赖包
RUN apt-get -y --no-install-recommends install openssh-server
#7.2 设置ssh端口号，如11022；允许root登录
RUN cat /etc/ssh/sshd_config | grep -vE "Port|PermitRootLogin" > /etc/ssh/sshd_config.new && \
echo " Port 11022" >> /etc/ssh/sshd_config.new && \
echo " PermitRootLogin yes" >> /etc/ssh/sshd_config.new && \
mv /etc/ssh/sshd_config.new /etc/ssh/sshd_config && \
service ssh restart
#7.3 修改root用户密码，生成密钥
RUN echo "root:1" | chpasswd && \
ssh-keygen -t rsa -f ~/.ssh/id_rsa -N "" -q
#7.4 设置mpirun --allow-run-as-root
ENV OMPI_ALLOW_RUN_AS_ROOT=1
ENV OMPI_ALLOW_RUN_AS_ROOT_CONFIRM=1
#7.5 容器启动后，设置免密登录到对端ip地址上
#ssh-copy-id root@xx.xx.xx.xx -p11022
#7.6 mpirun 运行多个docker mccl测试，需添加参数
#-mca plm_rsh_args "-p 11022"生成镜像
bash
docker build -t my_image:my_tag -f Dockerfile_ubuntu .mlx网卡docker中手动安装安装包
除了在物理机上安装ib驱动外，还需要在docker中安装用户态的ib驱动（ubuntu参考第2.3节，下载驱动和修改安装脚本。注意：安装参数与宿主机的不一样，见下面绿色部分）。
首先启动docker，执行如下命令（以ubuntu20.04-x86_64为例）：
bash
apt install libpci-dev
apt install perl
./mlnxofedinstall --user-space-only --without-neohost-backend --without-ucx博通网卡docker中安装网卡驱动
需要单独执行驱动包中脚本，在物理机上运行命令如下：
bash
./Docker/install_to_docker.sh -d ID #这里ID是指需要安装的容器ID，如果不指定，则默认安装到机器上所有容器启动docker
bash
docker run -it --rm --init --detach --net=host --uts=host --ipc=host --privileged=true --group-add video --device=/dev/dri --device=/dev/mxcd --shm-size=64g --ulimit memlock=-1 <my_image:my_tag> /bin/bash参数解释
- --privileged=true
透传IB网卡给docker
【多机必需：ib网卡挂载】考虑安全性和隔离性，--privileged=true参数也可用 --device=/dev/infiniband 代替。
- 特殊文件映射，参考6.5章节
如果涉及virtualSwitch，需注意映射或拷贝相关目录到docker中。如映射，则启动docker时添加参数：
-v /opt/pci_switch_link:/opt/pci_switch_link:ro
网卡透传检查
docker启动后检查网卡有没有透传成功。
如图docker执行ibv_devinfo显示fail表示没有透传成功
Docker中运行MCCL Perf Test
1、安装openssh-server/client
bash
apt update
apt install openssh-server
apt install openssh-client2、 重置 docker root用户密码（可选）：
bash
passwd root3、配置docker网络端口号 <1> vim /etc/ssh/sshd_config，设置如下字段，端口号可自己设置 Port 11022 PermitRootLogin yes <2> service ssh restart
4、配置两机docker免密登录
bash
ssh-keygen -t rsa
ssh-copy-id -p 11022 root@xx.xx.xx.xx验证是否设置成功，在本机可以不用输入密码登录到对端机器：ssh root@xx.xx.xx.xx -p 11022
5、mpirun运行mccl时，添加参数
-mca plm_rsh_args "-p 11022"
Docker镜像
黄区(北京)：https://sw-harbor-bj.mxcr.io 黄区(临港)：https://sw-harbor-lg.mxcr.io 绿区：https://mxcr.io
mxcr.io/cimaster和mxcr.io/library用于存放MXMACA软件栈的基础镜像， 其中cimaster用于存放master分支的每日构建，library仓则用于正式release的版本。
虚拟机（qemu PF透传）
物理机开启iommu
1、修改物理机/etc/default/grub：在GRUB_CMDLINE_LINUX_DEFAULT这一行末尾增加如下iommu相关参数:
intel平台: "iommu=pt intel _iommu=on"
amd平台: "iommu=pt amd_iommu=on"
修改后，更新配置：
bash
sudo update-grub重启物理机：
reboot
2、重启后检查iommu配置生效：cat /proc/cmdline
Mellanox网卡配置
1、使能物理机网卡ATS
- 开启mst管理工具
bash
sudo mst start
sudo mst status -v
- 检查所有网卡的ATS状态，例如 /dev/mst/mt4129_pciconf0代表connect X-7 网卡，通过sudo mst status查询得到。
bash
sudo mlxconfig -d /dev/mst/mt4129_pciconf0 query | grep -i ATSATS_ENABLED False(0) //表示ATS没有开启
- 如果网卡没有开启ATS，可通过下面命令开启ATS
bash
sudo mlxconfig -d /dev/mst/mt4123_pciconf0 set ATS_ENABLED=truereboot 载入新配置
检查网卡ATS是否使能
bash
sudo mlxconfig -d /dev/mst/mt4129_pciconf0 query | grep -i ATSATS_ENABLED True(1)
bash
sudo lspci -s ab:00.0 -vvv | grep -i ATSCapabilities: [480 v1] Address Translation Service (ATS)
ATSCap: Invalidate Queue Depth: 00
ATSCtl: Enable+, Smallest Translation Unit: 00
2、使能物理机网卡和GPU上游pcie bridge的 ACS Direct Translate
1）通过脚本开启
最简捷的办法是，通过下面脚本使能ACS的DirectTranslate
#!/bin/bash
for BDF in `lspci -d "*:*:*" | awk '{print $1}'`; do
# skip if it doesn't support ACS
sudo setpci -v -s ${BDF} ECAP_ACS+0x6.w > /dev/null 2>&1
if [ $? -ne 0 ]; then
continue
fi
sudo setpci -v -s ${BDF} ECAP_ACS+0x6.w=0x5D
done2）手动开启
在物理机上lspci -tvvv查看网卡和GPU进行pcie p2p通信要经过的上游pcie bridge
从图可知bridge设备号有：
10:10.0 05:0c.0
在物理机上用如下命令使能pcie bridge ACS的DirectTranslate
bash
setpci -s 10:10.0 ECAP_ACS+6.w=5d
setpci -s 05:0c.0 ECAP_ACS+6.w=5d在物理机上通过 sudo lspci -s 10:10.0 -vvv | grep ACSCtl查看是否开启成功，如图DirectTrans+代表开启，DirectTrans-代表未开启
qemu 配置
咨询虚拟化团队
MCCL相关配置
- 如果虚拟机中GPU拓扑与物理机不一致，需要在虚拟机导入物理机拓扑xml文件。
1）物理机导出topo文件：设置环境变量 MCCL_TOPO_DUMP_FILE=topo.xml，跑一下单机所有卡allreduce，跑完后会生成topo.xml文件；
2）虚拟机导入topo文件：将生成的topo.xml文件拷贝到虚拟机中，跑测试时设置环境变量MCCL_TOPO_FILE=topo.xml 导入topo信息。
- 虚拟机中MCCL_PCIE_BUFFER_MODE设置
GPU vbios不支持ATS，MCCL_PCIE_BUFFER_MODE需要设置为0；
GPU vbios支持ATS的，MCCL_PCIE_BUFFER_MODE无需设置。
GPU ATS特性（可选）
MACA版本在2.25之后，增加PCI ATS特性支持，解决开启IOMMU后多个物理卡透传到虚拟机后P2P性能过低问题。
- 软件包ATS安装：
支持ATS的PF vbios版本，后缀带有*-ATS.bin；
支持ATS的metax ko.
- 检测vbios版本是否支持ATS:
bash
sudo Ispci -s <bdf> -vvv I grep -i ATSCtrl若有匹配到该关键字说明vbios支持ATS；如果ATSCtrl的值为-，表明ATS功能没有开启，值为+表明ATS已开启。
- 开启ATS功能
虚机场景下无需人工开启ATS，hypervisor在启动虚机时会自动开启ATS，虚机启动后在宿主机和虚机中应当可以看到ATSCtrl的值从-变为+.
- 宿主机上开启PCI bridge的ACS DirectTrans功能。
通信测试
在开启虚拟机的场景下执行通信库的测试需要注意
单机mccl的通信测试时需增加 export MCCL_PCIE_BUFFER_MODE=0， 关闭PCIE；
deepep或多机mccl等需要使用网卡的通信场景，则需要开启网卡的ATS功能，具体配置请查看7.2.2节。
GPU VF
1、VF开启及版本安装
用VF功能，应该安装带VF后缀的vbios bin
默认配置安装:
sudo ./mxmaca-install.sh -f --vt-mode=flat (flat模式) 或
sudo ./mxmaca-install.sh -f --vt-mode=pt (vf透传模式)
默认VF个数是从"/etc/mxgvm_config"配置文件获取，如果没有此配置文件(系统没加载过mxgvm)时，VF个数为chip支持的最大个数，C500即是8个；
改变VF个数，执行"rmmod metax"和"rmmod mxgvm"卸载内核驱动，
重新执行“sudo modprobe mxgvm vf_num=N”(N表示VF个数)
- 指定vf_num安装：
如果机器已经加载了metax , 请先执行 sudo rmmod metax 卸载；
到maca安装包的deb目录下执行 sudo dpkg -i mxgvm* 安装 或 sudo rpm -i mxgvm* ；
sudo modprobe mxgvm vf_num=4
2、VF关闭及版本卸载
如果不使用虚拟化功能，卸载组件则执行：
sudo ./mxmaca-install.sh -U --vt-mode=flat (flat模式) 或
sudo ./mxmaca-install.sh -U --vt-mode=pt (vf透传模式)
3、VF场景下P2P测试及MCCL测试相关问题
- vf场景下，单个物理卡内的vf间p2p是否ok，与iommu配置有关。mccl测试如果用到卡内的两个或多个vf，vf间p2p失败会导致程序hang。解决方法有：
1）开启iommu，方法见5.2.1章节。把 iommu 打开后，强制所有流量都走到 RC。若每个 PF 上都有一个 switch，跨卡的 p2p 流量就会走到上级 switch；不跨卡的 p2p 流量只能在 switch 内部，这种情况看起来不支持。
2）mccl disable p2p, 设置环境变量：export MCCL_P2P_DISABLE=1
3）选择不同卡的一个vf，避免选择一张卡两个或多个vf：
CUDA_VISIBLE_DEVICES=0,4,8等（假设vf num=4）
- 单进程跑all-reduce-perf，hang问题：
参考命令：./all_reduce_perf -b 1024 -e 1G -f 2 -g 1 -n 10 -t 4
nccl channel数目对应blocks数，开启vf情况下，ap数目有限，需保证channel数目小于等于ap数目(vf_num = 8)；可设置channel数目： export MCCL_MIN_NCHANNELS=8 export MCCL_MAX_NCHANNELS=8
- 多进程跑all-reduce-perf，hang问题：
参考命令：${OMPI_PATH}/bin/mpirun -mca pml ^ucx -np 4 ./nccl-tests/build/all_reduce_perf -b 1024 -e 256M -f 2 -g 1 -n 10 创建ce或dma queue数目大于vf中的queue最大值，除了设置channel数目，还需开启queue调度： export MACA_MPS_MODE=1
Mellanox网卡VF
当前应用较少，如需设置，可参考链接
INFINIBAND
ETHERNET