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

快速开始

🛠️ 环境准备

根据本地是否有NPU设备和使用目标选择对应的环境准备方式：

环境准备	社区体验/算子开发(CANN商用/社区版)	生态开发者贡献(CANN master)
无NPU设备	云开发环境+手动下载安装CANN包
有NPU设备	CANN官方Docker镜像	手动下载安装CANN包

选择建议

为了保障开发体验环境的质量，推荐用户基于容器化技术完成环境准备。
如不希望使用容器，也可在带NPU设备的主机上完成环境准备，请参考CANN软件安装指南 - 在物理机上安装。
针对仅体验“编译本开源仓 + 编译验证样例”的用户，不要求主机带NPU设备，可跳过安装NPU驱动和固件，直接安装CANN包，请参考下载安装CANN包。hcomm_write_read_nbi样例运行需要至少2张NPU。

1️⃣ 云开发环境

对于无NPU设备的用户，可直接使用CANNLab云开发环境，即"一站式开发平台"，该平台提供了在线可直接运行的昇腾ARM架构环境，环境中已安装必备的驱动固件、软件包和依赖，无需手动安装。该平台目前仅适用于Atlas A2系列产品，提供两种接入方式：

WebIDE，提供网页版的便携开发体验。
VSCode IDE，支持远程连接云开发环境，提供VSCode强大插件市场的支持。

进入开源仓Gitcode页面，单击"CANNLab > 云开发"按钮，使用已认证过的华为云账号登录。若未注册或认证，请根据页面提示进行注册和认证。
根据页面提示创建NPU环境并配置规格，启动云开发环境后，单击"连接 > WebIDE或Visual Studio Code"进入一站式开发平台。开源项目的资源默认在/mnt/workspace目录下。

Note

使用说明

环境默认安装了最新的商用版NPU驱动和固件、CANN包，源码下载时注意与软件配套。
如需下载特定版本的CANN包，请参考下载安装CANN包。
更多关于CANNLab云开发环境的介绍，请参考CANNLab指导。
Huawei Developer Space插件为VSCode IDE接入云开发环境提供技术支持。

2️⃣ CANN官方Docker镜像

对于有NPU设备的用户，可使用CANN官方Docker镜像进行开发体验。

确认主机环境
- 是否已安装NPU驱动和固件，使用npu-smi info能够输出NPU相关信息，如没有安装，请参考《CANN软件安装指南》中“准备软件包”和“安装NPU驱动和固件”章节。驱动与固件是运行态依赖，若仅编译本项目源码，可以不安装。
- 是否已安装Docker，使用docker --version能够输出Docker版本信息，如没有安装，请参考Docker官方安装指南。
下载CANN镜像

从昇腾镜像仓库拉取已预集成CANN镜像：
```
# 示例：ascend/cann:tag为9.0.0-beta.2的CANN社区包
# docker pull swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.0-beta.2-910b-ubuntu22.04-py3.11
docker pull <ascend/cann:tag>
```
Note
使用说明
- 镜像默认安装了对应版本的CANN包，源码下载时注意与软件配套。
- 镜像文件比较大，正常网速下，下载时间约为5～10分钟，请您耐心等待。

运行Docker

拉取镜像后，需要以特定参数启动，以便容器内能访问宿主机的NPU设备。

docker run --name <cann_container> \
    --ipc=host --net=host --privileged \
    --device /dev/davinci0 \
    --device /dev/davinci1 \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v </home/your_host_dir>:</home/your_container_dir> \
    -it <ascend/cann:tag> bash

参数	说明	注意事项
`--name <cann_container>`	为容器指定名称，便于管理	自定义
`--ipc=host`	与宿主机共享IPC命名空间，NPU进程间通信（共享内存、信号量）所需	-
`--net=host`	使用宿主机网络栈，避免容器网络转发带来的通信延迟	-
`--privileged`	赋予容器完整设备访问权限，NPU驱动正常工作所需	-
`--device /dev/davinci<N>`	将指定的NPU设备映射到容器内；如需使用多张设备，可多次使用`--device`参数	根据`npu-smi info`显示的设备号调整。运行`hcomm_write_read_nbi`样例时至少映射两张Ascend 950PR/Ascend 950DT设备。
`--device /dev/davinci_manager`	映射NPU设备管理接口	-
`--device /dev/devmm_svm`	映射设备内存管理接口	-
`--device /dev/hisi_hdc`	映射主机与设备间的通信接口	-
`-v /usr/local/dcmi:/usr/local/dcmi`	挂载设备容器管理接口（DCMI）相关工具和库	-
`-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi`	挂载`npu-smi`工具	使容器内可以直接运行此命令来查询NPU状态和性能信息
`-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/`	将宿主机的NPU驱动库映射到容器内	-
`-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info`	挂载驱动版本信息文件	-
`-v /etc/ascend_install.info:/etc/ascend_install.info`	挂载CANN软件安装信息文件	-
`-v </home/your_host_dir>:</home/your_container_dir>`	挂载宿主机的一个路径到容器中	自定义
`-it`	`-i`（交互式）和`-t`（分配伪终端）的组合参数	-
`<ascend/cann:tag>`	指定要运行的Docker镜像	请确保此镜像名和标签（tag）与您通过`docker pull`拉取的镜像完全一致
`bash`	容器启动后立即执行的命令	-

📥 下载安装CANN包

CANN包分为CANN toolkit包和CANN ops包。

下载CANN包

下载CANN商用/社区版

如果您想体验官网正式发布的CANN包，请访问CANN安装部署-昇腾社区获取对应版本CANN包。
下载CANN master

如果您想体验CANN master，请访问CANN master obs镜像网站，下载日期最新的CANN包。

安装CANN包

安装CANN toolkit包 (必选)

chmod +x Ascend-cann-toolkit_${cann_version}_linux-$(uname -m).run
./Ascend-cann-toolkit_${cann_version}_linux-$(uname -m).run --install --install-path=${install_path}

安装CANN ops包 (可选)

chmod +x Ascend-cann-${soc_name}-ops_${cann_version}_linux-$(uname -m).run
./Ascend-cann-${soc_name}-ops_${cann_version}_linux-$(uname -m).run --install --install-path=${install_path}

Important

安装说明当前Hcomm AIV直驱URMA样例不依赖ops包；仅在后续使用依赖算子包的功能时按需安装。

参数	说明
`${cann_version}`	CANN包版本号
`${soc_name}`	NPU型号，如`910b`
`${install_path}`	安装路径，toolkit包和ops包需相同。默认：root用户`/usr/local/Ascend`，非root用户`$HOME/Ascend`

✅ 环境验证

Note

使用前须知云开发环境和CANN官方Docker镜像已预装CANN包，可直接执行以下命令验证。

验证环境和驱动是否正常：

检查NPU设备：

# 运行npu-smi，若能正常显示设备信息，则驱动正常
npu-smi info

检查CANN包安装：

# 查看CANN Toolkit的version字段提供的版本信息（默认路径安装）
cat /usr/local/Ascend/cann/$(uname -m)-linux/ascend_toolkit_install.info

⚙️ 环境变量配置

Note

使用前须知云开发环境和CANN官方Docker镜像已自动配置环境变量，可跳过此步骤。

按需选择合适的命令使环境变量生效：

# 默认路径安装，以root用户为例（非root用户，将/usr/local替换为${HOME}）
source /usr/local/Ascend/cann/set_env.sh
# 指定路径安装
# source ${install_path}/cann/set_env.sh

🔨 源码编译步骤

📥 下载源码

开发者可通过如下命令下载本仓源码：

git clone https://gitcode.com/cann/asc-comm.git
cd asc-comm

📦 依赖检查

Note

使用前须知如您使用容器化技术，容器中已为您安装好依赖，可跳过此步骤。

以下为本开源仓源码编译和UT验证的基础依赖条件：

python >= 3.7.0
gcc/g++支持C++17
cmake >= 3.16.0

⚡ 编译安装

进入本开源仓代码根目录，执行如下命令：

bash build.sh

🧪 UT验证

安装依赖

UT依赖googletest。若系统中没有GTest，可以通过CANN_3RD_LIB_PATH指向CANN third_party目录。

UT执行

方式一：在开源仓根目录执行下列命令，构建Hcomm UT。

bash build.sh -t

需要指定CANN third_party目录时执行：

bash build.sh -t --cann_3rd_lib_path=<path-to-third-party>

方式二：用户也可直接使用CMake命令指定离线GTest路径。

cmake -S tests/ut -B build/ut-hcomm -DCANN_3RD_LIB_PATH=<path-to-third-party>
cmake --build build/ut-hcomm

开源第三方软件依赖

在执行UT时，依赖的第三方开源软件列表如下：

开源软件	版本
googletest	1.14.0

🧩 样例验证

hcomm_write_read_nbi提供AIV直驱URMA WriteNbi和ReadNbi点对点通信样例。样例支持Ascend 950PR/Ascend 950DT，要求CANN 9.1.0或以上版本。运行样例需要至少2张NPU；单卡环境仅支持编译验证。

进入样例目录后执行：

source /usr/local/Ascend/cann/set_env.sh
cd examples/hcomm_write_read_nbi
mkdir -p build
cd build
cmake -DCMAKE_ASC_ARCHITECTURES=dav-3510 ..
make -j
./demo

执行成功时输出如下：

rank 0 test pass!
rank 1 test pass!
test pass!