企业官网建设流程全解析

• 人工智能
• 指令集
• 算子库
• CANN
• Ascend

导读：本文聚焦 CANN PTO-ISA 仓库中tget_async_rdma测试目标，它用于在 A5（HNS1825 网卡）平台上验证TGET_ASYNC指令的 RDMA 后端实现——即 root rank 通过 RDMA 单边远程 READ拉取各 peer 的 send buffer。文章以该 target 复用的共享实现（tput_async_rdma/README_zh.md）为主体，完整覆盖前置条件、构建运行命令、环境变量、端点发现流程与问题定位，并深入源码分析TGET_ASYNC的 RDMA 调用链、通信缓冲区布局与测试用例矩阵，帮助读者既能在真实 A5 环境跑通用例，也能理解底层实现原理。

1. RDMA 异步 ST 测试家族与 tget_async_rdma 的定位

在tests/npu/a5/comm/st/testcase/目录下，RDMA 异步 ST 由三个测试目标共享同一套 RDMA 测试 Kernel 实现（共享实现位于 tests/npu/a5/comm/st/testcase/tput_async_rdma）：

tget_async_rdma自身只包含一个简短的 README 说明，指出"该 target 复用 RDMA 异步 ST 的共享实现，前置条件、配置、运行命令和问题定位参见 RDMA异步ST说明"（转换后为 tests/npu/a5/comm/st/testcase/tput_async_rdma/README_zh.md）。其目录结构与tput_async_rdma对等：CMakeLists.txt、README.md/README_zh.md、gen_data.py、main.cpp，其中main.cpp通过#include "../tput_async_rdma/tput_async_rdma_kernel.h"直接复用共享 Kernel 的宿主入口RunGetAsyncRdmaRootGetPlan，而共享 Kernel 文件通过#ifdef PTO_RDMA_GET_TEST条件编译为 GET 目标单独构建TGetAsyncRdmaKernelImpl入口点（见 tput_async_rdma_kernel.cpp）。从源码结构看，tget_async_rdma是 PUT 目标在TPUT_ASYNC之外的平行验证通道，专门覆盖单边读路径。

2. 前置条件

在 A5 平台运行 RDMA 异步 ST 需要满足以下条件（来自 共享 README）：

• 硬件与软件：配备 HNS1825 网卡及匹配驱动、HCOMM 组件的 A5 环境；
• MPI 与 HCCL：按顶层测试说明配置 MPI 和 HCCL；
• 网络：各参与 rank 使用的 RDMA 网卡 IPv4 互相可达。

三个条件缺一不可：HNS1825 网卡驱动与 HCOMM 提供 RDMA 控制面（verbs provider 与 topology 解析），MPI/HCCL 提供多 rank 进程编排与集合通信原语，IPv4 可达性保证数据面通道能够建链。

3. 构建与运行

3.1 选择 RDMA 后端并运行 target

PTO_RDMA_BACKEND必须在CMake 配置阶段之前设置，随后运行所需的 RDMA ST target：

export PTO_RDMA_BACKEND=HNS_1825 python3 tests/script/run_st.py -r npu -v a5 -t comm/tput_async_rdma -d -n 2 python3 tests/script/run_st.py -r npu -v a5 -t comm/tget_async_rdma -d -n 2 python3 tests/script/run_st.py -r npu -v a5 -t comm/tput_async_notify_rdma -d -n 2

命令参数说明（以tests/script/run_st.py为准）：

3.2 关键约束：构建期变量与二进制复用

PTO_RDMA_BACKEND仅在 CMake 配置该 ST 构建时读取一次。未设置、空值或不支持的值会构建不含 RDMA 支持的测试（对应源码中PTO_RDMA_SUPPORTED宏未定义，Kernel 会退化为 SKIP 或空操作路径）。因此：

• run_st.py默认会重新构建，修改该变量后不要使用-w/--without-build复用已有二进制，否则 RDMA 支持不会进入新构建；
• 若 CMake 配置阶段提示 RDMA 未使能，需重新设置PTO_RDMA_BACKEND=HNS_1825并在不使用-w的情况下重新配置。

3.3 定向用例运行

run_st.py支持-g/--gtest_filter参数（见 run_st.py），用于只运行指定 gtest case。首次验证TPUT_ASYNC_NOTIFY时，建议先只运行 2 个 rank 的定向用例：

export PTO_RDMA_BACKEND=HNS_1825 python3 tests/script/run_st.py -r npu -v a5 -t comm/tput_async_notify_rdma \ -g TPutAsyncNotifyRdma.Int32SetAndCanaries -d -n 2

该用例检查远端 payload、远端 signal 及 signal 两侧 canary，并等待接口返回的AsyncEvent完成。接收端观察到 signal 后先维护数据缓存，再校验 payload。tget_async_rdma同样可以借助-g TGetAsyncRdma.*或具体 case 名做定向验证。

注意：当前 RDMA 后端不支持AtomicAdd，因此没有对应的 RDMA 用例。

4. 测试用例矩阵与覆盖维度

tget_async_rdma的用例全部定义在 main.cpp 中，通过ExpectGetPlan/ExpectGetResult模板统一驱动RunGetAsyncRdmaRootGetPlan，覆盖了多个数据形状与完成模式维度：

由此可以归纳出测试覆盖的四个维度：

1. 数据类型与字节宽度：float（4B）、int32（4B）、uint8（1B），覆盖不同元素大小的 RDMA 传输；
2. 数据规模：从 64B 小报文（Vec_Uint8_64B）到约 2MB 大缓冲区（Vec_Float_MR_6MB，524288×4B）的多档位；
3. 传输计划（transfer plan）：非零偏移（Vec_Uint8_Offset_63B）、多 WQE 分片（Vec_Int32_MultiWqe_*）；
4. 完成模式（completion mode）：三种模式全部覆盖（详见下文 5.4 节）。

所有用例在 rank 数不足时通过SKIP_IF_RANKS_LT直接跳过，多 rank 用例（如Vec_FloatSmall_4Ranks）需要mpirun至少 4 个进程。每个用例运行前还会校验传输计划的合法性：elemOffset >= 0 && elemCount > 0 && operationCount > 0，且offset + count×operations ≤ 总元素数（见 tput_async_rdma_kernel.cpp）。

5. 数据面实现：TGET_ASYNC 的 RDMA 调用链

5.1 指令入口与引擎分派

TGET_ASYNC的 A5 实现在 include/pto/comm/a5/async/TGetAsync.hpp 中，通过模板参数DmaEngine在 SDMA、URMA、RDMA 三种引擎间分派。当指定DmaEngine::RDMA时，编译路径进入TGET_ASYNC_RDMA_IMPL：

// 摘录自 include/pto/comm/a5/async/TGetAsync.hpp const uint64_t eventHandle = rdma::Read( session, reinterpret_cast<__gm__ uint8_t*>(dstGlobalData.data()), reinterpret_cast<__gm__ uint8_t*>(srcGlobalData.data()), transferSize, peer); return AsyncEvent(eventHandle, DmaEngine::RDMA);

其中dst是本端（本地 recv buffer）、src是远端（peer 的 send buffer），peer参数用于选择对应的 RDMA 队列/内存资源——这正是"单边远程 READ"语义的体现：数据由本端发起读取，远端网卡无需 CPU 参与。调用前有两条关键校验（见 TGetAsync.hpp）：

• TGetAsyncIsFlatContiguous1D：src/dst tensor 必须是 packed 布局的单逻辑行（flat contiguous 1D），否则触发PTO_ASSERT；
• dstElems >= srcElems：本地接收缓冲区必须不小于远端数据量。

5.2 通信缓冲区布局

共享 Kernel 采用与 URMA 测试一致的对齐通信缓冲区布局（见 tput_async_rdma_kernel.cpp）：

[64 × int32 header][sendBuf: count × T][recvBuf: count × T]

• kRdmaTestDataOffset = 64 * sizeof(int32_t)：数据区起始偏移，header 首字用于写 device status；
• GET 路径下，recvBuf = sendBuf + count（本地接收区紧随本地 send 区之后），远端目标 VA 通过PeerMrBaseAddr(rdmaWorkspace, sourcePeer) + kRdmaTestDataOffset计算得到——即从 peer 已注册 MR 的基址（PeerMrBaseAddr）加上接收区偏移。

5.3 多 peer、多 WQE 的 GET 执行流程

ExecuteGetRdma（见 tput_async_rdma_kernel.cpp）描述了 root rank 上的完整数据面流程：

1. 清空deviceStatus，通过pipe_barrier(PIPE_ALL)与其他 rank 同步；
2. 仅 root rank 继续：用TASSIGN清零 scratch tile，调用BuildRdmaTestSession建立AsyncSession（失败则写kRdmaSessionBuildError并退出）；
3. 遍历每个sourcePeer（跳过自身），取peerBase = PeerMrBaseAddr(workspace, sourcePeer)，调用PostGetOperations；
4. PostGetOperations内循环operationCount次：每次计算 operation 内偏移，构造本地 recvGlobalTensor与远端 sendGlobalTensor，调用TGET_ASYNC<DmaEngine::RDMA>(localRecvGlobal, remoteSendGlobal, session, sourcePeer)，将返回的AsyncEvent交给完成模式处理；
5. 任一操作失败即提前 break，最终状态写入deviceStatus并经pipe_barrier通知对端。

值得注意的是 PUT 路径中仅 root 写 peer，非 root 直接 barrier 返回；而 GET 路径中所有 rank 都先执行pipe_barrier且本地 recv 区按sourcePeer × count分槽，确保每个 peer 的数据互不覆盖（见InitializeRdmaBuffers<true,...>中的outputElements = nRanks × count）。

5.4 三种完成模式

完成模式枚举定义于 tput_async_rdma_kernel.h，其语义在CompleteRdmaEvent/CompleteRdmaOperation/CompleteRdmaPeer（tput_async_rdma_kernel.cpp）中体现：

STATUS_WAIT_EACH与STATUS_WAIT_LAST分别验证逐 WQE 同步与批量同步两条路径，PUBLIC_EVENT_WAIT_TEST则专门覆盖公共事件的 Test/Wait/Test 语义组合。

6. 控制面：端点发现（Bootstrap）机制

6.1 三级本地 IPv4 查找顺序

Bootstrap 先解析每个 rank 的物理设备 id（phyId）和 RDMA IPv4，再通过 MPI 交换端点与注册内存信息。本地 IPv4 的查找顺序为（见 hns_1825_bootstrap.hpp）：

1. 固定 root-info 文件：解析/etc/hccl_rootinfo.json中与 phyId 匹配的 rank 块，取"net_type":"CLOS"条目的 IPv4（ResolveLocalRdmaIp）；
2. HCOMM topology 组件：通过dlsym/dlopen解析GetRoceIpFromXml（libtopoaddrinfo.so），读取固定/var/run/ascend-topologyd/virtualTopology.xml（ResolveLocalRdmaIpFromVirtualTopology）；
3. 测试专用 IP 变量兜底：使用PTO_ROCE_LOCAL_IP/PTO_ROCE_IPS。

ST 不会生成或修改这两个拓扑文件，也不提供路径覆盖变量——路径在源码中以常量固定（kDefaultRootInfoPath、kDefaultVirtualTopologyPath）。phyId 的解析同样采用符号动态解析：优先aclrtGetPhyDevIdByUserDevId，其次aclrtGetPhyDevIdByLogicDevId、rtGetDevicePhyIdByIndex，均不可用时才回退到 ACL device id，或由PTO_ROCE_PHYIDS环境变量按 rank 索引直接指定（见 hns_1825_bootstrap.hpp）。

6.2 MPI 交换与一致性校验

解析出本地端点后，Bootstrap 通过MPI_Allgather完成三类信息的跨 rank 交换：

• peer IP：各 rank 的本地 IPv4 字符串（定长 64B 缓冲区）；
• peer phyId：各 rank 的物理设备 id；
• peer symAddr：各 rank 已注册通信缓冲区的基址 VA（symmetricAddr），后续PeerMrBaseAddr依赖它计算远端目标 VA。

一致性校验有两处关键约束：所有 rank 必须使用相同的 base port（ResolveAndAgreeBasePort会 Allgather 校验，默认60032）；使用PTO_ROCE_IPS时，还必须使用相同的按 rank 排序列表。任一 rank 本地 IP 解析失败都会产生集体 SKIP而非误报 PASS（AgreeOnLocalIp通过AllRanksReady协调）。

6.3 环境变量参考

优先级规则：PTO_ROCE_LOCAL_IP高于PTO_ROCE_IPS；root-info 或 virtual topology 解析成功时，两者均被忽略。

7. 问题定位

• CMake 提示 RDMA 未使能：设置PTO_RDMA_BACKEND=HNS_1825，并在不使用-w/--without-build的情况下重新配置构建。
• 端点发现失败：检查物理设备映射以及 root-info 或 virtual topology 中的 CLOS IPv4，必要时使用测试专用 IP 变量兜底。
• verbs provider 加载失败：HCOMM 无法从默认路径加载 HNS1825 verbs provider 时，将IBV_EXTEND_DRIVERS指向驱动提供的libhrn5-rdmav34.so。
• 阶段区分：设置PTO_ROCE_VERBOSE=1，可区分端点发现、MR 注册、channel 建链和释放阶段的错误。Kernel 侧还提供设备侧状态码辅助定位：0x30000（public event wait 失败）、0x30001（wait 后 test 失败），以及会话构建失败kRdmaSessionBuildError，host 端PrintRdmaDeviceStatus会将 CQE syndrome 或后端状态描述一并打印（见 tput_async_rdma_kernel.cpp）。

8. 小结

tget_async_rdma作为 RDMA 异步 ST 家族中的远程 READ 验证目标，完整覆盖了TGET_ASYNC<DmaEngine::RDMA>从指令分派、rdma::Read单边读、通信缓冲区寻址到多 WQE/多完成模式的整条链路。它与tput_async_rdma、tput_async_notify_rdma共享同一套 Kernel 与 Bootstrap 实现，体现了 PTO 测试体系"一个共享实现、多个验证视角"的组织方式。无论是排查端点发现问题，还是深入理解单边通信的数据面/控制面分工，本文所梳理的源码路径（tput_async_rdma_kernel.cpp、hns_1825_bootstrap.hpp、TGetAsync.hpp）都值得继续深读。

• 人工智能
• 指令集
• 算子库
• CANN
• Ascend