1. 简介
本文档描述了如何快速开始在曦云® 系列GPU上进行GPU编程，包括编程环境的安装验证、MXMACA® 的编程模型和MXMACA的编程接口等内容介绍。
本文档主要适用于以下人员：
在曦云系列GPU上进行程序开发工作的客户和用户
使用MXMACA进行GPU编程的程序员
2. 编程环境
本节以Ubuntu 18.04系统环境为例进行本地离线安装示范。支持的软硬件平台兼容列表，参见《曦云® 系列通用计算GPU用户指南》中“系统支持范围”章节。
2.1. 安装准备
操作步骤
执行以下命令，检查是否拥有支持MXMACA的GPU。
lspci | grep 9999
如果机器上有N（N＞0）张曦云GPU板卡，回显中含“9999”字段的行数为N时，则表示曦云GPU板卡正常在位。
例如，若机器上有2张曦云C500且都正常在位，回显信息如下所示。
01:00.0 Display controller: Device 9999:4001 (rev 01) 02:00.0 Display controller: Device 9999:4001 (rev 01)
如果机器上有曦云系列GPU板卡但无内容显示，执行以下命令，检查是否已成功安装对应的GPU板卡驱动。
lsmod | grep metax
若无内容显示，则表示未成功安装对应的GPU板卡驱动。驱动安装参见《曦云® 系列通用计算GPU驱动安装指南》中“安装驱动”章节。
备注
驱动安装成功后，需要重启系统。
验证是否拥有支持MXMACA编程环境的Linux发行版。
执行以下命令，确认正在运行的Linux发行版及其版本号。
uname -m && cat /etc/*release
MXMACA编程环境仅在某些特定的Linux发行版上受支持。详情参见《曦云® 系列通用计算GPU用户指南》中“系统支持范围”章节。
例如，机器是64位系统（x86_64），并且安装了Ubuntu 18.04的操作系统，回显信息如图 2.1 所示。
图 2.1 编程环境验证回显示例
验证系统是否已安装正确版本的GCC、g++、libstdc++、CMake和Make。
以验证系统上安装的GCC版本为例，执行以下命令：
gcc --version使用MXMACA工具包进行开发必须安装GCC、g++、libstdc++、CMake和Make。运行MXMACA应用程序不需要。 它们通常是作为Linux安装的一部分进行安装的，在大多数情况下，与受支持的Linux一起安装的GCC、g++、libstdc++、CMake和Make，都会正常工作。
例如，Ubuntu 18.04操作系统上安装了GCC 7.5.0版本，回显信息如图 2.2 所示。
图 2.2 系统验证回显示例
2.2. 安装MXMACA编程环境
MXC500 GPU的MXMACA编程环境从2.31.0开始支持以下两种安装方法：
本地离线安装MXMACA编程环境：支持所有发行版本的MXMACA软件栈。详细步骤参见 2.2.1 本地离线安装MXMACA编程环境。
在线安装MXMACA编程环境：支持2.31.0及之后版本的MXMACA软件栈，主要面向特定操作系统选定版本的包管理器安装（Package Manager Installation）。详细步骤参见 2.2.2 在线安装MXMACA编程环境。
2.2.1. 本地离线安装MXMACA编程环境
2.2.1.1. 安装MXMACA编程环境
备注
如果已安装了旧版本的MXMACA，请参见 2.2.1.5 卸载MXMACA编程环境的相应方式进行卸载后，再安装新版本的MXMACA。
操作步骤
安装MXMACA依赖。
MXMACA的依赖列表，参见表 2.1。
请确认表格中的依赖库是否都已安装；若没有，请自行获取并安装。
表 2.1 MXMACA依赖列表 序号
依赖名称
依赖安装命令
1
libmsgpackc2
sudo apt install libmsgpackc2
2
libelf1
sudo apt install libelf1
3
libnuma1
sudo apt install libnuma1
4
libssl1.1
sudo apt install libssl1.1
解压获取安装包。
获取MXMACA SDK的tar安装包 maca-sdk-mxc500-x.x.x.x-deb-x86_64.tar.xz，解压后可以看到 mxmaca-sdk-install.sh、version_compatible_check.sh、appimage、deb 等子目录。将安装包放入目标服务器，包内基础文件如下所示。
├── appimage ├── deb ├── mxmaca-sdk-install.sh └── version_compatible_check.sh 2 directories, 2 files
获取metax驱动安装包 metax-driver-mxc500-x.x.x.x-deb-x86_64.run。将安装包放入目标服务器。
执行以下命令，安装MXMACA编程环境。
cd xxx ##(MXMACA SDK解压目录) sudo ./mxmaca-sdk-install.sh -f cd xxx ##(MXMACA 驱动所在目录) sudo chmod +x metax-driver-mxc500-x.x.x.x-deb-x86_64.run sudo ./metax-driver-mxc500-x.x.x.x-deb-x86_64.run -- -f
安装成功后的目录如下所示。
root@device-01:/opt/maca$ tree -L 1 . ├── bin ├── etc ├── ffmpeg ├── include ├── lib ├── mxgpu_llvm ├── ompi ├── samples ├── share ├── tools ├── ucx ├── Version.txt └── wheel 12 directories, 1 file
2.2.1.2. 配置MXMACA编程环境
MXMACA目前仅支持在默认路径 /opt/maca 下进行安装。
操作步骤
将以下MXMACA路径加入
PATH环境变量中。export PATH=$PATH:/opt/maca/mxgpu_llvm/bin:/opt/maca/bin
定义以下MXMACA环境变量。
export MACA_PATH=/opt/maca export LD_LIBRARY_PATH=/opt/maca/lib:/opt/maca/mxgpu_llvm/lib
2.2.1.3. 启用MXMACA程序的访问权限
MXMACA程序需要特定文件夹的访问权限，但MXMACA程序进程不会修改文件夹中任何文件内容。
操作步骤
执行以下命令，启用访问权限。
sudo usermod –aG video $USER
将用户加入video用户组，为其启用访问权限。
2.2.1.4. 验证MXMACA编程环境的安装
操作步骤
执行以下命令，检查是否正确安装MXMACA编程环境。
macainfo
如下所示，如果
macainfo在有曦云系列GPU运行的系统中正常运行，说明MXMACA编程环境安装成功。root@device-01:/opt/maca$ macainfo ====================== MXC System Attributes ====================== Runtime Version: 1.0 System Timestamp Freq: 1000MHz Signal Max Wait Time: 18446744073709551615(0xffffffffffffffff) Machine Model: LARGE System Endianess: LITTLE
2.2.1.5. 卸载MXMACA编程环境
操作步骤
执行以下命令，卸载MXMACA编程环境。
sudo /opt/maca/bin/mxmaca-sdk-install.sh -U sudo /opt/mxdriver/mxdriver-install.sh -U
备注
使用MXMACA安装在系统路径下的 mxmaca-sdk-install.sh 和 mxdriver-install.sh 脚本进行卸载。
2.2.2. 在线安装MXMACA编程环境
在线安装MXMACA编程环境时，会与系统的包管理系统进行交互。rpm或deb软件包在安装时通过包管理器（如apt、yum或pip）自动下载。 详细步骤参见在线指导：https://developer.metax-tech.com/softnova/index。
2.3. 验证MXMACA编程环境
2.3.1. 获取MXMACA源码示例
操作步骤
参见 2.2 安装MXMACA编程环境，成功安装MXMACA编程环境后，在 samples 目录下获取MXMACA源码示例。
root@device-01:/opt/maca$ tree -L 1 . ├── bin ├── etc ├── ffmpeg ├── include ├── lib ├── mxgpu_llvm ├── ompi ├── samples (*) ├── share ├── tools ├── ucx ├── Version.txt └── wheel 12 directories, 1 file
2.3.2. 验证MXMACA编程环境
通过Makefile构建Linux MXMACA程序。
2.3.2.1. 用参考示例项目的Makefile构建MXMACA程序
示例项目的Makefile会使用一些特定选项，可参见表 2.2。
操作步骤
复制一个示例项目（比如 vectorAdd）到测试路径下，并将当前路径更改为要构建MXMACA程序的示例项目路径。
mkdir test cp /opt/maca/samples/0_Introduction/vectorAdd/ test/ -R cd test/vectorAdd/
选择以下任一方法构建MXMACA程序。
仅构建MXMACA程序：
$ makeMXMACA程序会被构建并生成到示例项目所在路径下，进行运行和启动。
构建并直接启动MXMACA程序：
$ make run [Vector addition of 50000 elements] Copy input data from the host memory to the MXMACA device MXMACA kernel launch with 196 blocks of 256 threads Copy output data from the MACA device to the host memory Test PASSED MXMACA Sample Done
执行以下命令，清除构建MXMACA程序时生成的项目文件。
make clean
2.3.2.2. 用自己的Makefile构建MXMACA程序
操作步骤
如需从零开始写一个MXMACA项目Makefile，可参见访问 Makefile官方指导手册 。
新建自己的Makefile时，如果需要使用一些特定选项，可参见表 2.2 进行配置。
表 2.2 列出了mxcc编译和构建MXMACA程序时支持的典型选项。mxcc支持的更多选项，参见《曦云® 系列通用计算GPU mxcc编译器用户指南》。
表 2.2 编译和构建MXMACA程序时的可用选项 序号
选项
选项备注
1
# Location of the MXMACA Toolkit
MACA_PATH ?= /opt/maca2
# start deprecated interface #
TARGET_ARCH ?= x86_64仅支持x86_64
3
#architecture
HOST_ARCH := $(shell uname -m)TARGET_ARCH ?= $(HOST_ARCH)仅支持x86_64
4
#operating system
HOST_OS := $(shell uname -s 2>/dev/null | tr "[:upper:]" "[:lower:]")TARGET_OS ?= $(HOST_OS)初始支持的操作系统为Ubuntu 18.04。
其他操作系统将会按需支持。
5
# host compiler
HOST_COMPILER ?= mxcc6
# Device compiler
MXCC := mxcc7
# Internal flags
MXCCFLAGS := -x maca8
#Install directory
MACA_INSTALL_TARGET_DIR := /opt/maca/bin示例项目不会使用此选项
参考 2.3.2.1 用参考示例项目的Makefile构建MXMACA程序，构建MXMACA程序并清除构建MXMACA程序时生成的项目文件。
3. 编程模型
本章节描述了MXMACA编程模型的几个主要概念。
3.1. GPGPU
GPU的处理内核远多于CPU。GPU最初用于图形处理，后来也用于向量计算和浮点运算，并逐渐用于很多高度并行计算的应用，进而衍生出了GPGPU，如图 3.1 所示。
图 3.1 CPU、GPU和GPGPU概念介绍
GPGPU擅长并行计算，分解是并行处理的核心。分解指的是：
将算法划分为单独的任务
将数据集划分为可并行操作的离散块
通常，应用程序由并行计算和顺序计算混合组成，因此系统采用GPU和CPU的混合设计，以最大限度地提高系统整体性能。
3.2. MXMACA：通用并行计算平台和编程模型
MXMACA® 是一个通用并行计算平台和编程模型，主要用于开发高度并行性的应用程序并部署在沐曦GPU上。
MXMACA的软件环境允许开发人员使用C++作为高级编程语言。MXMACA软件栈如图 3.2 所示。
图 3.2 MXMACA软件栈
MXMACA支持使用C/C++编程语言，且包括以下功能：
Templates
C++11 Lambdas
Classes
namespaces等
使用mxcc编译MXMACA C++代码，构建在沐曦GPU平台上运行的MXMACA程序。MXMACA提供以下API接口：
MXMACA运行时库：实现MXMACA在功能模块上的运行时API，例如设备管理，流管理，内存管理，执行控制，事件管理等。
MXMACA人工智能和计算库（AI & Compute Library，ACL）：为沐曦GPU定制的加速库，用于机器学习，数值分析和量子计算等现场应用。
MXMACA也为开发人员提供了一套专业的记录、跟踪、分析、部署和现场维护工具。
MXMACA平台支持多个GPU的并行计算，可以通过PCIe或MetaXLink在节点内，也可通过InfiniBand或以太网上的RDMA跨节点进行。 沐曦集合通信库（MetaX Collective Communication Library，MCCL）可用于多GPU编程，通过隐藏低级通信的细节来简化编程。
4. 编程接口
MXMACA C++为熟悉C++编程语言的用户提供了一种简单的途径，可以轻松编写由沐曦GPU设备执行的程序。MXMACA C++由C++语言的最小扩展集，MXMACA运行时API和MXMACA人工智能和计算库组成。
4.1. MXMACA C++语言扩展
MXMACA C++语言扩展允许程序员将核函数定义为 C++ 函数，并在每次调用函数时使用一些新句法来指定ND-Range和Workgroup维度。 任何包含这些扩展的源文件都必须使用mxcc进行编译，详情参见《曦云® 系列通用计算GPU mxcc编译器用户指南》。
4.2. MXMACA运行时API
MXMACA运行时API提供了在主机上执行的C和C++函数，用于分配和释放设备内存、在主机内存和设备内存之间传输数据以及管理具有多个设备的系统。 运行时API的详细介绍，参见《曦云® 系列通用计算GPU运行时API编程指南》。
4.3. MXMACA人工智能和计算库
支持的MXMACA人工智能和计算库，参见表 4.1。
序号 |
MXMACA 库 |
描述 |
|---|---|---|
1 |
mcBLAS |
基础线性代数程序集 |
2 |
mcFFT |
快速傅里叶变换库 |
3 |
mcDNN |
深度神经网络库 |
4 |
mcRAND |
生成高质量伪随机和准随机数字 |
5 |
mcThrust |
基于标准模板库的MXMACA C++模板库 |
6 |
mcCUB |
C++头库，为MXMACA编程模型的每层提供可重用的软件组件 |
7 |
mcSPARSE |
稀疏矩阵和向量的基本线性代数子程序 |
8 |
mcPyTorch |
mcPyTorch基于PyTorch 2.0/2.1 版本，在MXMACA环境中运行，并支持CPU和MXMACA设备上的张量操作 |
9 |
mcSOLVER |
基于mcBLAS和mcSPARSE库的高级包 |
4.4. 开发人工智能相关应用
开发人工智能相关应用，具体文档参见表 4.2。
序号 |
开发文档 |
描述 |
|---|---|---|
1 |
AI推理用户手册 |
指导用户如何使用MacaRT推理引擎，将训练好的模型部署到曦云系列GPU上 |
2 |
AI训练用户手册 |
指导用户在AI训练的场景下，如何使用曦云系列GPU进行人工智能算法的训练 |
4.5. 视频编解码相关应用
开发视频编解码相关应用，具体文档参见表 4.3。
序号 |
开发文档 |
描述 |
|---|---|---|
1 |
视频编解码VPU编程指南 |
指导用户如何使用曦云系列GPU视频编解码VPU，进行硬件加速的软件开发方法 |
4.6. 开发数据中心相关应用
开发数据中心相关应用的文档，具体文档参见表 4.4。
序号 |
开发文档 |
描述 |
|---|---|---|
1 |
mcDF使用手册 |
指导用户在曦云系列GPU上安装部署mcDF和使用mcDF |
2 |
mcPy使用手册 |
指导用户在曦云系列GPU上安装部署mcPy和使用mcPy |
3 |
mcFaiss使用手册 |
指导用户在曦云系列GPU上安装部署mcFaiss和使用mcFaiss |
4 |
mxvs测试工具套件使用手册 |
沐曦验收测试套件（MetaX Validation Suite，mxvs） |
5. 附录
5.1. 术语/缩略语
术语/缩略语 |
全称 |
描述 |
|---|---|---|
CMake |
一个开源的跨平台安装（编译）工具，可以用简单的语句来描述所有平台的安装（编译过程） |
|
GCC |
GNU Compiler Collection |
一个能够编译多种语言的编译器 |
GPGPU |
General-Purpose GPU |
通用GPU |
KVM |
Kernel Virtual Machine |
基于内核的虚拟机，是一种内建于Linux的开源虚拟化技术 |
Make |
一个智能的批处理工具，用于解释Makefile中的指令 |
|
Makefile |
描述了整个代码工程所有文件的编译顺序、编译规则。Makefile有自己的书写格式、关键字、函数，可以使用系统shell所提供的任何命令来完成想要的工作 |
|
mxcc |
MXMACA C/C++ Compiler |
MXMACA软件栈中，针对MetaX GPU的硬件架构和功能特性设计和发布的编译器 |
MXMACA |
MetaX Advanced Compute Architecture |
沐曦推出的GPU软件栈，包含了沐曦GPU的底层驱动、编译器、数学库及整套软件工具套件 |