1. 概述

本文档详细描述了曦云® 系列GPU的运行环境配置，所需软件及工具的安装和使用方法，以及日常管理等内容。

本文档主要适用于以下人员：

  • 服务器管理员

  • 曦云系列GPU用户

2. 产品简介

2.1. 概述

曦云系列通用计算GPU产品，采用沐曦自主知识产权的GPGPU架构，提供强大的多精度混合算力、大容量高带宽显存，支持MetaXLink卡间互联技术和新一代高速IO接口，配合全兼容主流GPU生态的MXMACA® 软件栈，可广泛应用于智算、通用计算和数据分析等场景。

2.2. 产品外观

曦云C500的外观如图 2.1 所示。

_images/image4.png

图 2.1 曦云C500外观图

曦云C500X的外观图如图 2.2 所示。

_images/image5.png

图 2.2 曦云C500X外观图

3. 安装与维护

若无特殊说明，本章是以曦云C500为例进行撰写。

3.1. 用户须知

3.1.1. 系统支持范围

目前已支持的CPU架构和内核版本，参见表 3.1。

表 3.1 软硬件平台兼容列表

CPU架构

操作系统

内核版本

状态

x86_64

Ubuntu 18.04

5.4.0-42-generic

支持

5.4.0-131-generic

x86_64

Ubuntu 20.04

5.4.0-144-generic

支持

5.15.0-58-generic

x86_64

Ubuntu 22.04

5.15.0-72-generic

支持

5.15.0-112-generic

x86_64

CentOS 8

4.18.0-240.el8.x86_64

支持

x86_64

CentOS 7

4.19.0-1.el7.elrepo.x86_64

支持加载Docker Container形式

5.14.0

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.18.0-477.27.1.3.kos5.x86_64

支持

x86_64

RockyOS 9.2

5.14.0-284.11.1.el9_2.x86_64

支持

x86_64

Debian 10

5.10.0-0.deb10.28-amd64

支持

x86_64

TencentOS 3.1

5.4.119-19.0009.54

支持

x86_64

TencentOS 3.1

5.4.119-19.0009.44

支持

3.1.2. 服务器配置建议

在AI模型训练和推理场景下，为了得到理想的多机通信性能，需要将服务器的PCIe Max Payload值设置为256。

某些服务器（比如同泰怡Arm服务器TG657V2）的PCIe Max Payload缺省值不是256，需要用户在服务器BIOS中手动设置，或者联系服务器制造商。

3.1.3. 安装包说明

为曦云系列GPU提供的基础软件包由Driver和MXMACA SDK两部分组成。

  • Driver部分通过run安装文件发布，安装包说明参见《曦云® 系列通用计算GPU驱动安装指南》中“安装包说明”章节。

  • MXMACA SDK部分通过tar包发布，以Ubuntu系统为例，软件包内容参见表 3.2 。MXMACA SDK的安装参见《曦云® 系列通用计算GPU快速上手指南》。

表 3.2 MXMACA SDK软件包列表

文件名

说明

commonLib_x.x.x.x_amd64.deb

曦云系列GPU通用lib库

macainfo_x.x.x.x_amd64.deb

曦云系列GPU软件MXMACA显示信息

mcanalyzer_x.x.x.x_amd64.deb

曦云系列GPU工具库

mcblas_x.x.x.x_amd64.deb

曦云系列GPU BLAS库，提供BLAS API接口

mccl_x.x.x.x_amd64.deb

曦云系列GPU集合通信库，实现对GPU的多线程多进程运行控制

mccompiler_x.x.x.x_amd64.deb

曦云系列GPU编译器库，提供编译功能

mcthrust_x.x.x.x_amd64.deb

曦云系列GPU CUB/Thrust库，提供CUB/Thrust API接口

mcdnn_x.x.x.x_amd64.deb

曦云系列GPU DNN库，提供DNN API接口

mceigen_x.x.x.x.amd64.deb

曦云系列GPU Eigen库，提供Eigen API接口

mcfft_x.x.x.x_amd64.deb

曦云系列GPU FFT库，提供FFT API接口

mcfile_x.x.x.x_amd64.deb

曦云系列GPU Direct Storage库

mcimage_x.x.x.x.amd64.deb

曦云系列GPU G2D库，提供G2D API接口

mcjpeg_x.x.x.x.amd64.deb

曦云系列GPU JPEG库，提供JPEG API接口

mckernellib_x.x.x.x.amd64.deb

曦云系列GPU核心库

mcmathlib_x.x.x.x.amd64.deb

曦云系列GPU数学库

mcpti_x.x.x.x_amd64.deb

曦云系列GPU pti库，提供pti API接口

mcrand_x.x.x.x_amd64.deb

曦云系列GPU random库，提供random API接口

mcruntime_x.x.x.x.amd64.deb

曦云系列GPU运行时库，提供MXMACA API接口

mcsolver_x.x.x.x_amd64.deb

曦云系列GPU SOLVER库，提供SOLVER API接口

mcsolverit_x.x.x.x_amd64.deb

曦云系列GPU SolverIT库，提供SolverIT API接口

mcsparse_x.x.x.x_amd64.deb

曦云系列GPU SPARSE库，提供SPARSE API接口

mctlass_x.x.x.x.amd64.deb

曦云系列GPU Tlass库，提供Tlass API接口

mctoolext_x.x.x.x.amd64.deb

曦云系列GPU工具

mctracer_x.x.x.x.amd64.deb

曦云系列GPU工具

metax-docker_x.x.x_amd64.deb

曦云系列GPU docker工具

mxcompute_x.x.x.x.amd64.deb

曦云系列GPU UMD硬件抽象层

mxgpu_llvm_x.x.x.x.amd64.deb

曦云系列GPU编译器

mxkw_x.x.x.x.amd64.deb

mxkw库，为与KMD交互的user-mode API

mxmaca-install_x.x.x.x.amd64.deb

曦云系列GPU辅助安装包

mxompi_x.x.x.x_amd64.deb

曦云系列GPU Open MPI库，实现GPU并行计算

mxreport_x.x.x.x.amd64.deb

mx-report工具，查询、设置日志级别，收集系统日志

mxucx_x.x.x.x_amd64.deb

曦云系列GPU UCX库

sample_x.x.x.x_amd64.deb

曦云系列GPU sample库，提供常用库的sample

3.2. 物理机上安装驱动和固件

在物理机上安装驱动和固件，参见《曦云® 系列通用计算GPU驱动安装指南》中“物理机上安装驱动和固件”章节。

4. 工具

4.1. mx-smi工具

mx-smi工具的详细介绍，请参见《曦云® 系列通用计算GPU mx-smi使用手册》。

4.2. mx-report工具

mx-report是曦云系列GPU的日志管理工具，负责收集KMD、UMD和Firmware模块的日志，并提供对KMD、UMD和Firmware模块的日志级别进行查询和设置的功能。

4.2.1. mx-report工具安装

曦云系列GPU软件包安装过程中会默认安装mx-report工具。软件包安装完成后，mx-report工具放置在/opt/maca/bin/目录下。

4.2.2. mx-report工具使用方法

mx-report是一个Linux命令行工具，其调用遵守如下格式。

mx-report [选项1 [参数1]] [参数2] …

4.2.3. mx-report在容器中使用

若需在容器中使用mx-report收集日志及环境信息，可在运行容器时传入以下参数：

docker run -it -d --device=/dev/dri --device=/dev/mxcd -v /sys/devices:/sys/devices -v /sys/kernel:/sys/kernel -v /opt/maca:/opt/maca -v /var/log:/var/log -v /usr/bin/kmd_diagnostic.sh:/usr/bin/kmd_diagnostic.sh -p 0.0.0.0:<hostPort>:<container_port> --hostname <host_name> --privileged=true <image ID> -p <container_port>

其中：

  • 指定 -v /sys/kernel:/sys/kernel 及 --privileged=true 用于收集 xcore_config_id

  • 指定 -v /var/log:/var/log 可在容器中收集日志

  • 推荐使用 <container_ID>-主机名 指定 <hostname>，便于后期区分设备

  • 指定 -v /usr/bin/kmd_diagnostic.sh:/usr/bin/kmd_diagnostic.sh 可收集KMD诊断相关信息

4.2.4. mx-report命令介绍

mx-report命令说明，可以通过在工作环境中执行 man mx-report 获取。

4.2.4.1. 通用选项

-h, --help

打印使用帮助信息。

-v, --version

打印mx-report的版本信息。

4.2.4.2. 日志导出选项

mx-report

导出当前GPU所有模块日志及收集的环境信息，若不指定 --path，默认存放在当前目录下以“主机名_时间戳”命名的文件夹中。

--path <target_path>

将导出的日志存放在指定目录，在收集完成后也会打印日志存放的地址。

--logmodule <umd|firmware|kmd>

导出指定模块的日志。若未指定，默认导出KMD、UMD、Firmware所有日志。

-c/--continue

持续导出KMD、UMD、Firmware的日志及收集的环境信息，可配合 --logmodule 持续导出指定模块的日志。 收集后的信息存放在当前目录下以“主机名_时间戳”命名的文件夹中。

由于环境信息是一次性收集完毕，请勿较早地使用Ctrl+C停止以免信息收集不全。

--set-fwlog-capacity <log file size, log files number>

持续导出日志时，设置Firmware单个日志文件的大小和日志文件的数量。若未设置，默认为20Mb，4个文件。

-p/--pack <target file folder>

将导出的日志文件夹打包。

备注

  • 非持续导出时KMD日志文件是软链接。为保证打包的文件是软链接指向的源文件，推荐使用 mx-report -p 进行打包。

  • 对于容器场景，一般不建议获取KMD日志，需要去对应物理机上获取。若确实需要在容器内获取KMD日志，需要在容器启动时将 /var/log 和 /proc 挂载到容器内部。

--dump-queue --pid xxx

当进程发生异常Hang住时，可导出异常进程的数据到当前目录下以pid命名的json文件中，以进一步分析。其中 pid 可通过 mx-smi --show-process 获取，可用 -i 指定设备，默认收集所有设备信息。

4.2.4.3. 日志级别操作选项

--show-loglevel

显示KMD、UMD所有运行中进程（ip: app, mcc, mcr, mxc, mctx, pti, prf, mxkw, mxs, mxvpu），Firmware（ip: smp0, smp1, ccx0, ccx1, ccx2）的日志级别。

--set-loglevel <moduleName,ipName,loglevel>

指定模块名和ip设置日志级别，其中ip可以设置为all，表示全部生效。

备注

如要对UMD进程进行日志级别查询和设置操作，需在启动UMD进程前设置环境变量 MACA_PATH 和 MCTX_TARGET_INIT=true （拉起rpc服务）。

4.2.4.4. 日志模块操作选项

--show-logmodule

查询板卡Firmware（ip: smp0, smp1, ccx0, ccx1, ccx2）日志模块的状态，默认为 00000001，即ip第一个模块的日志开关为打开状态。

--set-logmodule <ipName,state>

设置指定ip日志模块状态： 1 为打开； 0 为关闭，关闭时不显示该模块日志。若设置 f，即为二进制1111，表示打开4个模块日志开关。 每个ip共28个日志模块（0~0fffffff）。本设置仅当Firmware该ip日志级别为 5:debug 时生效。

4.2.4.5. 环境信息收集

mx-report --get-envinfo

仅收集当前设备的环境信息，存放在当前目录下以“主机名_时间戳”命名的文件夹中。其中：

  • envinfo.json以json格式存储所有环境信息；

  • envinfo.xlsx仅存储键值对形式的环境信息；

  • system_power_supply.txt存储系统电源信息；

  • topo_info.txt存储设备MataXLink拓扑信息、PCIe信息以及NUMA信息等。

备注

由于部分信息收集需root权限才能获取，因此需以root权限运行收集命令。

在容器中收集环境信息需在启动时增加参数 --privileged -v /sys/kernel:/sys/kernel；如需同时收集日志信息，增加参数 -v /var/log:/var/log。 推荐增加参数 --hostname <hostname>，使用 <container_ID>-主机名 以便知道收集的信息来自于哪个物理机。

4.2.4.6. 环境信息对比

两台服务器之间信息对比

mx-report --compare envinfo1.xlsx envinfo2.xlsx

excel各标签页对比信息如下：

  • Commoninfo：对比所有指标值存在的差异。

  • Server_info：对比服务器的指标值存在的差异（mem_used，mem_free，mem_buff，mem_available除外）。

  • Env_virable_info：根据工具已定义的环境变量列表进行对比：

    • 均包含某个环境变量，但值不同。

    • 一个服务器包含该环境变量，另外一个服务器不包含。

  • Pip_info：对所有的python安装包进行对比：

    • 均包含某个安装包，但版本不同。

    • 一个服务器有该安装包，另外一个服务器没有。

  • Device_info：对比设备的指标值存在的差异（board_type，board_sn除外）。

同一服务器不同设备之间信息对比

mx-report --compare envinfo.xlsx

服务器上GPU设备数量大于1时，会对比不同GPU设备指标差异。

Device_info：对比设备的指标值存在的差异（board_type，board_sn除外）。

4.2.4.7. 附加选项

-i ID, --index ID

指定板卡进行日志导出或日志级别查询和设置。如果没有指定，默认对全部板卡生效。 ID是从0开始的自然数，可以通过 -L， --list 获取板卡的ID信息。

--pid pid

当设置UMD的日志级别时（ moduleName 为 umd ）需要指定该参数，表示对指定pid进行操作， pid 为 all 时对所有进程生效。

当立即导出或持续导出日志时，添加该参数会同时收集与进程pid相关的内存使用数据，存放在子目录umd下的memInfo.csv文件中。

4.2.5. mx-report工具卸载

曦云系列GPU的驱动卸载后，mx-report工具会自动卸载。驱动卸载，参见《曦云® 系列通用计算GPU驱动安装指南》中“卸载驱动”章节。

在Root权限环境中，也可以通过执行以下命令直接删除工作目录下的二进制执行文件来卸载mx-report工具。

sudo rm /opt/maca/bin/mx-report

4.3. mx-exporter工具

mx-exporter工具的详细介绍，请参见《曦云® 系列通用计算GPU mx-exporter使用手册》和《曦云® 系列通用计算GPU mx-exporter Kubernetes集群监控部署手册》。

5. 维护管理

5.1. 带内管理

带内管理通过沐曦mx-smi工具提供。mx-smi工具的使用，参见《曦云® 系列通用计算GPU mx-smi使用手册》。 带内管理的功能有：提供命令行控制台供系统管理员查询系统软硬件配置和工作信息。

5.2. 带外管理

BMC提供带外管理功能，包括查询曦云系列GPU的配置信息，生产信息，时钟信息，电源功率信息，温度信息，固件版本。通过MCU，BMC可以触发曦云GPU的重启。

曦云系列GPU的带外管理功能，参见《曦云® 系列通用计算GPU带外管理手册》。

6. 虚拟化支持

虚拟化驱动安装和固件支持，参见《曦云® 系列通用计算GPU驱动安装指南》中“虚拟化支持”章节。

7. 容器相关场景支持

曦云系列GPU提供对Docker和Kubernetes的支持。Kubernetes的详细介绍，参见《曦云® 系列通用计算GPU云原生参考手册》。

7.1. 官方Docker支持

开发人员可以借助于容器引擎，运行预先构建好的容器镜像，快速建立软件开发或运行所需的环境。 曦云系列GPU提供预构建的MXMACA容器镜像。开发人员仅需执行一条 docker run 命令就可获得一个干净而完整的板卡开发环境。

在运行MXMACA容器镜像前，请确认环境满足以下条件：

  • 已正确安装曦云GPU的内核驱动。详细内容请参见 3 安装与维护。

  • 已安装Docker，Docker版本≥19.03。

7.1.1. 获取MXMACA容器镜像

MXMACA容器镜像是以离线形式发布。用户可在随本文档发布的软件包中找到相关压缩包。本文档中以maca-c500-container-2.0.0.tar.gz为例，用户应根据实际收到的软件包版本对版本字段进行相应替换。

操作步骤

  1. 执行以下命令，完成容器镜像的加载。

    docker load < ./maca-c500-container-2.0.0.tar.gz

7.1.2. 在Docker容器中使用板卡

7.1.2.1. 使用全部GPU

操作步骤

  1. 执行以下命令：

    docker run -it --device=/dev/mxcd --device=/dev/dri --group-add video \
cr.metax-tech.com/library/maca-c500:2.0.0 /bin/bash

7.1.2.2. 使用指定GPU

正确安装内核驱动后，默认在/dev/dri目录下为每一个GPU创建了一个card设备文件和一个renderD设备文件。 通过绑定设备文件来指定期望使用的板卡。如何确认板卡的ID与/dev/dri目录下设备文件之间的对应关系，请参见 7.1.3 GPU设备文件查询。

操作步骤

例如，指定的板卡所对应的设备文件为/dev/dri/card1和/dev/dri/renderD129。

  1. 执行以下命令：

    docker run -it --device=/dev/mxcd --device=/dev/dri/card1 \
--device=/dev/dri/renderD129 --group-add video \
cr.metax-tech.com/library/maca-c500:2.0.0 /bin/bash

7.1.3. GPU设备文件查询

操作步骤

  1. 执行以下命令查看板卡的设备ID和PCI总线地址的对应关系。

    mx-smi -L

    例如，GPU#0和GPU#1的设备ID 和PCI总线地址的对应关系如下所示。

    GPU#0 0000:01:00.0
GPU#1 0000:02:00.0

  2. 在/dev/dri/by-path路径下，使用PCI总线地址筛选得到板卡的设备文件路径。例如，执行以下命令得到GPU#1的dri设备文件路径。

    ls -l /dev/dri/by-path | grep 0000:01:00.0
lrwxrwxrwx 1 root root 8 Oct 24 19:03 pci-0000:01:00.0-card -> ../card1
lrwxrwxrwx 1 root root 13 Oct 24 19:03 pci-0000:01:00.0-render -> ../renderD129

8. 附录

8.1. 术语/缩略语

术语/缩略语

全称

描述

ACS

Access Control Services

访问控制服务

BIOS

Basic Input/Output System

基本输入输出系统

BMC

Baseboard Management Controller

基板管理控制器

Docker

一个开源的应用容器引擎

KMD

Kernel-Mode Driver

内核模式驱动程序

MCU

Microcontroller Unit

微控制单元

MetaXLink

沐曦GPU D2D接口总线

MXMACA

MetaX Advanced Compute Architecture

沐曦推出的GPU软件栈，包含了沐曦GPU的底层驱动、编译器、数学库及整套软件工具套件

NUMA

Non-Uniform Memory Access

非一致性内存访问

PCI

Peripheral Component Interconnect

一种连接主板和外部设备的总线标准

PCIe

PCI Express

一种高速串行计算机扩展总线标准

P2P

Peer-to-Peer

PCIe P2P是PCIe的一种特性，使两个PCIe设备之间可以直接传输数据

UMD

User Mode Driver

用户模式驱动程序