Star271
49
Code
Code
Issues72
Pull Requests53
Actions
Discussion
Wiki
Analysis
Star271
49
Merged
docs: add comprehensive project documentation and quickstart guide #63
LiuZongguAdd on Jul 7
docs: add comprehensive project documentation and quickstart guide #63
Merged
LiuZongguAdd on Jul 7
Merged fromDeleted :docs/readmeintocann/ops-rasmaster
Total: 22 files changed+1599-258
MREADME.md+49-0
@@ -1,2 +1,51 @@
1# ops-ras1# ops-ras
2 2 
3+## 🔥Latest News
4+ 
5+- [2026/07] ops-ras项目首次上线。
6+ 
7+## 🚀概述
8+ 
9+ops-ras是[CANN](https://hiascend.com/software/cann)（Compute Architecture for Neural Networks）算子库中的安全和维测类算子库（Reliability, Availability and Serviceability），提供可靠性、可用性和可维护性等能力，包含安全、加密以及维测相关算子，"ras"即来源于这三项核心特性的首字母缩写。算子库架构图如下：
10+ 
11+<img src="docs/zh/figures/architecture.png" alt="架构图" width="700px" height="320px">
12+ 
13+## 📌版本配套
14+ 
15+本项目源码会跟随CANN软件版本发布，关于CANN软件版本与本项目标签的对应关系请参阅[release仓库](https://gitcode.com/cann/release-management)中的相应版本说明。
16+请注意，为确保您的源码定制开发顺利进行，请选择配套的CANN版本与Gitcode标签源码，使用master分支可能存在版本不匹配的风险。
17+ 
18+## 🛠️环境准备
19+ 
20+[环境部署](docs/zh/install/quick_install.md)是体验本项目能力的前提，请先完成NPU驱动、CANN包安装等，确保环境正常。
21+ 
22+## ⬇️源码下载
23+ 
24+环境准备好后，下载与CANN版本配套的分支源码，通用命令如下，\$\{tag\_version\}替换为分支标签名。以9.0.0分支源码下载为例：
25+ 
26+```bash
27+# 通用命令：git clone -b ${tag_version} https://gitcode.com/cann/ops-ras.git
28+git clone -b 9.0.0 https://gitcode.com/cann/ops-ras.git
29+```
30+ 
31+> 说明：若环境中已存在配套分支源码，**可跳过本步骤**，例如CANNLab默认已提供最新商发版CANN对应的源码。
32+ 
33+## 📖学习教程
34+ 
35+- [快速入门](docs/QUICKSTART.md)：从零开始快速体验项目核心基础能力，涵盖源码编译、算子调用、开发与调试等操作。
36+- [进阶教程](docs/README.md)：如需深入了解项目编译部署、算子调用、开发、调试调优等能力，请查阅文档中心获取详细指引。
37+ 
38+## 💬相关信息
39+ 
40+- [目录结构](docs/zh/install/dir_structure.md)
41+- [贡献指南](CONTRIBUTING.md)
42+- [安全声明](SECURITY.md)
43+- [许可证](LICENSE)
44+- [所属SIG](https://gitcode.com/cann/community/tree/master/CANN/sigs/ops-basic)
45+ 
46+-----
47+PS：本项目功能和文档正在持续更新和完善中，欢迎您关注最新版本。
48+ 
49+- **问题反馈**：通过GitCode[【Issues】](https://gitcode.com/cann/ops-ras/issues)提交问题。
50+- **社区互动**：通过GitCode[【讨论】](https://gitcode.com/cann/ops-ras/discussions)参与交流。
51+- **技术专栏**：通过GitCode[【Wiki】](https://gitcode.com/cann/ops-ras/wiki)获取技术文章，如系列化教程、优秀实践等。
Adocs/CONTRIBUTING_DOCS.md+102-0
@@ -0,0 +1,102 @@
1+# 文档贡献指南
2+ 
3+欢迎您对本项目文档做出贡献，优质的文档对于项目成功至关重要。本指南将帮助您高效地提交符合规范的文档。
4+ 
5+## 贡献范围
6+ 
7+我们欢迎任何能提升文档质量的贡献，包括但不限于：
8+ 
9+- 纠错与改进：修复错别字、语法错误、错误的代码示例、过时的信息或失效的链接。
10+ 
11+- 澄清与优化：让描述更清晰易懂，优化语句结构，补充背景知识。
12+ 
13+- 内容补充：为现有功能添加使用示例、API文档、常见问题解答（FAQ）、最佳实践或警告说明等。
14+ 
15+- 新内容创作：为新增功能撰写全新的章节或教程，比如算子README、API介绍文档等，如有问题建议先创建Issue讨论。
16+ 
17+- 本地化翻译：帮助我们翻译或校对其他语言的文档。
18+ 
19+- 样式与导航：改进文档网站的布局、可读性和导航结构。
20+ 
21+## 贡献流程
22+ 
23+1. **准备工作**
24+ 
25+ - 确定任务：如有文档问题可新建Issues，建议标签类别`[Documentation|文档反馈]`，并提供详细描述。基于已有Issues列表，确定待解决的文档issue。
26+ - 认领任务：在对应的Issue下评论`/assign @yourself`，表明您将处理它，避免重复劳动。
27+ 
28+2. **文档修改**
29+ 
30+ - 选择分支：请从master或其他Tag分支下载源码到本地。
31+ - 遵循格式：
32+ - 本项目推荐使用**Markdown格式**。
33+ - 遵循项目既有的写作风格。
34+ - 图片等静态资源放入对应目录，例如图片一般在docs目录下`figures`文件夹，特殊情况可自行调整。
35+ - 谨慎增删：修改内容时，请尽量保持原有的行宽和换行约定。
36+ 
37+3. **提交更改**
38+ 
39+ - 原子化提交：每个提交应专注于一个独立的修改。例如，"修复xx指南的拼写错误"和"更新API参考的示例代码"应分两次提交。
40+ 
41+ - 撰写清晰的提交信息：
42+ 
43+ ```text
44+ 简短说明（不超过50字符）
45+
46+ 如有必要，在此处进行更详细描述。说明修改的原因和内容，而不是具体改了什么（代码本身会展示）。
47+ 关联的 Issue: #123
48+ ```
49+ 
50+4. **发起Pull Request**
51+ 
52+ - 目标分支：请将PR合并到项目的目标分支。
53+ - 标题与描述：
54+ - PR标题：应清晰概括修改，例如：`[Docs] 修复快速入门中的配置示例`。
55+ - PR描述：详细说明您的更改内容、动机，并关联对应Issue（使用Closes #123或Fixes #456）。
56+ - 预览检查：请提前检查本地或在线浏览的文档效果，确保渲染符合预期。
57+ - 等待审查：维护者会进行审查，可能会提出修改建议。请及时跟进讨论。
58+ 
59+## 写作规范
60+ 
61+开发者进行项目文档写作前，请务必先阅读如下规范，如有问题欢迎您随时提出建议！
62+ 
63+- 前提条件：请先学习CANN组织提供的统一写作规范，具体参见[CANN文档写作规范](https://gitcode.com/cann/community/blob/master/contributor/docs/document_writing_specs.md)。
64+ 
65+ - 文档内容要求：介绍项目里必选和可选文档交付件。
66+ - 目录结构规范：介绍目录划分的原则，例如中、英文管理等。
67+ - 内容元素规范：介绍不同写作元素的规则，例如文件命名、标题、字体、图片、代码块、链接等。
68+ 
69+- 注意事项：
70+ 
71+ 除了上述写作规则，还需注意以下事项：
72+ 
73+ - 语气：使用友好、专业且中立的语气。面向新手，避免不必要的行话。
74+ - 术语：保持术语一致性（如统一使用"点击"而非"单击"）。请参考项目术语表（如有）。
75+ - 代码示例：
76+ - 确保所有代码示例可运行并经过测试。
77+ - 提供足够的上下文和解释。
78+ - 注明代码运行所需的环境或前提条件。
79+ - 标点与格式：
80+ - 中英文混排时，使用全角标点，标点符号必须符合中/英文语境。
81+ - 标题使用合适的层级（#、 ##、 ###）。
82+ - 使用列表和表格来组织复杂信息。
83+ - 链接：使用描述性链接文本，避免"点击这里"，确保链接资源真实可靠。
84+ - 图片：
85+ - 常用格式：推荐png格式，风格尽量与已有图片保持一致。
86+ - 分辨率与清晰度：需清晰且尺寸适中，避免模糊或过度压缩。
87+ - 文件大小：单张图片不建议超过10M。
88+ - 版权：所有引用的图片、文献等资源，请确保合规性。
89+ 
90+## 获取帮助
91+ 
92+如果您在贡献过程中有任何疑问：
93+ 
94+1. 查阅现有文档：模板或规范有问题，请先查阅项目已有的指南、API文档或README等。
95+2. 发起讨论：您可以新建Issue或直接在相关Issue或PR中留言。
96+ 
97+## 文档模板
98+ 
99+算子交付件中涉及的关键文档主要包括如下，具体写作格式、内容要求请参考模板。
100+ 
101+- [算子README文档模板](https://gitcode.com/cann/ops-ras/wiki/%E7%AE%97%E5%AD%90README%E6%96%87%E6%A1%A3%E6%A8%A1%E6%9D%BF)
102+- [aclnn API文档模板](https://gitcode.com/cann/ops-ras/wiki/aclnn%20API%E6%96%87%E6%A1%A3%E6%A8%A1%E6%9D%BF)
Adocs/QUICKSTART.md+273-0
@@ -0,0 +1,273 @@
1+# 快速入门：基于ops-ras仓
2+ 
3+## 使用须知
4+ 
5+本指南旨在帮助您快速上手CANN和`ops-ras`算子仓的使用。为方便您快速了解算子开发全流程，以**AddExample**算子为实践对象，算子源码位于`ops-ras/examples/add_example`，操作流程如下：
6+ 
7+1. **[前提条件](../README.md)**：参考项目README完成环境准备和源码下载，此处不再赘述。快速入门场景**推荐CANNLab或Docker部署**，操作简单。
8+ 
9+ > **说明**：CANNLab或Docker环境默认提供最新商发版CANN包；如需体验master分支最新能力，可手动搭建环境。
10+ 
11+2. **[编译运行](#一编译运行)**：编译自定义算子包并安装，实现快速调用算子。
12+ 
13+3. **[算子开发](#二算子开发)**：通过修改现有算子Kernel，体验开发、编译、验证的完整闭环。
14+ 
15+4. **[算子调试](#三算子调试)**：掌握算子打印和性能采集方法。
16+ 
17+5. **[算子验证](#四算子验证)**：学习如何修改算子example样例，以验证算子在不同输入下的功能正确性。
18+ 
19+## 一、编译运行
20+ 
21+本阶段目的是**快速体验项目标准流程**，验证环境能否成功进行算子源码编译、打包、安装和运行。
22+ 
23+### 1. 进入项目源码
24+
25+- CANNLab云开发环境：
26+
27+ 默认提供最新商发版CANN包配套的项目源码，进入源码目录，\$\{gitCode\_id\}替换为开发者个人gitCode账号。
28+
29+ ```bash
30+ cd /mnt/workspace/gitCode/${gitCode_id}/ops-ras
31+ ```
32+ 
33+- 非CANNLab云开发环境：
34+
35+ 根据[release仓库](https://gitcode.com/cann/release-management)源码与CANN版本配套关系，执行如下命令下载源码，\$\{tag\_version\}替换为目标分支标签，例如9.0.0。
36+
37+ ```bash
38+ git clone -b ${tag_version} https://gitcode.com/cann/ops-ras.git && cd ops-ras
39+ ```
40+ 
41+> 说明：如需切换源码分支版本，请参考如下指导。
42+>
43+> 1. 在源码目录执行`git branch`，查询当前源码版本。
44+> 2. 在源码目录执行`git checkout ${tag_version}`，切换到目标分支源码，注意满足源码与CANN版本配套关系。若源码已存在，执行`git pull`拉取最新源码。
45+ 
46+### 2. 编译AddExample算子
47+ 
48+本指南默认采用**单算子编译**：仅构建目标算子，编译时间短，适合快速入门与日常开发。通用命令格式：`bash build.sh --pkg --soc=<芯片版本> --ops=<算子名>`。
49+ 
50+> 若需编译整个算子库（省略 `--ops`），请参阅 [build参数说明](zh/install/build.md)。
51+ 
52+以AddExample算子为例，编译命令如下：
53+ 
54+```bash
55+bash build.sh --pkg --soc=${soc_version} --ops=add_example -j16
56+```
57+ 
58+\$\{soc\_version\}取值请访问[CANN下载中心](https://www.hiascend.com/cann/download)，根据页面提示查询硬件产品名，产品名对应的${soc_version}取值如下，请按实际场景传参。
59+ 
60+- Atlas A2 训练系列产品/Atlas A2 推理系列产品：取值为ascend910b
61+- Atlas A3 训练系列产品/Atlas A3 推理系列产品：取值为ascend910_93
62+- 950系列产品：取值为ascend950
63+ 
64+若提示如下信息，说明编译成功。
65+ 
66+```bash
67+Self-extractable archive "cann-ops-ras-custom_linux-${arch}.run" successfully created.
68+```
69+ 
70+编译成功后，run包存放于项目根目录的build_out目录下。
71+ 
72+### 3. 安装AddExample算子包
73+ 
74+```bash
75+./build_out/cann-ops-ras-*linux*.run
76+```
77+ 
78+`AddExample`安装在```${ASCEND_HOME_PATH}/opp/vendors```路径中，```${ASCEND_HOME_PATH}```表示CANN软件安装目录。
79+ 
80+### 4. 配置环境变量
81+ 
82+将自定义算子包的路径加入环境变量，确保运行时能够找到。
83+ 
84+```bash
85+export LD_LIBRARY_PATH=${ASCEND_HOME_PATH}/opp/vendors/custom_ras/op_api/lib:${LD_LIBRARY_PATH}
86+```
87+ 
88+### 5. 快速验证：运行算子样例
89+ 
90+通用的运行命令格式：`bash build.sh --run_example <算子名> <运行模式> <包模式>`。
91+ 
92+以AddExample为例，其提供了简单算子样例`add_example/examples/test_aclnn_add_example.cpp`，运行该样例验证算子功能是否正常。
93+ 
94+```bash
95+bash build.sh --run_example add_example eager cust --vendor_name=custom
96+```
97+ 
98+预期输出：打印算子`AddExample`的加法计算结果，表明算子已成功部署并正确执行。
99+ 
100+```bash
101+mean result[0] is: 2.000000
102+mean result[1] is: 2.000000
103+mean result[2] is: 2.000000
104+mean result[3] is: 2.000000
105+mean result[4] is: 2.000000
106+mean result[5] is: 2.000000
107+mean result[6] is: 2.000000
108+mean result[7] is: 2.000000
109+...
110+```
111+ 
112+## 二、算子开发
113+ 
114+本阶段目的是对已成功运行的AddExample算子尝试**修改核函数代码**。
115+ 
116+### 1. 修改Kernel实现
117+ 
118+找到AddExample算子的核心kernel实现文件`ops-ras/examples/add_example/op_kernel/add_example.h`，尝试将算子中的Add操作改为Mul操作：
119+ 
120+```cpp
121+__aicore__ inline void AddExample<T>::Compute(int32_t progress)
122+{
123+ AscendC::LocalTensor<T> xLocal = inputQueueX.DeQue<T>();
124+ AscendC::LocalTensor<T> yLocal = inputQueueY.DeQue<T>();
125+ AscendC::LocalTensor<T> zLocal = outputQueueZ.AllocTensor<T>();
126+ // === 在此处将Add替换为Mul ===
127+ // AscendC::Add(zLocal, xLocal, yLocal, tileLength_);
128+ AscendC::Mul(zLocal, xLocal, yLocal, tileLength_);
129+ outputQueueZ.EnQue<T>(zLocal);
130+ inputQueueX.FreeTensor(xLocal);
131+ inputQueueY.FreeTensor(yLocal);
132+}
133+```
134+ 
135+### 2. 编译与验证
136+ 
137+重复[编译运行](#一编译运行)章节中的步骤：
138+ 
139+1. **重新编译**：
140+ 
141+ 先回到项目根目录，编译命令如下：
142+ 
143+ ```bash
144+ bash build.sh --pkg --soc=${soc_version} --ops=add_example -j16
145+ ```
146+ 
147+ > **说明**：`${soc_version}` 请根据实际芯片型号填写，取值方式同[编译AddExample算子](#2-编译addexample算子)中的说明。
148+ 
149+2. **重新安装**：
150+ 
151+ ```bash
152+ ./build_out/cann-ops-ras-*linux*.run
153+ ```
154+ 
155+3. **重新验证**：
156+ 
157+ ```bash
158+ bash build.sh --run_example add_example eager cust --vendor_name=custom
159+ ```
160+ 
161+4. **成功标志**：输出结果变成乘法结果。
162+ 
163+ ```bash
164+ mean result[0] is: 1.000000
165+ mean result[1] is: 1.000000
166+ mean result[2] is: 1.000000
167+ mean result[3] is: 1.000000
168+ mean result[4] is: 1.000000
169+ mean result[5] is: 1.000000
170+ mean result[6] is: 1.000000
171+ mean result[7] is: 1.000000
172+ ...
173+ ```
174+ 
175+## 三、算子调试
176+ 
177+本阶段以AddExample为例，在算子中添加打印并采集算子性能数据，以便后续问题分析定位。
178+ 
179+### 1. 打印
180+ 
181+算子如果出现执行失败、精度异常等问题，添加打印进行问题分析和定位。
182+ 
183+请在`examples/add_example/op_kernel/add_example.h`中进行代码修改。
184+ 
185+* **printf**
186+ 
187+ 该接口支持打印Scalar类型数据，如整数、字符型、布尔型等，详细介绍请参见[《Ascend C API》](https://hiascend.com/document/redirect/CannCommunityAscendCApi)中"算子调测API > printf"。
188+ 
189+ ```c++
190+ blockLength_ = (tilingData->totalLength + AscendC::GetBlockNum() - 1) / AscendC::GetBlockNum();
191+ tileNum_ = tilingData->tileNum;
192+ tileLength_ = ((blockLength_ + tileNum_ - 1) / tileNum_ / BUFFER_NUM) ?
193+ ((blockLength_ + tileNum_ - 1) / tileNum_ / BUFFER_NUM) : 1;
194+ // 打印当前核计算Block长度
195+ AscendC::PRINTF("Tiling blockLength is %llu\n", blockLength_);
196+ ```
197+ 
198+* **DumpTensor**
199+ 
200+ 该接口支持Dump指定Tensor的内容，同时支持打印自定义附加信息，比如当前行号等，详细介绍请参见[《Ascend C API》](https://hiascend.com/document/redirect/CannCommunityAscendCApi)中"算子调测API > DumpTensor"。
201+ 
202+ ```c++
203+ AscendC::LocalTensor<T> zLocal = outputQueueZ.DeQue<T>();
204+ // 打印zLocal Tensor信息
205+ DumpTensor(zLocal, 0, 128);
206+ ```
207+ 
208+### 2. 性能采集
209+ 
210+当算子功能验证正确后，可通过`msprof`工具采集算子性能数据。
211+ 
212+- **生成可执行文件**
213+ 
214+ 调用AddExample算子的example样例，生成可执行文件（test_aclnn_add_example），该文件位于项目`ops-ras/build`目录。
215+ 
216+ ```bash
217+ bash build.sh --run_example add_example eager cust --vendor_name=custom
218+ ```
219+ 
220+- **采集性能数据**
221+ 
222+ 进入AddExample算子可执行文件目录`ops-ras/build/`，执行如下命令：
223+ 
224+ ```bash
225+ msprof --application="./test_aclnn_add_example"
226+ ```
227+ 
228+采集结果在项目`ops-ras/build/`目录，msprof命令执行完后会自动解析并导出性能数据结果文件，详细内容请参见[msprof](https://www.hiascend.com/document/detail/zh/mindstudio/82RC1/T&ITools/Profiling/atlasprofiling_16_0110.html#ZH-CN_TOPIC_0000002504160251)。
229+ 
230+## 四、算子验证
231+ 
232+本阶段通过修改AddExample算子example样例中的输入数据，验证该算子在多种场景下的功能正确性。
233+ 
234+### 1. 修改测试输入
235+ 
236+找到并编辑`AddExample`的`ops-ras/examples/add_example/examples/test_aclnn_add_example.cpp`，修改输入张量的形状和数值。
237+ 
238+**修改输入/输出数据**：修改输入、输出的shape信息，以及初始化数据，构造相应的输入、输出tensor。
239+ 
240+```c++
241+int main() {
242+ // ... 初始化代码 ...
243+ 
244+ // === ① 修改selfX的输入 ===
245+ // 修改前：shape = {32, 4, 4, 4}, 数值全为1
246+ // 修改后：将输入shape改为 {8, 8, 8, 8}，并填充不同的测试数据
247+ std::vector<int64_t> selfXShape = {8, 8, 8, 8};
248+ std::vector<float> selfXHostData(4096); // 4096 = 8 * 8 * 8 *8
249+ // 可使用循环填充更有区分度的数据，例如递增序列
250+ for (int i = 0; i < 4096; ++i) {
251+ selfXHostData[i] = static_cast<float>(i % 10); // 填充0-9的循环值
252+ }
253+ // === ② 参考selfX，同理修改selfY、selfZ的输入 ===
254+ 
255+ // ... 后续执行代码 ...
256+}
257+```
258+ 
259+### 2. 重新编译并验证
260+ 
261+1. 由于只修改了example测试代码，无需重新编译算子包。
262+ 
263+2. 重新执行验证命令：
264+ 
265+ ```bash
266+ bash build.sh --run_example add_example eager cust --vendor_name=custom
267+ ```
268+ 
269+3. 观察算子输出结果是否符合预期。
270+ 
271+## 结语
272+ 
273+体验完上述流程，您已基本完成算子开发过程，如果您想进一步贡献新算子或学习更多高阶开发、调试等技能，请访问本项目README学习[进阶教程](../README.md#学习教程)和[贡献指南](../README.md#相关信息)等。
Mdocs/README.md+60-35
@@ -1,47 +1,72 @@
1-# 项目文档1+# 文档中心
2 2 
3-## 目录说明3+## 目录结构
4 4 
5-关键目录结构如下：5+Docs目录结构说明如下：
6 6 
7-```7+```text
8-├── context # 公共目录，存放包括基本概念、项目目录介绍、build参数说明等文档8+├── zh
9-│ ├── dir_structure.md 9+ ├── context # 公共文档，如术语、基础概念等
10-│ ├── build.md 10+ ├── debug # 算子调试指导文档
11-│ └── ...11+ │ ├── cann_sim.md
12-├── debug # 算子调试调优文档目录12+ │ ├── op_debug_prof.md
13-│ ├── op_debug_prof.md13+ │ └── ...
14-│ └── ...14+ ├── develop # 算子开发指导文档
15-├── develop # 算子开发文档目录(包括AI Core和AI CPU算子开发指南等)15+ │ ├── aicore_develop_guide.md
16-│ ├── aicore_develop_guide.md16+ │ ├── aicpu_develop_guide.md
17-│ ├── aicpu_develop_guide.md17+ │ ├── cross_platform_migration_guide.md
18-│ └── ...18+ │ ├── graph_develop_guide.md
19-├── figures # 图片目录19+ │ └── ...
20-├── invocation # 算子调用文档目录（包括aclnn调用、图模式调用等）20+ ├── figures # 图片目录
21-│ ├──op_invocation.md21+ ├── install # 环境安装和编译指导文档
22-│ └── ...22+ │ ├── build.md
23-├── op_api_list.md # 全量算子接口列表（aclnn）23+ │ ├── compile.md
24-├── op_list.md # 全量算子列表24+ │ ├── dir_structure.md
25-└── README25+ │ ├── quick_install.md
26+ │ └── ...
27+ ├── invocation # 算子调用指导文档（包括aclnn调用、图模式调用等）
28+ │ ├── quick_op_invocation.md
29+ │ ├── op_invocation.md
30+ │ └── ...
31+ ├── op_api_list.md # 全量算子接口列表（aclnn）
32+ ├── op_list.md # 全量算子列表
33+├── CONTRIBUTING_DOCS.md # 文档贡献说明
34+├── QUICKSTART.md # 快速入门
35+└── README.md
26```36```
27 37 
28-## 文档说明38+## 进阶教程
29 39 
30-为方便开发者快速熟悉本项目，可按需获取对应文档，文档内容包括：40+### 指南类文档
31 41 
32-| 文档 | 说明 |42+| 文档 | 说明 |
33-| ------------------------------------------------ | ------------------------------------------------------------ |43+| ------------------------------------------------------------ | ------------------------------------------------------------ |
34-| [算子列表](zh/op_list.md) | 介绍项目包含的所有算子。 |44+| [源码构建指南](zh/install/compile.md) | 介绍联网/未联网场景下不同的源码构建方式和验证方法。 |
35-| [aclnn列表](zh/op_api_list.md) | 介绍项目包含的所有aclnn前缀的算子API，通过该API可直调算子。 |45+| [算子调用指南](zh/invocation/quick_op_invocation.md) | 介绍调用算子样例方法和不同算子调用方式（如aclnn/图等）。 |
36-| [环境部署](zh/context/quick_install.md) | 介绍项目的基础环境搭建，包括软件包和第三方依赖的获取和安装。 |46+| [标准算子开发指南](zh/develop/aicore_develop_guide.md) | 介绍如何基于标准工程定义算子原型、实现Tiling和Kernel，此类算子称为"标准算子"。<br>标准算子支持aclnn和图模式调用。 |
37-| [算子调用](zh/invocation/quick_op_invocation.md) | 介绍如何快速调用项目内算子，包括编译执行算子包和UT等。 |47+| [简易算子开发指南](../examples/fast_kernel_launch_example/README.md) | 介绍如何基于简易工程实现fast_kernel_launch，即`<<<>>>`方式，此类算子称为"简易算子"。<br>简易算子仅支持PyTorch调用。 |
38-| [算子开发](zh/develop/aicore_develop_guide.md) | 介绍自定义算子的开发流程，包括算子原型定义、Tiling实现、Kernel实现等。 |48+| [算子调试调优](zh/debug/op_debug_prof.md) | 介绍常见的算子功能调试和性能调优方法（如数据采集和仿真流水等）。 |
39-| [算子调用方式](zh/invocation/op_invocation.md) | 介绍不同算子调用方式，包括aclnn调用、图模式调用等，方便算子快速应用于AI业务中。 |
40-| [算子调试调优](zh/debug/op_debug_prof.md) | 介绍常见的算子调试、调优方法。 |
41 49 
50+### API类文档
51+ 
52+| 文档 | 说明 |
53+| ----------------------- | ---------------------- |
54+| [算子列表](zh/op_list.md) | 介绍项目包含的所有算子清单。 |
55+| [aclnn列表](zh/op_api_list.md) | 介绍项目包含的所有算子aclnn API清单。为方便用户在Host侧调用算子，提供了C语言API，即aclnn前缀的API。 |
56+ 
57+### 工具类文档
58+ 
59+| 文档 | 说明 |
60+| ----------------------- | ---------------------- |
61+| [Simulator仿真工具](zh/debug/cann_sim.md) | 面向算子开发场景的SoC级仿真工具，用于分析运行在AI仿真器上AI任务在各阶段精度和性能数据。 |
62+ 
63+### 更多文档
64+ 
65+- 样例类文档：可参考[cann-samples](https://gitcode.com/cann/cann-samples)仓算子样例。
42 66 
43## 附录67## 附录
68+ 
44| 文档 | 说明 |69| 文档 | 说明 |
45| ----------------------------------- | ------------------------------------------------------------ |70| ----------------------------------- | ------------------------------------------------------------ |
46-| [算子基本概念](zh/context/基本概念.md) | 介绍算子相关的基础概念和特性，包括量化/稀疏等术语、数据类型、数据格式等。 |71+| [算子基本概念](zh/context/基本概念.md) | 介绍算子领域相关的基础概念和术语，如量化/稀疏、数据类型、数据格式等。 |
47-| [build参数说明](zh/context/build.md) | 介绍项目中build.sh脚本功能和具体参数。 |72+| [build参数说明](zh/install/build.md) | 介绍本项目build.sh参数功能和取值，包括源码编译、算子调用、调试等。 |
Mdocs/zh/context/aclnn返回码.md+3-2
@@ -1,6 +1,7 @@
1- # aclnn返回码1+# aclnn返回码
2 2 
3调用aclnn API时，常见的接口返回码如[表1](#zh-cn_topic_0000001563019104_table8155243135018)所示。3调用aclnn API时，常见的接口返回码如[表1](#zh-cn_topic_0000001563019104_table8155243135018)所示。
4+对于异常状态码值，可以通过aclGetRecentErrMsg接口（参见[《acl API（C）》](https://hiascend.com/document/redirect/CannCommunityCppApi)）获取异常信息，您可以根据报错提示排查问题或者联系技术支持。
4 5 
5**表 1** 返回状态码6**表 1** 返回状态码
6 7 
@@ -46,7 +47,7 @@
46</td>47</td>
47<td class="cellrowborder" valign="top" width="15.971597159715973%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000001563019104_p14156144313508"><a name="zh-cn_topic_0000001563019104_p14156144313508"></a><a name="zh-cn_topic_0000001563019104_p14156144313508"></a>561xxx</p>48<td class="cellrowborder" valign="top" width="15.971597159715973%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000001563019104_p14156144313508"><a name="zh-cn_topic_0000001563019104_p14156144313508"></a><a name="zh-cn_topic_0000001563019104_p14156144313508"></a>561xxx</p>
48</td>49</td>
49-<td class="cellrowborder" valign="top" width="53.48534853485349%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000001563019104_p10850181263218"><a name="zh-cn_topic_0000001563019104_p10850181263218"></a><a name="zh-cn_topic_0000001563019104_p10850181263218"></a>API内部发生内部异常，详细的错误信息，可以通过aclGetRecentErrMsg接口获取。您可以根据报错提示排查问题或者联系技术支持。</p>50+<td class="cellrowborder" valign="top" width="53.48534853485349%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000001563019104_p10850181263218"><a name="zh-cn_topic_0000001563019104_p10850181263218"></a><a name="zh-cn_topic_0000001563019104_p10850181263218"></a>API内部发生异常，详细的错误信息，可以通过aclGetRecentErrMsg接口获取。您可以根据报错提示排查问题或者联系技术支持。</p>
50 51 
51</td>52</td>
52</tr>53</tr>
Ddocs/zh/context/build_offline.md+0-31
@@ -1,31 +0,0 @@
1-# 离线编译
2-离线编译是指在没有连接互联网的环境下，将软件源代码编译成可执行程序，并安装或配置到目标服务器上的过程。
3-本项目[算子调用](../invocation/quick_op_invocation.md)或[算子开发](../develop/aicore_develop_guide.md)过程中均需编译算子包，编译过程中会依赖一些开源第三方软件，这些软件联网时会自动下载，离线状态下无法直接下载。
4- 
5-本章提供了离线编译安装指导，在此之前请确保已按[环境部署](./quick_install.md)完成基础环境搭建。
6-## 获取依赖
7-离线编译时，需手动安装如下依赖，否则无法正常编译和执行算子，其中`${cann_3rd_lib_path}`表示第三方软件存放的目录。
8- 
9-- 依赖json
10- 
11-下载[json](https://gitcode.com/cann-src-third-party/json/releases/download/v3.11.3/include.zip)，并解压到`${cann_3rd_lib_path}/json/include`，若无该目录请自行创建。
12- 
13-- 依赖makeself
14- 
15-下载[makeself](https://gitcode.com/cann-src-third-party/makeself/releases/download/release-2.5.0-patch1.0/makeself-release-2.5.0-patch1.tar.gz)，并解压到`${cann_3rd_lib_path}/makeself`，若无该目录请自行创建。
16- 
17-## 离线编译（自定义算子包）
18-自定义算子包编译时，需增加--cann_3rd_lib_path配置选项并指定路径，命令如下：
19- 
20-```bash
21-bash build.sh --pkg --soc=${soc_version} [--vendor_name=${vendor_name}] [--ops=${op_list}] --cann-3rd_lib_path=${cann_3rd_lib_path}
22-# 以TransposeBatchMatMul算子编译为例，假设第三方软件存放的目录为/path/cann_3rd_lib_path
23-# bash build.sh --pkg --soc=ascend910b --ops=transpose_batch_mat_mul --cann-3rd_lib_path=/path/cann_3rd_lib_path
24-```
25- 
26-## 离线编译（ops-ras包）
27-整包编译时，需增加--cann_3rd_lib_path配置选项并指定路径，命令如下：
28- 
29-```bash
30-bash build.sh --pkg [--jit] --soc=${soc_version} --cann-3rd_lib_path=${cann_3rd_lib_path}
31-```
Ddocs/zh/context/dir_structure.md+0-133
@@ -1,133 +0,0 @@
1-# 项目目录
2- 
3-> 本章罗列的部分目录是可选的，请以实际交付件为准。尤其**单算子目录**，不同场景下交付件有差异，具体说明如下：
4->
5-> - 若缺少op_host目录，可能是调用了其他算子op_host实现，调用逻辑参见该算子op_api或op_graph目录下源码实现；也可能是Kernel暂无Ascend C实现，如有需要，欢迎开发者参考[贡献指南](../../../CONTRIBUTING.md)补充贡献该算子。
6-> - 若缺少op_kernel目录，可能是调用了其他算子op_kernel实现，调用逻辑参见该算子op_api或op_graph目录下源码实现；也可能是Kernel暂无Ascend C实现，如有需要，欢迎开发者参考[贡献指南](../../../CONTRIBUTING.md)补充贡献该算子。
7-> - 若缺少op_api目录，说明该算子暂不支持aclnn调用。
8-> - 若缺少op_graph目录，说明该算子暂不支持图模式调用。
9- 
10-项目全量目录层级介绍如下：
11-```
12-├── cmake # 项目工程编译目录
13-│ ├── aclnn_ops_ras.h.in # aclnn汇总头文件模板
14-│ └── ...
15-├── common # 项目公共头文件和公共代码
16-│ ├── CMakeLists.txt
17-│ ├── inc # 公共头文件目录
18-│ └── src # 公共代码目录
19-├── ${op_class} # 算子分类，如activation、conv、matmul类算子
20-│ ├── ${op_name} # 算子工程目录，${op_name}表示算子名（小写下划线形式）
21-│ │ ├── CMakeLists.txt # 算子CMakeList入口
22-│ │ ├── README.md # 算子介绍文档
23-│ │ ├── docs # 算子文档目录
24-│ │ │ └── aclnn${OpName}.md # 算子aclnn接口介绍文档，${OpName}表示算子名（大驼峰形式）
25-│ │ ├── examples # 算子调用示例目录
26-│ │ │ ├── test_aclnn_${op_name}.cpp # 算子通过aclnn调用的示例
27-│ │ │ └── test_geir_${op_name}.cpp # 算子通过geir调用的示例
28-│ │ ├── op_graph # 图融合相关实现
29-│ │ │ ├── CMakeLists.txt # op_graph侧CMakeList文件
30-│ │ │ ├── ${op_name}_graph_infer.cpp # InferDataType文件，实现算子数据类型推导
31-│ │ │ ├── ${op_name}_proto.h # 算子原型定义，用于图优化和融合阶段识别算子
32-│ │ │ └── fusion_pass # 算子融合规则目录
33-│ │ ├── op_host # Host侧实现
34-│ │ │ ├── CMakeLists.txt # Host侧CMakeList文件
35-│ │ │ ├── config # 可选，二进制配置文件，若未配置工程自动生成
36-│ │ │ │ ├── ${soc_version} # 算子在NPU上配置的二进制信息，${soc_version}表示NPU型号
37-│ │ │ │ │ ├── ${op_name}_binary.json # 算子二进制配置文件
38-│ │ │ │ │ └── ${op_name}_simplified_key.ini # 算子SimplifiedKey配置信息
39-│ │ │ │ └── ...
40-│ │ │ ├── ${op_name}_def.cpp # 算子信息库，定义算子基本信息，如名称、输入输出、数据类型等
41-│ │ │ ├── ${op_name}_infershape.cpp # 可选，InferShape实现，根据算子形状推导输出shape，若未配置则输出shape与输入shape一样
42-│ │ │ ├── ${op_name}_tiling_${sub_case}.cpp # 可选，针对某些子场景下的Tiling优化，${sub_case}表示子场景，如${op_name}_tiling_arch35是针对arch35架构的优化，若无该文件表明该算子没有对应子场景的特定Tiling策略
43-│ │ │ ├── ${op_name}_tiling_${sub_case}.h # 可选，${sub_case}子场景下Tiling实现用的头文件
44-│ │ │ ├── ${op_name}_tiling.cpp # 可选，若无该文件表明对应场景下无Tiling实现(将张量划分为多个小块，区分数据类型进行并行计算)
45-│ │ │ ├── ${op_name}_tiling.h # 可选，Tiling实现用的头文件
46-│ │ │ └── op_api # 可选，算子aclnn实现文件目录，若未配置工程自动生成
47-│ │ │ ├── aclnn_${op_name}.cpp # 算子aclnn接口实现文件
48-│ │ │ ├── aclnn_${op_name}.h # 算子aclnn接口实现头文件
49-│ │ │ ├── ${op_name}.cpp # 算子l0接口实现文件
50-│ │ │ ├── ${op_name}.h # 算子l0接口实现头文件
51-│ │ │ └── CMakeLists.txt
52-│ │ │── op_kernel # AI Core算子Device侧Kernel实现
53-│ │ │ ├── ${sub_case} # 可选，${sub_case}子场景使用的目录
54-│ │ │ │ ├── ${op_name}_${model}.h # 算子kernel实现文件，${model}表示用户自定义文件名后缀，通常为Tiling模板名
55-│ │ │ │ └── ...
56-│ │ │ ├── ${op_name}_tiling_key.h # 可选，TilingKey文件，定义Tiling策略的Key，标识不同划分方式，若未配置表明该算子无相应的Tiling策略
57-│ │ │ ├── ${op_name}_tiling_data.h # 可选，TilingData文件，存储Tiling策略相关配置信息，如块大小、并行度，若未配置表明该算子无相应的Tiling策略
58-│ │ │ ├── ${op_name}.cpp # Kernel入口文件，包含主函数和调度逻辑
59-│ │ │ └── ${op_name}.h # Kernel实现文件，定义Kernel头文件，包含函数声明、结构定义、逻辑实现
60-│ │ │── op_kernel_aicpu # 可选，AI CPU算子Device侧Kernel实现
61-│ │ │ ├── ${op_name}_aicpu.cpp # Kernel入口文件，包含主函数和调度逻辑
62-│ │ │ └── ${op_name}_aicpu.h # Kernel头文件，包含函数声明、结构定义、逻辑实现
63-│ │ └── tests # 算子测试用例目录
64-│ │ ├── CMakeLists.txt
65-│ │ └── ut # 可选，UT测试用例，根据实际情况开发相应的用例
66-│ │ ├── CMakeLists.txt # UT用例CMakeList文件
67-│ │ ├── graph_plugin # graph_plugin测试用例目录
68-│ │ │ ├── CMakeLists.txt
69-│ │ │ └── fusion_pass # 融合规则测试用例目录
70-│ │ │ └── CMakeLists.txt
71-│ │ ├── op_host # op_host测试用例目录
72-│ │ │ ├── CMakeLists.txt
73-│ │ │ ├── ${op_name}_regbase_tiling.h
74-│ │ │ ├── op_api # op_api测试用例目录
75-│ │ │ │ ├── CMakeLists.txt
76-│ │ │ │ └── test_aclnn_${op_name}.cpp # 算子aclnn测试用例文件
77-│ │ │ ├── test_${op_name}_${sub_case}.cpp # ${sub_case}子场景下op_host测试用例文件
78-│ │ │ ├── test_${op_name}.cpp # op_host测试用例文件
79-│ │ │ ├── test_${op_name}_infershape.cpp # 算子InferShape测试用例文件
80-│ │ │ └── test_${op_name}_tiling.cpp # 算子Tiling测试用例文件
81-│ │ └── op_kernel # op_kernel测试用例目录
82-│ │ ├── CMakeLists.txt
83-│ │ │── test_${op_name}.cpp # 算子Kernel测试用例文件
84-│ │ └── ${op_name}_data # 可选，op_kernel测试用例中依赖的数据比对和生成脚本，若未配置需在对应用例中手动实现
85-│ │ ├── compare_data.py # 数据脚本
86-│ │ └── gen_data.py # 数据生成脚本
87-│ └── ...
88-├── docs # 项目相关文档目录（zh为中文，en为英文）
89-├── examples # 端到端算子开发和调用示例
90-│ ├── add_example # AI Core算子示例目录
91-│ │ ├── CMakeLists.txt # 算子编译配置文件
92-│ │ ├── examples # 算子使用示例目录
93-│ │ ├── op_graph # 算子构图相关目录
94-│ │ ├── op_host # 算子信息库、Tiling、InferShape相关实现目录
95-│ │ ├── op_kernel # 算子Kernel目录
96-│ │ └── tests # 算子测试用例目录
97-│ ├── add_example_aicpu # AI CPU算子示例目录
98-│ │ ├── CMakeLists.txt # 算子编译配置文件
99-│ │ ├── examples # 算子使用示例目录
100-│ │ ├── op_graph # 算子构图相关目录
101-│ │ ├── op_host # 算子信息库、InferShape相关实现
102-│ │ ├── op_kernel_aicpu # 算子Kernel目录
103-│ │ └── tests # 算子测试用例目录
104-│ ├── fast_kernel_launch_example # 轻量级，高性能的算子开发工程模板
105-│ │ ├── ascend_ops # 示例算子实现目录
106-│ │ ├── CMakeLists.txt # 算子编译配置文件
107-│ │ ├── README.md # 轻量级，高性能的算子开发工程说明资料
108-│ │ ├── requirements.txt
109-│ │ └── setup.py # 构建脚本
110-│ ├── CMakeLists.txt
111-│ └── README.md # 项目示例介绍文档
112-├── experimental # 用户自定义算子存放目录
113-├── scripts # 脚本目录，包含自定义算子、Kernel构建相关配置文件
114-├── tests # 项目级测试目录
115-│ ├── requirements.txt # 测试用例依赖的第三方组件
116-│ └── ut # UT用例工程
117-│ ├── CMakeLists.txt # UT工程的CMakeList脚本
118-│ ├── common # UT工程中使用的公共代码
119-│ ├── op_api # op_api测试工程
120-│ ├── op_host # op_host测试工程
121-│ └── op_kernel # op_kernel测试工程
122-├── CMakeLists.txt # 项目工程CMakeList入口
123-├── CONTRIBUTING.md # 项目贡献指南文件
124-├── LICENSE # 项目开源许可证信息
125-├── OAT.xml # 配置脚本，代码仓工具使用，用于检查License是否规范
126-├── README.md # 项目工程总介绍文档
127-├── SECURITY.md # 项目安全声明文件
128-├── build.sh # 项目工程编译脚本
129-├── classify_rule.yaml # 组件划分信息
130-├── install_deps.sh # 项目安装依赖包脚本
131-├── requirements.txt # 项目的第三方依赖包
132-└── version.info # 项目版本信息
133-```
Mdocs/zh/context/数据类型.md+8-0
@@ -26,6 +26,14 @@
26| ACL_INT4 | INT4 |26| ACL_INT4 | INT4 |
27| ACL_UINT1 | UINT1 |27| ACL_UINT1 | UINT1 |
28| ACL_COMPLEX32 | COMPLEX32 |28| ACL_COMPLEX32 | COMPLEX32 |
29+| ACL_HIFLOAT8 | HIFLOAT8 |
30+| ACL_FLOAT8_E5M2 | FLOAT8_E5M2 |
31+| ACL_FLOAT8_E4M3FN | FLOAT8_E4M3FN |
32+| ACL_FLOAT8_E8M0 | FLOAT8_E8M0 |
33+| ACL_FLOAT6_E3M2 | FLOAT6_E3M2 |
34+| ACL_FLOAT6_E2M3 | FLOAT6_E2M3 |
35+| ACL_FLOAT4_E2M1 | FLOAT4_E2M1 |
36+| ACL_FLOAT4_E1M2 | FLOAT4_E1M2 |
29 37 
30 38 
31 39 
Mdocs/zh/context/编译与运行样例.md+5-20
@@ -5,11 +5,11 @@
5- 算子API的调用流程和编译运行操作详情请参见[《应用开发（C&C++）》](https://hiascend.com/document/redirect/CannCommunityCppInferWizard)中“单算子调用>单算子API执行>调用aclnn接口示例代码”。5- 算子API的调用流程和编译运行操作详情请参见[《应用开发（C&C++）》](https://hiascend.com/document/redirect/CannCommunityCppInferWizard)中“单算子调用>单算子API执行>调用aclnn接口示例代码”。
6 6 
7## 编译前准备7## 编译前准备
8-本章以开发和运行环境合设场景为例，即带AI处理器的机器既作为开发环境又作为运行环境。该场景下，代码开发和代码运行在同一台机器上。这里以**AddMatMul算子**为例，其他算子的调用逻辑、流程、编译脚本与AddMatMul算子大致一样，请根据实际情况自行修改API调用脚本（\*.cpp）和编译脚本(CMakeLists)。8+本章以开发和运行环境合设场景为例，即带AI处理器的机器既作为开发环境又作为运行环境。该场景下，代码开发和代码运行在同一台机器上。这里以**AddExample算子**为例，其他算子的调用逻辑、流程、编译脚本与AddExample算子大致一样，请根据实际情况自行修改API调用脚本（\*.cpp）和编译脚本(CMakeLists)。
9 9 
10- **示例代码**10- **示例代码**
11 11 
12- 已知AddMatMul算子实现了张量加法运算，计算公式为：out = β self + α (mat1 @ mat2)。您可以从[aclnnAddmm&aclnnInplaceAddmm.md](../../../matmul/mat_mul_v3/docs/aclnnAddmm&aclnnInplaceAddmm.md)中“调用示例”获取示例代码，并将代码文件命名为“**test\_addmm.cpp**”。12+ 已知AddExample算子实现了张量加法运算。您可以从[test_aclnn_add_example.cpp](../../../examples/add_example/examples/test_aclnn_add_example.cpp)中获取示例代码，并将代码文件命名为“**test\_aclnn\_add\_example.cpp**”。
13 13 
14- **CMakeLists文件**14- **CMakeLists文件**
15 15 
@@ -33,7 +33,7 @@
33 33 
34 # 设置可执行文件名（如opapi_test），并指定待运行算子文件*.cpp所在目录34 # 设置可执行文件名（如opapi_test），并指定待运行算子文件*.cpp所在目录
35 add_executable(opapi_test35 add_executable(opapi_test
36- test_addmm.cpp)36+ test_aclnn_add_example.cpp)
37 37 
38 # 设置ASCEND_PATH（CANN软件包目录，请根据实际路径修改）和INCLUDE_BASE_DIR（头文件目录）38 # 设置ASCEND_PATH（CANN软件包目录，请根据实际路径修改）和INCLUDE_BASE_DIR（头文件目录）
39 if(NOT "$ENV{ASCEND_CUSTOM_PATH}" STREQUAL "")39 if(NOT "$ENV{ASCEND_CUSTOM_PATH}" STREQUAL "")
@@ -51,27 +51,12 @@
51 target_link_libraries(opapi_test PRIVATE51 target_link_libraries(opapi_test PRIVATE
52 ${ASCEND_PATH}/lib64/libascendcl.so52 ${ASCEND_PATH}/lib64/libascendcl.so
53 ${ASCEND_PATH}/lib64/librasopbase.so53 ${ASCEND_PATH}/lib64/librasopbase.so
54- ${ASCEND_PATH}/lib64/libopapi_math.so
55 ${ASCEND_PATH}/lib64/libopapi_ras.so)54 ${ASCEND_PATH}/lib64/libopapi_ras.so)
56 55 
57 # 可执行文件在CMakeLists文件所在目录的bin目录下56 # 可执行文件在CMakeLists文件所在目录的bin目录下
58 install(TARGETS opapi_test DESTINATION ${CMAKE_RUNTIME_OUTPUT_DIRECTORY})57 install(TARGETS opapi_test DESTINATION ${CMAKE_RUNTIME_OUTPUT_DIRECTORY})
59 ```58 ```
60- 对于集合通信和MatMul计算融合、并行的算子，统称为通算融合算子（简称MC2算子），包括AllGatherMatmul、AlltoAllAllGatherBatchMatMul、BatchMatMulReduceScatterAlltoAll、MatmulAllReduce、MatmulAllReduceAddRmsNorm、MatmulReduceScatter等。调用该类算子API时，一般会涉及多线程和HCCL（Huawei Collective Communication Library，集合通信库），因此CMake文件需要额外导入如下内容，否则无法成功编译。59+ 
61-
62- ```
63- # 设置链接的库文件路径
64- find_package(Threads REQUIRED)
65- target_link_libraries(opapi_test PRIVATE
66- ${ASCEND_PATH}/lib64/libascendcl.so
67- ${ASCEND_PATH}/lib64/librasopbase.so
68- ${ASCEND_PATH}/lib64/libopapi_math.so
69- ${ASCEND_PATH}/lib64/libopapi_ras.so
70- ${ASCEND_PATH}/lib64/libhccl.so # 集合通信库文件
71- ${CMAKE_THREAD_LIBS_INIT}) # 多线程依赖的库文件
72- ```
73- 其中“find_package(Threads REQUIRED)”是CMake用于查找线程库的命令，可自动链接线程库依赖的头文件或间接依赖的库文件。
74-
75## 编译与运行60## 编译与运行
76 61 
77 1. 提前准备好算子的调用代码（\*.cpp）和编译脚本（CMakeLists.txt）。62 1. 提前准备好算子的调用代码（\*.cpp）和编译脚本（CMakeLists.txt）。
@@ -106,7 +91,7 @@
106 ./opapi_test91 ./opapi_test
107 ```92 ```
108 93
109- 以AddMatMul算子的运行结果为例，运行后的结果示例如下：94+ 以AddExample算子的运行结果为例，运行后的结果示例如下：
110 95
111 ```96 ```
112 result[0] is: 1.20000097 result[0] is: 1.200000
Rdocs/zh/debug/cann_simulator.md→docs/zh/debug/cann_sim.md+50-4
@@ -15,16 +15,61 @@ CANN Simulator是一款面向算子开发场景的SoC级芯片仿真工具，用
15* 工具推荐环境配置：CPU 16核，内存32GB以上。15* 工具推荐环境配置：CPU 16核，内存32GB以上。
16* 本文中举例路径均需要确保运行用户具有读或读写权限。16* 本文中举例路径均需要确保运行用户具有读或读写权限。
17* 出于安全性和权限最小化考虑，建议使用普通用户权限执行本工具，避免使用root等高权限账户。17* 出于安全性和权限最小化考虑，建议使用普通用户权限执行本工具，避免使用root等高权限账户。
18-* 本工具依赖CANN软件包，在使用前请先安装CANN软件包，无需安装赖驱动和固件，并通过source命令执行CANN的set_env.sh环境变量文件。为确保安全，执行source命令后请勿修改set_env.sh中涉及的环境变量。18+* 本工具依赖CANN软件包，在使用前请先安装CANN软件包，无需安装驱动和固件，并通过source命令执行CANN的set_env.sh环境变量文件。为确保安全，执行source命令后请勿修改set_env.sh中涉及的环境变量。
19* 用户应遵循最小权限原则，例如，给工具输入的文件要求other用户不可写，在一些对安全要求更严格的功能场景下还需确保输入的文件group用户不可写。19* 用户应遵循最小权限原则，例如，给工具输入的文件要求other用户不可写，在一些对安全要求更严格的功能场景下还需确保输入的文件group用户不可写。
20* 本工具为开发工具，不建议在生产环境使用。20* 本工具为开发工具，不建议在生产环境使用。
21* 工具的仿真功能仅支持单卡场景，无法仿真多卡环境，代码中只能设置为0卡。若修改可见卡号，将导致仿真失败。21* 工具的仿真功能仅支持单卡场景，无法仿真多卡环境，代码中只能设置为0卡。若修改可见卡号，将导致仿真失败。
22* 仿真环境仅支持AI Core计算类算子（不支持MC2和HCCL类型的算子）。22* 仿真环境仅支持AI Core计算类算子（不支持MC2和HCCL类型的算子）。
23+CANN Simulator工具目前处于尝鲜版本阶段，仅支持Ascend950PR芯片，建议仿真器运行环境配置为16核CPU和32GB以上内存。
23* 目前不支持arm环境仿真。24* 目前不支持arm环境仿真。
24 25 
25## 环境准备26## 环境准备
26 27 
27-CANN Simulator集成在CANN toolkit包里，参考[环境部署](../context/quick_install.md)中的软件包安装 -> 安装社区版CANN toolkit包章节28+CANN Simulator集成在CANN toolkit包里，参考[环境部署](../install/quick_install.md)中的软件包安装 -> 安装社区版CANN toolkit包章节
29+ 
30+# 快速开始
31+ 
32+下面以[add_examples](../../../examples/add_example/)为例，对算子仿真进行详细说明
33+ 
34+## 算子编译
35+ 
36+* 参考[算子调用](../invocation/quick_op_invocation.md)完成add_example的算子编译和安装
37+ 
38+```bash
39+# 说明：进入项目根目录，执行如下编译命令，命令仅供参考，详细可以查看算子调用的说明。
40+bash build.sh --pkg --soc=Ascend950 --vendor_name=custom --ops=add_example
41+# 安装自定义算子包
42+./build_out/cann-ops-ras-${vendor_name}_linux-${arch}.run
43+```
44+ 
45+* 参考[aclnn调用](../invocation/quick_op_invocation.md#aclnn调用)完成test_aclnn_add_example.cpp的编译，编出可执行文件test_aclnn_add_example
46+ 
47+## 执行仿真命令
48+ 
49+```bash
50+cannsim record ./test_aclnn_add_example -s Ascend950 --gen-report
51+```
52+ 
53+仿真工具执行日志文件在examples/add_example/examples/build/bin/cannsim_*目录，执行日志文件为 cannsim.log。
54+ 
55+从仿真工具日志文件可以看到示例中的打印信息：
56+ 
57+```bash
58+mean result[0] is: 2.000000
59+mean result[1] is: 2.000000
60+mean result[2] is: 2.000000
61+...
62+```
63+ 
64+## 查看性能流水
65+ 
66+仿真性能流水文件在本项目`examples/add_example/examples/build/bin/cannsim_*/report`目录，流水相关文件为：
67+ 
68+```bash
69+trace_core0.json
70+```
71+ 
72+在Chrome浏览器中输入“chrome://tracing”地址，并将生成的指令流水图文件（trace_core0.json）拖到空白处打开，具体参数介绍参考“仿真结果解析”章节。
28 73 
29# 仿真执行74# 仿真执行
30 75 
@@ -45,8 +90,9 @@ cannsim record [options] user_app --user_options
45|-s <value> 或 --soc_version <value> [options]参数 | 必选 | 指定模拟目标芯片版本（如：Ascend950）。|90|-s <value> 或 --soc_version <value> [options]参数 | 必选 | 指定模拟目标芯片版本（如：Ascend950）。|
46|-o <value> 或 --output <value> [options]参数 | 可选| 生成文件所在路径，可配置为绝对路径或者相对路径，并且执行工具的用户需要具有读写权限。如果未指定路径，则默认在当前目录下保存数据。|91|-o <value> 或 --output <value> [options]参数 | 可选| 生成文件所在路径，可配置为绝对路径或者相对路径，并且执行工具的用户需要具有读写权限。如果未指定路径，则默认在当前目录下保存数据。|
47|-g 或 --gen-report[options]参数 | 可选 | 启用仿真完成后是否进行自动解析，并生成分析报告。默认不自动解析。|92|-g 或 --gen-report[options]参数 | 可选 | 启用仿真完成后是否进行自动解析，并生成分析报告。默认不自动解析。|
48-|user_app|必选|算子可执行文件。|93+|-n 或 --core-id | 可选 | 仿真期间启用日志的AI Core，格式同 report -n：'all'、'0-2,12-14'、'5'。默认全开；配合 -g 且未指定时回退到 core 0。|
49---user_options|可选|算子可执行文件的运行参数。|94+|-u 或 --user-option | 可选 | 用户自定义算子参数，以命令行选项形式传递给算子程序。|
95+|user_app|必选|待运行的算子程序或命令（如 ./app, python train.py, bash run.sh）。|
50 96 
51## 使用示例97## 使用示例
52 98 
Mdocs/zh/debug/op_debug_prof.md+40-4
@@ -6,7 +6,39 @@
6 6 
7算子运行过程中，如果出现算子执行失败、精度异常等问题，可以打印各阶段信息，如Kernel中间结果，进行问题分析和定位。7算子运行过程中，如果出现算子执行失败、精度异常等问题，可以打印各阶段信息，如Kernel中间结果，进行问题分析和定位。
8 8 
9-常见调试方法如下：9+### 1、Host侧日志获取方式
10+ 
11+* **plog获取**
12+ 
13+ 程序执行结束后，默认可在"$HOME/ascendc/log"下查看，host日志文件存储路径如下：
14+ 
15+ ```bash
16+ $HOME/ascend/log/debug/plog/plog-pid_*.log
17+ ```
18+ 
19+ 开启环境变量ASCEND_SLOG_PRINT_TO_STDOUT可以将log日志直接打屏显示(1:开启打屏，0：关闭打屏)，配置示例如下：
20+ 
21+ ```bash
22+ export ASCEND_SLOG_PRINT_TO_STDOUT=1
23+ ```
24+ 
25+ 日志相关介绍参见[《日志参考》](https://hiascend.com/document/redirect/CannCommunitylogref)，环境变量介绍参见[《环境变量参考》](https://hiascend.com/document/redirect/CannCommunityEnvRef)。
26+ 
27+* **aclnn异常错误信息获取**
28+
29+ 通过aclGetRecentErrMsg接口（参见[《acl API（C）》](https://hiascend.com/document/redirect/CannCommunityCppApi)）获取aclnn接口调用过程中的异常信息，使用方法如下：
30+ 
31+ ```bash
32+ printf(aclGetRecentErrMsg());
33+ ```
34+ 
35+ 打印错误信息样例如下：
36+ 
37+ ```bash
38+ [PID:646612] 2026-01-24-11:53:44.671.727 AclNN_Parameter_Error(EZ1001): Expected a proper Tensor but got null for argument addmmTennsor.self.
39+ ```
40+ 
41+### 2、Kernel调试
10 42 
11* **printf**43* **printf**
12 44 
@@ -36,7 +68,11 @@
36 68 
37算子运行过程中，如果出现算子执行失败、精度异常等问题，可以打印各阶段信息，如Kernel中间结果，进行问题分析和定位。69算子运行过程中，如果出现算子执行失败、精度异常等问题，可以打印各阶段信息，如Kernel中间结果，进行问题分析和定位。
38 70 
39-常见调试方法如下：71+### 1、Host侧日志获取方式
72+ 
73+ 见AI Core算子[Host侧日志获取方式](#1host侧日志获取方式)。
74+ 
75+### 2、Kernel调试
40 76 
41* **KERNEL\_LOG宏**77* **KERNEL\_LOG宏**
42 78 
@@ -122,7 +158,7 @@
122 158
123### 方式二（针对Ascend 950PR/Ascend 950DT系列产品）159### 方式二（针对Ascend 950PR/Ascend 950DT系列产品）
124 160 
125-算子开发过程中，如果出现执行精度下降、内存占用异常等问题，可以通过[CANN Simulator](./cann_simulator.md)仿真工具分析算子的指令流水情况，从而确定问题根源，并针对性地优化。161+算子开发过程中，如果出现执行精度下降、内存占用异常等问题，可以通过[CANN Simulator](./cann_sim.md)仿真工具分析算子的指令流水情况，从而确定问题根源，并针对性地优化。
126 162 
127本章以[AddExample自定义算子](../../../examples/add_example)为例，主要介绍仿真工具的使用。如何通过仿真工具进行精度和性能调优。163本章以[AddExample自定义算子](../../../examples/add_example)为例，主要介绍仿真工具的使用。如何通过仿真工具进行精度和性能调优。
128 164 
@@ -142,5 +178,5 @@
142 trace_core0.json178 trace_core0.json
143 ``` 179 ```
144 180 
145-3. 在Chrome浏览器中输入“chrome://tracing”地址，并将生成的指令流水图文件（trace_core0.json）拖到空白处打开，具体参数介绍参考CANN Simulator中[“仿真结果解析”](./cann_simulator.md/#仿真结果解析)章节。181+3. 在Chrome浏览器中输入“chrome://tracing”地址，并将生成的指令流水图文件（trace_core0.json）拖到空白处打开，具体参数介绍参考CANN Simulator中[“仿真结果解析”](./cann_sim.md#仿真结果解析)章节。
146 182 
Mdocs/zh/develop/aicore_develop_guide.md+3-3
@@ -24,7 +24,7 @@
24## 工程创建24## 工程创建
25**1. 环境部署** 25**1. 环境部署**
26 26 
27-开发算子前，请先参考[环境部署](../context/quick_install.md)完成基础环境搭建。27+开发算子前，请先参考[环境部署](../install/quick_install.md)完成基础环境搭建。
28 28 
29**2. 目录创建**29**2. 目录创建**
30 30 
@@ -34,7 +34,7 @@
34 34 
35```bash35```bash
36# 创建指定算子目录，如bash build.sh --genop=examples/add_example36# 创建指定算子目录，如bash build.sh --genop=examples/add_example
37-# ${op_class}表示算子类型，如matmul类。37+# ${op_class}表示算子类型，如reliability类。
38# ${op_name}表示算子名的小写下划线形式，如`AddExample`算子对应为add_example。38# ${op_name}表示算子名的小写下划线形式，如`AddExample`算子对应为add_example。
39bash build.sh --genop=${op_class}/${op_name}39bash build.sh --genop=${op_class}/${op_name}
40```40```
@@ -353,7 +353,7 @@ __aicore__ inline void AddExample<T>::Process()
353 353 
354 以`AddExample`算子为例，假设开发交付件在`examples`目录，完整代码参见[add_example](../../../examples/add_example)目录。354 以`AddExample`算子为例，假设开发交付件在`examples`目录，完整代码参见[add_example](../../../examples/add_example)目录。
355 355 
356- > 说明：编译过程依赖第三方开源软件，联网场景会自动下载，离线编译场景需要自行安装，具体参考[离线编译](../context/build_offline.md)。356+ > 说明：编译过程依赖第三方开源软件，联网场景会自动下载，离线编译场景需要自行安装，具体参考[离线编译](../install/compile.md#未联网编译)。
357 357 
358 ```bash358 ```bash
359 # 编译指定算子，如--ops=add_example359 # 编译指定算子，如--ops=add_example
Mdocs/zh/develop/aicpu_develop_guide.md+2-2
@@ -22,7 +22,7 @@
22## 工程创建22## 工程创建
23**1. 环境部署**23**1. 环境部署**
24 24 
25-开发算子前，请先参考[环境部署](../context/quick_install.md)完成基础环境搭建。25+开发算子前，请先参考[环境部署](../install/quick_install.md)完成基础环境搭建。
26 26 
27**2. 目录创建**27**2. 目录创建**
28 28 
@@ -32,7 +32,7 @@
32 32 
33```bash33```bash
34# 创建指定算子目录，如bash build.sh --genop_aicpu=examples/add_example34# 创建指定算子目录，如bash build.sh --genop_aicpu=examples/add_example
35-# ${op_class}表示算子类型，如matmul类。35+# ${op_class}表示算子类型，如reliability类。
36# ${op_name}表示算子名的小写下划线形式，如`AddExample`算子对应为add_example。36# ${op_name}表示算子名的小写下划线形式，如`AddExample`算子对应为add_example。
37bash build.sh --genop_aicpu=${op_class}/${op_name}37bash build.sh --genop_aicpu=${op_class}/${op_name}
38```38```
Adocs/zh/develop/cross_platform_migration_guide.md+466-0
@@ -0,0 +1,466 @@
1+# 算子跨平台迁移指导
2+ 
3+本指南介绍算子在多平台间迁移的适配要点与方案。以算子从Atlas A2系列迁移至Ascend 950系列为例，对比硬件架构差异项及所涉适配点，并提供相关算子适配样例。
4+ 
5+## 一、硬件架构及规格参数对比
6+ 
7+### Atlas A2系列硬件架构
8+ 
9+<div align="center">
10+ <img src="../figures/Atlas A2硬件架构.png" width="900" alt="Atlas A2硬件架构" />
11+</div>
12+ 
13+### Ascend 950系列硬件架构
14+ 
15+<div align="center">
16+ <img src="../figures/Ascend 950硬件架构.png" width="900" alt="Ascend 950硬件架构" />
17+</div>
18+ 
19+### 代际规格参数对比
20+ 
21+通常根据不同的应用场景、工艺或硬件配置划分为多个产品型号，各型号在性能、资源配置等方面可能存在一定差异。为便于说明与直接对比，本节选择代表性配置作为参数展示与差异解析对象，其他相关调整请以实际手册或官方发布为准。
22+ 
23+<table>
24+ <tr>
25+ <th colspan="2" style="width: 25%;">规格项</th>
26+ <th style="width:37.5%;">Atlas A2</th>
27+ <th style="width:37.5%;">Ascend 950</th>
28+ </tr>
29+ <tr>
30+ <td rowspan="4">AICore</td>
31+ <td>核数</td>
32+ <td>24</td>
33+ <td>32</td>
34+ </tr>
35+ <tr>
36+ <td>频率</td>
37+ <td>1.8</td>
38+ <td>1.65</td>
39+ </tr>
40+ <tr>
41+ <td>Cube算力规格</td>
42+ <td>353T/376T @BF16,FP16</td>
43+ <td>426T@BF16,FP16 757T@FP8,HIFP8,MXFP8,INT8 1514T@MXFP4</td>
44+ </tr>
45+ <tr>
46+ <td>Vector算力规格(FP16)</td>
47+ <td>23.5T</td>
48+ <td>54T</td>
49+ </tr>
50+ <tr>
51+ <td rowspan="2">Memory</td>
52+ <td>Memory容量(GB)</td>
53+ <td>64</td>
54+ <td>128</td>
55+ </tr>
56+ <tr>
57+ <td>Memory带宽</td>
58+ <td>1.6TB/s</td>
59+ <td>1.6TB/s</td>
60+ </tr>
61+</table>
62+ 
63+## 二、硬件能力变更引入适配点
64+ 
65+<table>
66+ <tr>
67+ <th style="width: 25%;">硬件单元</th>
68+ <th style="width:35%;">硬件能力变更</th>
69+ <th style="width:40%;">典型影响范围</th>
70+ </tr>
71+ <tr>
72+ <td rowspan="5">搬运单元</td>
73+ <td>删除L1到GM的数据通路</td>
74+ <td>依赖L1直接回写GM的kernel需改为L1→UB→GM或L0C/FIXPIPE→GM路径；相关DataCopy链路、事件同步与缓冲规划需调整</td>
75+ </tr>
76+ <tr>
77+ <td>删除GM到L0A、L0B的数据通路</td>
78+ <td>GM→L0A/L0B直连不再可用，需通过GM→L1→L0A/L0B完成；L1切块策略和MTE1/2流水需重构</td>
79+ </tr>
80+ <tr>
81+ <td>ND DMA灵活数据搬运，支持随路ND->NZ转换</td>
82+ <td>可用ND2NZ/DN2NZ在MTE2阶段完成格式转换，减少中间buffer和格式转换开销；需关注步长、对齐与NZ形状映射</td>
83+ </tr>
84+ <tr>
85+ <td>支持Cube-&gt;Vector高效内部数据通路:L1&lt;-&gt;UB、L0C-&gt;UB、FIXP-&gt;UB</td>
86+ <td>可在UB侧做中间累加/激活/融合（如切K累加、后处理），减少GM往返；对应同步与管线切分需调整</td>
87+ </tr>
88+ <tr>
89+ <td>引入集合通信加速器CCU1.0</td>
90+ <td>通算融合算子在Eager模式下调整HcclServerType；在Graph模式下改用CCU系列GE接口</td>
91+ </tr>
92+ <tr>
93+ <td rowspan="3">计算单元</td>
94+ <td>Vector新增Regbase范式</td>
95+ <td>原依赖Membase的访存pattern、对齐方式、寄存器数量假设等需要重新审查；模板/tiling可能需要更新到Regbase版本</td>
96+ </tr>
97+ <tr>
98+ <td>Cube不再支持int4_t</td>
99+ <td>所有使用int4_t的算子需要切换到支持的数据类型（如int8），并更新量化解算逻辑</td>
100+ </tr>
101+ <tr>
102+ <td>不支持4：2稀疏矩阵计算</td>
103+ <td>原依赖4：2稀疏特性提速的kernel需要改为稠密或其他支持的稀疏策略，并更新性能预期说明</td>
104+ </tr>
105+ <tr>
106+ <td rowspan="1">存储单元</td>
107+ <td>Local Buffer内存改进：Cube L0C 256KB、Vector UB 256KB</td>
108+ <td>更大L0C/UB允许增大基本块与双缓冲容量，减少切K/切块轮次；需重新评估L1/L0/UB配比与tile尺寸</td>
109+ </tr>
110+ <tr>
111+ <td rowspan="2">其他</td>
112+ <td>多核同时访问Global Memory同地址性能优化</td>
113+ <td>涉及矩阵乘相关算子的模板可优化</td>
114+ </tr>
115+ <tr>
116+ <td>SIMT</td>
117+ <td>SIMT引入后可用线程级并行处理分支/不规则计算，但需要适配线程划分、共享内存与同步语义；部分Vector实现可迁移为SIMT版本</td>
118+ </tr>
119+</table>
120+ 
121+## 三、推荐迁移步骤
122+ 
123+1. 确认算子涉及的计算单元（Cube/Vector）和对应单元支持的数据类型是否在平台间存在差异。
124+2. 确认涉及的数据搬运单元（ND-&gt;NZ、GM&lt;-&gt;Lx、集合通信等）是否在平台间存在差异。
125+3. 按硬件能力变更点逐项对照修改（Vector架构、Cube支持数据类型、L1/L0/UB大小、CCU通信等）。
126+4. 参考算子迁移样例调整/补齐Atlas A2/Ascend 950分支逻辑。
127+ 
128+## 四、算子迁移样例
129+ 
130+### Cube矩阵计算类算子
131+ 
132+#### Global Memory同地址访问冲突优化
133+ 
134+Ascend 950硬件新增同地址请求并行处理特性，不需要在各种分核场景额外规避同地址访问冲突。迁移时可将Atlas A2上为“错位规避冲突”设计的分核策略简化为更规则的滑动窗口模板（如行组窗口+列向往返扫描），减少无效偏移与冗余地址变换。实践中建议先以功能等价为目标保留原tile尺寸，再逐步放开分核约束，结合profiling数据观察MAC利用率、MTE2利用率、L2命中率等关键指标，确认模板调整是否带来稳定收益。
135+ 
136+<div align="center">
137+ <img src="../figures/SWAT滑动窗口模板.png" width="900" alt="SWAT滑动窗口模板" />
138+</div>
139+ 
140+#### Tile尺寸大小调整
141+ 
142+Atlas A2上L0C大小为128KB，Ascend 950提升到256KB，意味着单次可承载更大的累加结果块。迁移时可优先增大Tile块切分粒度或提高K方向单轮处理深度，以减少切块与切K轮次，降低循环控制和搬运开销。同时需要重新平衡L1/L0/UB容量预算，避免L0C放大后挤压A/B/scale缓冲导致流水断点。
143+ 
144+### Vector向量计算类算子
145+ 
146+#### SIMT
147+ 
148+Ascend 950系列新增了SIMT单元。SIMT在处理非规整离散访问方面相比SIMD有较大优势，适合地址不连续、访存跨度变化大、分支路径不一致的场景（如scatter/gather、索引重排、稀疏更新等）。
149+ 
150+迁移时建议优先识别“访存主导”且“向量化效率低”的算子子流程：若原有SIMD实现存在大量掩码分支、无效lane占比高、或需要复杂地址拼装，可将该部分改写为SIMT路径，通常可降低控制开销并提升有效访存吞吐。
151+ 
152+实践中需重点关注以下事项：一是线程任务切分要与数据稀疏性匹配，避免线程负载极不均衡；二是减少高频随机访存导致的流水空转，尽量在上游完成索引规整与分桶；三是将边界处理与主路径解耦，避免在热点循环中引入过多分支。建议在迁移后同时对比“纯SIMD实现”和“SIMD+SIMT混合实现”，按数据分布选择最优策略，而非固定单一路径。
153+ 
154+**以gather_v2算子为例：SIMD与SIMT实现对比**
155+ 
156+gather_v2算子根据合轴后的尾轴为单位进行gather，因此模板选择的依据是：尾轴 ≤ 2048时走SIMT模板，尾轴 > 2048时走SIMD模板。因为尾轴小时，需要离散访问多个不连续的小块地址，simt效率高。以下对比两种实现的核心差异：
157+ 
158+**1. 编程模型差异**
159+ 
160+SIMD实现采用传统的向量化编程模型，需显式管理UB缓冲区和流水队列：
161+ 
162+```cpp
163+// SIMD: 使用队列机制管理数据缓冲
164+TQueBind<QuePosition::VECIN, QuePosition::VECOUT, BUFFER_NUM> inQueue_;
165+TBuf<QuePosition::VECCALC> indexBuf_;
166+ 
167+// SIMD: 逐行处理，显式搬运和同步
168+for (int64_t j = 0; j < rows; j++) {
169+ INDICES_T index = GetIndex(yIdx, indiceEndIdx); // 标量读取索引
170+ int64_t xIndex = index * tilingData_->innerSize;
171+ DataCopyPad(xLocal[j * colsAlign], xGm[offset], dataCoptExtParams, dataCopyPadExtParams); // 批量连续数搬入
172+}
173+inQueue_.EnQue<int8_t>(xLocal); // 入队等待输出
174+```
175+ 
176+SIMT采用线程级并行模型，每个线程独立处理元素：
177+ 
178+```cpp
179+// SIMT: 使用线程级并行，无需显式buffer管理
180+__simt_vf__ LAUNCH_BOUND(2048) void GatherSimt(...) {
181+ for (INDEX_SIZE_T index = Simt::GetThreadIdx();
182+ index < currentCoreElements;
183+ index += Simt::GetThreadNum()) { // 线程跳跃式并行
184+ // 每个线程独立计算单点索引并访问
185+ INDEX_SIZE_T gatherI = Simt::UintDiv(yIndex, m0, shift0);
186+ INDICES_T indicesValue = indices[gatherI]; // 根据单点索引gatherI直接访问GM
187+ y[yIndex] = idxOutOfBound ? 0 : x[xIndex]; // 直接写回GM
188+ }
189+}
190+```
191+ 
192+**2. 访存模式差异**
193+ 
194+| 特性 | SIMD实现 | SIMT实现 |
195+|------|----------|----------|
196+| 数据访问 | 通过DataCopyPad显式搬运到UB | 线程直接通过`__gm__`指针访问GM |
197+| Buffer管理 | 需AllocTensor/EnQue/DeQue/FreeTensor | 无需显式buffer，硬件自动管理 |
198+| 同步机制 | 显式事件同步（HardEvent::MTE2_V等） | 线程间隐式同步 |
199+ 
200+**3. 适用场景差异**
201+ 
202+SIMD适合连续访问大块地址的场景，通过向量化指令高效处理连续数据；
203+ 
204+SIMT适合离散访存，线程并行处理；
205+ 
206+#### Regbase
207+ 
208+Ascend 950系列引入了Regbase编程范式，相比传统的Membase（Vector API）编程，Regbase更接近底层硬件的寄存器操作，提供更精细的向量化控制能力。
209+ 
210+**特点**
211+ 
212+- 使用`AscendC::MicroAPI`命名空间下的底层API
213+- 直接操作寄存器`RegTensor<T>`而非显式管理UB缓冲队列
214+- 通过`MaskReg`实现灵活的元素级掩码控制
215+ 
216+**与Membase编程模型对比**
217+ 
218+| 特性 | Membase（传统Vector API） | Regbase（MicroAPI） |
219+|------|---------------------------|---------------------|
220+| 数据载体 | `LocalTensor<T>` + Queue机制 | `RegTensor<T>`寄存器 |
221+| 内存管理 | 显式Alloc/EnQue/DeQue/Free | 寄存器自动分配 |
222+| 掩码控制 | 函数参数控制 | `MaskReg`寄存器控制 |
223+| 数据搬运 | `DataCopy`/`DataCopyPad` | `MicroAPI::DataCopy` + 分发模式 |
224+ 
225+**代码示例**
226+ 
227+```cpp
228+__simd_vf__ __aicore__ void GenIndexBuf(ubuf int32_t* helpAddr, int32_t colFactor)
229+{
230+ // 声明寄存器张量
231+ AscendC::MicroAPI::RegTensor<int32_t> v0;
232+ AscendC::MicroAPI::RegTensor<int32_t> v1;
233+ AscendC::MicroAPI::RegTensor<int32_t> vd1;
234+
235+ // 创建全量掩码
236+ AscendC::MicroAPI::MaskReg preg =
237+ AscendC::MicroAPI::CreateMask<int32_t, AscendC::MicroAPI::MaskPattern::ALL>();
238+
239+ // 标量复制到寄存器
240+ AscendC::MicroAPI::Duplicate(v1, colFactor, preg);
241+ // 生成序列 [0, 1, 2, ...]
242+ AscendC::MicroAPI::Arange(v0, 0);
243+ // 向量运算
244+ AscendC::MicroAPI::Div(vd1, v0, v1, preg);
245+ AscendC::MicroAPI::Mul(vd2, vd1, v1, preg);
246+ AscendC::MicroAPI::Sub(vd3, v0, vd2, preg);
247+ // 寄存器数据写回UB
248+ AscendC::MicroAPI::DataCopy(helpAddr, vd3, preg);
249+}
250+```
251+ 
252+```cpp
253+// 动态掩码：处理尾部不完整数据
254+__simd_vf__ __aicore__ void GatherProcess(ubuf int8_t* curYAddr, uint16_t repeatimes, uint16_t computeSize)
255+{
256+ MicroAPI::RegTensor<int8_t> vregTemp;
257+ MicroAPI::MaskReg preg;
258+
259+ for (uint16_t r = 0; r < repeatTimes; r++) {
260+ // 根据剩余元素数更新掩码
261+ preg = MicroAPI::UpdateMask<int8_t>(sreg);
262+ // 创建地址偏移寄存器
263+ MicroAPI::AddrReg offset = MicroAPI::CreateAddrReg<int8_t>(r, computeSize);
264+ MicroAPI::DataCopy(vregTemp, curXAddr, offset);
265+ // 带掩码的数据存储
266+ MicroAPI::DataCopy(curYAddr, vregTemp, offset, preg);
267+ }
268+}
269+```
270+ 
271+```cpp
272+// 数据聚合
273+__VEC_SCOPE__
274+{
275+ MicroAPI::RegTensor<uint32_t> indicesReg;
276+ MicroAPI::RegTensor<int32_t> vd0;
277+
278+ for (uint16_t indices = 0; indices < indicesLoopNum; indices++) {
279+ // 加载索引（E2B分发模式：将标量广播到向量）
280+ MicroAPI::DataCopy<uint32_t, MicroAPI::LoadDist::DIST_E2B_B32>(indicesReg, indicesAddr);
281+ // 根据索引进行Gather数据聚合
282+ MicroAPI::DataCopyGather(vd0, curXAddr, indicesReg, preg);
283+ // 数据块拷贝输出
284+ MicroAPI::DataCopy<int32_t, MicroAPI::DataCopyMode::DATA_BLOCK_COPY>(
285+ curYAddr, vd0, blockStride, preg);
286+ }
287+}
288+```
289+ 
290+**关键Regbase API说明**
291+ 
292+| API分类 | API名称 | 功能说明 |
293+|---------|---------|----------|
294+| 寄存器类型 | `RegTensor<T>` | 向量寄存器张量类型 |
295+| 掩码类型 | `MaskReg` | 掩码寄存器类型 |
296+| 掩码创建 | `CreateMask<T, Pattern>()` | 创建掩码（ALL/HALF等模式） |
297+| 掩码更新 | `UpdateMask<T>(count)` | 根据剩余元素数动态更新掩码 |
298+| 标量操作 | `Duplicate(reg, val, mask)` | 将标量值复制到寄存器所有元素 |
299+| 序列生成 | `Arange(reg, start)` | 生成连续序列 |
300+| 算术运算 | `Add/Sub/Mul/Div(dst, src1, src2, mask)` | 向量算术运算 |
301+| 标量运算 | `Adds/Muls(dst, src, scalar, mask)` | 向量与标量运算 |
302+| 类型转换 | `Cast<DT, ST>(dst, src, mask)` | 数据类型转换 |
303+| 比较运算 | `Compare<T, CMPMODE>(mask, src1, src2, pred)` | 向量比较生成掩码 |
304+| 数据加载 | `DataCopy<T, LoadDist>(reg, addr)` | 从UB加载到寄存器 |
305+| 数据存储 | `DataCopy<T>(addr, reg, mask)` | 从寄存器存储到UB |
306+| Gather | `DataCopyGather(dst, base, indices, mask)` | 根据索引收集数据 |
307+| 地址偏移 | `CreateAddrReg<T>(loop, stride)` | 创建循环地址偏移寄存器 |
308+ 
309+**分发模式（LoadDist）说明**
310+ 
311+| 模式 | 说明 | 典型用途 |
312+|------|------|----------|
313+| `DIST_NORM` | 正常连续加载 | 连续数据处理 |
314+| `DIST_UNPACK_B16` | 16位解包加载 | FP16/BF16转FP32 |
315+| `DIST_BRC_B32/B16` | 广播加载 | 标量scale广播 |
316+| `DIST_E2B_B32` | 标量到向量广播 | 索引值广播 |
317+ 
318+**迁移建议**
319+ 
320+1. 适合Regbase的场景：需要精细控制寄存器分配、复杂掩码逻辑、Gather/Scatter访存模式
321+2. 保留Membase的场景：简单的连续数据搬运和计算、双缓冲流水线
322+3. 混合使用：可在同一算子中结合两种范式，用Regbase处理核心计算逻辑，用Membase管理数据搬运
323+ 
324+### Cube-Vector融合类算子
325+ 
326+#### MTE数据搬运路径变化
327+ 
328+Ascend 950新架构引入UB2L1 & L0C2UB间的直连通路，实现矩阵计算数据的快速搬移，旨在简化CV融合算子开发并提升性能。
329+<div align="center">
330+ <img src="../figures/Ascend950新增CV直连通路.png" width="700" alt="Ascend950新增CV直连通路" />
331+</div>
332+ 
333+**矩阵搬入**
334+ 
335+启用UB至L1（UB2L1）直连通路，通过DataCopy接口，支持融合算子的向量计算结果直接搬入L1。
336+ 
337+**矩阵搬出**
338+ 
339+启用L0C至UB（L0C2UB）直连通路，通过DataCopy接口，支持融合算子的矩阵计算结果直接搬入UB进行后续向量计算。
340+ 
341+对于切K或多阶段融合场景，可将“L0C搬回GM再读回UB”改为“L0C直达UB累加/后处理”，降低GM往返带宽压力和时延。迁移时建议把中间结果归并、激活/量化前处理放到UB侧完成，并显式梳理MTE1/MTE2/MTE3与计算单元的事件同步顺序，确保跨单元流水连续，避免由于新增通路引入数据可见性或同步时序问题。关键开启接口定义可参考：
342+ 
343+```cpp
344+// 1. 新增: 搬入接口增加UB2L1的Nd2Nz搬入，支持Src&Dst都是LocalTensor的形式
345+template <typename T>  
346+__aicore__ inline void DataCopy(const LocalTensor<T>& dst, const LocalTensor<T>& src, const Nd2NzParams& intriParams)；
347+ 
348+// 2. 新增: 搬出接口增加L0C2UB的搬出,支持直接从L0C搬出到UB,支持Src&Dst都是LocalTensor的形式
349+template <typename T, typename U, const FixpipeConfig& config = CFG_ROW_MAJOR>
350+__aicore__ inline void Fixpipe(const LocalTensor<T>& dst, const LocalTensor<U>& src, const FixpipeParamsC310<config.format>& intriParams);
351+template <CO2Layout format = CO2Layout::ROW_MAJOR>
352+struct FixpipeParamsC310 {
353+    // ...
354+    uint8_t dualDstCtl = 0;
355+};
356+ 
357+// 3. 能力增强: 核间同步接口新增模式3
358+template <uint8_t modeId, pipe_t pipe>
359+__aicore__ inline void CrossCoreSetFlag(uint16_t flagId)
360+template <uint8_t modeId = 0, pipe_t pipe = PIPE_S>
361+__aicore__ inline void CrossCoreWaitFlag(uint16_t flagId)
362+ 
363+```
364+ 
365+#### 核间同步信号量匹配
366+ 
367+`CrossCoreSetFlag`和`CrossCoreWaitFlag`是核间同步信号量接口，广泛用于多核间的数据依赖与协同控制。本质上以“信号量”的方式实现不同AICore之间的数据处理阶段解耦与有序推进，常用于流水线控制、双缓冲切换、跨核协作等场景。
368+ 
369+- `CrossCoreSetFlag`：当前核（或线程）在完成某个阶段的数据处理后，主动设置指定的flag信号，告知依赖方（一般是其它核或下游流水线阶段）本阶段已完成，可以继续执行后续流程。
370+- `CrossCoreWaitFlag`：当前核（或线程）需等待某个flag信号被设置（即依赖的数据或事件完成），检测flag后才会继续向下执行。
371+ 
372+这套信号量的本质是保证多线程/多流水阶段间一致的同步序列，防止因资源未就绪或依赖没完成而发生数据竞争或死锁等硬件异常。详细的接口说明可参考官方文档：[CrossCoreSetFlag与CrossCoreWaitFlag核间同步接口详解](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/900beta1/API/ascendcopapi/atlasascendc_api_07_0273.html)。
373+ 
374+在Ascend 950上`CrossCoreWaitFlag`和`CrossCoreSetFlag`数量必须严格匹配，且建议在同一同步语义域内按“先生产后消费”的顺序成对设计。Atlas A2上算子与算子间若存在多余`CrossCoreSetFlag`信号量，HWTS会进行特殊处理清零计数器，Ascend 950系列为减少硬件开销，不再依赖该类兜底机制，要求单算子内核间同步信号量一一匹配，否则会出现必现卡死。
375+ 
376+迁移时请重点排查以下问题：其一，异常分支提前返回导致只执行`Set`未执行对应`Wait`（或反之）；其二，多stage流水复用同一`flagId`但生命周期重叠，造成“跨阶段串扰”；其三，循环内条件触发同步但循环边界未对齐，导致迭代次数不一致。以上问题在Atlas A2上可能被掩盖，在Ascend 950上会直接暴露为阻塞超时或死锁。对跨核流水较复杂的算子，可先构建最小数据集进行单stage验证，再逐步叠加双缓冲和多stage，以降低定位同步问题的复杂度。
377+ 
378+### 集合通信类算子
379+ 
380+Ascend 950引入集合通信加速器CCU1.0，降低了访存需求，减少了调度时延，为有效利用该特性，将算子跨片通信方式由A2的AICPU改为CCU通信。
381+ 
382+**Eager模式**
383+ 
384+在aclnn两段式接口中的第二段接口中，为算子执行器aclOpExecutor指定集合通信类型。
385+ 
386+以[MatmulAllReduce](https://gitcode.com/cann/ops-transformer/tree/master/mc2/matmul_all_reduce)算子迁移适配为例：
387+设置NnopbaseSetHcclServerType枚举值，A2为NNOPBASE_HCCL_SERVER_AICPU，950为NNOPBASE_HCCL_SERVER_TYPE_CCU。
388+ 
389+```CPP
390+// ...
391+aclnnStatus aclnnMatmulAllReduce(
392+ void* workspace, uint64_t workspaceSize, aclOpExecutor* executor, const aclrtStream stream)
393+{
394+ // ...
395+ if (NnopbaseSetHcclServerType) {
396+ if (op::GetCurrentPlatformInfo().GetCurNpuArch() == NpuArch::DAV_3510) {
397+ NnopbaseSetHcclServerType(executor, NnopbaseHcclServerType::NNOPBASE_HCCL_SERVER_TYPE_CCU);
398+ }
399+ }
400+ // ...
401+ return ACLNN_SUCCESS;
402+}
403+```
404+ 
405+**Graph模式**
406+ 
407+1. 用于资源计算与申请，涉及附属流相关信息的CalcParamFunc回调接口中，为GE的上下文context区分附属流的集合通信类型。
408+2. 用于设置主流/附属流上自定义任务、参数定制的GenerateTask回调接口中，区分两套GE的KernelLaunch接口，分别调用AICPU通信或CCU通信的创建及定制流程。
409+ 
410+静态图GE侧创建通信task的任务类型，A2为aicpu kfc server + kfc_stream；950为ccu server + ccu_stream。涉及代码文件：[matmul_all_reduce_gen_task.cpp](https://gitcode.com/cann/ops-transformer/blob/master/mc2/matmul_all_reduce/op_graph/matmul_all_reduce_gen_task.cpp)
411+ 
412+```CPP
413+// ...
414+ge::Status MatmulAllReduceCalcParamFunc(gert::ExeResGenerationContext *context)
415+{
416+ if (Mc2GenTaskOpsUtils::IsTargetPlatformNpuArch(context->GetNodeName(), NPUARCH_A5)) {
417+ // 950
418+ return Mc2GenTaskOpsUtils::CommonKFCMc2CalcParamFunc(context, "ccu server", "ccu_stream");
419+ }
420+ // A2
421+ return Mc2GenTaskOpsUtils::CommonKFCMc2CalcParamFunc(context, "aicpu kfc server", "kfc_stream");
422+}
423+// ...
424+```
425+ 
426+静态图GenTask调用接口有区别，流程有差异。涉及代码文件：[matmul_all_reduce_gen_task.cpp](https://gitcode.com/cann/ops-transformer/blob/master/mc2/matmul_all_reduce/op_graph/matmul_all_reduce_gen_task.cpp)
427+ 
428+```CPP
429+// ...
430+// A2
431+ge::Status MatmulAllReduceGenTaskOpsUtils::MatmulAllReduceGenTaskCallback(
432+ const gert::ExeResGenerationContext *context, std::vector<std::vector<uint8_t>>& tasks) {
433+ // ...
434+ // aicpu task
435+ ge::KernelLaunchInfo aicpu_task =
436+ ge::KernelLaunchInfo::CreateAicpuKfcTask(context, SO_NAME.c_str(), KERNEL_NAME_V1.c_str());
437+ // ...
438+}
439+ 
440+// 950
441+ge::Status Mc2Arch35GenTaskOpsUtils::Mc2Arch35GenTaskCallBack(const gert::ExeResGenerationContext *context, std::vector<std::vector<uint8_t>> &tasks) {
442+ // ...
443+ // ccu task
444+ ge::KernelLaunchInfo ccuTask = ge::KernelLaunchInfo::CreateCcuTask(context, ccuGroups);
445+ // ...
446+}
447+ 
448+ge::Status MatmulAllReduceGenTaskFunc(const gert::ExeResGenerationContext *context, std::vector<std::vector<uint8_t>> &tasks)
449+{
450+ if (Mc2GenTaskOpsUtils::IsTargetPlatformNpuArch(context->GetNodeName(), NPUARCH_A5)) {
451+ // 950
452+ return Mc2Arch35GenTaskOpsUtils::Mc2Arch35GenTaskCallBack(context, tasks);
453+ }
454+ // A2
455+ return MatmulAllReduceGenTaskOpsUtils::MatmulAllReduceGenTaskCallback(context, tasks);
456+}
457+// ...
458+```
459+ 
460+## 五、常见问题与性能调优建议（FAQ/性能小贴士）
461+ 
462+若算子在Ascend 950上性能不升反降时，可优先排查：
463+ 
464+1. 是否仍然使用Atlas A2的错位分核模板
465+2. 是否未开启CCU通信仍走AICPU
466+3. tiling是否沿用了Atlas A2的L1/L0/UB切分策略，导致Ascend 950更大的片上缓存未被充分利用
Rdocs/zh/context/build.md→docs/zh/install/build.md+5-3
@@ -37,8 +37,9 @@ bash build.sh --help
37| --ops | 可选 | 指定待编译的算子，如：mat_mul_v3，mse_loss，多个算子用英文逗号“,”分隔，不可与--ophost、--opapi、--opgraph同时使用。 |37| --ops | 可选 | 指定待编译的算子，如：mat_mul_v3，mse_loss，多个算子用英文逗号“,”分隔，不可与--ophost、--opapi、--opgraph同时使用。 |
38| --soc | 可选 | 指定NPU型号，每次编译只支持1个NPU型号。 |38| --soc | 可选 | 指定NPU型号，每次编译只支持1个NPU型号。 |
39| --jit | 可选 | 配置后，表示不编译算子的二进制文件。 |39| --jit | 可选 | 配置后，表示不编译算子的二进制文件。 |
40+| --static | 可选 | 配置后，表示生成静态库文件，包含libcann_ras_static.a和aclnn接口头文件，搭配--pkg参数，生成静态库压缩包。|
40| --vendor_name | 可选 | 指定自定义算子包的名称，默认值为custom。 |41| --vendor_name | 可选 | 指定自定义算子包的名称，默认值为custom。 |
41-| --build-type | 可选 | 启用调试模式。可选类型：Release/Debug，默认为Release。值为Debug时，不可与--mssanitizer、--oom同时使用。 |42+| --build-type | 可选 | 启用调试模式。可选类型：Release/Debug，默认为Release。值为Debug时，不可与--mssanitizer、--oom、--dump_cce同时使用。 |
42| --cov | 可选 | 启用覆盖率统计。 |43| --cov | 可选 | 启用覆盖率统计。 |
43| --noexec | 可选 | 仅编译单元测试二进制文件，不自动执行编译后的UT可执行文件。 |44| --noexec | 可选 | 仅编译单元测试二进制文件，不自动执行编译后的UT可执行文件。 |
44| --opkernel | 可选 | 编译二进制内核。 |45| --opkernel | 可选 | 编译二进制内核。 |
@@ -54,6 +55,7 @@ bash build.sh --help
54| --genop | 可选 | 创建AI Core自定义算子初始目录。 |55| --genop | 可选 | 创建AI Core自定义算子初始目录。 |
55| --genop_aicpu | 可选 | 创建AI CPU自定义算子初始目录。 |56| --genop_aicpu | 可选 | 创建AI CPU自定义算子初始目录。 |
56| --experimental | 可选 | 编译experimental目录下的用户算子。 |57| --experimental | 可选 | 编译experimental目录下的用户算子。 |
57-| --mssanitizer | 可选 | 开启kernel侧mssanitizer内存检测功能。不可与--oom同时使用。 |58+| --mssanitizer | 可选 | 开启kernel侧mssanitizer内存检测功能。不可与--oom、--dump_cce同时使用。 |
58-| --oom | 可选 | 开启kernel侧oom内存检测功能。不可与--mssanitizer同时使用。 |59+| --oom | 可选 | 开启kernel侧oom内存检测功能。不可与--mssanitizer、--dump_cce同时使用。 |
60+| --dump_cce | 可选 | 开启kernel侧dump预编译文件功能。不可与--mssanitizer、--oom同时使用。 |
59| --cann_3rd_lib_path| 可选 | 离线编译场景下第三方库存放的目录。 |61| --cann_3rd_lib_path| 可选 | 离线编译场景下第三方库存放的目录。 |
Adocs/zh/install/compile.md+266-0
@@ -0,0 +1,266 @@
1+# 源码构建
2+ 
3+源码构建前，请参考本项目README完成环境准备和源码下载，此处不再赘述。
4+ 
5+## 安装第三方依赖
6+ 
7+> **说明**：对于CANNLab或Docker环境，默认联网，编译过程中会自动下载第三方依赖，无需手动安装，可跳过本章操作。
8+ 
9+本项目编译过程依赖的第三方开源软件列表如下：
10+ 
11+| 开源软件 | 版本 | 下载地址 |
12+|---|---|---|
13+| json | 3.11.3 | [include.zip](https://gitcode.com/cann-src-third-party/json/releases/download/v3.11.3/include.zip) |
14+| makeself | 2.5.0 | [makeself-release-2.5.0-patch1.tar.gz](https://gitcode.com/cann-src-third-party/makeself/releases/download/release-2.5.0-patch1.0/makeself-release-2.5.0-patch1.tar.gz) |
15+| eigen | 5.0.0 | [eigen-5.0.0.tar.gz](https://gitcode.com/cann-src-third-party/eigen/releases/download/5.0.0-h0.trunk/eigen-5.0.0.tar.gz) |
16+| protobuf | 25.1.0 | [protobuf-25.1.tar.gz](https://gitcode.com/cann-src-third-party/protobuf/releases/download/v25.1/protobuf-25.1.tar.gz) |
17+| abseil-cpp | 20230802.1 | [abseil-cpp-20230802.1.tar.gz](https://gitcode.com/cann-src-third-party/abseil-cpp/releases/download/20230802.1/abseil-cpp-20230802.1.tar.gz) |
18+| opbase(自CANN 9.0.0及以后版本需要下载) | master | [opbase](https://gitcode.com/cann/opbase) |
19+| cann-cmake | master-015 | [cmake-master-015.tar.gz](https://cann-3rd.obs.cn-north-4.myhuaweicloud.com/cmake/cmake-master-015.tar.gz) |
20+ 
21+若您的编译环境可以访问网络，请参考[联网编译](#联网编译)，编译脚本会自动联网下载第三方软件。否则，请参考[未联网编译](#未联网编译)手动下载第三方软件。
22+ 
23+准备好开源第三方软件后，可采用如下编译方式，请按需选择：
24+ 
25+- **自定义算子包**：
26+ 
27+ 选择部分算子编译生成的包称为自定义算子包，以**挂载**形式作用于CANN包，不改变原始包内容。生成的自定义算子包优先级高于原始CANN包。该包支持aclnn和图模式调用AI Core、AI CPU算子。
28+ 
29+- **ops-ras包**：
30+ 
31+ 选择整个项目编译生成的包称为ops-ras包，可**完整替换**CANN包对应部分。该包支持aclnn和图模式调用AI Core算子。
32+ 
33+- **ops-ras静态库**：
34+ 
35+ > 说明：若您需要**基于本项目进行二次发布**并且对**软件包大小有要求**时，建议采用静态库编译，该库可以链接您的应用开发程序，仅保留业务所需的算子，从而实现软件最小化部署。
36+ 
37+ 表示整个项目编译为一个静态库文件，包含libcann_ras_static.a和aclnn接口头文件。该包仅支持aclnn调用AI Core算子。
38+ 
39+## 联网编译
40+ 
41+若在有互联网的环境下编译，编译过程中会自动安装第三方依赖，无需手动安装。不同场景下源码编译和部署命令如下：
42+ 
43+### 自定义算子包
44+ 
45+1. **编译自定义算子包**
46+ 
47+ 进入项目根目录，执行如下编译命令：
48+ 
49+ ```bash
50+ bash build.sh --pkg --soc=${soc_version} [--vendor_name=${vendor_name}] [--ops=${op_list}] [-j${n}]
51+ # 以AddExample算子编译为例
52+ # bash build.sh --pkg --soc=ascend910b --ops=add_example -j16
53+ # 编译experimental贡献目录下的用户算子（以AddExample算子为例，编译时请以实际贡献算子为准）
54+ # bash build.sh --pkg --experimental --soc=ascend910b --ops=add_example -j16
55+ ```
56+ 
57+ - --soc：\$\{soc\_version\}表示NPU型号。Atlas A2 训练系列产品/Atlas A2 推理系列产品使用"ascend910b"（默认），Atlas A3 训练系列产品/Atlas A3 推理系列产品使用"ascend910_93"，Ascend 950PR/Ascend 950DT产品使用"ascend950"。
58+ - --vendor_name（可选）：\$\{vendor\_name\}表示构建的自定义算子包名，默认名为custom。
59+ - --ops（可选）：\$\{op\_list\}表示待编译算子，不指定时默认编译所有算子。格式形如"add_example,crypto,..."，多算子之间用英文逗号","分隔。
60+ - --experimental（可选）：表示编译用户保存在experimental贡献目录下的算子。
61+ - -j（可选）：指定编译线程数，加快编译速度。
62+ 
63+ 若\$\{vendor\_name\}和\$\{op\_list\}都不传入编译的是ops-ras包；若编译所有算子的自定义算子包，需传入\$\{vendor\_name\}。当提示如下信息，说明编译成功。
64+ 
65+ ```bash
66+ Self-extractable archive "cann-ops-ras-${vendor_name}_linux-${arch}.run" successfully created.
67+ ```
68+ 
69+ 编译成功后，run包存放于项目根目录的build_out目录下。
70+ 
71+2. **安装自定义算子包**
72+ 
73+ ```bash
74+ ./build_out/cann-ops-ras-${vendor_name}_linux-${arch}.run
75+ ```
76+ 
77+ 自定义算子包默认安装路径为```${ASCEND_HOME_PATH}/opp/vendors```，\$\{ASCEND\_HOME\_PATH\}已通过环境变量配置，表示CANN toolkit包安装路径，一般为\$\{install\_path\}/cann。
78+ 
79+ > 说明：可通过配置--install-path=\$\{install\_path\}参数定义算子包安装目录，在使用自定义算子包前，需执行source \$\{install_path\}/vendors/${vendor_name}/bin/set_env.bash命令，set\_env.bash脚本将自定义算子包安装路径追加到环境变量ASCEND\_CUSTOM\_OPP\_PATH中，使自定义算子包在当前环境中生效。
80+ 
81+3. **（可选）卸载自定义算子包。**
82+ 
83+ 自定义算子包安装后在```${ASCEND_HOME_PATH}/opp/vendors/${vendor_name}_ras/scripts```目录会生成`uninstall.sh`，通过该脚本可卸载自定义算子包，命令如下：
84+ 
85+ ```bash
86+ bash ${ASCEND_HOME_PATH}/opp/vendors/${vendor_name}_ras/scripts/uninstall.sh
87+ ```
88+ 
89+### ops-ras包
90+ 
91+> **说明**：全量编译会构建仓库内全部算子，耗时较长，与机器配置、`-j` 并行度及是否联网下载第三方依赖有关；日常开发请优先使用单算子编译（`--ops=<算子名>`）。
92+ 
93+1. **编译ops-ras包**
94+ 
95+ 进入项目根目录，执行如下编译命令：
96+ 
97+ ```bash
98+ # 编译除experimental目录外的所有算子
99+ bash build.sh --pkg [--jit] --soc=${soc_version} [-j${n}]
100+ # 编译experimental目录下的所有算子
101+ # bash build.sh --pkg --experimental [--jit] --soc=${soc_version} [-j${n}]
102+ ```
103+ 
104+ - --soc：\$\{soc\_version\}表示NPU型号。Atlas A2 训练系列产品/Atlas A2 推理系列产品使用"ascend910b"（默认），Atlas A3 训练系列产品/Atlas A3 推理系列产品使用"ascend910_93"，Ascend 950PR/Ascend 950DT产品使用"ascend950"。
105+ - --jit（可选）：设置后表示不编译算子二进制文件，如需使用aclnn调用算子，该选项无需设置。
106+ - --experimental（可选）：表示编译用户保存在experimental目录下的算子。
107+ - -j（可选）：指定编译线程数，加快编译速度。
108+ 
109+ 若提示如下信息，说明编译成功。
110+ 
111+ ```bash
112+ Self-extractable archive "cann-${soc_name}-ops-ras_${cann_version}_linux-${arch}.run" successfully created.
113+ ```
114+
115+ \$\{soc\_name\}表示NPU型号名称，即\$\{soc\_version\}删除"ascend"后剩余的内容。编译成功后，run包存放于build_out目录下。
116+ 
117+2. **安装ops-ras包**
118+ 
119+ ```bash
120+ # 安装命令
121+ ./build_out/cann-${soc_name}-ops-ras_${cann_version}_linux-${arch}.run --full --install-path=${install_path}
122+ ```
123+ 
124+ \$\{install\_path\}：表示指定安装路径，需要与toolkit包安装在相同路径，默认安装在`/usr/local/Ascend`目录。
125+ 
126+3. **（可选）卸载ops-ras包**
127+ 
128+ ```bash
129+ # 卸载命令
130+ ./${install_path}/cann/share/info/ops_ras/script/uninstall.sh
131+ ```
132+ 
133+### ops-ras静态库
134+ 
135+> 说明：静态库仅支持Atlas A2、Atlas A3系列产品。experimental算子暂不支持使用静态库。
136+ 
137+1. **编译ops-ras静态库**
138+ 
139+ 进入项目根目录，执行如下编译命令：
140+ 
141+ ```bash
142+ bash build.sh --pkg --static --soc=${soc_version} [-j${n}]
143+ ```
144+ 
145+ - --soc：\$\{soc\_version\}表示NPU型号。Atlas A2系列产品使用"ascend910b"（默认），Atlas A3系列产品使用"ascend910_93"。
146+ - -j（可选）：指定编译线程数，加快编译速度。
147+ 若提示如下信息，说明编译并压缩成功。
148+ 
149+ ```bash
150+ [SUCCESS] Build static lib success!
151+ Successfully created compressed package: ${repo_path}/build_out/cann-${soc_name}-ops-ras-static_${cann_version}_linux-${arch}.tar.gz
152+ ```
153+ 
154+ \$\{repo\_path\}表示项目根目录，\$\{soc\_name\}表示NPU型号名称，即\$\{soc\_version\}删除"ascend"后剩余的内容。编译成功后，压缩包存放于build_out目录下。
155+ 
156+2. **解压ops-ras静态库**
157+ 
158+ 进入build_out目录执行解压命令：
159+ 
160+ ```bash
161+ tar -zxvf ./cann-${soc_name}-ops-ras-static_${cann_version}_linux-${arch}.tar.gz -C ${static_lib_path}
162+ ```
163+ 
164+ \$\{static\_lib\_path\}表示静态库解压路径。解压后目录结构如下：
165+ 
166+ ```text
167+ ├── cann-${soc_name}-ops-ras-static_${cann_version}_linux-${arch}
168+ │ ├── lib64
169+ │ │ ├── libcann_ras_static.a # 静态库文件
170+ │ └── include
171+ | ├── ... # aclnn接口头文件
172+ ```
173+ 
174+## 未联网编译
175+ 
176+若在没有连接互联网的环境下编译，需要提前准备好依赖的第三方软件，再进行源码编译。具体过程如下：
177+ 
178+1. **下载第三方依赖**
179+ 
180+ 在联网环境中提前下载第三方软件，目前有如下方式，请按需选择：
181+ 
182+ - 方式1：根据[第三方软件依赖](#安装第三方依赖)提供的表格手动下载，若从其他地址下载，请确保版本号一致。
183+ 
184+2. **编译算子包**
185+ 
186+ 将下载好的第三方软件上传至离线环境，可存放在`third_party`目录或自定义目录下。**推荐前者，其编译命令与联网编译场景下的命令一致。**
187+ 
188+ - **third\_party目录**（推荐）
189+
190+ 请在本项目根目录创建`third_party`目录（若有则无需创建），将第三方软件拷贝到该指定目录。此时编译命令与联网编译命令一致，具体参考[联网编译](#联网编译)。
191+
192+ - **自定义目录**
193+
194+ 在离线环境的任意位置新建`${cann_3rd_lib_path}`目录，将第三方软件拷贝到该目录，请确保该目录有权限访问。
195+ 
196+ ```bash
197+ mkdir -p ${cann_3rd_lib_path}
198+ ```
199+
200+ 此时编译命令需在联网编译命令基础上额外增加`--cann_3rd_lib_path=${cann_3rd_lib_path}`用于指定第三方软件所在路径。假设存放路径为`/path/cann_3rd_lib_path`，不同编译方式对应的命令如下：
201+
202+ - 自定义算子包
203+
204+ ```bash
205+ bash build.sh --pkg --soc=${soc_version} [--vendor_name=${vendor_name}] [--ops=${op_list}] --cann_3rd_lib_path=${cann_3rd_lib_path}
206+ # 以AddExample算子编译为例
207+ # bash build.sh --pkg --soc=ascend910b --ops=add_example -j16 --cann_3rd_lib_path=/path/cann_3rd_lib_path
208+ ```
209+
210+ - ops-ras整包
211+
212+ ```bash
213+ bash build.sh --pkg [--jit] --soc=${soc_version} --cann_3rd_lib_path=${cann_3rd_lib_path}
214+ # bash build.sh --pkg --soc=ascend910b --cann_3rd_lib_path=/path/cann_3rd_lib_path
215+ ```
216+
217+ - ops-ras静态库
218+
219+ ```bash
220+ bash build.sh --pkg --static --soc=${soc_version} --cann_3rd_lib_path=${cann_3rd_lib_path}
221+ # bash build.sh --pkg --static --soc=ascend910b --cann_3rd_lib_path=/path/cann_3rd_lib_path
222+ ```
223+ 
224+3. **安装/卸载算子包**
225+ 
226+ 未联网和联网场景下编译得到算子包结果一样，默认存放于项目根目录build_out目录下，并且安装和卸载的操作命令也一样，具体参见[联网编译](#联网编译)。
227+ 
228+## 本地验证
229+ 
230+源码包部署后，可通过项目根目录build.sh执行UT用例，验证项目功能是否正常。
231+ 
232+> 说明：执行UT用例依赖googletest单元测试框架，详细介绍参见[googletest官网](https://google.github.io/googletest/advanced.html#running-a-subset-of-the-tests)。
233+ 
234+```bash
235+# 安装根目录下test相关requirements.txt依赖
236+pip3 install -r tests/requirements.txt
237+# 方式1: 编译并执行指定算子和对应功能的UT测试用例（选其一）
238+bash build.sh -u --[opapi|ophost|opkernel] --ops=add_example
239+# 方式2: 编译并执行所有的UT测试用例
240+# bash build.sh -u
241+# 方式3: 编译所有的UT测试用例但不执行
242+# bash build.sh -u --noexec
243+# 方式4: 编译并执行对应功能的UT测试用例（选其一）
244+# bash build.sh -u --[opapi|ophost|opkernel]
245+# 方式5: 编译对应功能的UT测试用例但不执行（选其一）
246+# bash build.sh -u --noexec --[opapi|ophost|opkernel]
247+# 方式6: 执行UT测试用例时可指定soc编译
248+# bash build.sh -u --[opapi|ophost|opkernel] [--soc=${soc_version}]
249+```
250+ 
251+以验证ophost功能是否正常为例，执行如下命令：
252+ 
253+```bash
254+bash build.sh -u --ophost
255+```
256+ 
257+执行完成后出现如下内容，表示执行成功。
258+ 
259+```bash
260+Global Environment TearDown
261+[==========] ${n} tests from ${m} test suites ran. (${x} ms total)
262+[ PASSED ] ${n} tests.
263+[100%] Built target ras_op_host_ut
264+```
265+ 
266+\$\{n\}表示执行了n个用例，\$\{m\}表示m项测试，\$\{x\}表示执行用例消耗的时间，单位为毫秒。
Adocs/zh/install/dir_structure.md+241-0
@@ -0,0 +1,241 @@
1+# 项目目录
2+ 
3+> 本章罗列的部分目录是可选的，请以实际交付件为准。尤其**单算子目录**，不同场景下交付件有差异，具体说明如下：
4+>
5+> - 若缺少op_host目录，可能是调用了其他算子op_host实现，调用逻辑参见该算子op_api目录下源码实现；如有需要，欢迎开发者参考[贡献指南](../../../CONTRIBUTING.md)补充贡献该算子。
6+> - 若缺少op_api目录，说明该算子暂不支持aclnn调用。
7+> - 若缺少op_graph或op_kernel目录，说明该算子暂不支持图模式调用或暂无Ascend C Kernel实现。
8+ 
9+项目全量目录层级介绍如下：
10+ 
11+```text
12+├── cmake # 项目工程编译目录
13+│ ├── modules # CMake Find模块目录
14+│ │ ├── FindOPBASE.cmake # OPBASE依赖查找
15+│ │ ├── Findaicpu.cmake # aicpu依赖查找
16+│ │ ├── Finddlog.cmake # dlog依赖查找
17+│ │ ├── Findmetadef.cmake # metadef依赖查找
18+│ │ ├── Findnnopbase.cmake # nnopbase依赖查找
19+│ │ ├── Findplatform.cmake # platform依赖查找
20+│ │ ├── Findruntime.cmake # runtime依赖查找
21+│ │ ├── Findsecurec.cmake # securec依赖查找
22+│ │ └── Findtilingapi.cmake # tilingapi依赖查找
23+│ ├── third_party # 第三方依赖CMake配置目录
24+│ │ ├── build # 第三方依赖构建目录（含patch等）
25+│ │ ├── abseil-cpp.cmake # abseil-cpp依赖配置
26+│ │ ├── ascend_protobuf.cmake # protobuf依赖配置
27+│ │ ├── eigen.cmake # eigen依赖配置
28+│ │ ├── gtest.cmake # gtest依赖配置
29+│ │ ├── makeself-fetch.cmake # makeself获取配置
30+│ │ └── nlohmann_json.cmake # nlohmann_json依赖配置
31+│ ├── Third_Party_Open_Source_Software_List.yaml # 第三方开源软件清单
32+│ ├── aclnn_ops_ras.h.in # aclnn汇总头文件模板
33+│ ├── custom_kernel.cmake # 自定义Kernel编译配置
34+│ ├── dependencies.cmake # 项目依赖管理
35+│ ├── func.cmake # 公共CMake函数定义
36+│ ├── gen_ops_info.cmake # 算子信息生成脚本
37+│ ├── intf_pub_linux.cmake # Linux接口发布配置
38+│ ├── intf_pub_llt_gccnative.cmake # LLT GCC Native接口发布配置
39+│ ├── makeself_built_in.cmake # makeself内置配置
40+│ ├── makeself_custom.cmake # makeself自定义配置
41+│ ├── opbuild.cmake # 算子构建配置
42+│ ├── package.cmake # 打包配置
43+│ ├── runtimeKB.cmake # 运行时知识库配置
44+│ ├── static.cmake # 静态库编译配置
45+│ ├── symbol.cmake # 符号导出配置
46+│ ├── ut.cmake # UT测试编译配置
47+│ └── variables.cmake # 全局变量定义
48+├── common # 项目公共头文件和公共代码
49+│ ├── CMakeLists.txt
50+│ ├── act # Activation相关公共实现
51+│ │ ├── epilogue # Epilogue处理（如反量化、SwishGLU量化等）
52+│ │ ├── matmul # 矩阵乘相关实现（block、kernel、policy、tile）
53+│ │ ├── prologue # Prologue处理（如Cast、广播等）
54+│ │ └── utils # 公共工具（架构检测、坐标工具等）
55+│ ├── inc # 公共头文件目录
56+│ │ ├── common # 公共定义
57+│ │ ├── err # 错误码定义
58+│ │ ├── fallback # Fallback相关
59+│ │ ├── framework # 框架适配头文件
60+│ │ ├── kernel # Kernel相关头文件
61+│ │ ├── op_api # op_api相关头文件
62+│ │ ├── op_graph # op_graph相关头文件
63+│ │ ├── op_host # op_host相关头文件
64+│ │ ├── op_kernel # op_kernel相关头文件
65+│ │ ├── tiling_base # Tiling基础头文件
66+│ │ ├── error_util.h # 错误处理工具头文件
67+│ │ ├── legacy_common_manager.h # 旧版公共管理器头文件
68+│ │ └── op_util.h # 算子工具头文件
69+│ ├── src # 公共代码目录
70+│ │ ├── framework # 框架适配实现
71+│ │ ├── op_host # op_host公共实现
72+│ │ └── legacy_common_manager.cpp # 旧版公共管理器实现
73+│ └── stub # Stub实现目录
74+│ ├── CMakeLists.txt
75+│ ├── inc/framework # 框架Stub头文件
76+│ └── op_api # op_api Stub实现（aclnn_kernels、level0）
77+├── reliability # RAS算子分类目录（可靠性、可用性、可维护性类算子）
78+│ ├── CMakeLists.txt # reliability目录CMakeList入口
79+│ ├── ${op_name} # 算子工程目录，${op_name}表示算子名（小写下划线形式），如crypto、obfuscation_calculate、obfuscation_setup
80+│ │ ├── CMakeLists.txt # 算子CMakeList入口
81+│ │ ├── docs # 算子文档目录
82+│ │ │ ├── aclnn${OpName}.md # 算子aclnn接口介绍文档，${OpName}表示算子名（大驼峰形式）
83+│ │ │ └── aclnn${OpName}V2.md # 可选，V2版本接口文档
84+│ │ ├── op_host # Host侧实现
85+│ │ │ ├── CMakeLists.txt # Host侧CMakeList文件
86+│ │ │ ├── ${op_name}_aicpu_infershape.cpp # 可选，AI CPU场景下的InferShape实现
87+│ │ │ └── op_api # 算子aclnn实现文件目录
88+│ │ │ ├── aclnn_${op_name}.cpp # 算子aclnn接口实现文件
89+│ │ │ ├── aclnn_${op_name}.h # 算子aclnn接口实现头文件
90+│ │ │ ├── ${op_name}.cpp # 算子l0接口实现文件
91+│ │ │ └── ${op_name}.h # 算子l0接口实现头文件
92+│ │ └── tests # 算子测试用例目录
93+│ │ ├── CMakeLists.txt
94+│ │ └── ut # UT测试用例
95+│ │ ├── CMakeLists.txt # UT用例CMakeList文件
96+│ │ └── op_host # op_host测试用例目录
97+│ │ ├── CMakeLists.txt
98+│ │ ├── test_aclnn_${op_name}.cpp # 算子aclnn测试用例文件
99+│ │ └── test_${op_name}_infershape.cpp # 算子InferShape测试用例文件
100+│ └── ...
101+├── docs # 项目相关文档目录
102+│ ├── QUICKSTART.md # 快速入门指南
103+│ ├── README.md # 文档总览
104+│ ├── en # 英文文档目录
105+│ └── zh # 中文文档目录
106+│ ├── context # 基础概念与上下文文档（数据类型、数据结构、目录结构等）
107+│ ├── debug # 调试相关文档
108+│ ├── develop # 开发指南（AI Core、AI CPU、图开发）
109+│ ├── figures # 文档图片资源
110+│ ├── invocation # 算子调用说明
111+│ ├── op_api_list.md # op_api接口列表
112+│ └── op_list.md # 算子列表
113+├── examples # 端到端算子开发和调用示例
114+│ ├── add_example # AI Core算子示例目录
115+│ │ ├── CMakeLists.txt # 算子编译配置文件
116+│ │ ├── README.md # 示例介绍文档
117+│ │ ├── examples # 算子使用示例目录
118+│ │ ├── op_graph # 算子构图相关目录
119+│ │ ├── op_host # 算子信息库、Tiling、InferShape相关实现目录
120+│ │ ├── op_kernel # 算子Kernel目录
121+│ │ └── tests # 算子测试用例目录
122+│ ├── add_example_aicpu # AI CPU算子示例目录
123+│ │ ├── CMakeLists.txt # 算子编译配置文件
124+│ │ ├── README.md # 示例介绍文档
125+│ │ ├── examples # 算子使用示例目录
126+│ │ ├── op_graph # 算子构图相关目录
127+│ │ ├── op_host # 算子信息库、InferShape相关实现
128+│ │ ├── op_kernel_aicpu # 算子Kernel目录
129+│ │ └── tests # 算子测试用例目录
130+│ ├── fast_kernel_launch_example # 轻量级，高性能的算子开发工程模板
131+│ │ ├── ascend_ops # 示例算子实现目录
132+│ │ ├── cmake # 构建相关cmake脚本目录
133+│ │ ├── CMakeLists.txt # 算子编译配置文件
134+│ │ ├── csrc # C/C++扩展源码目录
135+│ │ ├── README.md # 轻量级，高性能的算子开发工程说明资料
136+│ │ ├── requirements.txt
137+│ │ ├── setup.py # 构建脚本
138+│ │ └── tests # 测试用例目录
139+│ ├── CMakeLists.txt
140+│ └── README.md # 项目示例介绍文档
141+├── experimental # 用户自定义算子存放目录
142+│ └── reliability # 用户开发的reliability类算子目录
143+│ └── CMakeLists.txt
144+├── scripts # 脚本目录，包含自定义算子、Kernel构建相关配置文件
145+│ ├── ci # CI持续集成脚本
146+│ │ ├── gen_ops_soc.py # 算子SoC信息生成脚本
147+│ │ └── ops_run_repackage.sh # 算子运行重打包脚本
148+│ ├── custom # 自定义算子安装脚本
149+│ │ ├── install.sh # 安装脚本
150+│ │ └── upgrade.sh # 升级脚本
151+│ ├── kernel # Kernel构建相关脚本
152+│ │ ├── binary_config # 二进制配置文件目录（ascendc_config.json等）
153+│ │ └── binary_script # 二进制构建脚本目录（构建、打包、信息生成等）
154+│ ├── opgen # 算子代码生成工具
155+│ │ ├── template # 算子工程模板（add_example、add_example_aicpu）
156+│ │ └── opgen_standalone.py # 独立算子生成脚本
157+│ ├── package # 打包相关脚本
158+│ │ ├── common # 打包公共模块（配置、Python/Shell工具）
159+│ │ ├── latest_manager # 最新版本管理脚本
160+│ │ ├── module # 打包模块定义
161+│ │ ├── ops_ras # ops-ras专属打包配置
162+│ │ └── package.py # 打包入口脚本
163+│ └── util # 构建工具脚本目录
164+│ ├── ascendc_bin_param_build.py # Ascend C二进制参数构建
165+│ ├── ascendc_gen_options.py # Ascend C编译选项生成
166+│ ├── ascendc_impl_build.py # Ascend C实现构建
167+│ ├── ascendc_ops_config.py # Ascend C算子配置
168+│ ├── ascendc_replay_build.py # Ascend C回放构建
169+│ ├── build_opp_kernel_static.py # OPP Kernel静态库构建
170+│ ├── code_channel_infer.py # 代码通道推导
171+│ ├── const_var.py # 常量变量定义
172+│ ├── dependency_parser.py # 依赖解析
173+│ ├── gen_version_info.sh # 版本信息生成
174+│ ├── generate_cpp_cov.sh # C++覆盖率生成
175+│ ├── get_opfile_from_opsinfo.py # 从算子信息获取文件
176+│ ├── insert_op_info.py # 插入算子信息
177+│ ├── insert_simplified_keys.py # 插入简化Key
178+│ ├── kernel_entry.py # Kernel入口处理
179+│ ├── merge_aicpu_info_json.sh # 合并AI CPU信息JSON
180+│ ├── merge_proto.py # 合并Proto文件
181+│ ├── modify_gen_aclnn_static.py # 修改aclnn静态库生成
182+│ ├── opdesc_parser.py # 算子描述解析
183+│ ├── parse_changed_files.py # 解析变更文件
184+│ ├── parse_compile_changed_files.py # 解析编译变更文件
185+│ ├── parse_ini_to_json.py # INI转JSON
186+│ ├── replay_codegen.py # 回放代码生成
187+│ └── tiling_data_def_build.py # TilingData定义构建
188+├── tests # 项目级测试目录
189+│ ├── requirements.txt # 测试用例依赖的第三方组件
190+│ └── ut # UT用例工程
191+│ ├── CMakeLists.txt # UT工程的CMakeList脚本
192+│ ├── empty.cpp # 空文件，用于CMake编译占位
193+│ ├── common # UT工程中使用的公共代码
194+│ │ ├── CMakeLists.txt
195+│ │ ├── any_value.h # 通用值类型工具
196+│ │ ├── infer_shape_context_faker.cpp/h # InferShape上下文Mock
197+│ │ ├── infer_datatype_context_faker.cpp/h # InferDataType上下文Mock
198+│ │ ├── infershape_test_util.cpp/h # InferShape测试工具
199+│ │ ├── tiling_context_faker.cpp/h # Tiling上下文Mock
200+│ │ ├── tiling_parse_context_faker.cpp/h # Tiling解析上下文Mock
201+│ │ ├── ut_op_common.cpp/h # UT公共测试用例
202+│ │ ├── ut_op_util.cpp/h # UT公共工具
203+│ │ └── ...
204+│ ├── op_api # op_api测试工程
205+│ │ ├── CMakeLists.txt
206+│ │ ├── op_api_ut_common # op_api UT公共模块
207+│ │ │ ├── inc # 公共头文件（tensor_desc、array_desc等）
208+│ │ │ └── src # 公共实现
209+│ │ ├── stub # op_api测试Stub实现
210+│ │ └── ut_main.cpp # op_api测试入口
211+│ ├── op_host # op_host测试工程
212+│ │ ├── CMakeLists.txt
213+│ │ └── test_op_host_main.cpp # op_host测试入口
214+│ ├── op_kernel # op_kernel测试工程
215+│ │ ├── CMakeLists.txt
216+│ │ ├── data_utils.cpp/h # 数据工具
217+│ │ ├── scripts # 测试脚本（tiling头文件生成等）
218+│ │ └── test_op_kernel_main.cpp # op_kernel测试入口
219+│ └── op_kernel_aicpu # op_kernel_aicpu测试工程
220+│ ├── CMakeLists.txt
221+│ ├── stub # AI CPU测试Stub实现
222+│ ├── utils # AI CPU测试工具（文件读取、测试辅助等）
223+│ └── test_op_kernel_aicpu_main.cpp # op_kernel_aicpu测试入口
224+├── third_party # 第三方依赖源码目录
225+│ ├── abseil-cpp # abseil-cpp库源码
226+│ ├── ascend_protobuf # protobuf库源码
227+│ └── pkg # 其他第三方依赖包
228+├── .clang-format # 代码格式化配置文件
229+├── CMakeLists.txt # 项目工程CMakeList入口
230+├── CONTRIBUTING.md # 项目贡献指南文件
231+├── LICENSE # 项目开源许可证信息
232+├── OAT.xml # 配置脚本，代码仓工具使用，用于检查License是否规范
233+├── README.md # 项目工程总介绍文档
234+├── SECURITY.md # 项目安全声明文件
235+├── Third_Party_Open_Source_Software_Notice # 第三方开源软件声明
236+├── build.sh # 项目工程编译脚本
237+├── classify_rule.yaml # 组件划分信息
238+├── install_deps.sh # 项目安装依赖包脚本
239+├── requirements.txt # 项目的第三方依赖包
240+└── version.info # 项目版本信息
241+```
Rdocs/zh/context/quick_install.md→docs/zh/install/quick_install.md+0-0
File renamed without changes.
Mdocs/zh/invocation/quick_op_invocation.md+16-16
@@ -1,7 +1,7 @@
1# 算子调用1# 算子调用
2## 前提条件2## 前提条件
3 3 
4-- 环境部署：调用算子之前，请先参考[环境部署](../context/quick_install.md)完成基础环境搭建。4+- 环境部署：调用算子之前，请先参考[环境部署](../install/quick_install.md)完成基础环境搭建。
5- 调用算子列表：项目可调用的算子参见[算子列表](../op_list.md)，算子对应的aclnn接口参见[aclnn列表](../op_api_list.md)。5- 调用算子列表：项目可调用的算子参见[算子列表](../op_list.md)，算子对应的aclnn接口参见[aclnn列表](../op_api_list.md)。
6 6 
7## 编译执行7## 编译执行
@@ -22,18 +22,18 @@
22 22 
23 进入项目根目录，执行如下编译命令：23 进入项目根目录，执行如下编译命令：
24 24 
25- > **说明**：编译过程依赖第三方开源软件，联网场景会自动下载，离线编译场景需要自行安装，具体参考[离线编译](../context/build_offline.md)。25+ > **说明**：编译过程依赖第三方开源软件，联网场景会自动下载，离线编译场景需要自行安装，具体参考[离线编译](../install/compile.md#未联网编译)。
26 26
27 ```bash27 ```bash
28 bash build.sh --pkg --soc=${soc_version} [--vendor_name=${vendor_name}] [--ops=${op_list}]28 bash build.sh --pkg --soc=${soc_version} [--vendor_name=${vendor_name}] [--ops=${op_list}]
29- # 以TransposeBatchMatMul算子编译为例29+ # 以AddExample算子编译为例
30- # bash build.sh --pkg --soc=ascend910b --vendor_name=transpose_batch_mat_mul --ops=transpose_batch_mat_mul30+ # bash build.sh --pkg --soc=ascend910b --vendor_name=add_example --ops=add_example
31 # 编译experimental贡献目录下的用户算子31 # 编译experimental贡献目录下的用户算子
32 # bash build.sh --pkg --experimental --soc=ascend910b --ops=${experimental_op}32 # bash build.sh --pkg --experimental --soc=ascend910b --ops=${experimental_op}
33 ```33 ```
34 - --soc：\$\{soc\_version\}表示NPU型号。Atlas A2系列产品使用"ascend910b"（默认），Atlas A3系列产品使用"ascend910_93"，Ascend 950PR/Ascend 950DT产品使用"ascend950"。34 - --soc：\$\{soc\_version\}表示NPU型号。Atlas A2系列产品使用"ascend910b"（默认），Atlas A3系列产品使用"ascend910_93"，Ascend 950PR/Ascend 950DT产品使用"ascend950"。
35 - --vendor_name（可选）：\$\{vendor\_name\}表示构建的自定义算子包名，默认名为custom。35 - --vendor_name（可选）：\$\{vendor\_name\}表示构建的自定义算子包名，默认名为custom。
36- - --ops（可选）：\$\{op\_list\}表示待编译算子，不指定时默认编译所有算子。格式形如"transpose_batch_mat_mul,gemm,..."，多算子之间用英文逗号","分隔。36+ - --ops（可选）：\$\{op\_list\}表示待编译算子，不指定时默认编译所有算子。格式形如"add_example,..."，多算子之间用英文逗号","分隔。
37 - --experimental（可选）：表示编译experimental贡献目录下的算子，${experimental_op}为新贡献算子目录名，贡献说明参见[贡献指南](../../../CONTRIBUTING.md)。37 - --experimental（可选）：表示编译experimental贡献目录下的算子，${experimental_op}为新贡献算子目录名，贡献说明参见[贡献指南](../../../CONTRIBUTING.md)。
38 38
39 若\$\{vendor\_name\}和\$\{op\_list\}都不传入编译的是ops-ras包；若编译所有算子的自定义算子包，需传入\$\{vendor\_name\}。当提示如下信息，说明编译成功。39 若\$\{vendor\_name\}和\$\{op\_list\}都不传入编译的是ops-ras包；若编译所有算子的自定义算子包，需传入\$\{vendor\_name\}。当提示如下信息，说明编译成功。
@@ -63,7 +63,7 @@
63 63 
64 进入项目根目录，执行如下编译命令：64 进入项目根目录，执行如下编译命令：
65 65 
66- > **说明**：编译过程依赖第三方开源软件，联网场景会自动下载，离线编译场景需要自行安装，具体参考[离线编译](../context/build_offline.md)。66+ > **说明**：编译过程依赖第三方开源软件，联网场景会自动下载，离线编译场景需要自行安装，具体参考[离线编译](../install/compile.md#未联网编译)。
67 67 
68 ```bash68 ```bash
69 # 编译除experimental贡献目录外的所有算子69 # 编译除experimental贡献目录外的所有算子
@@ -155,7 +155,7 @@
155 155 
156## 本地验证 156## 本地验证
157 157 
158-通过项目根目录build.sh执行算子和UT用例，验证项目功能是否正常，build参数参见[build参数说明](../context/build.md)。目前算子支持API方式（aclnn接口）和图模式调用，**推荐aclnn调用**。158+通过项目根目录build.sh执行算子和UT用例，验证项目功能是否正常，build参数参见[build参数说明](../install/build.md)。目前算子支持API方式（aclnn接口）和图模式调用，**推荐aclnn调用**。
159 159 
160- **执行算子样例**160- **执行算子样例**
161 161
@@ -164,11 +164,11 @@
164 - 完成自定义算子包安装后，执行如下命令：164 - 完成自定义算子包安装后，执行如下命令：
165 ```bash165 ```bash
166 bash build.sh --run_example ${op} ${mode} ${pkg_mode} [--example_name=${example_name}] [--vendor_name=${vendor_name}] [--soc=${soc_version}]166 bash build.sh --run_example ${op} ${mode} ${pkg_mode} [--example_name=${example_name}] [--vendor_name=${vendor_name}] [--soc=${soc_version}]
167- # 以TransposeBatchMatMul算子执行test_aclnn_transpose_batch_mat_mul.cpp为例167+ # 以AddExample算子执行test_aclnn_add_example.cpp为例
168- # bash build.sh --run_example transpose_batch_mat_mul eager cust --example_name=transpose_batch_mat_mul --vendor_name=transpose_batch_mat_mul168+ # bash build.sh --run_example add_example eager cust --example_name=add_example --vendor_name=add_example
169 ```169 ```
170 170 
171- - \$\{op\}：表示待执行算子，算子名为小写下划线形式，如transpose_batch_mat_mul。171+ - \$\{op\}：表示待执行算子，算子名为小写下划线形式，如add_example。
172 - \$\{mode\}：表示执行模式，目前支持eager（aclnn调用）、graph（图模式调用）。172 - \$\{mode\}：表示执行模式，目前支持eager（aclnn调用）、graph（图模式调用）。
173 - \$\{pkg_mode\}：表示包模式，目前仅支持cust，即自定义算子包。173 - \$\{pkg_mode\}：表示包模式，目前仅支持cust，即自定义算子包。
174 - \$\{example_name\}（可选）：表示待执行样例名，名称为各个算子examples文件夹下的文件名称，去掉`test_aclnn_`前缀和`.cpp`后缀。174 - \$\{example_name\}（可选）：表示待执行样例名，名称为各个算子examples文件夹下的文件名称，去掉`test_aclnn_`前缀和`.cpp`后缀。
@@ -180,15 +180,15 @@
180 - 完成ops-ras包安装后，执行命令如下：180 - 完成ops-ras包安装后，执行命令如下：
181 ```bash181 ```bash
182 bash build.sh --run_example ${op} ${mode} [--soc=${soc_version}]182 bash build.sh --run_example ${op} ${mode} [--soc=${soc_version}]
183- # 以TransposeBatchMatMul算子example执行为例183+ # 以AddExample算子example执行为例
184- # bash build.sh --run_example transpose_batch_mat_mul eager184+ # bash build.sh --run_example add_example eager
185 ```185 ```
186 186
187- - \$\{op\}：表示待执行算子，算子名为小写下划线形式，如transpose_batch_mat_mul。187+ - \$\{op\}：表示待执行算子，算子名为小写下划线形式，如add_example。
188 - \$\{mode\}：表示算子执行模式，目前支持eager（aclnn调用）、graph（图模式调用）。188 - \$\{mode\}：表示算子执行模式，目前支持eager（aclnn调用）、graph（图模式调用）。
189 - \$\{soc_version\}（可选）：表示NPU型号。当设置为"ascend950"时会额外运行"arch35"目录下的示例文件。189 - \$\{soc_version\}（可选）：表示NPU型号。当设置为"ascend950"时会额外运行"arch35"目录下的示例文件。
190 190
191- 执行算子样例后会打印结果，以TransposeBatchMatMul算子执行为例：191+ 执行算子样例后会打印结果，以AddExample算子执行为例：
192 192 
193 ```193 ```
194 result[0] is: 0.000000194 result[0] is: 0.000000
@@ -205,7 +205,7 @@
205 # 安装根目录下test相关requirements.txt依赖205 # 安装根目录下test相关requirements.txt依赖
206 pip3 install -r tests/requirements.txt206 pip3 install -r tests/requirements.txt
207 # 方式1: 编译并执行指定算子和对应功能的UT测试用例（选其一）207 # 方式1: 编译并执行指定算子和对应功能的UT测试用例（选其一）
208- bash build.sh -u --[opapi|ophost|opkernel] --ops=transpose_batch_mat_mul208+ bash build.sh -u --[opapi|ophost|opkernel] --ops=add_example
209 # 方式2: 编译并执行所有的UT测试用例209 # 方式2: 编译并执行所有的UT测试用例
210 # bash build.sh -u210 # bash build.sh -u
211 # 方式3: 编译所有的UT测试用例但不执行211 # 方式3: 编译所有的UT测试用例但不执行
@@ -228,6 +228,6 @@
228 Global Environment TearDown228 Global Environment TearDown
229 [==========] ${n} tests from ${m} test suites ran. (${x} ms total)229 [==========] ${n} tests from ${m} test suites ran. (${x} ms total)
230 [ PASSED ] ${n} tests.230 [ PASSED ] ${n} tests.
231- [100%] Built target nn_op_host_ut231+ [100%] Built target ras_op_host_ut
232 ```232 ```
233 \$\{n\}表示执行了n个用例，\$\{m\}表示m项测试，\$\{x\}表示执行用例消耗的时间，单位为毫秒。233 \$\{n\}表示执行了n个用例，\$\{m\}表示m项测试，\$\{x\}表示执行用例消耗的时间，单位为毫秒。
Mdocs/zh/op_api_list.md+8-3
@@ -7,9 +7,13 @@
7调用算子API时，需引用依赖的头文件和库文件，一般头文件默认在`${INSTALL_DIR}/include/aclnnop`，库文件默认在`${INSTALL_DIR}/lib64`，具体文件如下：7调用算子API时，需引用依赖的头文件和库文件，一般头文件默认在`${INSTALL_DIR}/include/aclnnop`，库文件默认在`${INSTALL_DIR}/lib64`，具体文件如下：
8 8 
9- 依赖的头文件：①方式1 （推荐）：引用算子总头文件aclnn\_ops\_\$\{ops\_project\}.h。②方式2：按需引用单算子API头文件aclnn\_\*.h。9- 依赖的头文件：①方式1 （推荐）：引用算子总头文件aclnn\_ops\_\$\{ops\_project\}.h。②方式2：按需引用单算子API头文件aclnn\_\*.h。
10-- 依赖的库文件：按需引用算子总库文件libopapi\_\$\{ops\_project\}.so。10+- 依赖的库文件：按需引用算子总库文件libopapi\_\$\{ops\_project\}.so。注意，原所有算子仓总库文件libopapi.so后续会废弃，不推荐使用，也不支持与单个算子仓库文件同时使用。
11 11 
12-其中${INSTALL_DIR}表示CANN安装后文件路径；\$\{ops\_project\}表示算子仓（如math、nn、cv、transformer），请配置为实际算子仓名。12+其中${INSTALL_DIR}表示CANN安装后文件路径；\$\{ops\_project\}表示算子仓名（如ras、nn、math等），请配置为实际算子仓名。
13+ 
14+- **V版本演进说明**
15+ 
16+ 请注意，部分API存在多个V版本，使用时选择最高V版本即可（高版本API已兼容低版本API的所有能力）。
13 17 
14## 接口列表18## 接口列表
15 19 
@@ -19,10 +23,11 @@
19> - 性能说明：同一个算子采用确定性计算通常比非确定性慢，因此模型单次运行性能可能会下降。但在实验、调试调测等需要保证多次运行结果相同来定位问题的场景，确定性计算可以提升效率。23> - 性能说明：同一个算子采用确定性计算通常比非确定性慢，因此模型单次运行性能可能会下降。但在实验、调试调测等需要保证多次运行结果相同来定位问题的场景，确定性计算可以提升效率。
20> - 线程说明：同一线程中只能设置一次确定性状态，多次设置以最后一次有效设置为准。有效设置是指设置确定性状态后，真正执行了一次算子任务下发。如果仅设置，没有算子下发，只能是确定性变量开启但未下发给算子，因此不执行算子。24> - 线程说明：同一线程中只能设置一次确定性状态，多次设置以最后一次有效设置为准。有效设置是指设置确定性状态后，真正执行了一次算子任务下发。如果仅设置，没有算子下发，只能是确定性变量开启但未下发给算子，因此不执行算子。
21> 解决方案：暂不推荐一个线程多次设置确定性。该问题在二进制开启和关闭情况下均存在，在后续版本中会解决该问题。25> 解决方案：暂不推荐一个线程多次设置确定性。该问题在二进制开启和关闭情况下均存在，在后续版本中会解决该问题。
26+> - 符号说明：表中“- ”符号表示该接口暂不支持当前列产品。
22 27 
23算子接口列表如下：28算子接口列表如下：
24 29 
25-| 接口名 | 说明 | 确定性说明（A2/A3） | 确定性说明（A5） |30+| 接口名 | 说明 | 确定性说明（A2/A3） | 确定性说明（Ascend 950） |
26|-----------|------------|------------|------------|31|-----------|------------|------------|------------|
27| [aclnnObfuscationCalculate](../../reliability/obfuscation_calculate/docs/aclnnObfuscationCalculate.md) | 将张量x和配置参数（如param、cmd）发送至PMCC混淆引擎。引擎的CA模块调用TA模块，进行张量混淆处理，最终返回shape与x一致的混淆后的张量y。 |默认确定性实现|32| [aclnnObfuscationCalculate](../../reliability/obfuscation_calculate/docs/aclnnObfuscationCalculate.md) | 将张量x和配置参数（如param、cmd）发送至PMCC混淆引擎。引擎的CA模块调用TA模块，进行张量混淆处理，最终返回shape与x一致的混淆后的张量y。 |默认确定性实现|
28| [aclnnObfuscationCalculateV2](../../reliability/obfuscation_calculate/docs/aclnnObfuscationCalculateV2.md) | 将张量x和配置参数（如param、cmd）发送至PMCC混淆引擎。引擎的CA模块调用TA模块，进行张量混淆处理，最终返回shape与x一致的混淆后的张量y。 |默认确定性实现|33| [aclnnObfuscationCalculateV2](../../reliability/obfuscation_calculate/docs/aclnnObfuscationCalculateV2.md) | 将张量x和配置参数（如param、cmd）发送至PMCC混淆引擎。引擎的CA模块调用TA模块，进行张量混淆处理，最终返回shape与x一致的混淆后的张量y。 |默认确定性实现|
Mdocs/zh/op_list.md+1-1
@@ -1,7 +1,7 @@
1# 算子列表1# 算子列表
2 2 
3> 说明：3> 说明：
4-> - **算子目录**：目录名为算子名小写下划线形式，每个目录承载该算子所有交付件，包括代码实现、examples、文档等，目录介绍参见[项目目录](./context/dir_structure.md)。4+> - **算子目录**：目录名为算子名小写下划线形式，每个目录承载该算子所有交付件，包括代码实现、examples、文档等，目录介绍参见[项目目录](./install/dir_structure.md)。
5> - **算子执行硬件单元**：大部分算子运行在AI Core，少部分算子运行在AI CPU。默认情况下，项目中提到的算子一般指AI Core算子。关于AI Core和AI CPU详细介绍参见[《Ascend C算子开发》](https://hiascend.com/document/redirect/CannCommunityOpdevAscendC)中“概念原理和术语 > 硬件架构与数据处理原理”。5> - **算子执行硬件单元**：大部分算子运行在AI Core，少部分算子运行在AI CPU。默认情况下，项目中提到的算子一般指AI Core算子。关于AI Core和AI CPU详细介绍参见[《Ascend C算子开发》](https://hiascend.com/document/redirect/CannCommunityOpdevAscendC)中“概念原理和术语 > 硬件架构与数据处理原理”。
6> - **算子接口列表**：为方便调用算子，CANN提供一套C API执行算子，一般以aclnn为前缀，全量接口参见[aclnn列表](op_api_list.md)。6> - **算子接口列表**：为方便调用算子，CANN提供一套C API执行算子，一般以aclnn为前缀，全量接口参见[aclnn列表](op_api_list.md)。
7 7 
Mexamples/fast_kernel_launch_example/README.md+1-1
@@ -2,7 +2,7 @@
2 2 
3## 环境部署 | Prerequisites3## 环境部署 | Prerequisites
4 4 
5-- 请先参考[环境部署](../../docs/zh/context/quick_install.md)完成基础环境搭建5+- 请先参考[环境部署](../../docs/zh/install/quick_install.md)完成基础环境搭建
6- GCC 9.4.0+6- GCC 9.4.0+
7- Python 3.8+7- Python 3.8+
8- PyTorch>=2.6.08- PyTorch>=2.6.0