diff --git a/MACA.md b/MACA.md new file mode 100644 index 0000000..5d103ad --- /dev/null +++ b/MACA.md @@ -0,0 +1,298 @@ +# MACA SDK + +### 适配 Centos、Kylin 系统 + +- **配置YUM源** + + ```bash + cat < /etc/yum.repos.d/maca-sdk-rpm.repo + [maca-sdk] + name=Maca Sdk Yum Repository + baseurl=https://repos.metax-tech.com/r/maca-sdk-rpm-$(uname -m)/ + enabled=1 + gpgcheck=0 + EOF + + yum makecache + ``` + +#### 安装MACA SDK + + - **安装maca_sdk最新版本** + ```bash + yum install maca_sdk + ``` + + - **安装maca_sdk指定版本** + ```bash + yum --showduplicates list |grep maca_sdk + yum install maca_sdk-- + ``` + + - **升级maca_sdk到最新版本** + ```bash + yum update maca_sdk + ``` + + - **卸载maca_sdk** + ```bash + yum autoremove maca_sdk + ``` + + + +### 适配 Ubuntu 系统 + +- **配置APT源** + ```bash + curl -fsSL https://repos.metax-tech.com/public.gpg.key | apt-key add - + echo "deb [arch=$(dpkg --print-architecture)] https://repos.metax-tech.com/r/maca-sdk-deb/ stable main" | tee /etc/apt/sources.list.d/maca-sdk-deb.list + apt-get update + + ``` + +#### 安装MACA SDK + + - **安装maca_sdk最新版本** + ```bash + apt install maca_sdk + ``` + + - **安装maca_sdk指定版本** + ```bash + apt list --all-versions |grep maca_sdk + apt install maca_sdk= + ``` + + - **升级maca_sdk到最新版本** + ```bash + apt install --only-upgrade maca_sdk + ``` + + - **卸载maca_sdk** + ```bash + apt autoremove maca_sdk + ``` + + +# Metax Driver + + +### 平台兼容列表 + +| CPU架构 | 操作系统 | 内核版本 | 状态 | +|-----------|----------------|------------------------------------|----------------------| +| x86_64 | Ubuntu 18.04 | 5.4.0-42-generic | 支持 | +| | | 5.4.0-131-generic | | +| | | 5.4.0-148-generic | | +| x86_64 | Ubuntu 20.04 | 5.4.0-26-generic | 支持 | +| | | 5.4.0-42-generic | | +| | | 5.15.0-58-generic | | +| x86_64 | Ubuntu 22.04 | 5.15.0-72-generic | 支持 | +| | | 5.19.0-46-generic | | +| x86_64 | CentOS 8 | 4.18.0-240.el8.x86_64 | 支持 | +| x86_64 | RedHat 8.3 | 4.18.0-240.el8.x86_64 | 支持 | +| x86_64 | RedHat 8.6 | 4.18.0-372.9.1.el8.x86_64 | 支持 | +| x86_64 | RedHat 9 | 5.14.0-70.22.1.el9_0.x86_64 | 支持 | +| x86_64 | CentOS 7 | 4.19.0-1.el7.elrepo.x86_64 | 支持加载Docker Container形式 | +| | | 5.14.0-7.x86_64 | | +| x86_64 | BC Linux | 4.19.90-2107.6.0.0100.oe1.bclinux | 支持 | +| x86_64 | BCLinux R8 U2 | 4.19.0-240.23.11.el8_2.bclinux.x86_64 | 支持 | +| x86_64 | CC Linux | 5.15.131-2.cl9.x86_64 | 支持 | +| x86_64 | Kylin V10 SP2 | 4.19.90-24.4.v2101.ky10.x86_64 | 支持 | +| x86_64 | ALinux3 | 5.10.134-13.1.al8.x86_64 | 支持 | +| x86_64 | CTYun 23.01 | 5.10.0-136.12.0.86.ctl3.x86_64 | 支持 | +| x86_64 | KeyarchOS 5.8 | 4.19.91-27.4.19.kos5.x86_64 | 支持 | + + +### 系统兼容性要求 + +- 若曦云系列GPU无法识别为PCIe设备(可通过 `lspci | grep 9999` 进行查看),需关闭BIOS里兼容性支持模块 (CSM)选项。 +- 若PCIe BAR需要支持4GB以上地址空间,需打开BIOS里Large Bar选项。 +- 每张曦云系列GPU板卡需要三个BAR,空间大小分别为1 MB、8 MB和64 GB。 + + +### 环境检查(以Ubuntu 18.04为例) + +| 序号 | 检查项目 | 检查命令 | 说明 | +|------|---------------------|-------------------------------|---------------------------------------------------------------------------------------------------------------| +| 1 | 服务器CPU架构、操作系统、内核版本 | uname -m, lsb_release -a, uname -r | 确认CPU架构、操作系统和内核版本是否在平台兼容列表中, 不匹配则需更新环境 | +| 2 | 系统是否安装过驱动 | lsmod \| grep metax | 若无内容显示, 表示未安装软件包, 可直接安装
若有内容显示, 表示已安装, 需要卸载后再安装 | +| 3 | 板卡是否在位 | lspci \| grep 9999 | 确认GPU板卡正常在位, 含“9999”的行数应与板卡数量匹配 | +| 4 | udev 配置 | cat /etc/udev/rules.d/70-metax.rules | 若有群组管理需要:
只允许 video 组的成员使用曦云 GPU, 则配置文件有如下内容:
KERNEL=="mxcd", GROUP="video", MODE="0660"
KERNEL=="renderD[0-9]*", GROUP="video", MODE="0660"
若没有以上内容, 则表示只有 root 用户可以使用曦云 GPU。
若无群组管理需要, 可删除此配置文件 (deb 包安装会自动创建此配置文件) | +| 5 | 虚拟化 | dmesg | grep "no space" | 确认系统是否支持 SRIOV 虚拟化 | +| 6 | IOMMU配置 | vim /etc/default/grub | 确保 IOMMU 配置生效, 添加 iommu.passthrough=1, 更新 grub 并重启系统 | +| 7 | gpu_sched模块 | modinfo gpu_sched | 确认是否缺少依赖模块, 若缺少则安装内核可选模块包 | +| 8 | 第三方驱动加载 | modprobe metax | 在 SLES 系统中, 确认是否允许第三方驱动加载 | + + + + +### 配置YUM源 + +- **适配 Centos7 系统** + + ```bash + cat < /etc/yum.repos.d/metax-driver-centos7.repo + [metax-centos7] + name=Maca Driver Yum Repository + baseurl=https://repos.metax-tech.com/r/metax-driver-centos7-$(uname -m)/ + enabled=1 + gpgcheck=0 + EOF + + yum makecache + ``` + +- **适配 CentOS 8、CentOS 9 及 Kylin 系统** + ```bash + cat < /etc/yum.repos.d/metax-driver-centos.repo + [metax-centos] + name=Maca Driver Yum Repository + baseurl=https://repos.metax-tech.com/r/metax-driver-centos-$(uname -m)/ + enabled=1 + gpgcheck=0 + EOF + + yum makecache + ``` + +##### YUM安装metax-driver + + - **安装metax-driver驱动** + ```bash + yum install metax-driver + ``` + + - **若需要启用SRIOV,需要安装额外的虚拟化支持包 mxgvm,以启用 SR-IOV 功能** + ```bash + yum install metax-driver mxgvm + ``` + - **卸载metax-driver** + ```bash + yum autoremove metax-driver + ``` + +### 配置APT源 + +- **适配所有 Ubuntu 发行版本系统** + ```bash + curl -fsSL https://repos.metax-tech.com/public.gpg.key | apt-key add - + echo "deb [arch=$(dpkg --print-architecture)] https://repos.metax-tech.com/r/metax-driver-ubuntu/ stable main" | tee /etc/apt/sources.list.d/metax-driver-ubuntu.list + apt-get update + +##### APT安装metax-driver + + - **安装metax-driver驱动** + ```bash + apt install metax-driver + ``` + + - **若需要启用SRIOV,需要安装额外的虚拟化支持包 mxgvm,以启用 SR-IOV 功能** + ```bash + apt install metax-driver mxgvm + ``` + + - **卸载metax-driver** + ```bash + apt autoremove --purge metax-driver + ``` + + + + +### 验证安装 + - **在安装完成后需要重启服务器** + ```bash + reboot + ``` + + - **重启服务器后,可以通过以下命令确认驱动是否成功加载,如果看到相关驱动模块列出,说明安装已成功** + ```bash + lsmod | egrep "(metax|mxgvm)" + ``` + +- **安装 metax-driver,安装过程中将包含四个软件包：** + - **metax-driver** + - **metax-linux** + - **mxsmt** + - **mxfw** + +- **检查已安装包,使用以下命令检查相关包的安装情况：** + + ```bash + dpkg -l | egrep "(metax|mxsmt|mxfw)" + rpm -qa | egrep "(metax|mxsmt|mxfw)" + ``` + +- **Driver 软件包内容清单** + | 文件名 | 说明 | + |------------------------------------|----------------------------------------------| + | metax-linux_x.x.x-xxx_amd64.deb | 曦云系列 GPU KMD 驱动、工具及相关配置文件 | + | mxgvm_x.x.x-xxx_amd64.deb | 曦云系列 GPU Virtualization Manager、工具及相关配置文件 | + | mxfw_x.x.x.x.all.deb | 曦云系列 GPU 固件包 | + | mxsmt_x.x.x.x.amd64.deb | mx-smi 系统管理工具,MXSML 系统管理库 | + + + +# MACA Pytorch + +### 环境准备 + +#### Python 环境 + - 匹配目标安装包的 Python 版本(Python 3.8 、Python 3.10、Python 3.12) + +#### MXMACA 环境 + - 安装 Driver 软件包以及 MXMACA SDK 软件包 + +#### cu-bridge 环境 + - 在安装 MXMACA 环境到 `/opt/maca/` 目录后，将 cu-bridge 解压到 `/opt/maca/tools/` 目录下，具体操作步骤参见相关文档。可以检验 `/opt/maca/tools/cu-bridge/bin/cucc` 文件是否存在，从而判断 cu-bridge 环境是否配置完成。 + - cu-bridge 环境不需要安装 CUDA Toolkit。 + - 如果不使用 PyTorch Extension 功能，可以不配置 cu-bridge 环境。关于 PyTorch Extension 功能，参见官网描述。 + + +### Pip安装 +#### 单包安装 + - **使用以下命令安装指定包** + ```bash + pip install -i https://repos.metax-tech.com/r/maca-pypi/simple --trusted-host repos.metax-tech.com + ``` + +#### 使用requirements.txt批量安装 + - **在命令行中指定 maca-pypi 源地址** + ```bash + pip install -r ./requirements.txt -i https://repos.metax-tech.com/r/maca-pypi/simple --trusted-host repos.metax-tech.com + ``` + ```bash + cat < ./requirements.txt + apex + dropout_layer_norm + flash_attn + fused_dense_lib + rotary_emb + torch + torchaudio + torchvision + triton + xentropy_cuda_lib + xformers + + EOF + ``` + + +#### 列出可用版本 + +- **对于 pip 22.0 及之前版本,使用以下命令触发错误并列出包的所有可用版本** + ```bash + pip install == -i https://repos.metax-tech.com/r/maca-pypi/simple --trusted-host repos.metax-tech.com + ``` + +- **对于 pip 22.0 之后版本,使用以下命令列出某个包的所有可用版本** + ```bash + pip index versions -i https://repos.metax-tech.com/r/maca-pypi/simple --trusted-host repos.metax-tech.com + ``` + + + + \ No newline at end of file