CANN SHMEM 标量 put/get 访问 Host 内存样例解析：rma_d2h_demo 编译、运行与排障指南-二趣网

CANN SHMEM 标量 put/get 访问 Host 内存样例解析：rma_d2h_demo 编译、运行与排障指南

【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库，基于OpenSHMEM 标准协议，实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmem

导读

本文围绕 CANN SHMEM 开源仓库中的 examples/rma_d2h_demo 样例，系统讲解如何在昇腾设备上使用 SHMEM 的标量 put/get 数据传输接口（aclshmem_int32_p/aclshmem_int32_g）访问 Host 侧内存。读者将掌握该样例的完整数据流与内核实现、在 Atlas A3 与 Ascend 950PR 平台上的编译与运行方法，以及运行前必须完成的内存容量检查和 Server ID 配置等前置校验，并了解背后的对称内存（symmetric memory）与 Host 侧堆机制。

样例概述与适用平台

该样例演示的是 SHMEM标量（scalar）put & get 数据传输接口访问 Host 内存的完整使用流程。与整段内存拷贝（putmem/getmem）不同，标量接口针对单个基础类型元素提供低延迟的远程访问能力，是构建细粒度跨节点同步逻辑的基础原语。

支持的运行平台如下：

Atlas A3 训练系列产品 / Atlas A3 推理系列产品
Ascend 950PR（暂不支持 Ascend 950DT）

说明：样例通过 CMakeLists.txt 中的aclshmem_add_fusion_example(rma_d2h_demo main.cpp)接入仓库统一的样例构建体系，构建产物为build/bin/rma_d2h_demo。

样例实现与数据流设计

总体流程：环形传递 PE 编号

测试用例的逻辑非常直观：每个 PE（Processing Element）把自己在本卡上的编号通过 put 接口"推"给下一个 PE，同时通过 get 接口从下一个 PE 的 output 中"拉"回对方的编号，最终验证每个 PE 拿到的数据是否恰好等于(my_pe + 1) % n_pes。

// 摘录自 examples/rma_d2h_demo/main.cpp int mype = aclshmem_my_pe(); int npes = aclshmem_n_pes(); int peer = (mype + 1) % npes;

测试用例实现步骤

完整用例由 main.cpp 中的test_aclshmem_rma_scalar_8p承载，分为四步：

初始化 ACL 与 SHMEM：依次调用aclInit、aclrtSetDevice(my_pe)、aclrtCreateStream完成 ACL 侧初始化；再通过aclshmemx_init_attr(ACLSHMEMX_INIT_WITH_DEFAULT, &attributes)完成 SHMEM 初始化。初始化参数由仓库公共工具函数 test_set_attr 填充，包括my_pe、n_pes、ip_port、local_mem_size与option_attr等。样例默认通过"tcp://127.0.0.1:8998"建立 PE 之间的 TCP 通信通道。
分配内存并初始化数据：通过aclrtMallocHost在 Host 侧分配input_host与output_host，其中input初始化为 0，output初始化为当前my_pe。随后调用aclshmemx_malloc(2*1024*1024, HOST_SIDE)分配 SHMEM 对称内存，并以ACL_MEMCPY_HOST_TO_DEVICE将 Host 初始化数据拷入设备侧内存。
启动内核执行：在aclshmem_barrier_all()全局同步后调用run_demo_scalar启动kernel_test内核，执行结束后再次以aclshmem_barrier_all()与aclrtSynchronizeStream确保所有 PE 完成通信。
结果校验与资源清理：将设备侧结果拷回 Host（ACL_MEMCPY_DEVICE_TO_HOST），检查output是否等于(my_pe + 1) % n_pes，最后依次释放对称内存、销毁流并调用aclshmem_finalize、aclFinalize完成收尾。

Kernel 实现：标量 put/get 的核心调用

内核侧（kernel_test）同样分为三步：

获取本 PE 编号、总 PE 数量与目标 PE 编号；
调用aclshmem_int32_p向下一个 PE 的 input发送本 PE 的编号，随后调用aclshmem_quiet()等待 scalar 数据发送完成；
调用aclshmem_int32_g获取下一个 PE 的 output，再次调用aclshmem_quiet()等待接收完成，并把取回的值写入本 PE 的 output。

for (int iii = 0; iii < 10; iii++) { aclshmem_int32_p(input, peer, peer); aclshmem_quiet(); auto get_num = aclshmem_int32_g(input, peer); aclshmem_quiet(); *(output) = get_num; }

值得注意的细节：

内核通过ASCEND_IS_AIC判断跳过 AI Core，并在coreId > 0时提前返回，即只由 block 0 执行通信逻辑；
循环 10 次是为了反复验证 put/get 与aclshmem_quiet同步组合的稳定性；
在 include/device/gm2gm/shmem_device_rma.h 中，shmem_int32_p/shmem_int32_g均被宏映射为aclshmem_int32_p/aclshmem_int32_g，Host 侧同名接口定义于 include/host/data_plane/shmem_host_rma.h。从源码注释看，p接口为"针对单个基础类型元素提供低延迟 put 能力"（Provide a low latency put capability for single element of most basic types），g接口则返回单个元素值。

为什么 put/get 能访问 Host 内存

样例的关键在于aclshmemx_malloc(..., HOST_SIDE)：在 include/host_device/shmem_common_types.h 中HOST_SIDE = 0表示"由 shmem 分配的内存位于 Host 侧"。也就是说，SHMEM 在 Host 物理内存上维护了一块可跨 PE 寻址的对称内存池（样例默认配置 1GB，见下文内存检查小节）。标量 put/get 接口传入的input指针正是这块 Host 对称内存的本地地址，SHMEM 运行时会依据对称内存的映射关系将其换算为目标 PE 上对应的对称地址，从而完成跨节点的单元素读写。

编译与运行

环境准备

环境配置请参考快速上手。完成 CANN Toolkit、驱动、固件以及构建依赖安装后，按以下命令编译运行：

# A3 平台：执行编译 bash scripts/build.sh -examples -cann # Ascend 950 平台：执行编译 bash scripts/build.sh -soc_type Ascend950 -examples -cann cd examples/rma_d2h_demo # 运行用例 bash run.sh

-cann选项用于链接 CANN 相关库；Ascend950 平台的构建还会自动拉取nlohmann/json等第三方依赖（详见编译与构建指南）。

运行脚本行为解读

run.sh 默认以8 个进程并行启动build/bin/rma_d2h_demo：

export SHMEM_UID_SESSION_ID=127.0.0.1:8899 export LD_LIBRARY_PATH=${PROJECT_ROOT}/build/lib:${ASCEND_HOME_PATH}/lib64:$LD_LIBRARY_PATH

SHMEM_UID_SESSION_ID指定 PE 间会话标识服务地址，用于多进程建连协调；
每个子进程执行rma_d2h_demo <n_pes> <my_pe>，主进程通过wait等待全部后台进程结束，并聚合退出码；
脚本支持-pes <N>参数自定义 PE 数量，当小于 8 时自动将启动进程数收敛为 PE 数量。

运行结果判定

用例执行完成后：

打屏出现[INFO] demo run end in pe <my_pe>，表示样例执行结束；
打屏出现[SUCCESS] run success in pe <my_pe>，表示该 PE 结果校验通过；
若校验失败，会打印[ERROR] run result incorrect in pe <my_pe>（源码中对应的期望是"input 变为前一个 PE 编号、output 变为后一个 PE 编号"）。

每个 PE 还会打印一行received message <input> <output>，可直接观察环形数据流动。

约束限制与前置检查

Ascend 950 运行环境要求

若初始化阶段出现aclrtMemSetAccess failed，请检查驱动、固件、CANN Toolkit 和 ops 包是否为相互兼容的配套版本。该错误通常意味着当前环境的内存访问权限设置与 SHMEM 初始化流程不匹配，升级或对齐各组件版本后重试。

查询 A3 超节点可用内存大小

本样例默认配置1GB Host 内存，因此要求查询得到的总可用内存大于 1GB。仓库提供了 check_support.py 脚本扫描物理内存中可被 SHMEM 使用的空闲连续段：

python3 check_support.py

脚本的核心逻辑是：

遍历/sys/devices/system/node/下的所有 NUMA 节点，通过/sys/devices/system/memory/block_size_bytes确定内存块粒度；
读取/proc/kpageflags的KPF_BUDDY（bit 10）标志，识别 buddy 系统中处于空闲状态的物理页；
针对脚本内置的 4 个地址段（0x29580000000、0xa9580000000、0x129580000000、0x1a9580000000，每段 682GB）计算"空闲内存 ∩ 目标地址段"的连续区间，并按CONFIG_FORCE_MAX_ZONEORDER换算的 zone 页大小对齐；
最终按 NUMA 节点输出可用的空闲内存量（MB），并在 Summary 中给出总计（GB）。

运行后（示例输出见下），请确认总空闲内存大于 1GB：

===== Summary ===== NUMA node 0: 649216.00 MB NUMA node 1: 646144.00 MB NUMA node 2: 642048.00 MB NUMA node 3: 651264.00 MB PageSize: 0x1000, ZonePageSize: 0x200000 TotalFree: 2528.00 GB

A3 超节点 Server ID 配置要求

本样例在 A3 超节点环境下运行时，必须确保各服务器的 Server ID 配置正确。特别是在更换故障硬件后，可能出现 Server ID 未正确配置的情况，导致样例运行失败。

查询 Server ID 方法

使用 npu-smi 工具查询当前服务器的 Server ID 配置：

npu-smi info -t spod-info -i 0 -c 0

输出示例：

SDID : 16777216 Super Pod Size : 384 Super Pod ID : 0 Server Index : 4

其中Server Index即为当前服务器的 Server ID，需要确保一个计算节点内所有 NPU 保持一致。

配置 Server ID 方法

如果发现 Server ID 配置不正确，可以通过Redfish 接口修改（具体操作步骤请参考昇腾硬件配套的 Redfish 接口修改文档）。配置完成后建议重启相关服务并再次使用上述 npu-smi 命令确认所有 NPU 的Server Index一致，再重新编译运行样例。

与仓库其他资源的关联

对称内存管理：HOST_SIDE类型内存的语义与 Host 侧堆基址说明见 include/host/mem/shmem_host_heap.h；
标量接口全集：除int32外，ACLSHMEM_TYPE_FUNC宏还为float/double/int8/int16/int64/uint8/uint16/uint32/uint64/char全类型生成*_p/*_g接口（include/host/data_plane/shmem_host_rma.h），有需要的开发者可直接替换数据类型；
同步原语：aclshmem_quiet与aclshmem_barrier_all的详细语义可参考 API 文档与 Python API 文档；
更多 RMA 样例：仓库 examples 目录下还有simt_rma、simt_rma_scalar、udma_demo、sdma_d2h_demo等传输路径与标量语义相近的样例，可作为对比学习材料。

总结

rma_d2h_demo 是理解 CANN SHMEM 标量 put/get 接口与 Host 侧对称内存访问的最小可运行样例：它用"环形传递 PE 编号"这一直观场景，完整覆盖了 ACL/SHMEM 初始化、Host 内存分配、内核标量通信、结果校验与资源释放的全链路。在实际部署到 A3 超节点或 Ascend 950PR 时，务必先完成check_support.py的内存容量扫描与 npu-smi 的 Server ID 一致性检查，二者是本样例稳定运行的两个关键前置条件。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析