🔥Latest News

• [2026/07] asc-comm项目首次上线

🚀 当前能力

• 提供AICore侧Hcomm点对点通信接口，覆盖普通Init、ReadNbi、WriteNbi、WriteWithNotifyNbi、AtomicFAA、AtomicCAS、Commit、Drain，以及Ascend 950 UB_CTP路径的MakeBatchHandle、批量读写、BatchCommit和批量Drain。
• 提供AIV直驱Hcomm RoCE和UB_CTP/URMA相关实现，主实现位于src/aicore/hcomm/。
• 提供AICore侧Ain单边通信接口，覆盖Put、PutValue、Get、Signal、ReadSignal、WaitSignal、Flush、FlushAsync、Wait，以及AinBarrierSession集合通信同步原语，主实现位于src/aicore/ain/。
• 提供Hcomm UT工程，覆盖ascend950pr_9599_AIV的RoCE/URMA普通接口和UB_CTP批量接口，以及ascend910B1_AIC基础接口用例。
• 提供Ain UT工程，覆盖ascend950pr_9599_AIV的URMA路径下Put/Get/Signal/ReadSignal/WaitSignal/BarrierSession接口用例。
• 提供hcomm_write_read_nbi样例，演示AIV直驱URMA场景下WriteNbi和ReadNbi点对点通信流程，并包含运行样例所需的Host侧资源准备流程。
• 提供SIMT URMA WriteNbi、WriteValueNbi、ReadNbi、WriteWithNotifyNbi、AtomicFAA、AtomicCAS和Drain，以及simt_urma功能样例和simt_urma_perftest性能样例。

📖 资料文档

• 新增快速开始、构建与测试、三方依赖与兼容性说明。
• 新增Hcomm使用说明和API参考，覆盖当前公开的Hcomm接口。
• 新增样例目录，提供Hcomm AIV直驱调用和端到端通信样例入口。

有关所有历史版本及更新的详细信息，请参阅CHANGELOG.md。

🚀概述

asc-comm是面向昇腾AI处理器通信场景的开源仓，当前用于承载AICore侧公开API、AIV直驱设备侧实现、API文档、样例和验证能力。

当前公开能力包括AscendC::Hcomm点对点通信和AscendC::Ain单边通信，面向算子Kernel侧通信数据路径。Hcomm侧使用方通过AscendC::Hcomm模板选择通信协议：普通接口通过ChannelHandle逐条提交通信任务；Ascend 950 UB_CTP路径还可以通过BatchHandle添加多个通信任务，并通过BatchCommit统一提交。两种流程分别通过对应的Drain重载管理完成等待。Ain侧使用方通过AscendC::Ain模板基于对称窗口（Symmetric Window）发起Put/Get/Signal等单边操作，通过Flush或FlushAsync+Wait管理完成等待。

交付与构建方式

asc-comm 数据面产物由 asc-devkit run 包联合编译并交付；本仓以构建挂接方式成为 asc-devkit 的构建子工程（源码仓独立、同级放置）。编译期不依赖 hcomm 源码树或已安装 hcomm 头文件；跨 SO ABI 头原样保存在本仓 include/hcomm 下。本仓另提供开发期头文件热补丁包（build.sh --pkg，仅 aicore 头，不含 SO）。

数据面能力

能力	当前状态
AICore Hcomm公开接口	已提供Kernel侧普通Init、读写、写通知、原子、Commit和Drain接口；Ascend 950 UB_CTP路径还提供MakeBatchHandle、批量ReadNbi/WriteNbi/WriteWithNotifyNbi、BatchCommit和批量Drain。
AICore Ain公开接口	已提供Kernel侧Put、PutValue、Get、Signal、ReadSignal、WaitSignal、Flush、FlushAsync、Wait，以及AinBarrierSession同步原语。
AIV直驱实现	已提供Hcomm RoCE和UB_CTP/URMA相关实现，主实现位于src/aicore/hcomm/；Ain实现位于src/aicore/ain/。
AIV直驱样例配套流程	hcomm_write_read_nbi包含AIV直驱URMA通信所需的通信域创建、通信内存注册、P2P通道创建和远端内存获取流程。
协议能力	COMM_PROTOCOL_ROCE支持普通读写、提交和等待；COMM_PROTOCOL_UB_CTP支持普通读写、写通知、原子操作、提交和等待，Ascend 950还支持批量读写、写通知、提交和等待。
UT验证	UT覆盖ascend950pr_9599_AIV的Hcomm RoCE/URMA普通接口、UB_CTP批量接口与Ain URMA路径，以及ascend910B1_AIC基础接口用例。
AIV直驱样例	提供hcomm_write_read_nbi样例，覆盖两卡AIV直驱URMA WriteNbi/ReadNbi对称通信和结果校验流程。
SIMT URMA接口	提供WriteNbi、WriteValueNbi、ReadNbi、WriteWithNotifyNbi、AtomicFAA、AtomicCAS和Drain；延迟任务由后续commit=true任务统一发布。
SIMT URMA样例	提供simt_urma功能样例，覆盖全部五个接口的单接口、连续提交和batch-last提交；提供simt_urma_perftest性能样例，统计下发时延与完成带宽。

如何使用Hcomm接口

Hcomm Kernel侧使用时包含如下头文件：

#include "hcomm/hcomm.h"

普通接口调用流程如下：

1. 创建AscendC::Hcomm对象，并选择通信协议。
2. 调用Init初始化临时工作区。
3. 通过ReadNbi、WriteNbi、WriteWithNotifyNbi、AtomicFAA或AtomicCAS提交通信任务。
4. 如果提交任务时设置commit = false，调用Commit显式提交通信任务。
5. 调用Drain等待通道上的通信任务完成。

Ascend 950 UB_CTP批量接口调用流程如下：

1. 准备UB工作区，通过MakeBatchHandle创建批量句柄。该流程不依赖Init。
2. 通过BatchHandle重载的ReadNbi、WriteNbi或WriteWithNotifyNbi向当前批次添加任务，同一批次可以混合三种任务。
3. 调用BatchCommit提交当前批次。
4. 可以复用句柄继续添加和提交任务，最后调用BatchHandle重载的Drain等待任务完成。

使用BatchHandle期间，调用方需要独占其关联的通道资源，不能混用普通接口或并发使用其他BatchHandle。批量操作访问的远端地址必须属于创建或选择批量句柄时指定的远端注册内存。

协议能力说明：

协议	能力说明
COMM_PROTOCOL_ROCE	RoCE点对点通信路径，支持普通ReadNbi、WriteNbi、Commit、Drain，不支持WriteWithNotifyNbi和BatchHandle接口。
COMM_PROTOCOL_UB_CTP	UBC CTP/URMA点对点通信路径，支持普通ReadNbi、WriteNbi、WriteWithNotifyNbi、AtomicFAA、AtomicCAS、Commit、Drain；Ascend 950还支持BatchHandle批量接口。

详细参数约束和返回值说明请参考Hcomm使用说明和API参考。

如何使用Ain接口

Ain Kernel侧使用时包含如下头文件：

#include "ain/ain.h"

基本调用流程如下：

1. 创建AscendC::Ain对象，绑定通信上下文索引。
2. 通过Put/PutValue/Get发起单边读写，或通过Signal发起远端原子信号操作。
3. 如果提交任务时设置AIN_COMMIT_DELAYED，提交将被延迟，直到后续AIN_COMMIT_IMMED任务触发敲门铃；否则立即提交。
4. 完成等待可通过Flush或FlushAsync+Wait管理。
5. 通过ReadSignal/WaitSignal读取或等待本地信号。
6. 如需集合同步，通过AinBarrierSession的Sync完成同步。

提交模式说明：

模式	行为说明
AIN_COMMIT_IMMED	组装通信任务后立即敲响门铃，提交给底层引擎执行。
AIN_COMMIT_DELAYED	仅组装通信任务，不敲门铃；延迟到后续AIN_COMMIT_IMMED任务触发提交。

详细参数约束和返回值说明请参考API参考。

🔍目录结构说明

本仓主要包含asc-comm AICore侧通信数据面API、设备侧实现、样例、文档和UT用例，目录结构如下：

├── cmake                         # asc-comm CMake辅助模块
├── docs                          # 项目文档介绍
├── examples                      # asc-comm API样例目录
│   ├── hcomm_write_read_nbi      # Hcomm AIV直驱URMA两卡P2P通信样例
│   ├── simt_urma                 # Hcomm SIMT URMA功能样例
│   └── simt_urma_perftest        # Hcomm SIMT URMA性能样例
├── include                       # asc-comm API声明源代码
│   ├── aicore/hcomm              # AICore侧Hcomm公开接口
│   └── aicore/ain                # AICore侧Ain单边通信公开接口
├── scripts                       # 脚本
├── src                           # asc-comm API实现源代码
│   ├── aicore/hcomm              # AICore侧Hcomm实现细节
│   │   ├── common                # Hcomm公共定义和工具
│   │   └── impl                  # Hcomm协议实现与平台差异代码
│   └── aicore/ain                # AICore侧Ain实现细节
│       └── impl                  # Ain单边通信原语实现
└── tests                         # asc-comm API UT用例
    └── ut/aicore
        ├── hcomm                 # AICore Hcomm UT工程
        └── ain                   # AICore Ain UT工程

⚡️快速入门

若您希望快速体验项目构建和UT验证，请先配置CANN环境：

source /usr/local/Ascend/cann/set_env.sh

默认构建用于检查基础环境。当前AICore Hcomm与Ain代码以头文件形式集成，非UT构建不会生成独立库：

bash build.sh

默认构建会复用已有的build/目录，不会自动删除构建产物。如需清理构建目录，请显式执行：

bash build.sh --make_clean

构建并运行Hcomm与Ain UT：

bash build.sh -t

将仓库中的asc-comm头文件制作为开发验证run包，并安装到已有CANN环境：

bash build.sh --pkg
./build_out/cann-asc-comm_9.2.0_linux-<arch>.run --full

制包脚本会递归收集include/和src/中的头文件，其中Hcomm安装到adv_api，其他头文件按相对路径安装到comm_api。安装目录、命令参数、权限和卸载说明见构建与测试。

如需直接使用CMake构建UT，可指定CANN三方依赖目录：

cmake -S tests/ut -B build/ut-hcomm -DCANN_3RD_LIB_PATH=<third_party_path>
cmake --build build/ut-hcomm

更多环境准备、Docker、CANN包安装和UT依赖说明请参考快速开始和构建与测试。

🧰clangd/IDE支持

• 安装clangd，推荐使用15或以上版本。
• 配置本地IDE时，需要将CANN头文件目录和本仓include/目录加入索引路径。
• 在修改Hcomm Kernel侧代码前，建议先source /usr/local/Ascend/cann/set_env.sh，确保CANN相关环境变量已配置。
• 如果使用VS Code，可结合C/C++、clangd等插件完成代码跳转、语法检查和头文件索引。

📖相关资源

• 文档

  文档	说明
  文档入口	asc-comm文档总入口。
  快速开始	环境准备、源码编译和UT验证。
  API参考	asc-comm当前公开接口列表。
  Hcomm使用说明	Hcomm点对点通信接口的基本使用流程。
  构建与测试	CANN环境、开发验证run包、UT构建和样例构建说明。
  三方依赖与兼容性	本仓直接依赖、样例运行依赖、安装配置和集成依赖边界。
  样例目录	asc-comm API样例入口。

• 贡献指南

  文档	说明
  CANN社区贡献指南	CANN社区Issue、PR等通用处理流程。
  asc-comm贡献指南	本仓Issue、开发、检查和PR提交流程。
  API文档贡献指南	新增或修改API文档时的结构、约束和检查要求。
  资料贡献指南	README、docs、examples等资料文档的补充规范。

• 其他

  文档	说明
  更新日志	版本变更记录。
  安全声明	安全问题反馈和处理说明。
  三方开源软件清单	本仓三方开源软件清单。
  三方开源软件声明	本仓三方开源软件声明。

📌相关规划

• 持续补充AIV直驱Hcomm端到端样例，覆盖更多协议路径和通信接口。
• 持续完善不同产品、协议路径下的构建验证和UT覆盖。
• 持续补充API约束、使用说明和常见问题。

📝相关信息

• 贡献指南
• 安全声明
• 许可证