docs:添加贡献、安全、CHANGELOG、以及docs下md的英文版本-asc-comm-AtomGit

已合并

docs:添加贡献、安全、CHANGELOG、以及docs下md的英文版本 #47

哈喽Kiter创建于 7月22日从zhengdun/asc-comm： docs/add-en 合入到 cann/asc-comm： master

docs:添加贡献、安全、CHANGELOG、以及docs下md的英文版本 #47

已合并

哈喽Kiter创建于 7月22日

从zhengdun/asc-comm docs/add-en合入到cann/asc-comm master

共 42 个文件变更+1386-41

Rpre-commit-config.yaml→.pre-commit-config.yaml+0-0

文件重命名但无更改。

ACHANGELOG_en.md+13-0

@@ -0,0 +1,13 @@
	1	+# Changelog
	2	+
	3	+This document records major changes to the asc-comm repository.
	4	+
	5	+## Unreleased
	6	+### Added
	7	+- Added project documentation index, Quick Start, Build & Test, and Third-party Dependencies & Compatibility documents.
	8	+- Added API reference documents for AICore Hcomm point-to-point communication interfaces, including `Hcomm`, `Init`, `ReadNbi`, `WriteNbi`, `WriteWithNotifyNbi`, `AtomicFAA`, `AtomicCAS`, `Commit`, `Drain`.
	9	+- Added the AIV direct-driven URMA Hcomm sample `hcomm_write_read_nbi`, covering two-card point-to-point communication workflow with `WriteNbi` and `ReadNbi`.
	10	+- Added Issue templates, contribution guide and documentation contribution specifications.
	11	+
	12	+### Notes
	13	+- The currently exposed capabilities mainly cover AICore Hcomm point-to-point communication interfaces.

ACONTRIBUTING_en.md+51-0

@@ -0,0 +1,51 @@
	1	+# Contribution Guide
	2	+
	3	+All developers are welcome to try out and contribute to this project. Before participating in community contributions, please refer to [cann-community](https://gitcode.com/cann/community) to review the code of conduct, sign the CLA, and learn about the contribution workflow for source repositories.
	4	+
	5	+Please pay attention to the following key points when preparing local code and submitting pull requests (PRs):
	6	+
	7	+1. When submitting a PR, carefully fill in information such as business background, objectives and implementation plan following the PR template.
	8	+2. If your changes are not simple bug fixes but involve new features, new APIs, new configuration parameters or modifications to code workflows, please initiate a design discussion via an Issue in advance to avoid PR rejection. If you are unsure whether your change qualifies as a "simple bug fix", you may also start a discussion by creating an Issue.
	9	+
	10	+## API Development Guide
	11	+Contributions related to APIs are accepted in this project. Before adding or modifying APIs, developers shall describe usage scenarios, interface design, compatibility impacts and test plans via an Issue. For changes introducing new features, new APIs or behavioral adjustments, PRs can only be submitted after the design discussion reaches consensus.
	12	+
	13	+Common API-related contributions include:
	14	+- Adding new API capabilities
	15	+- Fixing API defects
	16	+- Optimizing API implementations
	17	+- Supplementing API tests
	18	+- Improving API usage documentation and samples
	19	+
	20	+## Documentation Contribution Guide
	21	+Developers are welcome to correct, supplement and optimize project documentation. Documentation updates shall maintain accurate descriptions, clear structure, and consistency with source code, samples and test behaviors.
	22	+
	23	+Typical documentation contribution scenarios include:
	24	+- Correcting inaccurate descriptions in documents
	25	+- Adding missing API constraints, parameter descriptions or return value explanations
	26	+- Supplementing instructions for building, testing, dependencies or samples
	27	+- Fixing broken links, formatting errors or ambiguous wording
	28	+
	29	+When adding or updating API documentation, please refer to [API Documentation Contribution Guide](./docs/api_contributing_en.md).
	30	+When adding or updating README, docs, examples and other materials, please refer to [Documentation Contribution Guide](./docs/doc_contributing_en.md).
	31	+
	32	+## Main Contribution Scenarios for Developers
	33	+- Bug Fixes
	34	+If you discover bugs in this project and intend to fix them, feel free to create an Issue for tracking.
	35	+
	36	+Follow the guide at [Create & Process Issues](https://gitcode.com/cann/community#提交Issue处理Issue任务) to create a `Bug-Report` Issue describing the bug. You may type `/assign` or `/assign @yourself` in the comment area to assign this Issue to yourself for resolution.
	37	+
	38	+- Code Optimization
	39	+If you have ideas for general enhancements or optimizations to existing implementations, contributions are highly encouraged.
	40	+
	41	+Follow the guide at [Create & Process Issues](https://gitcode.com/cann/community#提交Issue处理Issue任务) to create a `Requirement` Issue with optimization details and your design proposal. Type `/assign` or `/assign @yourself` in the comment area to assign the Issue to yourself for tracking and implementation.
	42	+
	43	+- Documentation Corrections
	44	+If you spot incorrect descriptions in documents, create an Issue to report and fix them.
	45	+
	46	+Follow the guide at [Create & Process Issues](https://gitcode.com/cann/community#提交Issue处理Issue任务) to create a `Documentation` Issue pointing out document issues. Type `/assign` or `/assign @yourself` in the comment area to assign the Issue to yourself for revisions.
	47	+
	48	+- Assisting with Community Issues
	49	+If you have viable solutions to problems raised by other community members, feel free to comment under relevant Issues to share insights, resolve pain points and improve overall usability.
	50	+
	51	+If code modifications are required for the corresponding Issue, you may type `/assign` or `/assign @yourself` in the comment area to claim the Issue and follow up on the resolution.

MREADME.md+8-8

	@@ -24,8 +24,8 @@
24		24
25	### 📖 资料文档	25	### 📖 资料文档
26		26
27	-- 新增[快速开始](./docs/quick_start.md)、[构建与测试](./docs/guide/build_and_test.md)、[三方依赖与兼容性](./docs/guide/dependencies.md)说明。	27	+- 新增[快速开始](./docs/quick_start.md)、[构建与测试](./docs/zh/guide/build_and_test.md)、[三方依赖与兼容性](./docs/zh/guide/dependencies.md)说明。
28	-- 新增[Hcomm使用说明](./docs/guide/hcomm_usage.md)和[API参考](./docs/api/README.md)，覆盖当前公开的Hcomm接口。	28	+- 新增[Hcomm使用说明](./docs/zh/guide/hcomm_usage.md)和[API参考](./docs/zh/api/README.md)，覆盖当前公开的Hcomm接口。
29	- 新增[样例目录](./examples/README.md)，提供Hcomm AIV直驱调用和端到端通信样例入口。	29	- 新增[样例目录](./examples/README.md)，提供Hcomm AIV直驱调用和端到端通信样例入口。
30		30
31	有关所有历史版本及更新的详细信息，请参阅[CHANGELOG.md](./CHANGELOG.md)。	31	有关所有历史版本及更新的详细信息，请参阅[CHANGELOG.md](./CHANGELOG.md)。
	@@ -70,7 +70,7 @@ Hcomm Kernel侧使用时包含如下头文件：
70	\| `COMM_PROTOCOL_ROCE` \| RoCE点对点通信路径，支持`ReadNbi`、`WriteNbi`、`Commit`、`Drain`，不支持`WriteWithNotifyNbi`。 \|	70	\| `COMM_PROTOCOL_ROCE` \| RoCE点对点通信路径，支持`ReadNbi`、`WriteNbi`、`Commit`、`Drain`，不支持`WriteWithNotifyNbi`。 \|
71	\| `COMM_PROTOCOL_UBC_CTP` \| UBC CTP/URMA点对点通信路径，支持`ReadNbi`、`WriteNbi`、`WriteWithNotifyNbi`、`AtomicFAA`、`AtomicCAS`、`Commit`、`Drain`。 \|	71	\| `COMM_PROTOCOL_UBC_CTP` \| UBC CTP/URMA点对点通信路径，支持`ReadNbi`、`WriteNbi`、`WriteWithNotifyNbi`、`AtomicFAA`、`AtomicCAS`、`Commit`、`Drain`。 \|
72		72
73	-详细参数约束和返回值说明请参考[Hcomm使用说明](./docs/guide/hcomm_usage.md)和[API参考](./docs/api/README.md)。	73	+详细参数约束和返回值说明请参考[Hcomm使用说明](./docs/zh/guide/hcomm_usage.md)和[API参考](./docs/zh/api/README.md)。
74		74
75	## 🔍目录结构说明	75	## 🔍目录结构说明
76		76
	@@ -120,7 +120,7 @@ cmake -S tests/ut -B build/ut-hcomm -DCANN_3RD_LIB_PATH=<third_party_path>
120	cmake --build build/ut-hcomm	120	cmake --build build/ut-hcomm
121	```	121	```
122		122
123	-更多环境准备、Docker、CANN包安装和UT依赖说明请参考[快速开始](./docs/quick_start.md)和[构建与测试](./docs/guide/build_and_test.md)。	123	+更多环境准备、Docker、CANN包安装和UT依赖说明请参考[快速开始](./docs/quick_start.md)和[构建与测试](./docs/zh/guide/build_and_test.md)。
124		124
125	## 🧰clangd/IDE支持	125	## 🧰clangd/IDE支持
126		126
	@@ -137,10 +137,10 @@ cmake --build build/ut-hcomm
137	\| --- \| --- \|	137	\| --- \| --- \|
138	\| [文档入口](./docs/README.md) \| asc-comm文档总入口。 \|	138	\| [文档入口](./docs/README.md) \| asc-comm文档总入口。 \|
139	\| [快速开始](./docs/quick_start.md) \| 环境准备、源码编译和UT验证。 \|	139	\| [快速开始](./docs/quick_start.md) \| 环境准备、源码编译和UT验证。 \|
140	- \| [API参考](./docs/api/README.md) \| asc-comm当前公开接口列表。 \|	140	+ \| [API参考](./docs/zh/api/README.md) \| asc-comm当前公开接口列表。 \|
141	- \| [Hcomm使用说明](./docs/guide/hcomm_usage.md) \| Hcomm点对点通信接口的基本使用流程。 \|	141	+ \| [Hcomm使用说明](./docs/zh/guide/hcomm_usage.md) \| Hcomm点对点通信接口的基本使用流程。 \|
142	- \| [构建与测试](./docs/guide/build_and_test.md) \| CANN环境、构建脚本、UT构建和样例构建说明。 \|	142	+ \| [构建与测试](./docs/zh/guide/build_and_test.md) \| CANN环境、构建脚本、UT构建和样例构建说明。 \|
143	- \| [三方依赖与兼容性](./docs/guide/dependencies.md) \| 本仓直接依赖、样例运行依赖、安装配置和集成依赖边界。 \|	143	+ \| [三方依赖与兼容性](./docs/zh/guide/dependencies.md) \| 本仓直接依赖、样例运行依赖、安装配置和集成依赖边界。 \|
144	\| [样例目录](./examples/README.md) \| asc-comm API样例入口。 \|	144	\| [样例目录](./examples/README.md) \| asc-comm API样例入口。 \|
145		145
146	- 贡献指南	146	- 贡献指南

AREADME_en.md+154-0

Z zangyan7月28日

这个文档中存在多处链接失效，请使用Doc tools工具进行检查

哈喽Kiter

7月28日评论：

@@ -0,0 +1,154 @@
	1	+<div align="center">
	2	+
	3	+# asc-comm
	4	+
	5	+<h4>Provides Hcomm communication APIs, AIV direct drive implementation, samples and verification cases for communication scenarios on Ascend AI Processors</h4>
	6	+
	7	+[![docs](https://img.shields.io/badge/docs-repo-blue.svg?style=flat)](./docs)
	8	+[![examples](https://img.shields.io/badge/examples-repo-orange.svg?style=flat)](./examples)
	9	+[![license](https://img.shields.io/badge/license-CANN_Open_2.0-lightgrey.svg)](./LICENSE)
	10	+[![contributing](https://img.shields.io/badge/CONTRIBUTING-teal)](./CONTRIBUTING_en.md)
	11	+
	12	+</div>
	13	+
	14	+## 🔥 Latest News
	15	+- [2026/07] Initial release of the asc-comm project
	16	+
	17	+### 🚀 Current Capabilities
	18	+- Exposes AICore-side Hcomm point-to-point communication interfaces, covering `Init`, `ReadNbi`, `WriteNbi`, `WriteWithNotifyNbi`, `AtomicFAA`, `AtomicCAS`, `Commit`, `Drain`.
	19	+- Provides AIV direct-drive implementations for Hcomm RoCE and UBC_CTP/URMA. Core implementations are located under `src/aicore/hcomm/detail/`.
	20	+- Delivers Hcomm UT projects covering RoCE/URMA paths for `ascend950pr_9599_AIV` and basic interface test cases for `ascend910B1_AIC`.
	21	+- Supplies the `hcomm_write_read_nbi` sample, demonstrating the point-to-point communication workflow of `WriteNbi` and `ReadNbi` under the AIV direct-driven URMA scenario, including Host-side resource preparation required to run the sample.
	22	+
	23	+### 📖 Documentation
	24	+- Added [Quick Start](./docs/quick_start_en.md), [Build & Test](./docs/en/guide/build_and_test.md), [Third-party Dependencies & Compatibility](./docs/en/guide/dependencies.md).
	25	+- Added [Hcomm Usage Guide](./docs/en/guide/hcomm_usage.md) and [API Reference](./docs/en/api/README.md), covering all currently published Hcomm interfaces.
	26	+- Added [Samples Directory](./examples/README_en.md), serving as the entry for AIV direct-drive Hcomm invocations and end-to-end communication samples.
	27	+
	28	+For detailed information on all historical releases and updates, please refer to [CHANGELOG.md](./CHANGELOG_en.md).
	29	+
	30	+## 🚀 Overview
	31	+asc-comm is an open-source repository targeting communication scenarios on Ascend AI Processors. It hosts publicly exposed AICore APIs, AIV direct-drive device-side implementations, API documentation, samples and verification suites.
	32	+
	33	+The primary public capability is `AscendC::Hcomm`, designed for point-to-point data communication paths on operator Kernel side. Users select communication protocols via the `AscendC::Hcomm` template, specify communication channels with `ChannelHandle`, and submit communication tasks using non-blocking read/write interfaces. Tasks can be explicitly `Commit`ted on demand, and completion can be awaited via `Drain`.
	34	+
	35	+### Data Plane Capabilities
	36	+\| Capability \| Status \|
	37	+\| --- \| --- \|
	38	+\| Public AICore Hcomm Interfaces \| Kernel-side `Init`, `ReadNbi`, `WriteNbi`, `WriteWithNotifyNbi`, `AtomicFAA`, `AtomicCAS`, `Commit`, `Drain` available. \|
	39	+\| AIV Direct Drive Implementation \| Implementations for Hcomm RoCE and UBC_CTP/URMA are provided; core code resides in `src/aicore/hcomm/detail/`. \|
	40	+\| AIV Direct-drive Sample Supporting Workflow \| `hcomm_write_read_nbi` includes communication domain creation, communication memory registration, P2P channel creation and remote memory acquisition required for AIV direct-driven URMA communication. \|
	41	+\| Protocol Features \| `COMM_PROTOCOL_ROCE`: read/write, commit and wait; `COMM_PROTOCOL_UBC_CTP`: read/write, write-with-notify, atomic operations, commit and wait. \|
	42	+\| UT Verification \| UTs cover RoCE/URMA paths on `ascend950pr_9599_AIV` and basic interface cases for `ascend910B1_AIC`. \|
	43	+\| AIV Direct-drive Samples \| `hcomm_write_read_nbi` demonstrates symmetric two-card AIV direct-driven URMA `WriteNbi`/`ReadNbi` communication and result validation. \|
	44	+
	45	+### How to Use Hcomm Interfaces
	46	+Include the following header when invoking Hcomm on the Kernel side:
	47	+```cpp
	48	+#include "hcomm/hcomm.h"
	49	+```
	50	+
	51	+Basic invocation workflow:
	52	+1. Instantiate an `AscendC::Hcomm` object and select the communication protocol.
	53	+2. Call `Init` to initialize temporary workspace.
	54	+3. Submit communication tasks via `ReadNbi`, `WriteNbi`, `WriteWithNotifyNbi`, `AtomicFAA` or `AtomicCAS`.
	55	+4. If `commit = false` is set during task submission, invoke `Commit` to explicitly submit pending communication tasks.
	56	+5. Call `Drain` to wait for all communication tasks on the channel to complete.
	57	+
	58	+Protocol capability matrix:
	59	+\| Protocol \| Capability Description \|
	60	+\| --- \| --- \|
	61	+\| `COMM_PROTOCOL_ROCE` \| RoCE point-to-point path. Supports `ReadNbi`, `WriteNbi`, `Commit`, `Drain`. `WriteWithNotifyNbi` is not supported. \|
	62	+\| `COMM_PROTOCOL_UBC_CTP` \| UBC CTP/URMA point-to-point path. Supports `ReadNbi`, `WriteNbi`, `WriteWithNotifyNbi`, `AtomicFAA`, `AtomicCAS`, `Commit`, `Drain`. \|
	63	+
	64	+Refer to [Hcomm Usage Guide](./docs/en/guide/hcomm_usage.md) and [API Reference](./docs/en/api/README.md) for detailed parameter constraints and return value descriptions.
	65	+
	66	+## 🔍 Directory Layout
	67	+This repository contains AICore communication data plane APIs, device-side implementations, samples, documentation and UT cases for asc-comm. The structure is as follows:
	68	+```text
	69	+├── cmake # CMake helper modules for asc-comm
	70	+├── docs # Project documentation
	71	+├── examples # asc-comm API samples
	72	+│ └── hcomm_write_read_nbi # Two-card P2P communication sample for AIV direct-driven URMA Hcomm
	73	+├── include # asc-comm API declarations
	74	+│ ├── aicore/hcomm # Public AICore Hcomm interfaces
	75	+│ ├── ain # Reserved directory for AIN-related APIs
	76	+├── scripts # Utility scripts
	77	+├── src # asc-comm API implementations
	78	+│ ├── aicore/hcomm/detail # Internal implementation of AICore Hcomm
	79	+│ │ ├── common # Common definitions and utilities for Hcomm
	80	+│ │ └── impl # Protocol implementations and platform-specific logic
	81	+└── tests # asc-comm API unit tests
	82	+ └── ut/aicore/hcomm # AICore Hcomm UT project
	83	+```
	84	+
	85	+## ⚡️ Quick Start
	86	+To quickly build the project and run Hcomm UTs, configure the CANN environment first:
	87	+```bash
	88	+source /usr/local/Ascend/cann/set_env.sh
	89	+```
	90	+
	91	+Default build for basic environment validation. AICore Hcomm is header-only; no standalone library will be generated for non-UT builds:
	92	+```bash
	93	+bash build.sh
	94	+```
	95	+
	96	+Build and execute Hcomm unit tests:
	97	+```bash
	98	+bash build.sh -t
	99	+```
	100	+
	101	+To build UTs directly via CMake, specify the CANN third-party library path:
	102	+```bash
	103	+cmake -S tests/ut -B build/ut-hcomm -DCANN_3RD_LIB_PATH=<third_party_path>
	104	+cmake --build build/ut-hcomm
	105	+```
	106	+
	107	+See [Quick Start](./docs/quick_start_en.md) and [Build & Test](./docs/en/guide/build_and_test.md) for more details about environment setup, Docker, CANN package installation and UT dependencies.
	108	+
	109	+## 🧰 Clangd / IDE Support
	110	+- Install clangd (version 15 or newer recommended).
	111	+- When configuring local IDEs, add the CANN header directory and the repository `include/` directory to the index paths.
	112	+- Before modifying Hcomm Kernel-side code, run `source /usr/local/Ascend/cann/set_env.sh` to ensure CANN environment variables are loaded.
	113	+- For VS Code, combine C/C++ and clangd extensions to enable code navigation, static checking and header indexing.
	114	+
	115	+## 📖 Related Resources
	116	+- Documentation
	117	+
	118	+ \| Document \| Description \|
	119	+ \| --- \| --- \|
	120	+ \| [Documentation Index](./docs/README_en.md) \| Main entry for asc-comm documentation. \|
	121	+ \| [Quick Start](./docs/quick_start_en.md) \| Environment setup, source compilation and UT verification. \|
	122	+ \| [API Reference](./docs/en/api/README.md) \| List of published asc-comm interfaces. \|
	123	+ \| [Hcomm Usage Guide](./docs/en/guide/hcomm_usage.md) \| Basic workflow for Hcomm point-to-point communication interfaces. \|
	124	+ \| [Build & Test](./docs/en/guide/build_and_test.md) \| CANN environment, build scripts, UT and sample build instructions. \|
	125	+ \| [Third-party Dependencies & Compatibility](./docs/en/guide/dependencies.md) \| Direct dependencies, sample runtime dependencies, installation configuration and integration boundaries. \|
	126	+ \| [Samples Directory](./examples/README_en.md) \| Entry point for asc-comm API samples. \|
	127	+
	128	+- Contribution Guides
	129	+
	130	+ \| Document \| Description \|
	131	+ \| --- \| --- \|
	132	+ \| [CANN Community Contribution Guide](https://gitcode.com/cann/community) \| General workflow for CANN community Issues and PRs. \|
	133	+ \| [asc-comm Contribution Guide](./CONTRIBUTING_en.md) \| Repository-specific rules for Issues, development, checks and PR submission. \|
	134	+ \| [API Documentation Contribution Guide](./docs/api_contributing_en.md) \| Structure, constraints and checklist for adding or updating API docs. \|
	135	+ \| [Documentation Contribution Guide](./docs/doc_contributing_en.md) \| Specification for maintaining README, docs, examples and other documentation. \|
	136	+
	137	+- Others
	138	+
	139	+ \| Document \| Description \|
	140	+ \| --- \| --- \|
	141	+ \| [Changelog](./CHANGELOG_en.md) \| Release change records. \|
	142	+ \| [Security Statement](./SECURITY_en.md) \| Guidelines for vulnerability reporting and handling. \|
	143	+ \| [Third_Party_Open_Source_Software_List.yaml](./Third_Party_Open_Source_Software_List.yaml) \| Inventory of third-party open-source software. \|
	144	+ \| [Third_Party_Open_Source_Software_Notice](./Third_Party_Open_Source_Software_Notice) \| Notices for third-party open-source software. \|
	145	+
	146	+## 📌 Roadmap
	147	+- Continuously add end-to-end AIV direct-drive Hcomm samples covering more protocol paths and communication interfaces.
	148	+- Improve build verification and UT coverage across different products and protocol paths.
	149	+- Supplement API constraints, usage guidance and FAQs.
	150	+
	151	+## 📝 Related Links
	152	+- [Contribution Guide](./CONTRIBUTING_en.md)
	153	+- [Security Statement](./SECURITY_en.md)
	154	+- [License](./LICENSE)

MSECURITY.md+1-1

	@@ -51,6 +51,6 @@
51	\| 维护升级文件目录 \| 770（rwxrwx---） \|	51	\| 维护升级文件目录 \| 770（rwxrwx---） \|
52	\| 业务数据文件 \| 640（rw-r-----） \|	52	\| 业务数据文件 \| 640（rw-r-----） \|
53	\| 业务数据文件目录 \| 750（rwxr-x---） \|	53	\| 业务数据文件目录 \| 750（rwxr-x---） \|
54	-\| 密钥组件、私钥、证书、密文文件目录 \| 700（rwx—----） \|	54	+\| 密钥组件、私钥、证书、密文文件目录 \| 700（rwx------） \|
55	\| 密钥组件、私钥、证书、加密密文 \| 600（rw-------） \|	55	\| 密钥组件、私钥、证书、加密密文 \| 600（rw-------） \|
56	\| 加解密接口、加解密脚本 \| 500（r-x------） \|	56	\| 加解密接口、加解密脚本 \| 500（r-x------） \|

ASECURITY_en.md+47-0

@@ -0,0 +1,47 @@
	1	+# Security Statement
	Z Z zangyan7月28日所有英文文档一级标题后都缺少一行空行，请统一修改。哈喽Kiter 7月28日评论： 7月28日评论：
	2	+
	3	+## Recommendations for Running Users
	4	+For security considerations, it is not recommended to execute any commands using administrator accounts such as root. Follow the principle of least privilege.
	5	+
	6	+## File Permission Control
	7	+- Users are advised to set the system umask value to 0027 or higher on hosts (including physical machines) and containers. This ensures newly created directories have a maximum default permission of 750 and newly created files have a maximum default permission of 640.
	8	+- Users shall implement proper permission control and other security measures for sensitive content including personal private data, commercial assets, source files, and various files generated during code development. Examples include permission management for the project installation directory and public input data files. Refer to [A - Recommended Maximum Permissions for Files/Directories in Different Scenarios](https://gitcode.com/cann/asc-devkit/blob/master/SECURITY.md#a-文件夹各场景权限管控推荐最大值) for suggested permission settings.
	9	+- Users shall enforce permission control during installation and usage. Configure permissions with reference to the guidelines in [A - Recommended Maximum Permissions for Files/Directories in Different Scenarios](https://gitcode.com/cann/asc-devkit/blob/master/SECURITY.md#a-文件夹各场景权限管控推荐最大值).
	10	+
	11	+## Build Security Statement
	12	+If you compile and install this project from source code, intermediate files will be generated during compilation. After compilation completes, it is recommended to apply proper permission restrictions on these intermediate files to ensure file security.
	13	+
	14	+## Runtime Security Statement
	15	+- The process will exit and print error logs upon runtime exceptions. Locate the root cause according to the error prompts.
	16	+
	17	+## Public Network Address Disclosure
	18	+Public network addresses contained within the project source code are listed below:
	19	+
	20	+\| Type \| Open Source Repository URL \| File Name \| Public IP / Public URL / Domain / Email / Archive URL \| Purpose Description \|
	21	+\|:----:\|:--------------------------:\|:---------:\|:-----------------------------------------------------:\|:--------------------\|
	22	+\| Dependency \| N/A \| cmake/third_party/gtest.cmake \| https://gitcode.com/cann-src-third-party/googletest/releases/download/v1.14.0/googletest-1.14.0.tar.gz \| Download googletest source code from GitCode as compilation dependency \|
	23	+
	24	+## Vulnerability Handling Mechanism
	25	+[Vulnerability Management](https://gitcode.com/cann/community/blob/master/security/security.md)
	26	+
	27	+## Appendix
	28	+### A - Recommended Maximum Permissions for Files/Directories in Different Scenarios
	29	+\| Category \| Recommended Maximum Linux Permission \|
	30	+\| ---- \| ---- \|
	31	+\| User home directory \| 750 (rwxr-x---) \|
	32	+\| Program files (scripts, libraries, etc.) \| 550 (r-xr-x---) \|
	33	+\| Directory for program files \| 550 (r-xr-x---) \|
	34	+\| Configuration files \| 640 (rw-r-----) \|
	35	+\| Directory for configuration files \| 750 (rwxr-x---) \|
	36	+\| Archived / completed log files \| 440 (r--r-----) \|
	37	+\| Active log files (in writing) \| 640 (rw-r-----) \|
	38	+\| Directory for log files \| 750 (rwxr-x---) \|
	39	+\| Debug files \| 640 (rw-r-----) \|
	40	+\| Directory for debug files \| 750 (rwxr-x---) \|
	41	+\| Temporary file directory \| 750 (rwxr-x---) \|
	42	+\| Maintenance & upgrade file directory \| 770 (rwxrwx---) \|
	43	+\| Business data files \| 640 (rw-r-----) \|
	44	+\| Directory for business data files \| 750 (rwxr-x---) \|
	45	+\| Directory for key components, private keys, certificates and encrypted files \| 700 (rwx------) \|
	Z Z zangyan7月28日中文的SECURITY.md这一样存在笔误： 700（rwx—----） — 应为- 哈喽Kiter 7月28日评论： 7月28日评论：
	46	+\| Key components, private keys, certificates and encrypted data \| 600 (rw-------) \|
	47	+\| Encryption/decryption interfaces and scripts \| 500 (r-x------) \|

Mdocs/README.md+8-6

	@@ -4,8 +4,10 @@
4		4
5	```text	5	```text
6	docs/	6	docs/
7	-├── api/ # API参考文档	7	+├── zh/api/ # 中文API参考文档
8	-├── guide/ # 使用、构建与测试指南	8	+├── zh/guide/ # 中文使用、构建与测试指南
		9	+├── en/api/ # 英文API参考文档
		10	+├── en/guide/ # 英文使用、构建与测试指南
9	├── api_contributing.md # API文档贡献指南	11	├── api_contributing.md # API文档贡献指南
10	├── doc_contributing.md # 资料贡献指南	12	├── doc_contributing.md # 资料贡献指南
11	└── quick_start.md # 快速开始	13	└── quick_start.md # 快速开始
	@@ -16,10 +18,10 @@ docs/
16	\| 文档 \| 内容 \|	18	\| 文档 \| 内容 \|
17	\| --- \| --- \|	19	\| --- \| --- \|
18	\| [快速开始](./quick_start.md) \| asc-comm环境准备、源码编译和UT验证。 \|	20	\| [快速开始](./quick_start.md) \| asc-comm环境准备、源码编译和UT验证。 \|
19	-\| [API参考](./api/README.md) \| asc-comm当前公开接口列表。 \|	21	+\| [API参考](./zh/api/README.md) \| asc-comm当前公开接口列表。 \|
20	-\| [Hcomm使用说明](./guide/hcomm_usage.md) \| Hcomm点对点通信接口的基本使用流程。 \|	22	+\| [Hcomm使用说明](./zh/guide/hcomm_usage.md) \| Hcomm点对点通信接口的基本使用流程。 \|
21	-\| [构建与测试](./guide/build_and_test.md) \| CANN环境、构建脚本、UT构建和样例构建说明。 \|	23	+\| [构建与测试](./zh/guide/build_and_test.md) \| CANN环境、构建脚本、UT构建和样例构建说明。 \|
22	-\| [三方依赖与兼容性](./guide/dependencies.md) \| 本仓直接依赖、样例运行依赖、安装配置和集成依赖边界。 \|	24	+\| [三方依赖与兼容性](./zh/guide/dependencies.md) \| 本仓直接依赖、样例运行依赖、安装配置和集成依赖边界。 \|
23	\| [API文档贡献指南](./api_contributing.md) \| 新增或修改API文档时的结构、约束和检查要求。 \|	25	\| [API文档贡献指南](./api_contributing.md) \| 新增或修改API文档时的结构、约束和检查要求。 \|
24	\| [资料贡献指南](./doc_contributing.md) \| README、docs、examples等资料文档的补充规范。 \|	26	\| [资料贡献指南](./doc_contributing.md) \| README、docs、examples等资料文档的补充规范。 \|
25	\| [贡献指南](../CONTRIBUTING.md) \| Issue、开发、检查和PR提交流程。 \|	27	\| [贡献指南](../CONTRIBUTING.md) \| Issue、开发、检查和PR提交流程。 \|

Adocs/README_en.md+26-0

@@ -0,0 +1,26 @@
	1	+# Project Documentation
	2	+
	3	+## Directory Layout
	4	+```text
	5	+docs/
	6	+├── zh/api/ # Chinese API reference documents
	7	+├── zh/guide/ # Chinese usage, build and test guides
	8	+├── en/api/ # English API reference documents
	9	+├── en/guide/ # English usage, build and test guides
	10	+├── api_contributing_en.md # API documentation contribution guide
	11	+├── doc_contributing_en.md # General documentation contribution guide
	12	+└── quick_start_en.md # Quick Start
	13	+```
	14	+
	15	+## Document Index
	16	+\| Document \| Description \|
	17	+\| --- \| --- \|
	18	+\| [Quick Start](./quick_start_en.md) \| Environment setup, source compilation and UT verification for asc-comm. \|
	19	+\| [API Reference](./en/api/README.md) \| List of currently published asc-comm APIs. \|
	20	+\| [Hcomm Usage Guide](./en/guide/hcomm_usage.md) \| Basic workflow for Hcomm point-to-point communication interfaces. \|
	21	+\| [Build & Test](./en/guide/build_and_test.md) \| CANN environment, build scripts, UT compilation and sample build instructions. \|
	22	+\| [Third-party Dependencies & Compatibility](./en/guide/dependencies.md) \| Direct repository dependencies, sample runtime dependencies, installation configuration and integration boundaries. \|
	23	+\| [API Documentation Contribution Guide](./api_contributing_en.md) \| Structure, constraints and checklist for adding or updating API documents. \|
	24	+\| [Documentation Contribution Guide](./doc_contributing_en.md) \| Standards for maintaining README, docs, examples and other documentation. \|
	25	+\| [Contribution Guide](../CONTRIBUTING_en.md) \| Workflow for Issues, development, checks and PR submission. \|
	26	+\| [Samples](../examples/README_en.md) \| Entry point for asc-comm API samples, including the AIV direct-driven URMA WriteNbi/ReadNbi point-to-point communication sample. \|

Mdocs/api_contributing.md+1-1

	@@ -4,7 +4,7 @@
4		4
5	## 适用范围	5	## 适用范围
6		6
7	-适用于`docs/api/`下的公开API参考文档，以及与API行为直接相关的使用说明和样例文档。	7	+适用于`docs/zh/api/`下的公开API参考文档，以及与API行为直接相关的使用说明和样例文档。
8		8
9	## 文档结构	9	## 文档结构
10		10

Adocs/api_contributing_en.md+29-0

@@ -0,0 +1,29 @@
	1	+# API Documentation Contribution Guide
	2	+
	3	+This document specifies requirements for supplementing and modifying asc-comm API documentation. When adding or modifying public APIs, corresponding API references, usage guides, samples and test descriptions shall be updated synchronously.
	4	+
	5	+## Scope
	6	+Applicable to public API reference documents under `docs/en/api/`, as well as usage guides and sample documents directly related to API behaviors.
	7	+
	8	+## Document Structure
	9	+New API documents are recommended to contain the following sections:
	10	+- Function Description: Introduce the purpose, usage scenarios and applicable scope of the API.
	11	+- Function Prototype: Keep consistent with declarations in public header files.
	12	+- Parameter Description: List parameter names, input/output attributes, units and constraints.
	13	+- Template Parameters: For template APIs, explain default values, supported protocols or platform differences.
	14	+- Return Value: Describe success status, failure status and common failure conditions.
	15	+- Constraints: Specify invocation order, address requirements, alignment rules, supported protocol scope and dependent resources.
	16	+
	17	+## Writing Requirements
	18	+- API names, parameter names, default template parameters and return values must conform to source code definitions.
	19	+- When describing protocol capabilities in documents, clearly state supported scope such as `COMM_PROTOCOL_ROCE` and `COMM_PROTOCOL_UBC_CTP`.
	20	+- If an API involves communication channels, registered memory or operator capabilities, clarify resource preparation requirements in constraints.
	21	+- Sample code shall reflect verifiable invocation patterns. Explicitly state prerequisites for code snippets that cannot run independently.
	22	+- When changing API behaviors, synchronously update `docs/api/README.md`, relevant guides, examples and UT descriptions.
	23	+
	24	+## Pre-submission Checklist
	25	+Complete the following checks before submitting changes:
	26	+- Verify that function prototypes in documents match public header files under `include/`.
	27	+- Ensure all link paths can be resolved correctly relative to the current document.
	28	+- Confirm newly added constraints are consistent with existing UTs and implementation logic.
	29	+- If new third-party dependencies or bundled artifacts are introduced, update the third-party software inventory and Notice accordingly.

Mdocs/doc_contributing.md+18-11

	@@ -8,10 +8,10 @@ asc-comm资料体系包含仓库入口、快速开始、构建测试、API参考
8	\| --- \| --- \| --- \|	8	\| --- \| --- \| --- \|
9	\| 仓库入口 \| 项目概述、目录结构、常用文档入口 \| `README.md` \|	9	\| 仓库入口 \| 项目概述、目录结构、常用文档入口 \| `README.md` \|
10	\| 快速开始 \| 环境准备、源码下载、构建和UT验证 \| `docs/quick_start.md` \|	10	\| 快速开始 \| 环境准备、源码下载、构建和UT验证 \| `docs/quick_start.md` \|
11	-\| 构建与依赖 \| 构建脚本、CMake入口、三方依赖说明 \| `docs/guide/` \|	11	+\| 构建与依赖 \| 构建脚本、CMake入口、三方依赖说明 \| `docs/zh/guide/` \|
12	-\| API参考 \| 接口功能、原型、参数、返回值和约束 \| `docs/api/` \|	12	+\| API参考 \| 接口功能、原型、参数、返回值和约束 \| `docs/zh/api/` \|
13	-\| 使用指南 \| API调用流程、协议能力和注意事项 \| `docs/guide/` \|	13	+\| 使用指南 \| API调用流程、协议能力和注意事项 \| `docs/zh/guide/` \|
14	-\| 样例说明 \| 样例目录入口、运行边界和验证说明 \| `examples/` \|	14	+\| 样例说明 \| 样例目录入口、运行边界和验证说明 \| `examples/README.md`、`examples/*/README.md` \|
15		15
16	## 贡献场景	16	## 贡献场景
17		17
	@@ -96,16 +96,23 @@ API行为相关资料应与 `include/` 下公开头文件保持一致。涉及
96	asc-comm资料通过入口文档、指南、API参考和样例说明形成导航关系。新增或修改文档时，应遵循“谁提到其他文档负责的内容，谁添加链接”的原则。	96	asc-comm资料通过入口文档、指南、API参考和样例说明形成导航关系。新增或修改文档时，应遵循“谁提到其他文档负责的内容，谁添加链接”的原则。
97		97
98	```text	98	```text
99	-README.md ──快速上手──→ docs/quick_start.md	99	+README.md ──文档入口──→ docs/README.md
100	- ──构建测试──→ docs/guide/build_and_test.md	100	+ ──快速上手──→ docs/quick_start.md
101	- ──API参考───→ docs/api/	101	+ ──构建测试──→ docs/zh/guide/build_and_test.md
		102	+ ──API参考───→ docs/zh/api/README.md
102	──样例入口──→ examples/README.md	103	──样例入口──→ examples/README.md
103		104
104	-docs/guide/ ──首次引入API──→ docs/api/	105	+docs/README.md ──快速上手──→ docs/quick_start.md
105	- ──涉及样例────→ examples/README.md	106	+ ──使用指南──→ docs/zh/guide/hcomm_usage.md
		107	+ ──构建测试──→ docs/zh/guide/build_and_test.md
		108	+ ──API参考───→ docs/zh/api/README.md
		109	+ ──样例入口──→ examples/README.md
106		110
107	-docs/api/ ───使用流程──→ docs/guide/	111	+docs/zh/guide/ ──首次引入API──→ docs/zh/api/README.md
108	- ───调用示例──→ examples/README.md	112	+ ──涉及样例────→ examples/README.md
		113	+
		114	+docs/zh/api/ ───使用流程──→ docs/zh/guide/hcomm_usage.md
		115	+ ───调用示例──→ examples/hcomm_write_read_nbi/README.md
109	```	116	```
110		117
111	## 更多信息	118	## 更多信息

Adocs/doc_contributing_en.md+102-0

@@ -0,0 +1,102 @@
	1	+# Documentation Contribution Guide
	2	+
	3	+## Overview
	4	+The asc-comm documentation system covers repository overview, Quick Start, Build & Test, API References, usage guides and sample descriptions. Developers may submit PRs to correct, supplement and optimize documents.
	5	+
	6	+\| Document Type \| Content \| Directory \|
	7	+\| --- \| --- \| --- \|
	8	+\| Repository Homepage \| Project overview, directory structure, entry links to major documents \| `README_en.md` \|
	9	+\| Quick Start \| Environment preparation, source download, build and UT verification \| `docs/quick_start_en.md` \|
	10	+\| Build & Dependencies \| Build scripts, CMake entry, third-party dependency descriptions \| `docs/en/guide/` \|
	11	+\| API References \| API functionality, prototypes, parameters, return values and constraints \| `docs/en/api/` \|
	12	+\| Usage Guides \| API invocation workflow, protocol capabilities and notes \| `docs/en/guide/` \|
	13	+\| Sample Documentation \| Sample directory entry, runtime prerequisites and verification instructions \| `examples/README_en.md`, `examples/*/README_en.md` \|
	14	+
	15	+## Contribution Scenarios
	16	+### Document Correction
	17	+If you discover broken links, incorrect paths, non-executable commands, inaccurate parameter values, missing constraints and other issues:
	18	+1. Create a `Documentation \| Documentation Feedback` Issue, describing the location of the problem and expected revisions.
	19	+2. Type `/assign` or `/assign @yourself` in the comment area to assign the Issue to yourself.
	20	+3. Submit a PR after fixing the issue, and describe the verification method in the PR.
	21	+
	22	+### Document Supplement
	23	+To add API descriptions, build instructions, dependency notes, sample explanations or FAQs:
	24	+1. Create a `Requirement \| Feature Request` Issue describing the content to be added and applicable scenarios.
	25	+2. Add new content following the writing specifications defined in this document.
	26	+3. Update relevant entry documents synchronously to avoid orphaned pages.
	27	+
	28	+### Sample Documentation Addition
	29	+When adding new samples, complete supporting documentation that clearly states sample purpose, prerequisites, build & runtime procedures and verification commands.
	30	+
	31	+## Writing Specifications
	32	+### General Rules
	33	+\| Rule \| Requirement \|
	34	+\| --- \| --- \|
	35	+\| Consistency with Code \| Directory structure, build commands, API names, function prototypes and return values must match the actual repository content. \|
	36	+\| Clear Scope \| Explicitly state prerequisites and applicable scope for features that only work under specific conditions, along with verification methods. \|
	37	+\| Verification-oriented \| Quick Start, Build & Test and sample documents shall clarify which operations users can execute directly and which cannot. \|
	38	+\| Valid Links \| Update entry pages after adding new documents, and verify all relative links and image paths. \|
	39	+\| Link on First Mention \| Add hyperlinks when referencing concepts or APIs defined in other documents for the first time; repeated mentions do not require duplicate links. \|
	40	+
	41	+### Document Structure
	42	+New dedicated documents are recommended to include the following sections:
	43	+1. Background or applicable scope
	44	+2. Prerequisites and dependencies
	45	+3. Operation steps or API usage workflow
	46	+4. Constraints and applicable scope
	47	+5. Verification methods
	48	+6. Links to related documents
	49	+
	50	+### API-related Documentation
	51	+Content related to API behaviors must be consistent with public header files under `include/`. Descriptions about protocol capabilities, address constraints, alignment requirements, invocation order or chip differences shall be updated in both API references and usage guides.
	52	+
	53	+### Sample-related Documentation
	54	+Sample documentation shall cover:
	55	+- Sample purpose and covered APIs
	56	+- Sample file structure
	57	+- Whether the sample can be built or run independently
	58	+- Build, run and verification commands
	59	+- Mandatory prerequisites and resource preparation
	60	+
	61	+## Common Modification Scenarios
	62	+- New APIs: Update API references, usage guides, sample documentation and document entry pages synchronously.
	63	+- New samples: Update `examples/README_en.md` with sample purpose, prerequisites and verification steps.
	64	+- Build workflow changes: Update Quick Start and Build & Test documents.
	65	+- New dependencies: Update third-party dependency documentation, third-party software inventory and Notice file.
	66	+- Directory restructuring: Update `README_en.md`, docs entry pages and all affected relative links.
	67	+
	68	+## Pre-PR Self-check Checklist
	69	+- [ ] Document descriptions align with current repository code, directories and scripts.
	70	+- [ ] Markdown tables, code blocks, heading hierarchy and lists are properly formatted.
	71	+- [ ] Relative links and image paths resolve correctly from the location of the document.
	72	+- [ ] Command examples are executable, or clearly marked as illustrative snippets only.
	73	+- [ ] API prototypes, parameters and return values match public header files.
	74	+- [ ] Sample documentation includes prerequisites, build/run procedures and verification steps.
	75	+- [ ] New dependencies are reflected in the third-party software inventory and Notice.
	76	+- [ ] Features not yet merged into code or documents are not described as supported.
	77	+
	78	+## Documentation Navigation & Link Relationships
	79	+asc-comm documents form a navigation network consisting of entry pages, guides, API references and sample materials. When adding or modifying documents, follow the principle: who references content owned by another document adds the corresponding link.
	80	+```text
	81	+README_en.md ──Documentation Index──→ docs/README_en.md
	82	+ ──Quick Start──→ docs/quick_start_en.md
	83	+ ──Build & Test──→ docs/en/guide/build_and_test.md
	84	+ ──API Reference──→ docs/en/api/README.md
	85	+ ──Samples──→ examples/README_en.md
	86	+
	87	+docs/README_en.md ──Quick Start──→ docs/quick_start_en.md
	88	+ ──Usage Guide──→ docs/en/guide/hcomm_usage.md
	89	+ ──Build & Test──→ docs/en/guide/build_and_test.md
	90	+ ──API Reference──→ docs/en/api/README.md
	91	+ ──Samples──→ examples/README_en.md
	92	+
	93	+docs/en/guide/ ──First API reference──→ docs/en/api/README.md
	94	+ ──Sample reference──→ examples/README_en.md
	95	+
	96	+docs/en/api/ ──Usage workflow──→ docs/en/guide/hcomm_usage.md
	97	+ ──Invocation sample──→ examples/hcomm_write_read_nbi/README_en.md
	98	+```
	99	+
	100	+## More Information
	101	+- API Documentation Contribution Guide: [api_contributing_en.md](./api_contributing_en.md)
	102	+- asc-comm Contribution Guide: [CONTRIBUTING_en.md](../CONTRIBUTING_en.md)

Adocs/en/api/README.md+23-0

@@ -0,0 +1,23 @@
	1	+# API Reference
	2	+
	3	+## AICore Hcomm
	4	+\| Document \| Description \|
	5	+\| --- \| --- \|
	6	+\| [Hcomm](./aicore/hcomm/Hcomm.md) \| Overview of AICore-side point-to-point communication interface template, protocol capabilities and usage constraints. \|
	7	+\| [Init](./aicore/hcomm/Init.md) \| Initialize the temporary workspace for Hcomm. \|
	8	+\| [ReadNbi](./aicore/hcomm/ReadNbi.md) \| Submit a point-to-point read task via the specified channel. \|
	9	+\| [WriteNbi](./aicore/hcomm/WriteNbi.md) \| Submit a point-to-point write task via the specified channel. \|
	10	+\| [WriteWithNotifyNbi](./aicore/hcomm/WriteWithNotifyNbi.md) \| Submit a write task and write a remote notification value. \|
	11	+\| [AtomicFAA](./aicore/hcomm/AtomicFAA.md) \| Submit a Fetch-and-add atomic operation task. \|
	12	+\| [AtomicCAS](./aicore/hcomm/AtomicCAS.md) \| Submit a Compare-and-swap atomic operation task. \|
	13	+\| [Commit](./aicore/hcomm/Commit.md) \| Explicitly submit pending communication tasks on the channel. \|
	14	+\| [Drain](./aicore/hcomm/Drain.md) \| Wait for all communication tasks on the channel to complete. \|
	15	+
	16	+## Header File
	17	+```cpp
	18	+#include "hcomm/hcomm.h"
	19	+```
	20	+
	21	+## Related Documents
	22	+- [Hcomm Usage Guide](../guide/hcomm_usage.md)
	23	+- [AIV Direct-driven URMA WriteNbi/ReadNbi Sample](../../../examples/hcomm_write_read_nbi/README_en.md)

Adocs/en/api/aicore/hcomm/AtomicCAS.md+52-0

@@ -0,0 +1,52 @@
	1	+# AtomicCAS
	2	+
	3	+## Function Description
	4	+Submits a Compare-and-swap atomic operation task. It compares the value stored at the remote address `dst` with `compareVal`. If equal, the remote value is replaced with `swapVal`, and the original value before replacement is written to the local `fetchAddr`.
	5	+
	6	+This interface currently only supports the `COMM_PROTOCOL_UBC_CTP` path.
	7	+
	8	+## Function Prototype
	9	+```cpp
	10	+template <
	11	+ typename T,
	12	+ bool commit = true,
	13	+ pipe_t commitPipe = PIPE_S,
	14	+ pipe_t reqPipe = PIPE_MTE3,
	15	+ auto const& config = URMA_DEFAULT_CFG>
	16	+__aicore__ inline int32_t AtomicCAS(
	17	+ AscendC::ChannelHandle channel,
	18	+ GM_ADDR dst,
	19	+ GM_ADDR fetchAddr,
	20	+ T compareVal,
	21	+ T swapVal);
	22	+```
	23	+
	24	+## Parameter Description
	25	+\| Parameter \| Input/Output \| Description \|
	26	+\| --- \| --- \| --- \|
	27	+\| `channel` \| Input \| Communication channel handle. \|
	28	+\| `dst` \| Input/Output \| Remote target GM address for atomic operations. \|
	29	+\| `fetchAddr` \| Output \| Local GM address used to store the original value at the remote address before CAS execution. \|
	30	+\| `compareVal` \| Input \| Comparison value. \|
	31	+\| `swapVal` \| Input \| New value written to the remote target address when comparison succeeds. \|
	32	+
	33	+## Template Parameters
	34	+\| Parameter \| Description \|
	35	+\| --- \| --- \|
	36	+\| `T` \| Data type for atomic operations. Only `int32_t`, `uint32_t`, `int64_t`, `uint64_t` are supported. \|
	37	+\| `commit` \| Whether to perform an immediate commit when submitting the task. \|
	38	+\| `commitPipe` \| Pipe used for commit operations. Default: `PIPE_S`. \|
	39	+\| `reqPipe` \| Pipe used for requests. Default: `PIPE_MTE3`. \|
	40	+\| `config` \| URMA WQE control configuration, only used for URMA path. Defaults to `URMA_DEFAULT_CFG` (strong ordering + fence + CQE enabled). \|
	41	+
	42	+## Return Value
	43	+\| Return Value \| Description \|
	44	+\| --- \| --- \|
	45	+\| `0` \| Task submission succeeded. \|
	46	+\| `-1` \| Task submission failed. \|
	47	+
	48	+## Constraints
	49	+- The communication channel must be initialized before invocation.
	50	+- The passed `ChannelHandle` must correspond to a `COMM_PROTOCOL_UBC_CTP` channel.
	51	+- `dst` must be within the range of the remote buffer registered for the channel. `fetchAddr` stores the original value with a size of `sizeof(T)`.
	52	+- A single `AtomicCAS` task occupies 2 WQE blocks in the URMA SQ.

Adocs/en/api/aicore/hcomm/AtomicFAA.md+47-0

@@ -0,0 +1,47 @@
	1	+# AtomicFAA
	2	+
	3	+## Function Description
	4	+Submits a Fetch-and-add atomic operation task. It performs an atomic addition on the value at the remote address `dst`, and writes the original value before addition to the local `fetchAddr`.
	5	+
	6	+This interface currently only supports the `COMM_PROTOCOL_UBC_CTP` path.
	7	+
	8	+## Function Prototype
	9	+```cpp
	10	+template <
	11	+ typename T,
	12	+ bool commit = true,
	13	+ pipe_t commitPipe = PIPE_S,
	14	+ pipe_t reqPipe = PIPE_MTE3,
	15	+ auto const& config = URMA_DEFAULT_CFG>
	16	+__aicore__ inline int32_t AtomicFAA(
	17	+ AscendC::ChannelHandle channel, GM_ADDR dst, GM_ADDR fetchAddr, T addVal);
	18	+```
	19	+
	20	+## Parameter Description
	21	+\| Parameter \| Input/Output \| Description \|
	22	+\| --- \| --- \| --- \|
	23	+\| `channel` \| Input \| Communication channel handle. \|
	24	+\| `dst` \| Input/Output \| Remote target GM address for atomic operations. \|
	25	+\| `fetchAddr` \| Output \| Local GM address used to store the original value at the remote address before atomic addition. \|
	26	+\| `addVal` \| Input \| Value to be added to the remote target address. \|
	27	+
	28	+## Template Parameters
	29	+\| Parameter \| Description \|
	30	+\| --- \| --- \|
	31	+\| `T` \| Data type for atomic operations. Only `int32_t`, `uint32_t`, `int64_t`, `uint64_t` are supported. \|
	32	+\| `commit` \| Whether to perform an immediate commit when submitting the task. \|
	33	+\| `commitPipe` \| Pipe used for commit operations. Default: `PIPE_S`. \|
	34	+\| `reqPipe` \| Pipe used for requests. Default: `PIPE_MTE3`. \|
	35	+\| `config` \| URMA WQE control configuration, only used for URMA path. Defaults to `URMA_DEFAULT_CFG` (strong ordering + fence + CQE enabled). \|
	36	+
	37	+## Return Value
	38	+\| Return Value \| Description \|
	39	+\| --- \| --- \|
	40	+\| `0` \| Task submission succeeded. \|
	41	+\| `-1` \| Task submission failed. \|
	42	+
	43	+## Constraints
	44	+- The communication channel must be initialized before invocation.
	45	+- The passed `ChannelHandle` must correspond to a `COMM_PROTOCOL_UBC_CTP` channel.
	46	+- `dst` must be within the range of the remote buffer registered for the channel. `fetchAddr` stores the original value with a size of `sizeof(T)`.
	47	+- A single `AtomicFAA` task occupies 2 WQE blocks in the URMA SQ.

Adocs/en/api/aicore/hcomm/Commit.md+26-0

@@ -0,0 +1,26 @@
	1	+# Commit
	2	+
	3	+## Function Description
	4	+Notifies the specified channel that submitted communication tasks can start execution. It is typically invoked explicitly when `commit` is set to `false` in calls to `ReadNbi`, `WriteNbi`, `WriteWithNotifyNbi`, `AtomicFAA` or `AtomicCAS`.
	5	+
	6	+## Function Prototype
	7	+```cpp
	8	+template <pipe_t pipe = PIPE_S>
	9	+__aicore__ inline int32_t Commit(AscendC::ChannelHandle channel);
	10	+```
	11	+
	12	+## Parameter Description
	13	+\| Parameter \| Input/Output \| Description \|
	14	+\| --- \| --- \| --- \|
	15	+\| `channel` \| Input \| Communication channel handle. \|
	16	+
	17	+## Template Parameters
	18	+\| Parameter \| Description \|
	19	+\| --- \| --- \|
	20	+\| `pipe` \| Pipe used for commit operations. Default: `PIPE_S`. \|
	21	+
	22	+## Return Value
	23	+\| Return Value \| Description \|
	Z Z zangyan7月28日其他md，例如AtomicFAA.md中返回值都是翻译的：Task submission succeeded 建议保持统一。哈喽Kiter 7月28日评论： 7月28日评论：
	24	+\| --- \| --- \|
	25	+\| `0` \| Task submission succeeded. \|
	26	+\| `-1` \| Task submission failed. \|

Adocs/en/api/aicore/hcomm/Drain.md+26-0

@@ -0,0 +1,26 @@
	1	+# Drain
	2	+
	3	+## Function Description
	4	+Blocks and waits until all communication tasks on the specified channel complete execution.
	5	+
	6	+## Function Prototype
	7	+```cpp
	8	+template <pipe_t pipe = PIPE_MTE3>
	9	+__aicore__ inline int32_t Drain(AscendC::ChannelHandle channel);
	10	+```
	11	+
	12	+## Parameter Description
	13	+\| Parameter \| Input/Output \| Description \|
	14	+\| --- \| --- \| --- \|
	15	+\| `channel` \| Input \| Communication channel handle. \|
	16	+
	17	+## Template Parameters
	18	+\| Parameter \| Description \|
	19	+\| --- \| --- \|
	20	+\| `pipe` \| Pipe used for drain operations. Default: `PIPE_MTE3`. \|
	21	+
	22	+## Return Value
	23	+\| Return Value \| Description \|
	24	+\| --- \| --- \|
	25	+\| `0` \| Waiting succeeded. \|
	26	+\| `-1` \| Waiting failed. \|

Adocs/en/api/aicore/hcomm/Hcomm.md+58-0

@@ -0,0 +1,58 @@
	1	+# Hcomm
	2	+
	3	+## Function Description
	4	+Header file:
	5	+```cpp
	6	+#include "hcomm/hcomm.h"
	7	+```
	8	+`AscendC::Hcomm` is a point-to-point communication interface template on the AICore side. It supports submitting read, write, write-with-notify and atomic operation tasks via communication channels. Task submission and completion waiting are controlled through `Commit` and `Drain`. This document describes protocol capabilities and usage constraints for RoCE and UBC_CTP/URMA paths.
	9	+
	10	+## Template Parameters
	11	+```cpp
	12	+template <AscendC::CommProtocol commProtocol = AscendC::COMM_PROTOCOL_UBC_CTP>
	13	+class Hcomm;
	14	+```
	15	+
	16	+\| Parameter \| Description \|
	17	+\| --- \| --- \|
	18	+\| `commProtocol` \| Communication protocol type. Supports `COMM_PROTOCOL_ROCE` and `COMM_PROTOCOL_UBC_CTP`. Default value: `COMM_PROTOCOL_UBC_CTP`. \|
	19	+
	20	+## Protocol Capabilities
	21	+\| API \| `COMM_PROTOCOL_ROCE` \| `COMM_PROTOCOL_UBC_CTP` \|
	22	+\| --- \| --- \| --- \|
	23	+\| `Init` \| Supported; requires UB temporary workspace. \| Supported; requires URMA temporary workspace. \|
	24	+\| `ReadNbi` \| Supported. \| Supported. \|
	25	+\| `WriteNbi` \| Supported. \| Supported. \|
	26	+\| `WriteWithNotifyNbi` \| Not supported; invocation returns failure. \| Supported. \|
	27	+\| `AtomicFAA` \| Not supported. \| Supported. \|
	28	+\| `AtomicCAS` \| Not supported. \| Supported. \|
	29	+\| `Commit` \| Supported. \| Supported. \|
	30	+\| `Drain` \| Supported. \| Supported. \|
	31	+
	32	+## Common APIs
	33	+\| API \| Description \|
	34	+\| --- \| --- \|
	35	+\| [Init](./Init.md) \| Initialize Hcomm temporary workspace. \|
	36	+\| [ReadNbi](./ReadNbi.md) \| Submit a read task via the specified channel. \|
	37	+\| [WriteNbi](./WriteNbi.md) \| Submit a write task via the specified channel. \|
	38	+\| [WriteWithNotifyNbi](./WriteWithNotifyNbi.md) \| Submit a write task and write a notification value. \|
	39	+\| [AtomicFAA](./AtomicFAA.md) \| Submit a Fetch-and-add atomic operation task. \|
	40	+\| [AtomicCAS](./AtomicCAS.md) \| Submit a Compare-and-swap atomic operation task. \|
	41	+\| [Commit](./Commit.md) \| Explicitly submit pending tasks on the channel. \|
	42	+\| [Drain](./Drain.md) \| Wait for all communication tasks on the channel to complete. \|
	43	+
	44	+## Return Value
	45	+\| Return Value \| Description \|
	46	+\| --- \| --- \|
	47	+\| `0` \| Execution succeeded. \|
	48	+\| `-1` \| Execution failed. \|
	49	+
	50	+## Usage Constraints
	51	+- The communication channel shall be initialized by the caller before invoking communication APIs.
	52	+- Both `COMM_PROTOCOL_ROCE` and `COMM_PROTOCOL_UBC_CTP` paths require a temporary workspace provided via `Init`. The layout of the temporary workspace differs between protocols.
	53	+- `WriteWithNotifyNbi` is only available for the `COMM_PROTOCOL_UBC_CTP` path; calls on the `COMM_PROTOCOL_ROCE` path will return failure.
	54	+- `AtomicFAA` and `AtomicCAS` are only supported for the `COMM_PROTOCOL_UBC_CTP` path. Supported data types are limited to `int32_t`, `uint32_t`, `int64_t`, `uint64_t`.
	55	+- The passed `ChannelHandle` must point to a channel entity matching the selected protocol.
	56	+
	57	+## Related Sample
	58	+[hcomm_write_read_nbi](../../../../../examples/hcomm_write_read_nbi/README_en.md) demonstrates that the AIV Kernel invokes `WriteNbi` and `ReadNbi` over the `COMM_PROTOCOL_UBC_CTP` path in a two-card scenario. This sample does not cover the RoCE path.

Adocs/en/api/aicore/hcomm/Init.md+30-0

@@ -0,0 +1,30 @@
	1	+# Init
	2	+
	3	+## Function Description
	4	+Initializes the temporary workspace for Hcomm. Both `COMM_PROTOCOL_ROCE` and `COMM_PROTOCOL_UBC_CTP` paths require this API to configure the temporary workspace before submitting any communication tasks.
	5	+
	6	+## Function Prototype
	7	+```cpp
	8	+__aicore__ inline int32_t Init(__ubuf__ uint8_t* buff, uint32_t len);
	9	+
	10	+template <typename T>
	11	+__aicore__ inline int32_t Init(const AscendC::LocalTensor<T>& buff, uint32_t len);
	12	+```
	13	+
	14	+## Parameter Description
	15	+\| Parameter \| Input/Output \| Description \|
	16	+\| --- \| --- \| --- \|
	17	+\| `buff` \| Input \| User-provided UB buffer or `LocalTensor`. \|
	18	+\| `len` \| Input \| Buffer length in bytes. \|
	19	+
	20	+## Return Value
	21	+\| Return Value \| Description \|
	22	+\| --- \| --- \|
	23	+\| `0` \| Initialization succeeded. \|
	24	+\| `-1` \| Initialization failed. \|
	25	+
	26	+## Constraints
	27	+- For the RoCE path, `buff` serves as the temporary workspace for WQE/CQE/doorbell. The minimum workspace size is currently 512 bytes.
	28	+- For the UBC_CTP/URMA path, `buff` serves as the temporary workspace for WQE/CQE. The minimum workspace size is currently 512 bytes.
	29	+- When initialized with `__ubuf__ uint8_t*`, the implementation takes the 32-byte aligned address of `buff` as the start address of the temporary workspace.
	30	+- When initialized with `LocalTensor`, the implementation directly uses the input tensor. For the RoCE path, both `len` and `buff.GetSize()` must be no less than 512 bytes. For the UBC_CTP/URMA path, `len` must be no less than 512 bytes and must not exceed `buff.GetSize()`.

Adocs/en/api/aicore/hcomm/ReadNbi.md+44-0

@@ -0,0 +1,44 @@
	1	+# ReadNbi
	2	+
	3	+## Function Description
	4	+Submits a point-to-point read task via the specified communication channel to read data from `src` to `dst`.
	5	+
	6	+## Function Prototype
	7	+```cpp
	8	+template <
	9	+ bool commit = true,
	10	+ pipe_t commitPipe = PIPE_S,
	11	+ pipe_t reqPipe = PIPE_MTE3,
	12	+ auto const& config = URMA_DEFAULT_CFG>
	13	+__aicore__ inline int32_t ReadNbi(
	14	+ AscendC::ChannelHandle channel, GM_ADDR dst, GM_ADDR src, uint64_t len);
	15	+```
	16	+
	17	+## Parameter Description
	18	+\| Parameter \| Input/Output \| Description \|
	19	+\| --- \| --- \| --- \|
	20	+\| `channel` \| Input \| Communication channel handle. \|
	21	+\| `dst` \| Output \| Destination GM address. \|
	22	+\| `src` \| Input \| Source GM address. \|
	23	+\| `len` \| Input \| Read length in bytes. \|
	24	+
	25	+## Template Parameters
	26	+\| Parameter \| Description \|
	27	+\| --- \| --- \|
	28	+\| `commit` \| Whether to perform an immediate commit when submitting the task. \|
	29	+\| `commitPipe` \| Pipe used for commit operations. Default: `PIPE_S`. \|
	30	+\| `reqPipe` \| Pipe used for requests. Default: `PIPE_MTE3`. \|
	31	+\| `config` \| URMA WQE control configuration, only used for the URMA path. Defaults to `URMA_DEFAULT_CFG` (strong ordering + fence + CQE enabled). \|
	32	+
	33	+## Return Value
	34	+\| Return Value \| Description \|
	35	+\| --- \| --- \|
	36	+\| `0` \| Task submission succeeded. \|
	37	+\| `-1` \| Task submission failed. \|
	38	+
	39	+## Constraints
	40	+- The communication channel must be initialized before invocation.
	41	+- Under the `COMM_PROTOCOL_UBC_CTP` path, `src` must be within the range of the remote buffer registered for the channel, and `dst` is the local destination address.
	42	+
	43	+## Related Sample
	44	+Refer to the two-card read/write workflow for AIV direct-driven URMA in [hcomm_write_read_nbi](../../../../../examples/hcomm_write_read_nbi/README_en.md).

Adocs/en/api/aicore/hcomm/WriteNbi.md+44-0

@@ -0,0 +1,44 @@
	1	+# WriteNbi
	2	+
	3	+## Function Description
	4	+Submits a point-to-point write task via the specified communication channel to write data from `src` to `dst`.
	5	+
	6	+## Function Prototype
	7	+```cpp
	8	+template <
	9	+ bool commit = true,
	10	+ pipe_t commitPipe = PIPE_S,
	11	+ pipe_t reqPipe = PIPE_MTE3,
	12	+ auto const& config = URMA_DEFAULT_CFG>
	13	+__aicore__ inline int32_t WriteNbi(
	14	+ AscendC::ChannelHandle channel, GM_ADDR dst, GM_ADDR src, uint64_t len);
	15	+```
	16	+
	17	+## Parameter Description
	18	+\| Parameter \| Input/Output \| Description \|
	19	+\| --- \| --- \| --- \|
	20	+\| `channel` \| Input \| Communication channel handle. \|
	21	+\| `dst` \| Output \| Destination GM address. \|
	22	+\| `src` \| Input \| Source GM address. \|
	23	+\| `len` \| Input \| Write length in bytes. \|
	24	+
	25	+## Template Parameters
	26	+\| Parameter \| Description \|
	27	+\| --- \| --- \|
	28	+\| `commit` \| Whether to perform an immediate commit when submitting the task. \|
	29	+\| `commitPipe` \| Pipe used for commit operations. Default: `PIPE_S`. \|
	30	+\| `reqPipe` \| Pipe used for requests. Default: `PIPE_MTE3`. \|
	31	+\| `config` \| URMA WQE control configuration, only used for the URMA path. Defaults to `URMA_DEFAULT_CFG` (strong ordering + fence + CQE enabled). \|
	32	+
	33	+## Return Value
	34	+\| Return Value \| Description \|
	35	+\| --- \| --- \|
	36	+\| `0` \| Task submission succeeded. \|
	37	+\| `-1` \| Task submission failed. \|
	38	+
	39	+## Constraints
	40	+- The communication channel must be initialized before invocation.
	41	+- Under the `COMM_PROTOCOL_UBC_CTP` path, `dst` must be within the range of the remote buffer registered for the channel, and `src` is the local source address.
	42	+
	43	+## Related Sample
	44	+Refer to the two-card read/write workflow for AIV direct-driven URMA in [hcomm_write_read_nbi](../../../../../examples/hcomm_write_read_nbi/README_en.md).

Adocs/en/api/aicore/hcomm/WriteWithNotifyNbi.md+52-0

@@ -0,0 +1,52 @@
	1	+# WriteWithNotifyNbi
	2	+
	3	+## Function Description
	4	+Submits a point-to-point write task carrying a remote notification address and notification value.
	5	+
	6	+This interface currently only supports the `COMM_PROTOCOL_UBC_CTP` path. An interface with the same name is reserved for the `COMM_PROTOCOL_ROCE` path, but its implementation will return a failure.
	7	+
	8	+## Function Prototype
	9	+```cpp
	10	+template <
	11	+ bool commit = true,
	12	+ pipe_t commitPipe = PIPE_S,
	13	+ pipe_t reqPipe = PIPE_MTE3,
	14	+ auto const& config = URMA_DEFAULT_CFG>
	15	+__aicore__ inline int32_t WriteWithNotifyNbi(
	16	+ AscendC::ChannelHandle channel,
	17	+ GM_ADDR dst,
	18	+ GM_ADDR src,
	19	+ uint64_t len,
	20	+ GM_ADDR notifyAddr,
	21	+ uint64_t notifyVal);
	22	+```
	23	+
	24	+## Parameter Description
	25	+\| Parameter \| Input/Output \| Description \|
	26	+\| --- \| --- \| --- \|
	27	+\| `channel` \| Input \| Communication channel handle. \|
	28	+\| `dst` \| Output \| Destination GM address. \|
	29	+\| `src` \| Input \| Source GM address. \|
	30	+\| `len` \| Input \| Write length in bytes. \|
	31	+\| `notifyAddr` \| Input \| Remote notification address. \|
	32	+\| `notifyVal` \| Input \| Remote notification value. \|
	33	+
	34	+## Template Parameters
	35	+\| Parameter \| Description \|
	36	+\| --- \| --- \|
	37	+\| `commit` \| Whether to perform an immediate commit when submitting the task. \|
	38	+\| `commitPipe` \| Pipe used for commit operations. Default: `PIPE_S`. \|
	39	+\| `reqPipe` \| Pipe used for requests. Default: `PIPE_MTE3`. \|
	40	+\| `config` \| URMA WQE control configuration, only used for URMA path. Defaults to `URMA_DEFAULT_CFG` (strong ordering + fence + CQE enabled). \|
	41	+
	42	+## Return Value
	43	+\| Return Value \| Description \|
	44	+\| --- \| --- \|
	45	+\| `0` \| Task submission succeeded. \|
	46	+\| `-1` \| Task submission failed. \|
	47	+
	48	+## Constraints
	49	+- The communication channel must be initialized before invocation.
	50	+- The passed `ChannelHandle` must correspond to a `COMM_PROTOCOL_UBC_CTP` channel.
	51	+- This interface is not supported on the `COMM_PROTOCOL_ROCE` path; invocation returns `-1`.
	52	+- A single `WriteWithNotifyNbi` task occupies 2 WQE blocks in the URMA SQ.

Adocs/en/guide/build_and_test.md+82-0

@@ -0,0 +1,82 @@
	1	+# Build & Test
	2	+
	3	+## Environment Preparation
	4	+Before executing `build.sh`, source the CANN environment script to set environment variables (`build.sh` checks `ASCEND_HOME_PATH`, which must be configured whether building UTs or not).
	5	+
	6	+```bash
	7	+# Default installation path (root user example; replace /usr/local with ${HOME} for non-root users)
	8	+source /usr/local/Ascend/cann/set_env.sh
	9	+# Custom installation path
	10	+# source ${install_path}/cann/set_env.sh
	11	+```
	12	+
	13	+Refer to [Third-party Dependencies & Compatibility](./dependencies.md) for the list of basic environment and third-party dependencies.
	14	+
	15	+## Build Instructions
	16	+When running the build script directly, it will perform basic environment checks. UT building must be triggered separately via dedicated build arguments.
	17	+```bash
	18	+bash build.sh
	19	+```
	20	+
	21	+## Build Unit Tests
	22	+Use `-t` or `--test` to build Hcomm UTs.
	23	+```bash
	24	+bash build.sh -t
	25	+```
	26	+
	27	+Default build directory:
	28	+```text
	29	+build/ut-hcomm
	30	+```
	31	+
	32	+## CMake Entry
	33	+The CMake entry for unit tests is:
	34	+```text
	35	+tests/ut/CMakeLists.txt
	36	+```
	37	+
	38	+Common CMake variables:
	39	+\| Variable \| Description \|
	40	+\| --- \| --- \|
	41	+\| `ASCEND_CANN_PACKAGE_PATH` \| Path to the CANN package. If not explicitly specified, it is derived from environment variables by priority. \|
	42	+\| `PRODUCT_TYPE_LIST` \| List of product types to build. Defaults to `ascend950pr_9599_AIV` and `ascend910B1_AIC`. \|
	43	+\| `TEST_MOD` \| Filter for UT targets to execute. Defaults to `all`. \|
	44	+\| `ASCCOMM_UT_RUN_AFTER_BUILD` \| Whether to run UTs after compilation. Defaults to `ON`. Set to `OFF` for compilation only. \|
	45	+
	46	+## GTest Dependency
	47	+UTs will search for system-installed GTest first. If GTest is unavailable locally, point `CANN_3RD_LIB_PATH` to the CANN third-party directory.
	48	+```bash
	49	+cmake -S tests/ut -B build/ut-hcomm -DCANN_3RD_LIB_PATH=<path-to-third-party>
	50	+```
	51	+
	52	+You may also pass the CANN third-party directory via the build script:
	53	+```bash
	54	+bash build.sh -t --cann_3rd_lib_path=<path-to-third-party>
	55	+```
	56	+
	57	+## Build and Run Samples
	58	+`examples/hcomm_write_read_nbi` provides a point-to-point communication sample using AIV direct-driven URMA `WriteNbi` and `ReadNbi`. This sample adopts an independent CMake project for building:
	59	+```bash
	60	+source /usr/local/Ascend/cann/set_env.sh
	61	+cd examples/hcomm_write_read_nbi
	62	+mkdir -p build
	63	+cd build
	64	+cmake -DCMAKE_ASC_ARCHITECTURES=dav-3510 ..
	65	+make -j
	66	+```
	67	+
	68	+The sample can launch two ranks directly by default:
	69	+```bash
	70	+./demo
	71	+```
	72	+
	73	+You can also specify ranks manually:
	74	+```bash
	75	+# Terminal 1: rank 0
	76	+./demo 0 2 tcp://127.0.0.1:29621
	77	+
	78	+# Terminal 2: rank 1
	79	+./demo 1 2 tcp://127.0.0.1:29621
	80	+```
	81	+
	82	+The sample supports Ascend 950PR / Ascend 950DT and requires CANN 9.1.0 or later. At least two NPUs are required to run the sample; single-NPU environments only support compilation verification.

Adocs/en/guide/dependencies.md+59-0

@@ -0,0 +1,59 @@
	1	+# Third-party Dependencies & Compatibility
	2	+
	3	+## Scope
	4	+The in-repository build of asc-comm is mainly used for environment verification, AICore Hcomm interface UT validation and Hcomm sample validation. This document describes the direct dependencies integrated into the repository build, verification and sample workflows.
	5	+
	6	+## Basic Environment
	7	+\| Dependency \| Requirement \| Description \|
	8	+\| --- \| --- \| --- \|
	9	+\| CANN Toolkit \| Matches the current branch or tag \| `source ${install_path}/cann/set_env.sh` must be executed before running `build.sh`. The script checks `ASCEND_HOME_PATH`. \|
	10	+\| CANN Runtime / HCCL / Hcomm \| CANN 9.1.0 or later \| The `hcomm_write_read_nbi` sample requires capabilities for communication domain creation, memory registration and AIV P2P channel creation, and depends on the Host-side `hcomm` library at link time. \|
	11	+\| CMake \| >= 3.16 \| UT CMake entry: `tests/ut/CMakeLists.txt`. \|
	12	+\| C++ Compiler \| C++17 support \| UT targets adopt `CMAKE_CXX_STANDARD 17`. It is recommended to use `gcc/g++ >= 7.3.0` with consistent versions. \|
	13	+\| Python \| Python 3 \| UT can generate tiling header files; OAT hooks require Python 3.7+. Python >= 3.9.0 is recommended for source and examples environments. \|
	14	+
	15	+## Direct Third-party Dependencies of This Repository
	16	+\| Scenario \| Dependency \| Version \| Acquisition & Configuration \|
	17	+\| --- \| --- \| --- \| --- \|
	18	+\| UT \| googletest \| 1.14.0 \| System GTest is preferred. If unavailable, point `CANN_3RD_LIB_PATH` to the CANN third_party directory. \|
	19	+\| Samples \| CANN ASC CMake utilities and hcomm library \| CANN 9.1.0 or later \| After running `source ${install_path}/cann/set_env.sh`, build via CMake under `examples/hcomm_write_read_nbi`. \|
	20	+\| Code Formatting \| clang-format \| v18.1.8 \| Pulled from `pre-commit-clang/mirrors-clang-format` defined in `pre-commit-config.yaml`. \|
	21	+\| Open Source Compliance Check \| oat-py \| >= 1.0.1 \| `scripts/oat_check.sh` attempts automatic installation. Run `pip install oat-py>=1.0.1` manually upon failure. \|
	22	+
	23	+`Third_Party_Open_Source_Software_List.yaml` at repository root currently only records `googletest` used directly for testing. If new third-party libraries for linking or packaging are introduced later, this inventory and Notice file shall be updated synchronously.
	24	+
	25	+## Sample Runtime Dependencies
	26	+The `examples/hcomm_write_read_nbi` sample supports Ascend 950PR / Ascend 950DT and requires at least two NPUs for runtime. Compilation verification can be completed on single-NPU environments, whereas two-card point-to-point communication runtime verification is unavailable.
	27	+This sample uses `COMM_ENGINE_AIV` and `COMM_PROTOCOL_UBC_CTP` exclusively and does not cover the RoCE path.
	28	+
	29	+Sample build commands:
	30	+```bash
	31	+source /usr/local/Ascend/cann/set_env.sh
	32	+cd examples/hcomm_write_read_nbi
	33	+mkdir -p build
	34	+cd build
	35	+cmake -DCMAKE_ASC_ARCHITECTURES=dav-3510 ..
	36	+make -j
	37	+```
	38	+
	39	+## GTest Installation & Configuration
	40	+If GTest is not installed on the system, prepare the following directory layout:
	41	+```text
	42	+<third_party>/gtest/include/gtest/gtest.h
	43	+<third_party>/gtest/lib64/libgtest.a
	44	+```
	45	+
	46	+Then execute:
	47	+```bash
	48	+source /usr/local/Ascend/cann/set_env.sh
	49	+cmake -S tests/ut -B build/ut-hcomm -DCANN_3RD_LIB_PATH=<third_party>
	50	+cmake --build build/ut-hcomm
	51	+```
	52	+
	53	+`build.sh -t` triggers UT building. To specify an offline GTest path, you can either use the above CMake command directly or pass the path via the build script:
	54	+```bash
	55	+bash build.sh -t --cann_3rd_lib_path=<third_party>
	56	+```
	57	+
	58	+## Integration Dependency Boundary
	59	+When new third-party components are introduced by newly added modules, samples or end-to-end workflows in the future, this section, the repository third-party open source inventory and Notice shall be updated synchronously.

Adocs/en/guide/hcomm_usage.md+68-0

@@ -0,0 +1,68 @@
	1	+# Hcomm Usage Guide
	2	+
	3	+## Overview
	4	+Hcomm is the AICore-side point-to-point communication interface provided by asc-comm. Users select communication protocols via the `AscendC::Hcomm` template and specify communication channels using `ChannelHandle`. This repository mainly hosts AIV direct-driven implementations covering two paths: RoCE and UBC_CTP/URMA.
	5	+
	6	+## Basic Workflow
	7	+1. Include the header file.
	8	+```cpp
	9	+#include "hcomm/hcomm.h"
	10	+```
	11	+
	12	+2. Instantiate the Hcomm object.
	13	+```cpp
	14	+AscendC::Hcomm<AscendC::COMM_PROTOCOL_UBC_CTP> hcomm;
	15	+```
	16	+
	17	+3. Call `Init` to initialize the temporary workspace.
	18	+```cpp
	19	+int32_t ret = hcomm.Init(tmpBuf, tmpLen);
	20	+```
	21	+
	22	+4. Submit communication tasks.
	23	+```cpp
	24	+ret = hcomm.WriteNbi(channel, dst, src, len);
	25	+ret = hcomm.ReadNbi(channel, dst, src, len);
	26	+ret = hcomm.WriteWithNotifyNbi(channel, dst, src, len, notifyAddr, notifyVal);
	27	+ret = hcomm.AtomicFAA<uint64_t>(channel, remoteCounter, fetchAddr, addVal);
	28	+ret = hcomm.AtomicCAS<uint64_t>(channel, remoteValue, fetchAddr, compareVal, swapVal);
	29	+```
	30	+
	31	+5. If `commit = false` is set during task submission, explicitly invoke `Commit`.
	32	+```cpp
	33	+ret = hcomm.WriteNbi<false>(channel, dst, src, len);
	34	+ret = hcomm.Commit(channel);
	35	+```
	36	+
	37	+6. Call `Drain` to wait for task completion.
	38	+```cpp
	39	+ret = hcomm.Drain(channel);
	40	+```
	41	+
	42	+## Protocol Description
	43	+\| Protocol \| Description \|
	44	+\| --- \| --- \|
	45	+\| `COMM_PROTOCOL_ROCE` \| RoCE point-to-point communication path. Supports `ReadNbi`, `WriteNbi`, `Commit`, `Drain`. `WriteWithNotifyNbi` is not supported. \|
	46	+\| `COMM_PROTOCOL_UBC_CTP` \| UBC CTP/URMA path. Supports `ReadNbi`, `WriteNbi`, `WriteWithNotifyNbi`, `AtomicFAA`, `AtomicCAS`, `Commit`, `Drain`. \|
	47	+
	48	+## Notes
	49	+- Both `COMM_PROTOCOL_ROCE` and `COMM_PROTOCOL_UBC_CTP` paths require a temporary workspace allocated via `Init`. The minimum workspace size is currently 512 bytes.
	50	+- When initialized with `__ubuf__ uint8_t*`, the implementation aligns the start address of the temporary workspace to 32 bytes. When initialized with `LocalTensor`, the caller must ensure the tensor capacity meets workspace requirements.
	51	+- The caller is responsible for initializing and maintaining the channel entity referenced by `ChannelHandle`.
	52	+- Source addresses, destination addresses and transfer lengths must comply with underlying protocol and hardware constraints.
	53	+- `WriteWithNotifyNbi`, `AtomicFAA` and `AtomicCAS` are only available for the `COMM_PROTOCOL_UBC_CTP` path.
	54	+- Supported data types for atomic operations are limited to `int32_t`, `uint32_t`, `int64_t` and `uint64_t`.
	55	+- For the `COMM_PROTOCOL_UBC_CTP` path: a single `WriteWithNotifyNbi`, `AtomicFAA` or `AtomicCAS` task occupies 2 WQE blocks; regular `ReadNbi` / `WriteNbi` tasks occupy 1 WQE block.
	56	+- Return value `0` indicates success; `-1` indicates failure.
	57	+
	58	+## Sample
	59	+Refer to [hcomm_write_read_nbi](../../../examples/hcomm_write_read_nbi/README_en.md) to learn about AIV Kernel-side API invocation and Host-side communication resource creation workflow. This sample uses `COMM_ENGINE_AIV` and `COMM_PROTOCOL_UBC_CTP` exclusively and does not cover the RoCE path.
	60	+
	61	+This sample executes symmetric `WriteNbi` and `ReadNbi` in a two-card scenario:
	62	+```cpp
	63	+hcomm.WriteNbi(channel, remoteBuf + DATA_SIZE, localBuf, DATA_SIZE);
	64	+hcomm.ReadNbi(channel, localBuf + 2 * DATA_SIZE, remoteBuf, DATA_SIZE);
	65	+hcomm.Drain(channel);
	66	+```
	67	+
	68	+The sample requires Ascend 950PR / Ascend 950DT and at least two NPUs for runtime verification. Single-NPU environments only support compilation checks.

Mdocs/quick_start.md+16-9

	@@ -1,6 +1,6 @@
1	-# 快速开始	1	+# 快速开始
2		2
3	-## 🛠️ 环境准备<a name="prepare&install"></a>	3	+## 🛠️ 环境准备<a name="prepare-install"></a>
4		4
5	根据本地是否有NPU设备和使用目标选择对应的环境准备方式：	5	根据本地是否有NPU设备和使用目标选择对应的环境准备方式：
6		6
	@@ -46,7 +46,8 @@
46		46
47	<p align="center"><img src="./figures/webIDE.png" alt="云平台" width="1000px" height="150px"></p>	47	<p align="center"><img src="./figures/webIDE.png" alt="云平台" width="1000px" height="150px"></p>
48		48
49	-> [!NOTE] 使用说明	49	+> [!NOTE]
		50	+> 使用说明
50	>	51	>
51	> - 环境默认安装了最新的商用版NPU驱动和固件、CANN包，源码下载时注意与软件配套。	52	> - 环境默认安装了最新的商用版NPU驱动和固件、CANN包，源码下载时注意与软件配套。
52	> - 如需下载特定版本的CANN包，请参考[下载安装CANN包](#cann-install)。	53	> - 如需下载特定版本的CANN包，请参考[下载安装CANN包](#cann-install)。
	@@ -72,7 +73,8 @@
72	docker pull <ascend/cann:tag>	73	docker pull <ascend/cann:tag>
73	```	74	```
74		75
75	- > [!NOTE] 使用说明	76	+ > [!NOTE]
		77	+ > 使用说明
76	> - 镜像默认安装了对应版本的CANN包，源码下载时注意与软件配套。	78	> - 镜像默认安装了对应版本的CANN包，源码下载时注意与软件配套。
77	> - 镜像文件比较大，正常网速下，下载时间约为5～10分钟，请您耐心等待。	79	> - 镜像文件比较大，正常网速下，下载时间约为5～10分钟，请您耐心等待。
78		80
	@@ -147,9 +149,11 @@ CANN包分为CANN toolkit包和CANN ops包。
147	./Ascend-cann-${soc_name}-ops_${cann_version}_linux-$(uname -m).run --install --install-path=${install_path}	149	./Ascend-cann-${soc_name}-ops_${cann_version}_linux-$(uname -m).run --install --install-path=${install_path}
148	```	150	```
149		151
150	- > [!IMPORTANT] 安装说明	152	+ > [!IMPORTANT]
		153	+ > 安装说明
151	> 当前[Hcomm AIV直驱URMA样例](../examples/hcomm_write_read_nbi/README.md)不依赖ops包；仅在后续使用依赖算子包的功能时按需安装。	154	> 当前[Hcomm AIV直驱URMA样例](../examples/hcomm_write_read_nbi/README.md)不依赖ops包；仅在后续使用依赖算子包的功能时按需安装。
152		155
		156	+
153	\| 参数 \| 说明 \|	157	\| 参数 \| 说明 \|
154	\| :--- \| :--- \|	158	\| :--- \| :--- \|
155	\| `${cann_version}` \| CANN包版本号 \|	159	\| `${cann_version}` \| CANN包版本号 \|
	@@ -158,7 +162,8 @@ CANN包分为CANN toolkit包和CANN ops包。
158		162
159	## ✅ 环境验证<a name="cann-verify"></a>	163	## ✅ 环境验证<a name="cann-verify"></a>
160		164
161	-> [!NOTE] 使用前须知	165	+> [!NOTE]
		166	+> 使用前须知
162	> 云开发环境和CANN官方Docker镜像已预装CANN包，可直接执行以下命令验证。	167	> 云开发环境和CANN官方Docker镜像已预装CANN包，可直接执行以下命令验证。
163		168
164	验证环境和驱动是否正常：	169	验证环境和驱动是否正常：
	@@ -179,7 +184,8 @@ CANN包分为CANN toolkit包和CANN ops包。
179		184
180	## ⚙️ 环境变量配置<a name="cann-env-setup"></a>	185	## ⚙️ 环境变量配置<a name="cann-env-setup"></a>
181		186
182	-> [!NOTE] 使用前须知	187	+> [!NOTE]
		188	+> 使用前须知
183	> 云开发环境和CANN官方Docker镜像已自动配置环境变量，可跳过此步骤。	189	> 云开发环境和CANN官方Docker镜像已自动配置环境变量，可跳过此步骤。
184		190
185	按需选择合适的命令使环境变量生效：	191	按需选择合适的命令使环境变量生效：
	@@ -204,7 +210,8 @@ cd asc-comm
204		210
205	### 📦 依赖检查<a name="dependency-check"></a>	211	### 📦 依赖检查<a name="dependency-check"></a>
206		212
207	-> [!NOTE] 使用前须知	213	+> [!NOTE]
		214	+> 使用前须知
208	> 如您使用容器化技术，容器中已为您安装好依赖，可跳过此步骤。	215	> 如您使用容器化技术，容器中已为您安装好依赖，可跳过此步骤。
209		216
210	以下为本开源仓源码编译和UT验证的基础依赖条件：	217	以下为本开源仓源码编译和UT验证的基础依赖条件：
	@@ -213,7 +220,7 @@ cd asc-comm
213	- gcc/g++支持C++17	220	- gcc/g++支持C++17
214	- cmake >= 3.16.0	221	- cmake >= 3.16.0
215		222
216	-### ⚡ 编译安装<a name="compile&install"></a>	223	+### ⚡ 编译安装<a name="compile-install"></a>
217		224
218	进入本开源仓代码根目录，执行如下命令：	225	进入本开源仓代码根目录，执行如下命令：
219		226

Adocs/quick_start_en.md+253-0

@@ -0,0 +1,253 @@
	1	+# Quick Start
	2	+
	3	+## 🛠️ Environment Preparation<a name="prepare-install"></a>
	4	+Select the corresponding environment setup method according to whether local NPU devices are available and your usage goals:
	5	+
	6	+<table>
	7	+ <thead>
	8	+ <tr>
	9	+ <th align="center">Environment Option</th>
	10	+ <th align="center">Community Evaluation / Operator Development (CANN Commercial / Community Release)</th>
	11	+ <th align="center">Ecosystem Developer Contribution (CANN master)</th>
	12	+ </tr>
	13	+ </thead>
	14	+ <tbody>
	15	+ <tr>
	16	+ <td align="center"><strong>No NPU Device</strong></td>
	17	+ <td align="center" colspan="2"><a href="#cloud-dev-env">Cloud Development Environment</a> + <a href="#cann-install">Manual CANN Package Download & Installation</a></td>
	18	+ </tr>
	19	+ <tr>
	20	+ <td align="center"><strong>NPU Device Available</strong></td>
	21	+ <td align="center"><a href="#cann-docker-image">Official CANN Docker Image</a></td>
	22	+ <td align="center"><a href="#cann-install">Manual CANN Package Download & Installation</a></td>
	23	+ </tr>
	24	+ </tbody>
	25	+</table>
	26	+
	27	+> [!TIP]
	28	+> Recommendations
	29	+>
	Y Y YeZZzzz17月23日 🤖 CANN 检视意见严重性: ✅ Low 问题类别: 可读性 / 渲染问题详情: 使用告警块 `> [!TIP] Recommendations`，标题与 `[!TIP]` 同行，多数渲染器要求 `[!TIP]` 单独成行，否则可能不渲染（下方 `[!NOTE]/[!IMPORTANT]` 同样）。另锚点 `<a name="prepare&install">` 含 `&` 不规范（中文版亦有）。修改建议: 告警标题另起一行；锚点改为不含 `&`（如 `prepare-install`），并同步中文版。哈喽Kiter 7月24日评论： 7月24日评论：
	30	+> - For stable development experience, it is recommended to prepare your environment using containerization technology.
	31	+> - If you prefer not to use containers, you may set up the environment on a physical machine equipped with NPUs. Refer to [CANN Software Installation Guide - Physical Machine Installation](https://www.hiascend.com/cann/download).
	32	+> - Users who only intend to compile this open-source repository and perform compilation verification of samples do not require local NPUs. You can skip NPU driver and firmware deployment and directly install the CANN package; see [Download and Install CANN Package](#cann-install).
	33	+> - The `hcomm_write_read_nbi` sample requires at least two NPUs for runtime execution.
	34	+
	35	+### 1️⃣ Cloud Development Environment<a name="cloud-dev-env"></a>
	36	+Users without physical NPU hardware can directly use the CANNLab Cloud Development Environment, a one-stop development platform. It provides an online ready-to-run Ascend ARM environment with pre-installed drivers, firmware, software packages and dependencies without manual setup. This platform currently supports Atlas A2 series products and offers two access methods:
	37	+
	38	+- WebIDE: Lightweight web-based development experience.
	39	+- VSCode IDE: Supports remote connection to the cloud development environment with full access to the VSCode extension marketplace.
	40	+
	41	+1. Navigate to the GitCode repository page, click `CANNLab > Cloud Dev`, and log in with your authenticated Huawei Cloud account. Complete registration and authentication following page prompts if you have not done so.
	42	+
	43	+ <p align="center"><img src="./figures/cloudIDE.png" alt="Cloud Platform" width="750px" height="90px"></p>
	44	+
	45	+2. Create an NPU environment and configure specifications following page instructions. After launching the cloud environment, click `Connect > WebIDE or Visual Studio Code` to enter the one-stop platform. Repository resources are located under `/mnt/workspace` by default.
	46	+
	47	+ <p align="center"><img src="./figures/webIDE.png" alt="Cloud Platform" width="1000px" height="150px"></p>
	48	+
	49	+> [!NOTE]
	50	+> Usage Notes
	51	+>
	52	+> - The environment comes with the latest commercial NPU driver, firmware and CANN packages. Match your source code version with installed software.
	53	+> - If you need a specific CANN release, refer to [Download and Install CANN Package](#cann-install).
	54	+> - For more details about CANNLab Cloud Development Environment, see [CANNLab Guide](https://gitcode.com/org/cann/discussions/54).
	55	+> - The [Huawei Developer Space Extension](https://marketplace.visualstudio.com/items?itemName=HuaweiCloud.developerspace) enables VSCode IDE connectivity to the cloud environment.
	56	+
	57	+### 2️⃣ Official CANN Docker Image<a name="cann-docker-image"></a>
	58	+Users with physical NPU hardware can develop with the official CANN Docker image.
	59	+
	60	+1. Verify host prerequisites
	61	+ - Confirm NPU driver and firmware are installed. Run `npu-smi info` to check device status. If missing, follow the sections Prepare Software Packages and Install NPU Driver and Firmware in the [CANN Software Installation Guide](https://www.hiascend.com/document/redirect/CannCommunityInstWizard). Drivers and firmware are runtime dependencies; you may skip them if only compiling source code.
	62	+ - Confirm Docker is installed. Run `docker --version` to verify. If missing, follow the [official Docker installation guide](https://docs.docker.com/engine/install/).
	63	+
	64	+2. Pull the CANN image
	65	+ Fetch the pre-integrated CANN image from the Ascend Hub repository:
	66	+ ```bash
	67	+ # Example: CANN community package tag 9.0.0-beta.2
	68	+ # docker pull swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.0-beta.2-910b-ubuntu22.04-py3.11
	69	+ docker pull <ascend/cann:tag>
	70	+ ```
	71	+
	72	+ > [!NOTE]
	73	+ > Usage Notes
	74	+ > - The image contains the corresponding CANN release. Match your source code with the software version.
	75	+ > - Image size is large; downloading normally takes 5–10 minutes under standard network conditions.
	76	+
	77	+3. Launch the Docker container
	78	+ After pulling the image, start the container with dedicated parameters to grant access to host NPUs.
	79	+ ```bash
	80	+ docker run --name <cann_container> \
	81	+ --ipc=host --net=host --privileged \
	82	+ --device /dev/davinci0 \
	83	+ --device /dev/davinci1 \
	84	+ --device /dev/davinci_manager \
	85	+ --device /dev/devmm_svm \
	86	+ --device /dev/hisi_hdc \
	87	+ -v /usr/local/dcmi:/usr/local/dcmi \
	88	+ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
	89	+ -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
	90	+ -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
	91	+ -v /etc/ascend_install.info:/etc/ascend_install.info \
	92	+ -v </home/your_host_dir>:</home/your_container_dir> \
	93	+ -it <ascend/cann:tag> bash
	94	+ ```
	95	+
	96	+ \| Parameter \| Description \| Remarks \|
	97	+ \| :--- \| :--- \| :--- \|
	98	+ \| `--name <cann_container>` \| Assign a custom name for container management \| User-defined \|
	99	+ \| `--ipc=host` \| Share IPC namespace with host; required for NPU inter-process communication (shared memory, semaphores) \| - \|
	100	+ \| `--net=host` \| Use host network stack to avoid communication latency from container forwarding \| - \|
	101	+ \| `--privileged` \| Grant full device access permissions required for NPU driver operation \| - \|
	102	+ \| `--device /dev/davinci<N>` \| Map specified NPU device into the container; repeat the argument to attach multiple NPUs \| Adjust device index according to `npu-smi info`. At least two Ascend 950PR/Ascend 950DT devices shall be mapped to run the `hcomm_write_read_nbi` sample. \|
	103	+ \| `--device /dev/davinci_manager` \| Mount NPU device management interface \| - \|
	104	+ \| `--device /dev/devmm_svm` \| Mount device memory management interface \| - \|
	105	+ \| `--device /dev/hisi_hdc` \| Mount host-device communication interface \| - \|
	106	+ \| `-v /usr/local/dcmi:/usr/local/dcmi` \| Mount DCMI tools and libraries for device management \| - \|
	107	+ \| `-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi` \| Mount `npu-smi` utility \| Enables querying NPU status and performance inside the container \|
	108	+ \| `-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/` \| Map host NPU driver libraries into container \| - \|
	109	+ \| `-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info` \| Mount driver version file \| - \|
	110	+ \| `-v /etc/ascend_install.info:/etc/ascend_install.info` \| Mount CANN installation metadata file \| - \|
	111	+ \| `-v </home/your_host_dir>:</home/your_container_dir>` \| Mount a host directory into the container \| User-defined \|
	112	+ \| `-it` \| Combined `-i` (interactive) and `-t` (pseudo-TTY) flags \| - \|
	113	+ \| `<ascend/cann:tag>` \| Target Docker image name and tag \| Must exactly match the tag used in `docker pull` \|
	114	+ \| `bash` \| Command executed immediately after container startup \| - \|
	115	+
	116	+### 📥 Download and Install CANN Package<a name="cann-install"></a>
	117	+CANN packages include the CANN toolkit package and CANN ops package.
	118	+
	119	+#### Download CANN Packages
	120	+1. <a name="download-cann-commercial-community"></a>Download CANN Commercial / Community Release
	121	+ To use officially published CANN builds, visit [CANN Download Page - Ascend Community](https://www.hiascend.com/cann/download) to obtain the corresponding release.
	122	+
	123	+2. <a name="download-cann-master"></a>Download CANN master
	124	+ To test CANN master branch builds, visit the [CANN master OBS mirror website](https://ascend.devcloud.huaweicloud.com/artifactory/cann-run-mirror/software/master) and download the most recent CANN packages by date.
	125	+
	126	+#### Install CANN Packages
	127	+1. Install CANN toolkit package (Mandatory)
	128	+ ```bash
	129	+ chmod +x Ascend-cann-toolkit_${cann_version}_linux-$(uname -m).run
	130	+ ./Ascend-cann-toolkit_${cann_version}_linux-$(uname -m).run --install --install-path=${install_path}
	131	+ ```
	132	+
	133	+2. Install CANN ops package (Optional)
	134	+ ```bash
	135	+ chmod +x Ascend-cann-${soc_name}-ops_${cann_version}_linux-$(uname -m).run
	136	+ ./Ascend-cann-${soc_name}-ops_${cann_version}_linux-$(uname -m).run --install --install-path=${install_path}
	137	+ ```
	138	+
	139	+ > [!IMPORTANT]
	140	+ > Installation Note
	141	+ > The [AIV direct-driven URMA Hcomm sample](../examples/hcomm_write_read_nbi/README_en.md) does not depend on the ops package. Install it later only when you require features relying on the operator package.
	142	+
	143	+\| Parameter \| Description \|
	144	+\| :--- \| :--- \|
	145	+\| `${cann_version}` \| CANN package version string \|
	146	+\| `${soc_name}` \| NPU model name, e.g. `910b` \|
	147	+\| `${install_path}` \| Installation directory. Toolkit and ops packages must share the same path. Default: `/usr/local/Ascend` for root users, `$HOME/Ascend` for non-root users \|
	148	+
	149	+## ✅ Environment Verification<a name="cann-verify"></a>
	150	+> [!NOTE]
	151	+> Precondition
	152	+> The cloud development environment and official CANN Docker images come with pre-installed CANN packages; you may directly execute the verification commands.
	153	+
	154	+Verify environment and driver health:
	155	+
	156	+- Check NPU devices:
	157	+ ```bash
	158	+ # Normal output indicates functional drivers
	159	+ npu-smi info
	160	+ ```
	161	+
	162	+- Check CANN package installation:
	163	+ ```bash
	164	+ # View CANN Toolkit version info (default installation path)
	165	+ cat /usr/local/Ascend/cann/$(uname -m)-linux/ascend_toolkit_install.info
	166	+ ```
	167	+
	168	+## ⚡ Environment Variable Setup<a name="cann-env-setup"></a>
	169	+> [!NOTE]
	170	+> Precondition
	171	+> Cloud development environments and official CANN Docker images configure environment variables automatically; skip this section.
	172	+
	173	+Select the corresponding command to load environment variables:
	174	+```bash
	175	+# Default installation path (root user example; replace /usr/local with ${HOME} for non-root users)
	176	+source /usr/local/Ascend/cann/set_env.sh
	177	+# Custom installation path
	178	+# source ${install_path}/cann/set_env.sh
	179	+```
	180	+
	181	+## 🔨 Source Compilation Steps<a name="source-build"></a>
	182	+### 📥 Clone Source Code<a name="source-download"></a>
	183	+Clone this repository:
	184	+```bash
	185	+git clone https://gitcode.com/cann/asc-comm.git
	186	+cd asc-comm
	187	+```
	188	+
	189	+### 📦 Dependency Check<a name="dependency-check"></a>
	190	+> [!NOTE]
	191	+> Precondition
	192	+> If you use containerization technology, required dependencies are pre-installed inside the container and this step can be skipped.
	193	+
	194	+Prerequisites for source compilation and UT validation:
	195	+- python >= 3.7.0
	196	+- gcc/g++ with C++17 support
	197	+- cmake >= 3.16.0
	198	+
	199	+### ⚡ Build Source Code<a name="compile-install"></a>
	200	+Enter repository root and execute:
	201	+```bash
	202	+bash build.sh
	203	+```
	204	+
	205	+### 🧪 Unit Test Verification<a name="ut-verify"></a>
	206	+#### Dependency Preparation
	207	+UTs depend on googletest. If system GTest is unavailable, point `CANN_3RD_LIB_PATH` to the CANN third-party directory.
	208	+
	209	+#### Run UTs
	210	+Option 1: Build Hcomm UTs from repository root
	211	+```bash
	212	+bash build.sh -t
	213	+```
	214	+
	215	+Specify the CANN third-party directory when needed:
	216	+```bash
	217	+bash build.sh -t --cann_3rd_lib_path=<path-to-third-party>
	218	+```
	219	+
	220	+Option 2: Direct CMake invocation with offline GTest path
	221	+```bash
	222	+cmake -S tests/ut -B build/ut-hcomm -DCANN_3RD_LIB_PATH=<path-to-third-party>
	223	+cmake --build build/ut-hcomm
	224	+```
	225	+
	226	+#### Open-Source Third-Party Dependencies
	227	+Third-party open-source software used for UT execution:
	228	+
	229	+\| Software \| Version \|
	230	+\| :---: \| :---: \|
	231	+\| googletest \| 1.14.0 \|
	232	+
	233	+### 🧩 Sample Verification<a name="sample-verify"></a>
	234	+[hcomm_write_read_nbi](../examples/hcomm_write_read_nbi/README_en.md) provides a point-to-point communication sample using AIV direct-driven URMA `WriteNbi` and `ReadNbi`.
	235	+The sample supports Ascend 950PR / Ascend 950DT and requires CANN 9.1.0 or newer. At least two NPUs are required for runtime; single-NPU environments only support compilation verification.
	236	+
	237	+Navigate to the sample directory and run:
	238	+```bash
	239	+source /usr/local/Ascend/cann/set_env.sh
	240	+cd examples/hcomm_write_read_nbi
	241	+mkdir -p build
	242	+cd build
	243	+cmake -DCMAKE_ASC_ARCHITECTURES=dav-3510 ..
	244	+make -j
	245	+./demo
	246	+```
	247	+
	248	+Successful execution outputs:
	249	+```text
	250	+rank 0 test pass!
	251	+rank 1 test pass!
	252	+test pass!
	253	+```

Rdocs/api/README.md→docs/zh/api/README.md+1-1

	@@ -23,4 +23,4 @@
23	## 相关文档	23	## 相关文档
24		24
25	- [Hcomm使用说明](../guide/hcomm_usage.md)	25	- [Hcomm使用说明](../guide/hcomm_usage.md)
26	-- [AIV直驱URMA WriteNbi/ReadNbi样例](../../examples/hcomm_write_read_nbi/README.md)	26	+- [AIV直驱URMA WriteNbi/ReadNbi样例](../../../examples/hcomm_write_read_nbi/README.md)

Rdocs/api/aicore/hcomm/AtomicCAS.md→docs/zh/api/aicore/hcomm/AtomicCAS.md+0-0

文件重命名但无更改。

Rdocs/api/aicore/hcomm/AtomicFAA.md→docs/zh/api/aicore/hcomm/AtomicFAA.md+0-0

文件重命名但无更改。

Rdocs/api/aicore/hcomm/Commit.md→docs/zh/api/aicore/hcomm/Commit.md+0-0

文件重命名但无更改。

Rdocs/api/aicore/hcomm/Drain.md→docs/zh/api/aicore/hcomm/Drain.md+0-0

文件重命名但无更改。

Rdocs/api/aicore/hcomm/Hcomm.md→docs/zh/api/aicore/hcomm/Hcomm.md+1-1

	@@ -64,4 +64,4 @@ class Hcomm;
64		64
65	## 相关样例	65	## 相关样例
66		66
67	-[hcomm_write_read_nbi](../../../../examples/hcomm_write_read_nbi/README.md)演示两卡场景下，AIV Kernel通过`COMM_PROTOCOL_UBC_CTP`路径调用`WriteNbi`和`ReadNbi`。该样例不覆盖RoCE路径。	67	+[hcomm_write_read_nbi](../../../../../examples/hcomm_write_read_nbi/README.md)演示两卡场景下，AIV Kernel通过`COMM_PROTOCOL_UBC_CTP`路径调用`WriteNbi`和`ReadNbi`。该样例不覆盖RoCE路径。

Rdocs/api/aicore/hcomm/Init.md→docs/zh/api/aicore/hcomm/Init.md+0-0

文件重命名但无更改。

Rdocs/api/aicore/hcomm/ReadNbi.md→docs/zh/api/aicore/hcomm/ReadNbi.md+1-1

Z zangyan7月28日

里面的样式链接错误

哈喽Kiter

7月28日评论：

	@@ -48,4 +48,4 @@ __aicore__ inline int32_t ReadNbi(
48		48
49	## 相关样例	49	## 相关样例
50		50
51	-参考[hcomm_write_read_nbi](../../../../examples/hcomm_write_read_nbi/README.md)中的AIV直驱URMA两卡读写流程。	51	+参考[hcomm_write_read_nbi](../../../../../examples/hcomm_write_read_nbi/README.md)中的AIV直驱URMA两卡读写流程。

Rdocs/api/aicore/hcomm/WriteNbi.md→docs/zh/api/aicore/hcomm/WriteNbi.md+1-1

Z zangyan7月28日

里面的样例链接错误

哈喽Kiter

7月28日评论：

	@@ -48,4 +48,4 @@ __aicore__ inline int32_t WriteNbi(
48		48
49	## 相关样例	49	## 相关样例
50		50
51	-参考[hcomm_write_read_nbi](../../../../examples/hcomm_write_read_nbi/README.md)中的AIV直驱URMA两卡读写流程。	51	+参考[hcomm_write_read_nbi](../../../../../examples/hcomm_write_read_nbi/README.md)中的AIV直驱URMA两卡读写流程。

Rdocs/api/aicore/hcomm/WriteWithNotifyNbi.md→docs/zh/api/aicore/hcomm/WriteWithNotifyNbi.md+0-0

文件重命名但无更改。

Rdocs/guide/build_and_test.md→docs/zh/guide/build_and_test.md+0-0

Z zangyan7月28日

这个md路径变了，但是仓的主README.md中的链接并未修改。

文件重命名但无更改。

Rdocs/guide/dependencies.md→docs/zh/guide/dependencies.md+0-0

文件重命名但无更改。

Rdocs/guide/hcomm_usage.md→docs/zh/guide/hcomm_usage.md+1-1

	@@ -67,7 +67,7 @@ ret = hcomm.Drain(channel);
67		67
68	## 样例	68	## 样例
69		69
70	-可参考[hcomm_write_read_nbi](../../examples/hcomm_write_read_nbi/README.md)了解AIV Kernel侧接口调用方式和Host侧通信资源创建流程。该样例固定使用`COMM_ENGINE_AIV`和`COMM_PROTOCOL_UBC_CTP`，不覆盖RoCE路径。	70	+可参考[hcomm_write_read_nbi](../../../examples/hcomm_write_read_nbi/README.md)了解AIV Kernel侧接口调用方式和Host侧通信资源创建流程。该样例固定使用`COMM_ENGINE_AIV`和`COMM_PROTOCOL_UBC_CTP`，不覆盖RoCE路径。
71		71
72	该样例在两卡场景下对称执行`WriteNbi`和`ReadNbi`：	72	该样例在两卡场景下对称执行`WriteNbi`和`ReadNbi`：
73		73

Aexamples/README_en.md+43-0

@@ -0,0 +1,43 @@
	1	+# asc-comm Samples
	2	+
	3	+This directory contains usage samples for asc-comm APIs.
	4	+
	5	+## Sample List
	6	+\| Sample \| Description \| Supported Products \|
	7	+\| --- \| --- \| --- \|
	8	+\| [hcomm_write_read_nbi](./hcomm_write_read_nbi/README_en.md) \| Demonstrates AIV Kernel invoking `Hcomm::WriteNbi` and `Hcomm::ReadNbi` over the URMA path in a two-card scenario, with communication result verification. \| Ascend 950PR / Ascend 950DT \|
	9	+
	10	+## hcomm_write_read_nbi
	11	+`hcomm_write_read_nbi` demonstrates the complete AIV direct-driven URMA point-to-point communication workflow, including Host-side communication domain creation, communication memory registration, AIV P2P channel establishment, and Kernel-side invocations of `Init`, `WriteNbi`, `ReadNbi` and `Drain`. This sample does not cover the RoCE path.
	12	+
	13	+The sample runs symmetrically on two cards:
	14	+1. The Host creates a communication domain and registers communication buffers for each rank.
	15	+2. Establish a P2P channel to the peer rank via `HcclChannelAcquire`.
	16	+3. The Kernel writes local data to the remote buffer using `WriteNbi`.
	17	+4. The Kernel reads data back from the remote buffer using `ReadNbi`.
	18	+5. The Host reads back and verifies results. `test pass!` is printed if both ranks pass validation.
	19	+
	20	+## Build & Run
	21	+Navigate to the sample directory and execute:
	22	+```bash
	23	+source /usr/local/Ascend/cann/set_env.sh
	24	+mkdir -p build
	25	+cd build
	26	+cmake -DCMAKE_ASC_ARCHITECTURES=dav-3510 ..
	27	+make -j
	28	+./demo
	29	+```
	30	+
	31	+You can also launch the two ranks manually:
	32	+```bash
	33	+# Terminal 1: rank 0
	34	+./demo 0 2 tcp://127.0.0.1:29621
	35	+
	36	+# Terminal 2: rank 1
	37	+./demo 1 2 tcp://127.0.0.1:29621
	38	+```
	39	+
	40	+## Runtime Constraints
	41	+- Supported chips: Ascend 950PR / Ascend 950DT. CANN version 9.1.0 or later is required.
	42	+- At least two NPUs are required for runtime execution; single-NPU environments only support compilation verification.
	43	+- Sample build relies on CANN ASC CMake utilities and links against the CANN `hcomm` library at link time.

🤖 CANN 检视意见