补充一级目录下md文档和docs目录下md文档英文-ops-nn-AtomGit

ACHANGELOG_en.md+72-0

@@ -0,0 +1,72 @@

1 +# CHANGELOG

2 +

3 +> This document records important changes in each version. Versions are arranged in reverse chronological order.

4 +

5 +## v8.5.0-beta.1

6 +

7 +Release Date: 2025-12-30

8 +

9 +The first Beta version of ops-nn operator v8.5.0-beta.1 has been released.

10 +This version introduces multiple new features, problem fixes, and performance improvements, and is currently in the testing stage.

11 +We sincerely welcome community feedback to further improve the stability and functional completeness of ops-nn.

12 +For usage, please refer to the [Official Documentation](https://gitcode.com/cann/ops-nn/blob/master/README.md).

13 +

14 +### 🔗 Version Address

15 +

16 +[CANN 8.5.0-beta 1](https://ascend.devcloud.huaweicloud.com/cann/run/software/8.5.0-beta.1/)

17 +

18 +```text

19 +The version directory description is as follows:

20 +├── aarch64 # CPU is ARM type

21 +│ ├── ops # ops operator package directory, used to archive operator sub-packages

22 +│ ├── ...

23 +├── x86_64 # CPU is X86 type

24 +│ ├── ops # ops operator package directory, used to archive operator sub-packages

25 +│ ├── ...

26 +```

27 +

28 +### 📌 Version Compatibility

29 +

30 +**CANN Independent Upgrade Sub-package Version Compatibility Relationship**

31 +

32 +| CANN Sub-package Version | Version Source Code Tag | Compatible CANN Version|

33 +|--|--|--|

34 +| [cann-ops-math 8.5.0-beta.1](https://ascend.devcloud.huaweicloud.com/cann/run/software/8.5.0-beta.1/) | [v8.5.0-beta.1](https://gitcode.com/cann/ops-math/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

35 +| [cann-ops-nn 8.5.0-beta.1](https://ascend.devcloud.huaweicloud.com/cann/run/software/8.5.0-beta.1/) | [v8.5.0-beta.1](https://gitcode.com/cann/ops-nn/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

36 +| [cann-ops-cv 8.5.0-beta.1](https://ascend.devcloud.huaweicloud.com/cann/run/software/8.5.0-beta.1/) | [v8.5.0-beta.1](https://gitcode.com/cann/ops-cv/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

37 +| [cann-ops-transformer 8.5.0-beta.1](https://ascend.devcloud.huaweicloud.com/cann/run/software/8.5.0-beta.1/) | [v8.5.0-beta.1](https://gitcode.com/cann/ops-transformer/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

38 +| [cann-hccl 8.5.0-beta.1](https://ascend.devcloud.huaweicloud.com/cann/run/software/8.5.0-beta.1/) | [v8.5.0-beta.1](https://gitcode.com/cann/hccl/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

39 +| [cann-hixl 8.5.0-beta.1](https://ascend.devcloud.huaweicloud.com/cann/run/software/8.5.0-beta.1/) | [v8.5.0-beta.1](https://gitcode.com/cann/hixl/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

40 +

41 +**CANN Open Source Sub-package Version Compatibility Relationship**

42 +

43 +| CANN Sub-package Version | Version Source Code Tag | Compatible CANN Version |

44 +| ------------------------------------ | ------------------------------------------------------------ | ------------------- |

atomgit-bot7月23日

🟡 Medium Priority

变更行: CHANGELOG_en.md 第 41–44 行，新增的 "CANN Open Source Sub-package Version Compatibility Relationship" 表格。

影响行为: 表格的表头行（第 42 行）与分隔符行（第 44 行）之间存在一个空行（第 43 行）。在标准 Markdown（含 GitHub/GitCode Flavored Markdown）中，表头与分隔符之间不允许有空行，否则表头会被解析为普通段落，分隔符行变为 <hr>，数据行变成无表头的独立表格，导致整个表格无法正常渲染。

失效模式: 用户在 GitCode 等平台上查看 CHANGELOG_en.md 时，该表格将显示为断裂的文本块，无法正确识别列结构，影响版本兼容性信息的可读性。

建议：删除第 43 行空行，使第 42 行表头与第 44 行分隔符紧密相连。修改后如下：

CANN Open Source Sub-package Version Compatibility Relationship

CANN Sub-package Version	Version Source Code Tag	Compatible CANN Version

改动建议

44	+ CANN Open Source Sub-package Version Compatibility Relationship
45	+ \| CANN Sub-package Version \| Version Source Code Tag \| Compatible CANN Version \|
44 46	\| ------------------------------------ \| ------------------------------------------------------------ \| ------------------- \|

应用建议

Y

yanglu-1

7月23日评论：

45 +| cann-opbase 8.5.0-beta.1 | [v8.5.0-beta.1](https://gitcode.com/cann/opbase/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

46 +| cann-oam-tools 8.5.0-beta.1 | [v8.5.0-beta.1](https://gitcode.com/cann/oam-tools/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

47 +| cann-asc-tools 8.5.0-beta.1 | [v8.5.0-beta.1](https://gitcode.com/cann/asc-tools/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

48 +| cann-asc-devkit 8.5.0-beta.1 | [v8.5.0-beta.1](https://gitcode.com/cann/asc-devkit/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

49 +| cann-pto-isa 8.5.0-beta.1 | [v8.5.0-beta.1](https://gitcode.com/cann/pto-isa/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

50 +| cann-ge-compiler 8.5.0-beta.1 | [v8.5.0-beta.1](https://gitcode.com/cann/ge/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

51 +| cann-ge-executor 8.5.0-beta.1 | [v8.5.0-beta.1](https://gitcode.com/cann/ge/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

52 +| cann-graph-autofusion 8.5.0-beta.1 | [v8.5.0-beta.1](https://gitcode.com/cann/graph-autofusion/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

53 +| cann-metadef 8.5.0-beta.1 | [v8.5.0-beta.1](https://gitcode.com/cann/metadef/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

54 +| cann-dflow-executor 8.5.0-beta.1 | [v8.5.0-beta.1](https://gitcode.com/cann/ge/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

55 +| cann-hcomm 8.5.0-beta.1 | [v8.5.0-beta.1](https://gitcode.com/cann/hcomm/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

56 +| cann-npu-runtime 8.5.0-beta.1 | [v8.5.0-beta.1](https://gitcode.com/cann/runtime/tags/v8.5.0-beta.1) | CANN 8.5.0-beta.1 |

57 +

58 +### 🚀 Key Features

59 +

60 +- [Engineering Capability] nn class onnx operator plugin support. ([#452](https://gitcode.com/cann/ops-nn/pull/452))

61 +- [Engineering Capability] Added compilation options oom, asan, mssanitizer, build-type, and other engineering-level stability and debuggability capabilities. ([#391](https://gitcode.com/cann/ops-nn/pull/391))

62 +- [Operator Implementation] Some operators added support for KirinX90. ([#609](https://gitcode.com/cann/ops-nn/pull/609), [#610](https://gitcode.com/cann/ops-nn/pull/610), [#612](https://gitcode.com/cann/ops-nn/pull/612))

63 +- [Operator Implementation] Newly supported [sparse 4:2 quantization matmul operator](matmul/sparse4to2quant_matmul), enabling hardware acceleration capabilities for sparse matrices. ([#429](https://gitcode.com/cann/ops-nn/pull/429))

64 +- [Documentation Optimization] Added QUICK_START, offline compilation mode, aicore/aicpu/graph mode development guide improvement. ([#702](https://gitcode.com/cann/ops-nn/pull/702), [#562](https://gitcode.com/cann/ops-nn/pull/562))

65 +- [Documentation Optimization] Optimized the new operator contribution process in the contribution guide. ([#294](https://gitcode.com/cann/ops-nn/pull/294))

66 +- [Performance Optimization] Added asc_opc operator parallel compilation capability, optimized compilation efficiency; added ccache, optimized compilation duration. ([#692](https://gitcode.com/cann/ops-nn/pull/692))

67 +

68 +### 🐛 Problem Fixes

69 +

70 +- Fixed conv class operator compilation warning issues. ([Issue33](https://gitcode.com/cann/ops-nn/issues/33))

71 +- Used constexpr to modify if to enable compilation optimization. ([Issue98](https://gitcode.com/cann/ops-nn/issues/98))

72 +- add_example sample operator execution invocation problem fix. ([Issue245](https://gitcode.com/cann/ops-nn/issues/245))

ACONTRIBUTING_en.md+137-0

@@ -0,0 +1,137 @@
	1	+# Contribution Guide
	2	+
	3	+This project welcomes developers to experience and participate in contributions. Before participating in community contributions, please see [cann-community](https://gitcode.com/cann/community) to understand the code of conduct, sign the CLA agreement, and understand the contribution process of the source code repository.
	4	+
	5	+Developers need to pay attention to the following points when preparing local code and submitting PRs:
	6	+
	7	+1. When submitting a PR, please carefully fill in the business background, purpose, solution, and other information of this PR according to the PR template.
	8	+2. If your modification is not a simple bug fix, but involves adding new features, new interfaces, new configuration parameters, or modifying code flow, please be sure to discuss the solution through an Issue first to avoid your code being rejected. If you are not sure whether this modification can be classified as a "simple bug fix", you can also discuss the solution by submitting an Issue.
	9	+
	10	+Developer contribution scenarios mainly include:
	11	+
	12	+## I. Contribute New Operators
	13	+
	14	+The operator development contribution process is as follows:
	15	+
	16	+<!--[Operator Development Contribution Process](./docs/en/figures/operator_development_contribution_process.png "Operator Development Contribution Process Diagram")-->
	17	+
	18	+If you have a brand new operator that you want to design and implement based on NPU, we welcome you to propose your ideas and design solutions in an Issue. The complete contribution process is as follows:
	19	+
	20	+### 1. Create Issue Requirement
	21	+
	22	+Create a new `Requirement\|Feature Request` type Issue and clarify the design solution of the new operator. The Issue generally needs to include the following content:
	23	+
	24	+- Background Information
	25	+- Value/Function
	26	+- Design Solution
	27	+
	28	+Please comment `/assign @yourself` in the submitted Issue to claim this task.
	29	+
	30	+### 2. Requirement Review
	31	+
	32	+The Sig group will assign a Committer to review the Issue you submitted and provide feedback on modification opinions. After completing the modification, please @ the corresponding Committer in the Issue.
	33	+
	34	+If the requirement is accepted, [sig members](https://gitcode.com/cann/community/blob/master/CANN/sigs/ops-nn/sig-info.yaml) will assign you a suitable operator classification path (such as `experimental/activation`). Please submit the contributed operator to the corresponding operator classification directory under `experimental`.
	35	+
	36	+### 3. PR Submission
	37	+
	38	+The minimum deliverables for ecosystem operators are as follows:
	39	+
	40	+```text
	41	+${op_class} # operator classification
	42	+├── ${op_name} # operator name
	43	+│ ├── ${op_name}.cpp # operator Kernel implementation file
	44	+│ └── tests
	45	+│ │ ├── test_${op_name}.py # operator test file
	46	+│ ├── CMakeLists.txt # operator compilation configuration file
	47	+│ ├── README.md # operator README document
	48	+```
	49	+
	50	+PR submission requirements:
	51	+
	52	+- Code Deliverables: Need to provide operator Kernel implementation and operator test files. For the development process, refer to [fast_kernel_launch_example](examples/fast_kernel_launch_example/README.md).
	53	+- Document Deliverables: Operator README document is required. Other documents can be provided as needed. For document writing templates and standards, refer to [Document Contribution Guide](docs/CONTRIBUTING_DOCS_en.md).
	54	+- Compliance Check:
	55	+ - Whether the code conforms to "[C++ Coding Standards](https://gitcode.com/cann/community/blob/master/contributor/coding-standards/C++%20Coding%20standards.md)"
	56	+ - Whether the code compiles successfully
	57	+ - Whether Markdown document syntax conforms to standards
	58	+- Contribution Directory: Submit to the specified directory `experimental/${op_class}` according to sig member opinions. You can refer to the existing operator file placement rules.
	59	+- PR Submission: Submit the target branch PR through the `git` command. Check whether the PR title is clear, whether the PR description is standardized (specify the change content and reason, whether it is associated with the corresponding Issue), and whether the CLA is signed.
	60	+
	61	+If you want to contribute project standard operators, their deliverables and development process are more complex than ecosystem operators, including Kernel, Tiling implementation, and so on. For specific contribution guidance, refer to [Appendix](#appendix).
	62	+
	63	+### 4. CI Gate
	64	+
	65	+Trigger the open-source repository gate by commenting the `compile` instruction, and make modifications according to the CI detection results. Currently, the CI gate includes the following check items:
	66	+
	67	+- Code compilation
	68	+- Static check (if codecheck false positives are involved, please submit them to sig members for shielding)
	69	+- UT test
	70	+- Smoke test
	71	+
	72	+After the gate passes, please @ the assigned Committer in the associated Issue.
	73	+
	74	+### 5. Committer Review
	75	+
	76	+After the Committer reviews, feedback will be provided on review opinions. Please modify according to the opinions, and then @ the assigned Committer after completion.
	77	+
	78	+### 6. Maintainer Merge
	79	+
	80	+After the Committer review passes, mark the `/lgtm` label. The Maintainer will conduct a final review within 1 day. After confirming that there are no problems, the `/approve` label will be marked to merge the PR.
	81	+
	82	+## II. Operator Bug Fix
	83	+
	84	+If you discover certain operator bugs in this project and want to fix them, we welcome you to create a new Issue for feedback and tracking.
	85	+
	86	+You can create a new `Bug-Report\|Bug Report` type Issue according to the [Submit Issue/Handle Issue Task](https://gitcode.com/cann/community#提交Issue处理Issue任务) guide to describe the bug, and then enter "/assign" or "/assign @yourself" in the comment box to assign this Issue to you for processing.
	87	+
	88	+## III. Operator Optimization
	89	+
	90	+If you have generalization enhancement/performance optimization ideas for certain operator implementations in this project and want to implement these optimization points, we welcome you to contribute operator optimizations.
	91	+
	92	+You can create a new `Requirement\|Feature Request` type Issue according to the [Submit Issue/Handle Issue Task](https://gitcode.com/cann/community#提交Issue处理Issue任务) guide to explain the optimization points and provide your design solution, and then enter "/assign" or "/assign @yourself" in the comment box to assign this Issue to you for tracking optimization.
	93	+
	94	+## IV. Document Correction
	95	+
	96	+If you discover certain operator document description errors in this project, we welcome you to create a new Issue for feedback and correction. For document standards, refer to [Document Contribution Guide](docs/CONTRIBUTING_DOCS_en.md).
	97	+
	98	+You can create a new `Documentation\|Documentation Feedback` type Issue according to the [Submit Issue/Handle Issue Task](https://gitcode.com/cann/community#提交Issue处理Issue任务) guide to point out the problems in the corresponding document, and then enter "/assign" or "/assign @yourself" in the comment box to assign this Issue to you to correct the corresponding document description.
	99	+
	100	+## V. Help Solve Others' Issues
	101	+
	102	+If you have suitable solutions for problems encountered by others in the community, we welcome you to comment and communicate in the Issue to help others solve problems and pain points, and jointly optimize usability.
	103	+
	104	+If the corresponding Issue requires code modification, you can enter "/assign" or "/assign @yourself" in the Issue comment box to assign this Issue to you for tracking and assisting in solving the problem.
	105	+
	106	+## Appendix
	107	+
	108	+The project standard operator deliverables are as follows:
	109	+
	110	+```text
	111	+${op_class} # operator classification
	112	+├── ${op_name} # operator name
	113	+│ ├── op_host # operator definition, Tiling related implementation
	114	+│ │ ├── ${op_name}_def.cpp # operator definition file
	115	+│ │ ├── ${op_name}_tiling.cpp # operator Tiling implementation file
	116	+│ │ └── CMakeLists.txt
	117	+│ ├── op_kernel # operator Kernel directory
	118	+│ │ ├── ${op_name}.cpp # Kernel entry file, containing main function and scheduling logic
	119	+│ │ ├── ${op_name}.h # Kernel implementation file, defining Kernel header file, containing function description, structure definition, logic implementation
	120	+│ │ ├── ${op_name}_tiling_data.h # TilingData file, storing Tiling strategy related configuration information
	121	+│ │ └── ${op_name}_tiling_key.h # TilingKey file, defining the key of Tiling strategy, identifying different division methods
	122	+│ ├── CMakeLists.txt # operator compilation configuration file, keep the original file
	123	+│ └── README.md # operator description document
	124	+│ └── tests # operator test file
	125	+│ │ ├── ut # operator UT test file
	126	+```
	127	+
	128	+PR submission requirements:
	129	+
	130	+- Code Deliverables: Need to provide op_host operator Tiling implementation, op_kernel operator Kernel implementation, operator UT test files. For the development process, please refer to [Operator Development Guide](docs/en/develop/aicore_develop_guide.md).
	131	+- Document Deliverables: Operator README document is required. Other documents can be provided as needed. For document writing templates and standards, please see [Document Contribution Guide](docs/CONTRIBUTING_DOCS_en.md).
	132	+- Compliance Check:
	133	+ - Whether the code conforms to "[C++ Coding Standards](https://gitcode.com/cann/community/blob/master/contributor/coding-standards/C++%20Coding%20standards.md)", whether it conforms to standard operator basic programming standards
	134	+ - Whether the code compiles successfully
	135	+ - Whether Markdown document syntax conforms to standards
	136	+- Contribution Directory: Submit to the specified directory `experimental/${op_class}` according to sig member opinions. You can refer to the existing operator file placement rules.
	137	+- PR Submission: Submit the target branch PR through the `git` command. Check whether the PR title is clear, whether the PR description is standardized (specify the change content and reason, whether it is associated with the corresponding Issue), and whether the CLA is signed.

MQUICKSTART.md+19-19

	@@ -36,23 +36,23 @@
36	2. 根据页面提示创建并启动云开发环境，单击“`连接 > WebIDE`”进入算子一站式开发平台，开源项目的资源默认在`/mnt/workspace`目录下。	36	2. 根据页面提示创建并启动云开发环境，单击“`连接 > WebIDE`”进入算子一站式开发平台，开源项目的资源默认在`/mnt/workspace`目录下。
37		37
38	<img src="docs/zh/figures/webIDE.png" alt="云平台" width="1000px" height="150px">	38	<img src="docs/zh/figures/webIDE.png" alt="云平台" width="1000px" height="150px">
39	-	39	+
40	3. 检查环境是否完备。	40	3. 检查环境是否完备。
41		41
42	在云平台终端窗口，执行如下命令验证环境和驱动是否正常。	42	在云平台终端窗口，执行如下命令验证环境和驱动是否正常。
43		43
44	- 检查NPU设备	44	- 检查NPU设备
45		45
46	- 执行如下命令，若返回驱动相关信息说明已成功挂载。	46	+ 执行如下命令，若返回驱动相关信息说明已成功挂载。
47	-	47	+
48	- ```bash	48	+ ```bash
49	npu-smi info	49	npu-smi info
50	```	50	```
51		51
52	- 检查CANN版本	52	- 检查CANN版本
53		53
54	执行如下命令查看CANN Toolkit版本信息。	54	执行如下命令查看CANN Toolkit版本信息。
55	-	55	+
56	```bash	56	```bash
57	cat /home/developer/Ascend/ascend-toolkit/latest/opp/version.info	57	cat /home/developer/Ascend/ascend-toolkit/latest/opp/version.info
58	```	58	```
	@@ -64,7 +64,7 @@
64	* Docker环境：以Atlas A2产品（910B）为例，环境里宿主机已安装Docker引擎（版本1.11.2及以上）。	64	* Docker环境：以Atlas A2产品（910B）为例，环境里宿主机已安装Docker引擎（版本1.11.2及以上）。
65		65
66	* 驱动与固件：宿主机已安装昇腾NPU的[驱动与固件](https://www.hiascend.com/hardware/firmware-drivers/community?product=1&model=30&cann=8.0.RC3.alpha002&driver=1.0.26.alpha)Ascend HDK 24.1.0版本以上。安装指导详见《[CANN 软件安装指南](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/850alpha002/softwareinst/instg/instg_0005.html?Mode=PmIns&OS=openEuler&Software=cannToolKit)》。	66	* 驱动与固件：宿主机已安装昇腾NPU的[驱动与固件](https://www.hiascend.com/hardware/firmware-drivers/community?product=1&model=30&cann=8.0.RC3.alpha002&driver=1.0.26.alpha)Ascend HDK 24.1.0版本以上。安装指导详见《[CANN 软件安装指南](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/850alpha002/softwareinst/instg/instg_0005.html?Mode=PmIns&OS=openEuler&Software=cannToolKit)》。
67	-	67	+
68	> 注意：使用`npu-smi info`查看对应的驱动与固件版本。	68	> 注意：使用`npu-smi info`查看对应的驱动与固件版本。
69		69
70	#### 下载镜像	70	#### 下载镜像
	@@ -73,15 +73,15 @@
73		73
74	1. 以root用户登录宿主机。	74	1. 以root用户登录宿主机。
75	2. 执行拉取命令（请根据你的宿主机架构选择）：	75	2. 执行拉取命令（请根据你的宿主机架构选择）：
76	-	76	+
77	* ARM架构：	77	* ARM架构：
78	-	78	+
79	```bash	79	```bash
80	docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops	80	docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops
81	```	81	```
82		82
83	* X86架构：	83	* X86架构：
84	-	84	+
85	```bash	85	```bash
86	docker pull --platform=amd64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops	86	docker pull --platform=amd64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops
87	```	87	```
	@@ -112,14 +112,14 @@ docker run --name cann_container --device /dev/davinci0 --device /dev/davinci_ma
112		112
113	执行如下命令，若返回驱动相关信息说明已成功挂载。	113	执行如下命令，若返回驱动相关信息说明已成功挂载。
114		114
115	- ```bash	115	+ ```bash
116	npu-smi info	116	npu-smi info
117	```	117	```
118		118
119	- 检查CANN版本	119	- 检查CANN版本
120	-	120	+
121	执行如下命令查看CANN Toolkit版本信息。	121	执行如下命令查看CANN Toolkit版本信息。
122	-	122	+
123	```bash	123	```bash
124	cat /usr/local/Ascend/ascend-toolkit/latest/opp/version.info	124	cat /usr/local/Ascend/ascend-toolkit/latest/opp/version.info
125	```	125	```
	@@ -141,7 +141,7 @@ docker run --name cann_container --device /dev/davinci0 --device /dev/davinci_ma
141	```	141	```
142		142
143	若出现“`fatal: destination path 'ops-nn' already exists and is not an empty directory.`”说明项目源码已存在，如需刷新项目代码可使用`git pull`命令。	143	若出现“`fatal: destination path 'ops-nn' already exists and is not an empty directory.`”说明项目源码已存在，如需刷新项目代码可使用`git pull`命令。
144	-	144	+
145	2. 进入项目根目录，命令如下，请区分Docker和WebIDE场景。	145	2. 进入项目根目录，命令如下，请区分Docker和WebIDE场景。
146	- Docker场景：	146	- Docker场景：
147		147
	@@ -252,7 +252,7 @@ __aicore__ inline void AddExample<T>::Compute(int32_t progress)
252	```bash	252	```bash
253	./build_out/cann-ops-nn-linux.run	253	./build_out/cann-ops-nn-linux.run
254	```	254	```
255	-	255	+
256	3. 重新验证：	256	3. 重新验证：
257		257
258	```bash	258	```bash
	@@ -286,7 +286,7 @@ __aicore__ inline void AddExample<T>::Compute(int32_t progress)
286	* printf	286	* printf
287		287
288	该接口支持打印Scalar类型数据，如整数、字符型、布尔型等，详细介绍请参见[《Ascend C API》](https://hiascend.com/document/redirect/CannCommunityAscendCApi)中“算子调测API > printf”。	288	该接口支持打印Scalar类型数据，如整数、字符型、布尔型等，详细介绍请参见[《Ascend C API》](https://hiascend.com/document/redirect/CannCommunityAscendCApi)中“算子调测API > printf”。
289	-	289	+
290	```c++	290	```c++
291	blockLength_ = (tilingData->totalLength + AscendC::GetBlockNum() - 1) / AscendC::GetBlockNum();	291	blockLength_ = (tilingData->totalLength + AscendC::GetBlockNum() - 1) / AscendC::GetBlockNum();
292	tileNum_ = tilingData->tileNum;	292	tileNum_ = tilingData->tileNum;
	@@ -299,7 +299,7 @@ __aicore__ inline void AddExample<T>::Compute(int32_t progress)
299	* DumpTensor	299	* DumpTensor
300		300
301	该接口支持Dump指定Tensor的内容，同时支持打印自定义附加信息，比如当前行号等，详细介绍请参见[《Ascend C API》](https://hiascend.com/document/redirect/CannCommunityAscendCApi)中“算子调测API > DumpTensor”。	301	该接口支持Dump指定Tensor的内容，同时支持打印自定义附加信息，比如当前行号等，详细介绍请参见[《Ascend C API》](https://hiascend.com/document/redirect/CannCommunityAscendCApi)中“算子调测API > DumpTensor”。
302	-	302	+
303	```c++	303	```c++
304	AscendC::LocalTensor<T> zLocal = outputQueueZ.DeQue<T>();	304	AscendC::LocalTensor<T> zLocal = outputQueueZ.DeQue<T>();
305	// 打印zLocal Tensor信息	305	// 打印zLocal Tensor信息
	@@ -311,7 +311,7 @@ __aicore__ inline void AddExample<T>::Compute(int32_t progress)
311	当算子功能验证正确后，可通过`msprof`工具采集算子性能数据。	311	当算子功能验证正确后，可通过`msprof`工具采集算子性能数据。
312		312
313	- 生成可执行文件	313	- 生成可执行文件
314	-	314	+
315	调用AddExample算子的example样例，生成可执行文件（test_aclnn_add_example），该文件位于项目`ops-nn/build`目录。	315	调用AddExample算子的example样例，生成可执行文件（test_aclnn_add_example），该文件位于项目`ops-nn/build`目录。
316		316
317	```bash	317	```bash
	@@ -341,7 +341,7 @@ __aicore__ inline void AddExample<T>::Compute(int32_t progress)
341	```c++	341	```c++
342	int main() {	342	int main() {
343	// ... 初始化代码 ...	343	// ... 初始化代码 ...
344	-	344	+
345	// === ① 修改selfX的输入 ===	345	// === ① 修改selfX的输入 ===
346	// 修改前：shape = {32, 4, 4, 4}, 数值全为1	346	// 修改前：shape = {32, 4, 4, 4}, 数值全为1
347	// 修改后：将输入shape改为 {8, 8, 8, 8}，并填充不同的测试数据	347	// 修改后：将输入shape改为 {8, 8, 8, 8}，并填充不同的测试数据
	@@ -352,7 +352,7 @@ int main() {
352	selfXHostData[i] = static_cast<float>(i % 10); // 填充0-9的循环值	352	selfXHostData[i] = static_cast<float>(i % 10); // 填充0-9的循环值
353	}	353	}
354	// === ② 参考selfX，同理修改selfY、selfZ的输入 ===	354	// === ② 参考selfX，同理修改selfY、selfZ的输入 ===
355	-	355	+
356	// ... 后续执行代码 ...	356	// ... 后续执行代码 ...
357	}	357	}
358	```	358	```

AQUICKSTART_en.md+374-0

@@ -0,0 +1,374 @@
	1	+# Quick Start: Based on ops-nn Repository
	2	+
	3	+## Usage Notice
	4	+
	5	+This guide aims to help you quickly get started with CANN and the `ops-nn` operator repository, providing simplified software installation and compilation and running guidance based on WebIDE or Docker environment. Note that WebIDE or Docker environment provides the latest commercial release version of CANN software package by default, which is currently CANN 8.5.0.
	6	+
	7	+> Note: If you are manually installing the CANN package or experiencing the latest capabilities of the master branch in other scenarios, you can skip the quick start and refer to the guides below for detailed tutorials. These tutorials provide rich operational methods in different scenarios to meet diverse business requirements.
	8	+>
	9	+> 1. [Environment Deployment Guide](./docs/en/context/quick_install.md): Environment setup guidance in different scenarios, including Docker installation, manual CANN software package installation, and so on.
	10	+> 2. [Compile and Execute Operator Guide](./docs/en/invocation/quick_op_invocation.md): Operator package compilation and verification guidance in different scenarios, such as offline compilation, in-depth understanding of compilation parameters and invocation methods.
	11	+> 3. [Operator Development Guide](./docs/en/develop/aicore_develop_guide.md): Guide for custom development of standard operators, learning to create operator projects from scratch and implement Tiling and Kernel.
	12	+> 4. [Debugging and Tuning Guide](./docs/en/debug/op_debug_prof.md): Systematic debugging techniques and performance optimization methods in different scenarios.
	13	+
	14	+The basic process of operator development and contribution is shown in the figure below. We welcome and encourage you to contribute operators in the community to jointly enrich the project ecosystem.
	15	+
	16	+<!--![Operator Development Contribution Process](./docs/en/figures/operator_development_contribution_process.png "Operator Development Contribution Process Diagram")-->
	17	+
	18	+To help you quickly understand the entire process of operator development, we will use the AddExample operator as a practical object. Its source files are located in `ops-nn/examples/add_example`. The specific operation steps are as follows:
	19	+
	20	+1. [Environment Installation](#i-environment-installation-choose-one-of-two): Set up the operator development and running environment.
	21	+2. [Compilation and Deployment](#ii-compilation-and-deployment): Compile the custom operator package and deploy the installation to achieve quick operator invocation.
	22	+3. [Operator Development](#iii-operator-development): Experience the complete loop of development, compilation, and verification by modifying the existing operator Kernel.
	23	+4. [Operator Debugging](#iv-operator-debugging): Master the methods of operator printing and performance collection.
	24	+5. [Operator Verification](#v-operator-verification): Learn how to modify operator example samples to verify the functional correctness of operators under different inputs.
	25	+
	26	+## I. Environment Installation (Choose One of Two)
	27	+
	28	+### 1. No Environment Scenario: WebIDE Development
	29	+
	30	+For users without an environment, you can directly use the WebIDE development platform, that is, the "Operator One-Stop Development Platform". This platform provides you with an online directly runnable Ascend environment, where necessary software packages have been installed, without manual installation. For more introduction about the development platform, refer to [LINK](https://gitcode.com/org/cann/discussions/54).
	31	+
	32	+1. Enter the ops-nn open-source project and click the "`Cloud Development`" button. Log in with a certified Huawei Cloud account. If you have not registered or certified, please register and certify according to the page prompts.
	33	+
	34	+ <!--<img src="docs/en/figures/cloudIDE.png" alt="Cloud Platform" width="750px" height="90px">-->
	35	+
	36	+2. Create and start the cloud development environment according to the page prompts, and click "`Connect > WebIDE`" to enter the operator one-stop development platform. The resources of the open-source project are in the `/mnt/workspace` directory by default.
	37	+
	38	+ <!--<img src="docs/en/figures/webIDE.png" alt="Cloud Platform" width="1000px" height="150px">-->
	39	+
	40	+3. Check whether the environment is complete.
	41	+
	42	+ In the cloud platform terminal window, execute the following commands to verify whether the environment and driver are normal.
	43	+
	44	+ - Check NPU Device
	45	+
	46	+ Execute the following command. If driver-related information is returned, it means that the device has been successfully mounted.
	47	+
	48	+ ```bash
	49	+ npu-smi info
	50	+ ```
	51	+
	52	+ - Check CANN Version
	53	+
	54	+ Execute the following command to view the CANN Toolkit version information.
	55	+
	56	+ ```bash
	57	+ cat /home/developer/Ascend/ascend-toolkit/latest/opp/version.info
	58	+ ```
	59	+
	60	+### 2. Existing Environment Scenario: Docker Installation
	61	+
	62	+#### Prerequisites
	63	+
	64	+* Docker Environment: Taking Atlas A2 product (910B) as an example, the Docker engine (version 1.11.2 or above) has been installed on the host machine in the environment.
	65	+
	66	+* Driver and Firmware: The host machine has installed Ascend NPU [driver and firmware](https://www.hiascend.com/hardware/firmware-drivers/community?product=1&model=30&cann=8.0.RC3.alpha002&driver=1.0.26.alpha) Ascend HDK version 24.1.0 or above. For installation instructions, see the "[CANN Software Installation Guide](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/softwareinst/instg/instg_0107.html)".
	67	+
	68	+ > Note: Use `npu-smi info` to view the corresponding driver and firmware version.
	69	+
	70	+#### Download Image
	71	+
	72	+Pull the image that has pre-integrated the CANN software package and `ops-nn` required dependencies.
	73	+
	74	+1. Log in to the host machine as the root user.
	75	+2. Execute the pull command (select according to your host machine architecture):
	76	+
	77	+ * ARM architecture:
	78	+
	79	+ ```bash
	80	+ docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops
	81	+ ```
	82	+
	83	+ * X86 architecture:
	84	+
	85	+ ```bash
	86	+ docker pull --platform=amd64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops
	87	+ ```
	88	+
	89	+> Note: Under normal network speed, the image download time is about 5-10 minutes.
	90	+
	91	+#### Docker Run
	92	+
	93	+Run docker according to the following command:
	94	+
	95	+```bash
	96	+docker run --name cann_container --device /dev/davinci0 --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 -it swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops bash
	97	+```
	98	+
	99	+The following are parameter descriptions that users need to pay attention to:
	100	+
	101	+\| Parameter \| Description \| Precautions \|
	102	+\| :--- \| :--- \| :--- \|
	103	+\| `--name cann_container` \| Specify a name for the container for management. \| Can be customized. \|
	104	+\| `--device /dev/davinci0` \| Core: Map the host machine's NPU device card to the container. Multiple NPU device cards can be specified for mapping. \| Must be adjusted according to the actual situation: `davinci0` corresponds to the 0th NPU card in the system. Please execute the `npu-smi info` command on the host machine first, and modify this number according to the device number displayed in the output (such as `NPU 0`, `NPU 1`).\|
	105	+\| `-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/` \| Key mount: Map the host machine's NPU driver library to the container. \| - \|
	106	+
	107	+#### Check Environment
	108	+
	109	+After entering the container, verify whether the environment and driver are normal.
	110	+
	111	+- Check NPU Device
	112	+
	113	+ Execute the following command. If driver-related information is returned, it means that the device has been successfully mounted.
	114	+
	115	+ ```bash
	116	+ npu-smi info
	117	+ ```
	118	+
	119	+- Check CANN Version
	120	+
	121	+ Execute the following command to view the CANN Toolkit version information.
	122	+
	123	+ ```bash
	124	+ cat /usr/local/Ascend/ascend-toolkit/latest/opp/version.info
	125	+ ```
	126	+
	127	+You now have an "out-of-the-box" operator development environment. Next, you need to verify the complete toolchain from source code to runnable operators in this environment.
	128	+
	129	+## II. Compilation and Deployment
	130	+
	131	+The purpose of this stage is to quickly experience the project standard process and verify whether the environment can successfully perform operator source code compilation, packaging, installation, and running.
	132	+
	133	+### 1. Obtain Project Source Code
	134	+
	135	+1. Obtain the project source code.
	136	+
	137	+ Docker or WebIDE environment provides the latest commercial release version source code by default. If you need to obtain other version source code, you can download through the following command. ${tag_version} needs to be replaced with the target branch tag name. For the correspondence between branch tags and CANN versions, see the [release repository](https://gitcode.com/cann/release-management).
	138	+
	139	+ ```bash
	140	+ git clone -b ${tag_version} https://gitcode.com/cann/ops-nn.git
	141	+ ```
	142	+
	143	+ If "`fatal: destination path 'ops-nn' already exists and is not an empty directory.`" appears, it means that the project source code already exists. If you need to refresh the project code, you can use the `git pull` command.
	144	+
	145	+2. Enter the project root directory. The command is as follows. Please distinguish between Docker and WebIDE scenarios.
	146	+ - Docker scenario:
	147	+
	148	+ ```bash
	149	+ cd ops-nn
	150	+ ```
	151	+
	152	+ - WebIDE scenario:
	153	+
	154	+ ```bash
	155	+ cd /mnt/workspace/ops-nn
	156	+ ```
	157	+
	158	+### 2. Compile AddExample Operator
	159	+
	160	+Enter the project root directory and compile the specified operator. The general compilation command format: `bash build.sh --pkg --soc=<chip version> --ops=<operator name>`.
	161	+
	162	+Taking the AddExample operator as an example, the compilation command is as follows:
	163	+
	164	+```bash
	165	+bash build.sh --pkg --soc=ascend910b --ops=add_example -j16
	166	+```
	167	+
	168	+If the following information is prompted, the compilation is successful.
	169	+
	170	+```bash
	171	+Self-extractable archive "cann-ops-nn-custom-linux.${arch}.run" successfully created.
	172	+```
	173	+
	174	+After successful compilation, the run package is stored in the build_out directory under the project root directory.
	175	+
	176	+### 3. Install AddExample Operator Package
	177	+
	178	+```bash
	179	+./build_out/cann-ops-nn-linux.run
	180	+```
	181	+
	182	+`AddExample` is installed in the ```${ASCEND_HOME_PATH}/opp/vendors``` path. ```${ASCEND_HOME_PATH}``` indicates the CANN software installation directory.
	183	+
	184	+### 4. Configure Environment Variables
	185	+
	186	+Add the path of the custom operator package to the environment variables to ensure that it can be found at runtime.
	187	+
	188	+```bash
	189	+export LD_LIBRARY_PATH=${ASCEND_HOME_PATH}/opp/vendors/custom_nn/op_api/lib:${LD_LIBRARY_PATH}
	190	+```
	191	+
	192	+### 5. Quick Verification: Run Operator Sample
	193	+
	194	+The general running command format: `bash build.sh --run_example <operator name> <running mode> <package mode>`.
	195	+
	196	+Taking AddExample as an example, it provides a simple operator sample `add_example/examples/test_aclnn_add_example.cpp`. Run this sample to verify whether the operator function is normal.
	197	+
	198	+```bash
	199	+bash build.sh --run_example add_example eager cust --vendor_name=custom
	200	+```
	201	+
	202	+Expected output: Print the addition calculation result of the operator `AddExample`, indicating that the operator has been successfully deployed and executed correctly.
	203	+
	204	+```bash
	205	+add_example first input[0] is: 1.000000, second input[0] is: 1.000000, result[0] is: 2.000000
	206	+add_example first input[1] is: 1.000000, second input[1] is: 1.000000, result[1] is: 2.000000
	207	+add_example first input[2] is: 1.000000, second input[2] is: 1.000000, result[2] is: 2.000000
	208	+add_example first input[3] is: 1.000000, second input[3] is: 1.000000, result[3] is: 2.000000
	209	+add_example first input[4] is: 1.000000, second input[4] is: 1.000000, result[4] is: 2.000000
	210	+add_example first input[5] is: 1.000000, second input[5] is: 1.000000, result[5] is: 2.000000
	211	+add_example first input[6] is: 1.000000, second input[6] is: 1.000000, result[6] is: 2.000000
	212	+add_example first input[7] is: 1.000000, second input[7] is: 1.000000, result[7] is: 2.000000
	213	+...
	214	+```
	215	+
	216	+## III. Operator Development
	217	+
	218	+The purpose of this stage is to try modifying the kernel function code for the successfully running AddExample operator.
	219	+
	220	+### 1. Modify Kernel Implementation
	221	+
	222	+Find the core kernel implementation file of the AddExample operator `ops-nn/examples/add_example/op_kernel/add_example.h`, and try to change the Add operation in the operator to a Mul operation:
	223	+
	224	+```cpp
	225	+__aicore__ inline void AddExample<T>::Compute(int32_t progress)
	226	+{
	227	+ AscendC::LocalTensor<T> xLocal = inputQueueX.DeQue<T>();
	228	+ AscendC::LocalTensor<T> yLocal = inputQueueY.DeQue<T>();
	229	+ AscendC::LocalTensor<T> zLocal = outputQueueZ.AllocTensor<T>();
	230	+ // === Replace Add with Mul here ===
	231	+ // AscendC::Add(zLocal, xLocal, yLocal, tileLength_);
	232	+ AscendC::Mul(zLocal, xLocal, yLocal, tileLength_);
	233	+ outputQueueZ.EnQue<T>(zLocal);
	234	+ inputQueueX.FreeTensor(xLocal);
	235	+ inputQueueY.FreeTensor(yLocal);
	236	+}
	237	+```
	238	+
	239	+### 2. Compile and Verify
	240	+
	241	+Repeat steps 2 to 5 in the [Compilation and Deployment](#ii-compilation-and-deployment) section:
	242	+
	243	+1. Recompile:
	244	+ First return to the project root directory. The compilation command is as follows:
	245	+
	246	+ ```bash
	247	+ bash build.sh --pkg --soc=ascend910b --ops=add_example -j16
	248	+ ```
	249	+
	250	+2. Reinstall:
	251	+
	252	+ ```bash
	253	+ ./build_out/cann-ops-nn-linux.run
	254	+ ```
	255	+
	256	+3. Re-verify:
	257	+
	258	+ ```bash
	259	+ bash build.sh --run_example add_example eager cust --vendor_name=custom
	260	+ ```
	261	+
	262	+4. Success Sign: The output result becomes the multiplication result.
	263	+
	264	+ ```bash
	265	+ add_example first input[0] is: 1.000000, second input[0] is: 1.000000, result[0] is: 1.000000
	266	+ add_example first input[1] is: 1.000000, second input[1] is: 1.000000, result[1] is: 1.000000
	267	+ add_example first input[2] is: 1.000000, second input[2] is: 1.000000, result[2] is: 1.000000
	268	+ add_example first input[3] is: 1.000000, second input[3] is: 1.000000, result[3] is: 1.000000
	269	+ add_example first input[4] is: 1.000000, second input[4] is: 1.000000, result[4] is: 1.000000
	270	+ add_example first input[5] is: 1.000000, second input[5] is: 1.000000, result[5] is: 1.000000
	271	+ add_example first input[6] is: 1.000000, second input[6] is: 1.000000, result[6] is: 1.000000
	272	+ add_example first input[7] is: 1.000000, second input[7] is: 1.000000, result[7] is: 1.000000
	273	+ ...
	274	+ ```
	275	+
	276	+## IV. Operator Debugging
	277	+
	278	+This stage takes AddExample as an example to add printing in the operator and collect operator performance data for subsequent problem analysis and positioning.
	279	+
	280	+### 1. Printing
	281	+
	282	+If the operator has execution failure, precision abnormality, or other problems, add printing for problem analysis and positioning.
	283	+
	284	+Please modify the code in `examples/add_example/op_kernel/add_example.h`.
	285	+
	286	+* printf
	287	+
	288	+ This interface supports printing Scalar type data, such as integers, character type, Boolean type, and so on. For detailed introduction, see "Operator Debugging API > printf" in "[Ascend C API](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/API/ascendcopapi/atlasascendc_api_07_0003.html)".
	289	+
	290	+ ```c++
	291	+ blockLength_ = (tilingData->totalLength + AscendC::GetBlockNum() - 1) / AscendC::GetBlockNum();
	292	+ tileNum_ = tilingData->tileNum;
	293	+ tileLength_ = ((blockLength_ + tileNum_ - 1) / tileNum_ / BUFFER_NUM) ?
	294	+ ((blockLength_ + tileNum_ - 1) / tileNum_ / BUFFER_NUM) : 1;
	295	+ // Print the current kernel calculation Block length
	296	+ AscendC::PRINTF("Tiling blockLength is %llu\n", blockLength_);
	297	+ ```
	298	+
	299	+* DumpTensor
	300	+
	301	+ This interface supports dumping the content of the specified Tensor, and also supports printing custom additional information, such as the current line number. For detailed introduction, see "Operator Debugging API > DumpTensor" in "[Ascend C API](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/API/ascendcopapi/atlasascendc_api_07_0003.html)".
	302	+
	303	+ ```c++
	304	+ AscendC::LocalTensor<T> zLocal = outputQueueZ.DeQue<T>();
	305	+ // Print zLocal Tensor information
	306	+ DumpTensor(zLocal, 0, 128);
	307	+ ```
	308	+
	309	+### 2. Performance Collection
	310	+
	311	+When the operator function verification is correct, you can collect operator performance data through the `msprof` tool.
	312	+
	313	+- Generate Executable File
	314	+
	315	+ Call the example sample of the AddExample operator to generate an executable file (test_aclnn_add_example), which is located in the project `ops-nn/build` directory.
	316	+
	317	+ ```bash
	318	+ bash build.sh --run_example add_example eager cust --vendor_name=custom
	319	+ ```
	320	+
	321	+- Collect Performance Data
	322	+
	323	+ Enter the AddExample operator executable file directory `ops-nn/build/` and execute the following command:
	324	+
	325	+ ```bash
	326	+ msprof --application="./test_aclnn_add_example"
	327	+ ```
	328	+
	329	+The collection result is in the project `ops-nn/build/` directory. After the msprof command is executed, it will automatically parse and export the performance data result file. For detailed content, see [msprof](https://www.hiascend.com/document/detail/zh/mindstudio/82RC1/T&ITools/Profiling/atlasprofiling_16_0110.html#ZH-CN_TOPIC_0000002504160251).
	330	+
	331	+## V. Operator Verification
	332	+
	333	+This stage verifies the functional correctness of the operator in multiple scenarios by modifying the input data of the AddExample operator example sample.
	334	+
	335	+### 1. Modify Test Input
	336	+
	337	+Find and edit the `ops-nn/examples/add_example/examples/test_aclnn_add_example.cpp` of `AddExample`, and modify the shape and numerical values of the input tensor.
	338	+
	339	+Modify Input/Output Data: Modify the shape information of input and output, as well as the initialization data, and construct the corresponding input and output tensors.
	340	+
	341	+```c++
	342	+int main() {
	343	+ // ... initialization code ...
	344	+
	345	+ // === ① Modify selfX input ===
	346	+ // Before modification: shape = {32, 4, 4, 4}, all values are 1
	347	+ // After modification: change input shape to {8, 8, 8, 8}, and fill with different test data
	348	+ std::vector<int64_t> selfXShape = {8, 8, 8, 8};
	349	+ std::vector<float> selfXHostData(4096); // 4096 = 8 * 8 * 8 *8
	350	+ // You can use a loop to fill more distinguishable data, such as an increasing sequence
	351	+ for (int i = 0; i < 4096; ++i) {
	352	+ selfXHostData[i] = static_cast<float>(i % 10); // Fill with cyclic values of 0-9
	353	+ }
	354	+ // === ② Refer to selfX, similarly modify selfY and selfZ inputs ===
	355	+
	356	+ // ... subsequent execution code ...
	357	+}
	358	+```
	359	+
	360	+### 2. Recompile and Verify
	361	+
	362	+1. Since only the example test code is modified, there is no need to recompile the operator package.
	363	+
	364	+2. Re-execute the verification command:
	365	+
	366	+ ```bash
	367	+ bash build.sh --run_example add_example eager cust --vendor_name=custom
	368	+ ```
	369	+
	370	+3. Observe whether the operator output result meets expectations.
	371	+
	372	+## VI. Development Contribution
	373	+
	374	+After experiencing the above operations, you have basically completed an operator development. You can contribute the operator to the `experimental` directory of this project. For the contribution process, refer to the [Contribution Guide](CONTRIBUTING_en.md). During the process, any questions can be consulted through the Issue method.

AREADME_en.md+102-0

@@ -0,0 +1,102 @@
	1	+# ops-nn
	2	+
	3	+## 🔥Latest News
	4	+
	5	+- [2026/01] Added [QuickStart](QUICKSTART_en.md) to guide beginners through zero-based deployment of operator projects (supporting Docker environments), operator development, and contribution processes.
	6	+- [2025/12] Open-source operators support Ascend 950PR/Ascend 950DT/KirinX90, which can be developed and debugged through the [CANN Simulator](docs/en/debug/cann_simulator.md) simulation tool; optimized guideline documents, focusing on the [Operator Development Guide](docs/en/develop/aicore_develop_guide.md), clarifying minimum deliverables and key sample code, providing guidance for migrating operators from the Ascend/samples repository to this project; newly supported [sparse 4:2 quantization matmul operator](matmul/sparse4to2quant_matmul), enabling hardware acceleration capabilities for sparse matrices.
	7	+- [2025/11] Newly supported operators: [index_fill](index/index_fill/), [masked_scatter](index/masked_scatter/), [scatter](index/scatter/), [tf_scatter_add](index/tf_scatter_add/), [fused_cross_entropy_loss_with_max_sum](loss/fused_cross_entropy_loss_with_max_sum/).
	8	+- [2025/10] Added experimental directory, improved [Contribution Guide](CONTRIBUTING_en.md), supporting developers to debug and contribute custom operators.
	9	+- [2025/09] The ops-nn project was first released, with open-source operators supporting Atlas A2/A3 series products.
	10	+
	11	+## 🚀Overview
	12	+
	13	+ops-nn is a high-level operator library that provides neural network computing capabilities in the [CANN](https://hiascend.com/software/cann) (Compute Architecture for Neural Networks) operator library, including matmul, activation, and other types of operators. The operator library architecture is shown below:
	14	+
	15	+<!--<img src="docs/en/figures/architecture.png" alt="Architecture Diagram" width="700px" height="320px">-->
	16	+
	17	+## 📝Version Compatibility
	18	+
	19	+The source code of this project will be released along with the CANN software version. For the correspondence between CANN software versions and project tags, refer to the relevant version descriptions in the [release repository](https://gitcode.com/cann/release-management).
	20	+Note that to ensure smooth custom development of your source code, select the matching CANN version and Gitcode tag source code. Using the master branch may pose version mismatch risks.
	21	+
	22	+## ⚡️Quick Start
	23	+
	24	+If you want to understand and quickly experience the project from scratch, visit the following documents. You can first learn about the project operator information, then try operator invocation, development, contribution, and so on.
	25	+
	26	+1. [Operator List](docs/zh/op_list.md): Complete operator information of the project for quick query.
	27	+2. [QuickStart](QUICKSTART_en.md): Provides a minimalist quick start guide based on WebIDE or Docker environment, including environment setup, compilation and deployment, operator invocation/development/debugging, contribution, and so on.
	28	+
	29	+ > Note: Whether using WebIDE or Docker environment, the latest commercial release version of CANN software package is provided by default, which is currently CANN 8.5.0. If you want to manually install the CANN package or experience the latest capabilities of the master branch, refer to the steps in [Learning Tutorials](#learning-tutorials) to complete environment setup, compilation and execution, operator development, and other operations.
	30	+
	31	+## 📖Learning Tutorials
	32	+
	33	+If you have completed the Quick Start learning, have a certain understanding of this project, and want to deeply understand and experience the project, visit the following documents.
	34	+
	35	+These documents provide diverse scenarios and more comprehensive operational guidance for you to apply to various AI business scenarios.
	36	+
	37	+1. [Environment Deployment](docs/en/context/quick_install.md): Guide for setting up the basic environment, providing installation methods for third-party dependencies and software packages in various scenarios.
	38	+2. [Operator Invocation](docs/en/invocation/quick_op_invocation.md): Guide for operator source code compilation and execution, providing methods for operator package compilation (including online/offline scenarios) and operator running (including executing operator samples and UT) in different scenarios.
	39	+3. [Operator Development](docs/en/develop/aicore_develop_guide.md): Guide for developing new operators based on this project engineering, providing guidance for creating operator projects, implementing Tiling and Kernel core deliverables.
	40	+4. [Operator Debugging and Tuning](docs/en/debug/op_debug_prof.md): Provides common operator debugging and tuning methods, such as DumpTensor, msProf, Simulator, and so on.
	41	+
	42	+In addition to the above guidelines, other documents are also provided, such as [Operator Invocation Methods](docs/en/invocation/op_invocation.md), terminology concepts, build parameter introduction, and so on. For complete documentation, visit [docs](docs/README_en.md).
	43	+
	44	+## 🔍Directory Structure
	45	+
	46	+The key directories are as follows. For detailed directory introduction, see [Project Directory](./docs/en/context/dir_structure.md).
	47	+
	48	+```text
	49	+├── activation # activation class operators
	50	+├── cmake # project compilation directory
	51	+├── common # project common header files and common source code
	52	+├── control # control class operators
	53	+├── conv # conv class operators
	54	+├── docs # project documentation introduction
	55	+├── examples # end-to-end operator development and invocation examples
	56	+├── experimental # user-defined operator storage directory
	57	+├── foreach # foreach class operators
	58	+├── index # index class operators
	59	+├── loss # loss class operators
	60	+├── matmul # matmul class operators
	61	+│ ├── transpose_batch_mat_mul # all deliverables of transpose_batch_mat_mul operator, such as Tiling, Kernel, and so on
	62	+│ │ ├── docs # operator documentation
	63	+│ │ ├── examples # operator usage examples
	64	+│ │ ├── op_graph # operator graph construction related directory
	65	+│ │ ├── op_host # operator information library, Tiling, InferShape related implementation directory
	66	+│ │ │ └── op_api # operator aclnn interface implementation directory
	67	+│ │ ├── op_kernel # operator Kernel directory
	68	+│ │ ├── CMakeLists.txt # operator compilation configuration file
	69	+│ │ └── README.md # operator introduction document
	70	+│ ├── ...
	71	+│ └── CMakeLists.txt # operator compilation configuration file
	72	+├── ...
	73	+├── rnn # rnn class operators
	74	+├── scripts # script directory, containing custom operator and Kernel build related configuration files
	75	+├── tests # test project directory
	76	+├── vfusion # vfusion class operators
	77	+├── CMakeLists.txt
	78	+├── README.md
	79	+├── build.sh # project compilation script
	80	+├── install_deps.sh # dependency package installation script
	81	+└── requirements.txt # third-party dependency packages required by the project
	82	+```
	83	+
	84	+## 💬Related Information
	85	+
	86	+- [Contribution Guide](CONTRIBUTING_en.md)
	87	+- [Security Statement](SECURITY_en.md)
	88	+- [License](LICENSE)
	89	+- [Affiliated SIG](https://gitcode.com/cann/community/tree/master/CANN/sigs/ops-nn)
	90	+
	91	+## 🤝Contact Us
	92	+
	93	+The functions and documentation of this project are being continuously updated and improved. We recommend that you follow the latest version.
	94	+
	95	+- Issue Feedback: Submit issues through GitCode [Issues](https://gitcode.com/cann/ops-nn/issues).
	96	+- Community Interaction: Participate in discussions through GitCode [Discussions](https://gitcode.com/cann/ops-nn/discussions).
	97	+- Technical Column: Access technical articles through GitCode [Wiki](https://gitcode.com/cann/ops-nn/wiki), such as serialized tutorials and best practices.
	98	+
	99	+ \|Technical Topic\|Sample\|
	100	+ \|----\|----\|
	101	+ \|Operator Performance Optimization\|[MatMul Operator Performance Optimization Practice and Effect Analysis](https://gitcode.com/cann/ops-nn/wiki/MatMul%E7%AE%97%E5%AD%90%E6%80%A7%E8%83%BD%E4%BC%98%E5%8C%96%E5%AE%9E%E8%B7%B5%E4%B8%8E%E6%95%88%E6%9E%9C%E5%88%86%E6%9E%90.md)\|
	102	+ \|Operator Performance Optimization\|[MatMul Operator VCV Performance Optimization Practice and Effect Analysis](https://gitcode.com/cann/ops-nn/wiki/MatMul%E7%AE%97%E5%AD%90VCV%E6%80%A7%E8%83%BD%E4%BC%98%E5%8C%96%E5%AE%9E%E8%B7%B5%E4%B8%8E%E6%95%88%E6%9E%9C%E5%88%86%E6%9E%90.md)\|

ASECURITY_en.md+65-0

@@ -0,0 +1,65 @@
	1	+# Security Statement
	2	+
	3	+## Running User Recommendations
	4	+
	5	+Based on security considerations, we do not recommend using root or other administrator type accounts to execute any commands. Follow the principle of minimum permissions.
	6	+
	7	+## File Permission Control
	8	+
	9	+- We recommend that users set the running system umask value to 0027 or above on the host machine (including the host machine) and in the container to ensure that the default maximum permission for new folders is 750 and the default maximum permission for new files is 640.
	10	+- We recommend that users take security measures such as permission control for sensitive content such as personal privacy data, business assets, source files, and various files saved during operator development. For example, for project installation directory permission control and input public data file permission control, the set permissions should refer to [A-File (Folder) Permission Control Recommended Maximum Values in Various Scenarios](#a-file-folder-permission-control-recommended-maximum-values-in-various-scenarios).
	11	+- When the operator runs, it may cache operator compilation files, which are stored in the `kernel_meta_*` folder under the running directory to speed up subsequent operator invocation. Users can perform permission control on the generated related files as needed.
	12	+- Users need to perform permission control during installation and use. We recommend referring to [A-File (Folder) Permission Control Recommended Maximum Values in Various Scenarios](#a-file-folder-permission-control-recommended-maximum-values-in-various-scenarios) for file permission reference settings.
	13	+
	14	+## Build Security Statement
	15	+
	16	+When compiling and installing this project from source code, you need to compile it yourself. During the compilation process, some intermediate files will be generated. We recommend that you perform permission control on the intermediate files after compilation to ensure file security.
	17	+
	18	+## Running Security Statement
	19	+
	20	+- We recommend that users write corresponding operator invocation scripts based on the running environment resource status. If the operator invocation script does not match the resource status, such as the space used for generating input data or benchmark calculation results exceeding the memory capacity limit, or the script saving data locally exceeding the disk space size, it may cause errors and lead to unexpected process exit.
	21	+- When the operator runs abnormally, it will exit the process and print error information. We recommend locating the specific error cause based on the error prompt, including setting operator synchronous execution, viewing log files, and other methods.
	22	+- When the operator is invoked through [PyTorch](https://gitee.com/ascend/pytorch), running errors may occur due to version mismatch. For details, please refer to [PyTorch Security Statement](https://gitee.com/ascend/pytorch#%E5%AE%89%E5%85%A8%E5%A3%B0%E6%98%8E).
	23	+
	24	+## Public Network Address Statement
	25	+
	26	+The public network addresses contained in this project code are declared as follows:
	27	+
	28	+\| Type \| Open Source Code Address \| File Name \| Public Network IP Address/Public Network URL Address/Domain Name/Email Address/Compressed File Address \| Usage Description \|
	29	+\| :------------: \|:------------------------------------------------------------------------------------------:\|:----------------------------------------------------------\| :---------------------------------------------------------- \|:-----------------------------------------\|
	30	+\| Dependency \| Not involved \| cmake/third_party/makeself-fetch.cmake \| [https://gitcode.com/cann-src-third-party/makeself/releases/download/release-2.5.0-patch1.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) \| Download makeself source code from gitcode, used as compilation dependency \|
	31	+\| Dependency \| Not involved \| cmake/third_party/nlohmann_json.cmake \| [https://gitcode.com/cann-src-third-party/json/releases/download/v3.11.3/include.zip](https://gitcode.com/cann-src-third-party/json/releases/download/v3.11.3/include.zip) \| Download json source code from gitcode, used as compilation dependency \|
	32	+\| Dependency \| Not involved \| cmake/third_party/gtest.cmake \| [https://gitcode.com/cann-src-third-party/googletest/releases/download/v1.14.0/googletest-1.14.0.tar.gz](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, used as compilation dependency \|
	33	+\| Dependency \| Not involved \| cmake/third_party/eigen.cmake \| [https://gitcode.com/cann-src-third-party/eigen/releases/download/5.0.0-h0.trunk/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) \| Download eigen source code from gitcode, used as compilation dependency \|
	34	+\| Dependency \| Not involved \| ops-nn/install_deps.sh \| [https://apt.kitware.com/keys/kitware-archive-latest.asc](https://apt.kitware.com/keys/kitware-archive-latest.asc) \| Download install_deps source code from gitcode, used as compilation dependency \|
	35	+\| Dependency \| Not involved \| ops-nn/install_deps.sh \| [https://apt.kitware.com/ubuntu/](https://apt.kitware.com/ubuntu/) \| Download install_deps source code from gitcode, used as compilation dependency \|
	36	+\| Dependency \| Not involved \| cmake \| [https://apt.kitware.com/keys/kitware-archive-latest.asc](https://apt.kitware.com/keys/kitware-archive-latest.asc) \| Download cmake software from kitware, used as compilation dependency \|
	37	+\| Dependency \| Not involved \| cmake \| [https://apt.kitware.com/ubuntu/](https://apt.kitware.com/ubuntu/) \| Download cmake software from kitware, used as compilation dependency \|
	38	+
	39	+## Vulnerability Mechanism Description
	40	+
	41	+[Vulnerability Management](https://gitcode.com/cann/community/blob/master/security/security.md)
	42	+
	43	+## Appendix
	44	+
	45	+### A-File (Folder) Permission Control Recommended Maximum Values in Various Scenarios
	46	+
	47	+\| Type \| Linux Permission Reference Maximum Value \|
	48	+\| -------------- \| --------------- \|
	49	+\| User Home Directory \| 750 (rwxr-x---) \|
	50	+\| Program Files (including script files, library files, etc.) \| 550 (r-xr-x---) \|
	51	+\| Program File Directory \| 550 (r-xr-x---) \|
	52	+\| Configuration File \| 640 (rw-r-----) \|
	53	+\| Configuration File Directory \| 750 (rwxr-x---) \|
	54	+\| Log File (recording completed or archived) \| 440 (r--r-----) \|
	55	+\| Log File (currently recording) \| 640 (rw-r-----) \|
	56	+\| Log File Directory \| 750 (rwxr-x---) \|
	57	+\| Debug File \| 640 (rw-r-----) \|
	58	+\| Debug File Directory \| 750 (rwxr-x---) \|
	59	+\| Temporary File Directory \| 750 (rwxr-x---) \|
	60	+\| Maintenance Upgrade File Directory \| 770 (rwxrwx---) \|
	61	+\| Business Data File \| 640 (rw-r-----) \|
	62	+\| Business Data File Directory \| 750 (rwxr-x---) \|
	63	+\| Key Component, Private Key, Certificate, Ciphertext File Directory \| 700 (rwx-----) \|
	64	+\| Key Component, Private Key, Certificate, Encrypted Ciphertext \| 600 (rw-------) \|
	65	+\| Encryption/Decryption Interface, Encryption/Decryption Script \| 500 (r-x------) \|

Adocs/CONTRIBUTING_DOCS_en.md+203-0

@@ -0,0 +1,203 @@
	1	+# Documentation Contribution Guide
	2	+
	3	+We welcome your contributions to the project documentation. High-quality documentation is crucial for project success. This guide will help you efficiently submit documentation that meets the standards.
	4	+
	5	+## Contribution Scope
	6	+
	7	+We welcome any contributions that can improve documentation quality, including but not limited to:
	8	+
	9	+- Correction and Improvement: Fix typos, grammar errors, incorrect code examples, outdated information, or broken links.
	10	+
	11	+- Clarification and Optimization: Make descriptions clearer and easier to understand, optimize sentence structure, and supplement background knowledge.
	12	+
	13	+- Content Supplement: Add usage examples, API documentation, frequently asked questions (FAQ), best practices, or warning descriptions for existing features.
	14	+
	15	+- New Content Creation: Write new chapters or tutorials for newly added features, such as operator README, API introduction documents, and so on. If you have questions, we recommend creating an Issue for discussion first.
	16	+
	17	+- Localization Translation: Help us translate or proofread documents in other languages.
	18	+
	19	+- Style and Navigation: Improve the layout, readability, and navigation structure of the documentation website.
	20	+
	21	+## Contribution Process
	22	+
	23	+1. Preparation Work
	24	+
	25	+ - Determine the Task: If there are documentation issues, you can create new Issues. We recommend using the label category `[Documentation\|文档反馈]` and providing a detailed description. Based on the existing Issues list, determine the documentation issues to be resolved.
	26	+ - Claim the Task: Comment `/assign @yourself` under the corresponding Issue to indicate that you will handle it and avoid duplicate work.
	27	+
	28	+2. Document Modification
	29	+
	30	+ - Select Branch: Please download the source code from the master or other Tag branches to the local machine.
	31	+ - Follow Format:
	32	+ - This project recommends using Markdown format.
	33	+ - Follow the existing writing style of the project.
	34	+ - Put static resources such as images in the corresponding directory. For example, images are generally in the `figures` folder under the docs directory. You can adjust them yourself in special cases.
	35	+ - Careful Addition and Deletion: When modifying content, please try to maintain the original line width and line break conventions.
	36	+
	37	+3. Submit Changes
	38	+
	39	+ - Atomic Commit: Each commit should focus on an independent modification. For example, "Fix spelling errors in xx guide" and "Update example code in API reference" should be submitted separately.
	40	+
	41	+ - Write Clear Commit Messages:
	42	+
	43	+ ```text
	44	+ Brief description (no more than 50 characters)
	45	+
	46	+ If necessary, provide a more detailed description here. Explain the reason and content of the modification, rather than what specifically was changed (the code itself will show).
	47	+ Associated Issue: #123
	48	+ ```
	49	+
	50	+4. Initiate Pull Request
	51	+
	52	+ - Target Branch: Please merge the PR into the target branch of the project.
	53	+ - Title and Description:
	54	+ - PR Title: Should clearly summarize the modification, for example: `[Docs] Fix configuration example in quick start`.
	55	+ - PR Description: Detailed explanation of your changes, motivation, and associated Issues (use Closes #123 or Fixes #456).
	56	+ - Preview Check: Please check the document effect in local or online browsing in advance to ensure that the rendering meets expectations.
	57	+ - Wait for Review: Maintainers will review and may propose modification suggestions. Please follow up on the discussion in a timely manner.
	58	+
	59	+## Writing Standards
	60	+
	61	+Before developers write project documentation, please be sure to read the following standards first. If you have questions, you are welcome to make suggestions at any time!
	62	+
	63	+- Prerequisites: Please first learn the unified writing standards provided by the CANN organization. For details, see [CANN Document Writing Standards](https://gitcode.com/cann/community/blob/master/contributor/docs/document_writing_specs.md).
	64	+
	65	+ - Document Content Requirements: Introduce the required and optional document deliverables in the project.
	66	+ - Directory Structure Standards: Introduce the principles of directory division, such as Chinese and English management.
	67	+ - Content Element Standards: Introduce rules for different writing elements, such as file naming, titles, fonts, images, code blocks, links, and so on.
	68	+
	69	+- Precautions:
	70	+
	71	+ In addition to the above writing rules, you also need to pay attention to the following:
	72	+
	73	+ - Tone: Use a friendly, professional, and neutral tone. For beginners, avoid unnecessary jargon.
	74	+ - Terminology: Maintain terminology consistency (such as uniformly using "click" instead of "single click"). Please refer to the project terminology table (if available).
	75	+ - Code Examples:
	76	+ - Ensure that all code examples are runnable and tested.
	77	+ - Provide sufficient context and explanation.
	78	+ - Indicate the environment or prerequisites required for code running.
	79	+ - Punctuation and Format:
	80	+ - When mixing Chinese and English, use full-width punctuation. Punctuation marks must conform to the Chinese/English context.
	81	+ - Use appropriate hierarchy for titles (#, ##, ###).
	82	+ - Use lists and tables to organize complex information.
	83	+ - Links: Use descriptive link text, avoid "click here", and ensure that link resources are authentic and reliable.
	84	+ - Images:
	85	+ - Common Formats: We recommend the png format. Try to keep the style consistent with existing images.
	86	+ - Resolution and Clarity: Must be clear and of moderate size. Avoid blurring or excessive compression.
	87	+ - File Size: We do not recommend that a single image exceeds 10M.
	88	+ - Copyright: For all quoted images, literature, and other resources, please ensure compliance.
	89	+
	90	+## Get Help
	91	+
	92	+If you have any questions during the contribution process:
	93	+
	94	+1. Check Existing Documentation: If there are problems with templates or standards, please first check the existing guides, API documentation, or README of the project.
	95	+2. Initiate Discussion: You can create a new Issue or leave a message directly in the relevant Issue or PR.
	96	+
	97	+## Operator README Template
	98	+
	99	+For `experimental` newly contributed operators, the operator README is a required document deliverable. You can refer to the simple template provided in this section. You are also supported to expand the content based on this template.
	100	+
	101	+- Document Format: We recommend the Markdown file format. You can use native or Html syntax. Please ensure that all syntax conforms to official standards.
	102	+- Document Function: Clearly explain the operator function, implementation principle, parameter specifications, and operator invocation methods.
	103	+- Chapter Title: Prioritize using template chapter names (such as Function Description, Parameter Description, and so on). The title hierarchy is ##. If there are special cases, please increase the hierarchy in order. Support chapter customization and expansion. Optional chapters can be presented as needed.
	104	+- Content Requirements: For the writing goals and writing standards of each chapter, please refer to the detailed description below. For easy understanding, we will take the [AddExample](../examples/add_example/README.md) operator README as an example.
	105	+
	106	+### Product Support Status
	107	+
	108	+> Writing Standard: We recommend the table format. List the supported product models and mark them with √. For product form introduction, see [Ascend Product Form Description](https://www.hiascend.com/document/detail/en/AscendFAQ/ProduTech/productform/hardwaredesc_0001.html).
	109	+
	110	+\| Product \| Support Status \|
	111	+\| :----------------------------------------- \| :------:\|
	112	+\| Atlas A3 Training Series Products/Atlas A3 Inference Series Products \| √ \|
	113	+\| Atlas A2 Training Series Products/Atlas A2 Inference Series Products \| √ \|
	114	+
	115	+### Function Description
	116	+
	117	+> [!NOTE]
	118	+>
	119	+> Writing Goal: Clarify the operator function, calculation principle, parameter specifications, invocation methods, usage scenarios, and so on.
	120	+>
	121	+> Writing Standard: We recommend the unordered list format, which generally includes the following dimensions
	122	+>
	123	+> - Operator Function (Required): Please explain the function concisely and clearly in one sentence.
	124	+> - Calculation Formula (Optional): For complex functions, you can use formulas to introduce the operator implementation principle or calculation process in different scenarios.
	125	+> - Other Dimensions (Optional): Support unordered list expansion. Please customize according to the actual situation, such as calculation examples, flowcharts, and so on.
	126	+
	127	+- Operator Function: Complete tensor addition calculation.
	128	+- Calculation Formula:
	129	+ $$
	130	+ y = x1 + x2
	131	+ $$
	132	+
	133	+### Parameter Description
	134	+
	135	+> [!NOTE]
	136	+>
	137	+> Writing Goal: Clarify the meaning, function, specifications, and other information of the parameters defined by the operator.
	138	+>
	139	+> Writing Standard: Use the table format, which generally includes the following dimensions
	140	+>
	141	+> - Parameter Name: Explain the parameters in the operator definition file. Keep the order consistent, such as `op_host/add_example_def.cpp` or `op_graph/add_example_proto.h`.
	142	+> - Input/Output/Attribute: Clarify the parameter positioning. The default is required. If it is optional, it is generally an optional input/optional output/optional attribute.
	143	+> - Description: Provide the parameter meaning, function, usage scenario, and other introductions, including the mapping relationship with the above formula variables.
	144	+> - Data Type: The data type supported by the parameter. The tensor data type is generally in the `DT_XXX` form. For easy writing, you can omit the `DT_` prefix.
	145	+> - Data Format: The data layout mode supported by the parameter. The tensor format is generally in the `FORMAT_xxx` form. For easy writing, you can omit the `FORMAT_` prefix.
	146	+> - Other Dimensions (Optional): Support table field expansion. Please customize according to the actual situation, such as shape specifications.
	147	+
	148	+\|Parameter Name\|Input/Output/Attribute\|Description\|Data Type\|Data Format\|
	149	+\|-----\|-----------\|----\|---------\|------\|
	150	+\|x1\|Input\|Indicates the first tensor of the add_example calculation, that is, `x1` in the formula.\|FLOAT, FLOAT16, INT32\|ND\|
	151	+\|x2\|Input\|Indicates the second tensor of the add_example calculation, that is, `x2` in the formula.\|The data type is consistent with x1\|ND\|
	152	+\|y\| Output \| Indicates the result tensor of the add_example calculation, that is, `y` in the formula. \|FLOAT, FLOAT16, INT32\|ND\|
	153	+
	154	+### Constraint Description (Optional)
	155	+
	156	+> [!NOTE]
	157	+>
	158	+> Writing Goal: Clarify the precautions during operator use, such as parameter combination constraints, applicable scenarios, impact on business, operator performance or precision, and so on.
	159	+>
	160	+> Writing Standard: This chapter is optional. If there are no constraints, this chapter content does not need to be presented; if there are, please use the unordered list format.
	161	+
	162	+None
	163	+
	164	+### Invocation Description
	165	+
	166	+> [!NOTE]
	167	+>
	168	+> Writing Goal: Provide the operator invocation method. Try to provide sample code that can be directly copied and run for quick verification.
	169	+>
	170	+> Writing Standard: We recommend the table format. If the content is complex, you can use other forms.
	171	+>
	172	+> - Invocation Method: Support aclnn, graph mode, and other invocation methods. You can also customize. Please provide at least one method.
	173	+> - Sample Code: Please provide invocation example code in the `examples` directory of the operator, such as `examples/test_aclnn_add_example.cpp`. The file naming rule is test_${invoke_mode}_${op_name}. ${invoke_mode} indicates the invocation method, and ${op_name} indicates the operator name.
	174	+> - Description: Supplementary descriptions for different invocation methods, such as invocation scenarios, invocation principles, compilation and running guidance, and so on. Please customize according to the actual situation.
	175	+
	176	+<table><thead>
	177	+ <tr>
	178	+ <th>Invocation Method</th>
	179	+ <th>Invocation Sample</th>
	180	+ <th>Description</th>
	181	+ </tr></thead>
	182	+<tbody>
	183	+ <tr>
	184	+ <td>aclnn Invocation</td>
	185	+ <td><a href="../examples/add_example/examples/test_aclnn_add_example.cpp">test_aclnn_add_example</a></td>
	186	+ <td rowspan="2">See <a href="./en/invocation/quick_op_invocation.md">Operator Invocation</a> to complete operator compilation and verification.</td>
	187	+ </tr>
	188	+ <tr>
	189	+ <td>Graph Mode Invocation</td>
	190	+ <td><a href="../examples/add_example/examples/test_geir_add_example.cpp">test_geir_add_example</a></td>
	191	+ </tr>
	192	+</tbody>
	193	+</table>
	194	+
	195	+### Reference Resources (Optional)
	196	+
	197	+> [!NOTE]
	198	+>
	199	+> Writing Goal: Provide other supplementary introductions besides operator function, specifications, and invocation, such as operator design documents (Tiling/Kernel design), reference literature, and so on.
	200	+>
	201	+> Writing Standard: This chapter is optional. If there are no constraints, this chapter content does not need to be presented; if there are, please use the unordered list format.
	202	+
	203	+None

Adocs/README_en.md+47-0

@@ -0,0 +1,47 @@
	1	+# Project Documentation
	2	+
	3	+## Directory Description
	4	+
	5	+The key directory structure is as follows:
	6	+
	7	+```text
	8	+├── context # public directory, storing documents including basic concepts, project directory introduction, build parameter description, and so on
	9	+│ ├── dir_structure.md
	10	+│ ├── build.md
	11	+│ └── ...
	12	+├── debug # operator debugging and tuning document directory
	13	+│ ├── op_debug_prof.md
	14	+│ └── ...
	15	+├── develop # operator development document directory (including AI Core and AI CPU operator development guides)
	16	+│ ├── aicore_develop_guide.md
	17	+│ ├── aicpu_develop_guide.md
	18	+│ └── ...
	19	+├── figures # image directory
	20	+├── invocation # operator invocation document directory (including aclnn invocation, graph mode invocation, and so on)
	21	+│ ├──op_invocation.md
	22	+│ └── ...
	23	+├── op_api_list.md # complete operator interface list (aclnn)
	24	+├── op_list.md # complete operator list
	25	+└── README
	26	+```
	27	+
	28	+## Document Description
	29	+
	30	+The complete documentation of the project is as follows. Please obtain the corresponding content as needed.
	31	+
	32	+\| Document \| Description \|
	33	+\| ------------------------------------------------ \| ------------------------------------------------------------ \|
	34	+\| [Operator List](zh/op_list.md) \| Introduces the list of all operators included in the project. \|
	35	+\| [aclnn List](zh/op_api_list.md) \| Introduces all operator APIs included in the project. You can directly invoke operators through this API. \|
	36	+\| [Environment Deployment](en/context/quick_install.md) \| Introduces the basic environment setup process, including the acquisition and installation of software packages and third-party dependencies in different scenarios. \|
	37	+\| [Operator Invocation](en/invocation/quick_op_invocation.md) \| Introduces how to compile source code and execute operators, including operator package compilation, operator sample execution, UT execution, and so on in different scenarios. \|
	38	+\| [Operator Development](en/develop/aicore_develop_guide.md) \| Introduces how to develop new operators based on this project engineering, including operator prototype definition, Tiling implementation, Kernel implementation, and so on. \|
	39	+\| [Operator Invocation Methods](en/invocation/op_invocation.md) \| Introduces multiple operator invocation methods and invocation processes, such as aclnn invocation, graph mode invocation, and so on. \|
	40	+\| [Operator Debugging and Tuning](en/debug/op_debug_prof.md) \| Introduces common operator debugging and tuning methods. \|
	41	+
	42	+## Appendix
	43	+
	44	+\| Document \| Description \|
	45	+\| ----------------------------------- \| ------------------------------------------------------------ \|
	46	+\| [Operator Basic Concepts](en/context/basic_concept.md) \| Introduces basic concepts and terminology in the operator domain, such as quantization/sparse, data type, data format, and so on. \|
	47	+\| [build Parameter Description](en/context/build.md) \| Introduces the functions and parameter meanings of the build.sh script in this project. \|

Adocs/en/context/aclnn_return_code.md+161-0

@@ -0,0 +1,161 @@
	1	+# aclnn Return Codes
	2	+
	3	+When calling aclnn APIs, common interface return codes are shown in [Table 1](#table1).
	4	+For abnormal status code values, you can use the aclGetRecentErrMsg interface (refer to [ACL API (C)](https://www.hiascend.com/document/detail/en/canncommercial/latest/API/appdevgapi/aclcppdevg_03_0004.html)) to obtain exception information. You can troubleshoot the problem based on the error message or contact technical support.
	5	+
	6	+Table 1 Return Status Codes
	7	+
	8	+<a name="table1"></a>
	9	+<table><thead align="left"><tr><th class="cellrowborder" valign="top" width="30.543054305430545%" id="mcps1.2.4.1.1"><p>Status Code Name</p>
	10	+</th>
	11	+<th class="cellrowborder" valign="top" width="15.971597159715973%" id="mcps1.2.4.1.2"><p>Status Code Value</p>
	12	+</th>
	13	+<th class="cellrowborder" valign="top" width="53.48534853485349%" id="mcps1.2.4.1.3"><p>Status Code Description</p>
	14	+</th>
	15	+</tr>
	16	+</thead>
	17	+<tbody><tr><td class="cellrowborder" valign="top" width="30.543054305430545%" headers="mcps1.2.4.1.1 "><p>ACLNN_SUCCESS</p>
	18	+</td>
	19	+<td class="cellrowborder" valign="top" width="15.971597159715973%" headers="mcps1.2.4.1.2 "><p>0</p>
	20	+</td>
	21	+<td class="cellrowborder" valign="top" width="53.48534853485349%" headers="mcps1.2.4.1.3 "><p>Success.</p>
	22	+</td>
	23	+</tr>
	24	+<tr><td class="cellrowborder" valign="top" width="30.543054305430545%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_PARAM_NULLPTR</p>
	25	+</td>
	26	+<td class="cellrowborder" valign="top" width="15.971597159715973%" headers="mcps1.2.4.1.2 "><p>161001</p>
	27	+</td>
	28	+<td class="cellrowborder" valign="top" width="53.48534853485349%" headers="mcps1.2.4.1.3 "><p>Parameter validation error, illegal nullptr exists in parameters.</p>
	29	+</td>
	30	+</tr>
	31	+<tr><td class="cellrowborder" valign="top" width="30.543054305430545%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_PARAM_INVALID</p>
	32	+</td>
	33	+<td class="cellrowborder" valign="top" width="15.971597159715973%" headers="mcps1.2.4.1.2 "><p>161002</p>
	34	+</td>
	35	+<td class="cellrowborder" valign="top" width="53.48534853485349%" headers="mcps1.2.4.1.3 "><p>Parameter validation error, such as two input data types not satisfying the input type promotion relationship.</p>
	36	+</td>
	37	+</tr>
	38	+<tr><td class="cellrowborder" valign="top" width="30.543054305430545%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_RUNTIME_ERROR</p>
	39	+</td>
	40	+<td class="cellrowborder" valign="top" width="15.971597159715973%" headers="mcps1.2.4.1.2 "><p>361001</p>
	41	+</td>
	42	+<td class="cellrowborder" valign="top" width="53.48534853485349%" headers="mcps1.2.4.1.3 "><p>API internally calls npu runtime interface abnormally.</p>
	43	+</td>
	44	+</tr>
	45	+<tr><td class="cellrowborder" valign="top" width="30.543054305430545%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER_XXX</p>
	46	+</td>
	47	+<td class="cellrowborder" valign="top" width="15.971597159715973%" headers="mcps1.2.4.1.2 "><p>561xxx</p>
	48	+</td>
	49	+<td class="cellrowborder" valign="top" width="53.48534853485349%" headers="mcps1.2.4.1.3 "><p>API internal exception occurred.</p>
	50	+
	51	+</td>
	52	+</tr>
	53	+</tbody>
	54	+</table>
	55	+
	56	+For more information about ACLNN_ERR_INNER_XXX status codes, see [Table 2](#table2).
	57	+
	58	+Table 2 Exception Status Codes
	59	+
	60	+<a name="table2"></a>
	61	+<table><thead align="left"><tr><th class="cellrowborder" valign="top" width="30.183018301830185%" id="mcps1.2.4.1.1"><p>Status Code Name</p>
	62	+</th>
	63	+<th class="cellrowborder" valign="top" width="16.521652165216523%" id="mcps1.2.4.1.2"><p>Status Code Value</p>
	64	+</th>
	65	+<th class="cellrowborder" valign="top" width="53.295329532953296%" id="mcps1.2.4.1.3"><p>Status Code Description</p>
	66	+</th>
	67	+</tr>
	68	+</thead>
	69	+<tbody><tr><td class="cellrowborder" valign="top" width="30.183018301830185%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER</p>
	70	+</td>
	71	+<td class="cellrowborder" valign="top" width="16.521652165216523%" headers="mcps1.2.4.1.2 "><p>561000</p>
	72	+</td>
	73	+<td class="cellrowborder" valign="top" width="53.295329532953296%" headers="mcps1.2.4.1.3 "><p>Internal exception: API internal exception occurred.</p>
	74	+</td>
	75	+</tr>
	76	+<tr><td class="cellrowborder" valign="top" width="30.183018301830185%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER_INFERSHAPE_ERROR</p>
	77	+</td>
	78	+<td class="cellrowborder" valign="top" width="16.521652165216523%" headers="mcps1.2.4.1.2 "><p>561001</p>
	79	+</td>
	80	+<td class="cellrowborder" valign="top" width="53.295329532953296%" headers="mcps1.2.4.1.3 "><p>Internal exception: API internal output shape deduction error occurred.</p>
	81	+</td>
	82	+</tr>
	83	+<tr><td class="cellrowborder" valign="top" width="30.183018301830185%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER_TILING_ERROR</p>
	84	+</td>
	85	+<td class="cellrowborder" valign="top" width="16.521652165216523%" headers="mcps1.2.4.1.2 "><p>561002</p>
	86	+</td>
	87	+<td class="cellrowborder" valign="top" width="53.295329532953296%" headers="mcps1.2.4.1.3 "><p>Internal exception: API internal tiling for npu kernel exception occurred.</p>
	88	+</td>
	89	+</tr>
	90	+<tr><td class="cellrowborder" valign="top" width="30.183018301830185%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER_FIND_KERNEL_ERROR</p>
	91	+</td>
	92	+<td class="cellrowborder" valign="top" width="16.521652165216523%" headers="mcps1.2.4.1.2 "><p>561003</p>
	93	+</td>
	94	+<td class="cellrowborder" valign="top" width="53.295329532953296%" headers="mcps1.2.4.1.3 "><p>Internal exception: API internal npu kernel lookup exception (possibly because operator binary package is not installed).</p>
	95	+</td>
	96	+</tr>
	97	+<tr><td class="cellrowborder" valign="top" width="30.183018301830185%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER_CREATE_EXECUTOR</p>
	98	+</td>
	99	+<td class="cellrowborder" valign="top" width="16.521652165216523%" headers="mcps1.2.4.1.2 "><p>561101</p>
	100	+</td>
	101	+<td class="cellrowborder" valign="top" width="53.295329532953296%" headers="mcps1.2.4.1.3 "><p>Internal exception: API internal aclOpExecutor creation failed (possibly due to operating system exception).</p>
	102	+</td>
	103	+</tr>
	104	+<tr><td class="cellrowborder" valign="top" width="30.183018301830185%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER_NOT_TRANS_EXECUTOR</p>
	105	+</td>
	106	+<td class="cellrowborder" valign="top" width="16.521652165216523%" headers="mcps1.2.4.1.2 "><p>561102</p>
	107	+</td>
	108	+<td class="cellrowborder" valign="top" width="53.295329532953296%" headers="mcps1.2.4.1.3 "><p>Internal exception: API internal uniqueExecutor ReleaseTo not called.</p>
	109	+</td>
	110	+</tr>
	111	+<tr><td class="cellrowborder" valign="top" width="30.183018301830185%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER_NULLPTR</p>
	112	+</td>
	113	+<td class="cellrowborder" valign="top" width="16.521652165216523%" headers="mcps1.2.4.1.2 "><p>561103</p>
	114	+</td>
	115	+<td class="cellrowborder" valign="top" width="53.295329532953296%" headers="mcps1.2.4.1.3 "><p>Internal exception: aclnn API internal exception occurred, nullptr exception appeared.</p>
	116	+</td>
	117	+</tr>
	118	+<tr><td class="cellrowborder" valign="top" width="30.183018301830185%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER_WRONG_ATTR_INFO_SIZE</p>
	119	+</td>
	120	+<td class="cellrowborder" valign="top" width="16.521652165216523%" headers="mcps1.2.4.1.2 "><p>561104</p>
	121	+</td>
	122	+<td class="cellrowborder" valign="top" width="53.295329532953296%" headers="mcps1.2.4.1.3 "><p>Internal exception: aclnn API internal exception occurred, operator attribute count exception.</p>
	123	+</td>
	124	+</tr>
	125	+<tr><td class="cellrowborder" valign="top" width="30.183018301830185%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER_KEY_CONFILICT</p>
	126	+</td>
	127	+<td class="cellrowborder" valign="top" width="16.521652165216523%" headers="mcps1.2.4.1.2 "><p>561105</p>
	128	+</td>
	129	+<td class="cellrowborder" valign="top" width="53.295329532953296%" headers="mcps1.2.4.1.3 "><p>Internal exception: aclnn API internal exception occurred, operator kernel matching hash key conflict.</p>
	130	+</td>
	131	+</tr>
	132	+<tr><td class="cellrowborder" valign="top" width="30.183018301830185%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER_INVALID_IMPL_MODE</p>
	133	+</td>
	134	+<td class="cellrowborder" valign="top" width="16.521652165216523%" headers="mcps1.2.4.1.2 "><p>561106</p>
	135	+</td>
	136	+<td class="cellrowborder" valign="top" width="53.295329532953296%" headers="mcps1.2.4.1.3 "><p>Internal exception: aclnn API internal exception occurred, operator implementation mode parameter error.</p>
	137	+</td>
	138	+</tr>
	139	+<tr><td class="cellrowborder" valign="top" width="30.183018301830185%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER_OPP_PATH_NOT_FOUND</p>
	140	+</td>
	141	+<td class="cellrowborder" valign="top" width="16.521652165216523%" headers="mcps1.2.4.1.2 "><p>561107</p>
	142	+</td>
	143	+<td class="cellrowborder" valign="top" width="53.295329532953296%" headers="mcps1.2.4.1.3 "><p>Internal exception: aclnn API internal exception occurred, environment variable ASCEND_OPP_PATH to be configured not detected.</p>
	144	+</td>
	145	+</tr>
	146	+<tr><td class="cellrowborder" valign="top" width="30.183018301830185%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER_LOAD_JSON_FAILED</p>
	147	+</td>
	148	+<td class="cellrowborder" valign="top" width="16.521652165216523%" headers="mcps1.2.4.1.2 "><p>561108</p>
	149	+</td>
	150	+<td class="cellrowborder" valign="top" width="53.295329532953296%" headers="mcps1.2.4.1.3 "><p>Internal exception: aclnn API internal exception occurred, failed to load operator information json file in operator kernel library.</p>
	151	+</td>
	152	+</tr>
	153	+<tr><td class="cellrowborder" valign="top" width="30.183018301830185%" headers="mcps1.2.4.1.1 "><p>ACLNN_ERR_INNER_JSON_VALUE_NOT_FOUND</p>
	154	+</td>
	155	+<td class="cellrowborder" valign="top" width="16.521652165216523%" headers="mcps1.2.4.1.2 "><p>561109</p>
	156	+</td>
	157	+<td class="cellrowborder" valign="top" width="53.295329532953296%" headers="mcps1.2.4.1.3 "><p>Internal exception: aclnn API internal exception occurred, failed to load a field in operator information json file in operator kernel library.</p>
	158	+</td>
	159	+</tr>
	160	+</tbody>
	161	+</table>

Adocs/en/context/basic_concept.md+12-0

@@ -0,0 +1,12 @@
	1	+# Basic Concepts
	2	+
	3	+ - [Two Phase API](./two_phase_api.md)
	4	+ - [Data Structure](./data_structure.md)
	5	+ - [Data Type](./data_type.md)
	6	+ - [Data Format](./data_format.md)
	7	+ - [Non Contiguous Tensor](./non_contiguous_tensor.md)
	8	+ - [Broadcast Relationship](./broadcast_relationship.md)
	9	+ - [Decuction Relationship](./decuction_relationship.md)
	10	+ - [Conversion Relationship](./conversion_relationship.md)
	11	+ - [Quant more Introduction](./quant_more_introduction.md)
	12	+ - [Sparse Mode Introduction](./sparse_mode_introduction.md)

Adocs/en/context/broadcast_relationship.md+55-0

@@ -0,0 +1,55 @@
	1	+# Broadcast Relationships
	2	+
	3	+## Broadcast Concept
	4	+
	5	+Broadcast describes how operators handle tensors (or arrays) of different shapes during computation. In most cases, tensors (or arrays) of different shapes are allowed to automatically expand their shapes during element operations to make their dimensions compatible. Usually, smaller tensors (or arrays) are "broadcast" to larger tensors (or arrays).
	6	+
	7	+Currently, many CANN operator API parameter shapes support broadcasting, which can appropriately improve calculation efficiency and reduce memory usage (especially in large-scale data scenarios). For more detailed broadcast technology introduction, refer to the [NumPy](https://numpy.org/doc/stable/user/basics.broadcasting.html) official website.
	8	+
	9	+## Broadcast Rules
	10	+
	11	+When performing broadcast calculations, you generally need to understand the following rules:
	12	+
	13	+- Rule 1: If the number of dimensions between arrays is inconsistent, all arrays align to the array with the longest shape, and the insufficient part of the shape is padded with 1 on the left until the number of dimensions is the same.
	14	+
	15	+ > Note:
	16	+ > - Example 1: Number of Dimensions refers to the dimension count of the tensor (or array) corresponding to the shape. For example, x.shape=(1,1,2,4), the number of dimensions is 4.
	17	+ > - Example 2: For example, when calculating a+b, where a.shape=(2, 2, 3) and b.shape=(2, 3), array b will be broadcast to b.shape=(1, 2, 3).
	18	+
	19	+- Rule 2: If the number of dimensions between arrays is consistent, and a certain dimension of an array is 1, then the array with dimension 1 will be stretched to match the corresponding dimension shape of the other array.
	20	+
	21	+ > Note:
	22	+ > In this scenario, you only need to ensure broadcasting in a certain dimension. For example, when calculating a+b, where a.shape=(1, 3) and b.shape=(3, 1), both arrays will be broadcast to a.shape=(3, 3) and b.shape=(3, 3).
	23	+
	24	+- Rule 3: If the number of dimensions between arrays is inconsistent, and neither has a dimension equal to 1, an error will be reported.
	25	+
	26	+Based on the above rules, the broadcast process generally first expands dimensions according to Rule 1, and then stretches the shape according to Rule 2. Specific examples are as follows:
	27	+
	28	+```text
	29	+Assuming a.shape=(2,2,3), values look like:
	30	+[[[1 2 3],[4 5 6]],
	31	+ [[1 2 3],[4 5 6]]]
	32	+Assuming b.shape=(2,3), values look like:
	33	+[[1 2 3],
	34	+ [-1 -2 -3]]
	35	+According to Rule 1, expand dimensions, b.shape=(1,2,3), values are:
	36	+[[[1 2 3],
	37	+ [-1 -2 -3]]]
	38	+According to Rule 2, stretch shape, b.shape=(2,2,3), values are:
	39	+[[[1 2 3],[-1 -2 -3]],
	40	+ [[1 2 3],[-1 -2 -3]]]
	41	+Calculate a+b, actual result is:
	42	+ [[[2 4 6],[3 3 3]],
	43	+ [[2 4 6],[3 3 3]]]
	44	+```
	45	+
	46	+## Limitations
	47	+
	48	+When the data types of two inputs a and b that satisfy the broadcast relationship, or the deduced data types, are among COMPLEX64, COMPLEX128, DOUBLE, INT16, UINT16, or UINT64, in addition to satisfying the above broadcast rules, the following conditions must also be met, otherwise the broadcast will fail and cause the operator execution to report an error.
	49	+
	50	+Condition: The merged dimension of consecutive axes that need broadcasting and consecutive axes that do not need broadcasting must be less than 6.
	51	+
	52	+Examples:
	53	+
	54	+- When a.shape=(5, 1, 5, 1, 5, 1) and b.shape=(5, 5, 5, 5, 5, 5), there are no axes that need to be merged, the final dimension is 6, and the broadcast reports an error.
	55	+- When a.shape=(5, 1, 5, 5, 1, 1) and b.shape=(5, 5, 5, 5, 5, 5), broadcasting is not needed in dimensions 2 and 3, and broadcasting is needed in dimensions 4 and 5. They are merged separately and continuously, and the merged dimension is 4, so the broadcast succeeds.

Adocs/en/context/build.md+70-0

@@ -0,0 +1,70 @@
	1	+# build Parameter Description
	2	+
	3	+## Introduction
	4	+
	5	+build.sh is the build script of this project, located in the project root directory by default. Its function is to automatically compile, link, and configure the source code, and finally generate executable files, library files, or other target files that can be installed or run directly. Specifically, the script configures different parameters to achieve multiple functions, including building multiple target libraries (such as libophost_nn.so), compiling operator packages, executing unit tests, etc.
	6	+
	7	+## Usage
	8	+
	9	+1. Configure Environment Variables
	10	+
	11	+ Complete the basic environment setup by referring to [Environment Deployment](../context/quick_install.md).
	12	+
	13	+ ```bash
	14	+ # Default path installation, taking root user as an example
	15	+ source /usr/local/Ascend/cann/set_env.sh
	16	+ ```
	17	+
	18	+2. Build Command Format
	19	+
	20	+ Taking the compile operator package command as an example, the format is as follows, where `--vendor_name` and `--ops` are optional in this scenario.
	21	+
	22	+ ```bash
	23	+ bash build.sh --pkg --soc=${soc_version} [--vendor_name=${vendor_name}] [--ops=${op_list}]
	24	+ ```
	25	+
	26	+ For the meaning of all parameters, refer to the parameter description section below. Choose the appropriate parameters according to the actual situation.
	27	+
	28	+## Parameter Description
	29	+
	30	+build.sh supports multiple functions. You can view all function parameters through the following command.
	31	+
	32	+```bash
	33	+bash build.sh --help
	34	+```
	35	+
	36	+\| Parameter Name \| Optional/Required \| Parameter Description \|
	37	+\|------------------\|--------\|-----------------------------------------------------------------------------\|
	38	+\| -j${n} \| Optional \| Specifies the number of compilation threads. ${n} is the specific number of threads. The default value is 8 (such as -j8). If the number of threads exceeds the number of CPU cores, it will be automatically adjusted to the number of CPU cores. \|
	39	+\| -v \| Optional \| View CMake compilation configuration information. \|
	40	+\| -O${n} \| Optional \| Specifies the compilation optimization level. Supports O0/O1/O2/O3 (such as -O3). ${n} is the optimization level identifier. \|
	41	+\| -u \| Optional \| Enables unit test (UT) compilation mode and compiles all UT targets. \|
	42	+\| --help, -h \| Optional \| Prints script usage help information. \|
	43	+\| --ops \| Optional \| Specifies the operators to be compiled, such as mat_mul_v3, mse_loss. Multiple operators are separated by English commas ",". Cannot be used with --ophost and --opapi at the same time. \|
	44	+\| --soc \| Optional \| Specifies the NPU model. Only 1 NPU model is supported per compilation. \|
	45	+\| --jit \| Optional \| In the static graph scenario, when compiling the `cann-${soc_name}-ops-nn_${cann_version}_linux-${arch}.run` package, you do not need to compile the operator binary files (the graph runtime will compile online). You can configure this option to improve compilation speed. \|
	46	+\| --static \| Optional \| When configured, it means generating a static library file, including libcann_nn_static.a and aclnn interface header files. Combined with the --pkg parameter, it generates a static library compressed package.\|
	47	+\| --vendor_name \| Optional \| Specifies the name of the custom operator package. The default value is custom. \|
	48	+\| --build-type \| Optional \| Enables debug mode. Optional types: Release/Debug. The default is Release. When the value is Debug, it cannot be used with --mssanitizer, --oom, --dump_cce at the same time \|
	49	+\| --debug \| Optional \| Enables debug mode. \|
	50	+\| --cov \| Optional \| Reserved parameter, developers do not need to pay attention for now. \|
	51	+\| --noexec \| Optional \| Only compiles the unit test binary file without automatically executing the compiled UT executable file. \|
	52	+\| --opkernel \| Optional \| Compiles the binary kernel. \|
	53	+\| --pkg \| Optional \| Generates the installation package. Cannot be used with -u (UT mode) or --ophost, --opapi at the same time. \|
	54	+\| --asan \| Optional \| Enables host-side ASAN (AddressSanitizer) memory detection function. \|
	55	+\| --valgrind \| Optional \| Reserved parameter, developers do not need to pay attention for now. \|
	56	+\| --make_clean \| Optional \| Executes basic cleanup operations (cleans compilation products). The script exits after execution. \|
	57	+\| --make_clean_all \| Optional \| Executes complete cleanup operations (deletes all compilation-related files). The script exits after execution. \|
	58	+\| --ophost \| Optional \| Compiles the libophost_nn.so library. Cannot be used with --pkg, --ops at the same time. \|
	59	+\| --opapi \| Optional \| Compiles the libopapi_nn.so library. Cannot be used with --pkg, --ops at the same time. \|
	60	+\| --run_example \| Optional \| Compiles the sample of the specified operator and mode and executes the compiled executable file. Use --run_example --help to view the usage. \|
	61	+\| --genop \| Optional \| Creates the AI Core custom operator initial directory. \|
	62	+\| --genop_aicpu \| Optional \| Creates the AI CPU custom operator initial directory. \|
	63	+\| --experimental \| Optional \| Compiles user operators in the experimental directory. \|
	64	+\| --mssanitizer \| Optional \| Enables kernel-side mssanitizer memory detection function. \|
	65	+\| --oom \| Optional \| Enables kernel-side oom memory detection function. \|
	66	+\| --dump_cce \| Optional \| Enables kernel-side dump precompiled file function. \|
	67	+\| --cann_3rd_lib_path\| Optional \| The directory where third-party libraries are stored in the offline compilation scenario. \|
	68	+\| --simulator \| Optional \| Used in combination with --run_example to enable simulator mode to execute --run_example tasks. In simulator mode, the corresponding simulator library will be linked according to soc_version. \|
	69	+\| --bisheng_flags \| Optional \| Specifies the BiSheng compiler compilation parameters. Multiple compilation parameters are separated by English commas ",". Cannot be used with --mssanitizer, --oom, --dump_cce at the same time. \|
	70	+\| --kernel_template_input \| Optional \| Specifies the tilingKey template when compiling the kernel. Only one template can be specified. Used with --ops and only one operator can be specified. It will not compile the binary files of other operators that this operator depends on. \|

Adocs/en/context/compile_and_run_sample.md+143-0

@@ -0,0 +1,143 @@
	1	+# Compilation and Running Examples
	2	+
	3	+## Prerequisites
	4	+
	5	+- If you need to compile and execute operator APIs, ensure that the basic environment has been set up, including driver, firmware, CANN software package, ops package, etc.
	6	+- For the operator API calling process and compilation and running operations, refer to [Application Development (C&C++)](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/programug/acldevg/aclcppdevg_000006.html) under "Single Operator Invocation > Single Operator API Execution > Calling aclnn Interface Example Code".
	7	+
	8	+## Pre-compilation Preparation
	9	+
	10	+This chapter takes the development and runtime environment co-location scenario as an example, that is, the machine with AI processor serves as both the development environment and the runtime environment. In this scenario, code development and code running are on the same machine. Here we take the AddMatMul operator as an example. The calling logic, process, and compilation script of other operators are roughly the same as the AddMatMul operator. Please modify the API calling script (*.cpp) and compilation script (CMakeLists) according to the actual situation.
	11	+
	12	+- Example Code
	13	+
	14	+ The AddMatMul operator implements tensor addition operation, and the calculation formula is: out = β * self + α * (mat1 @ mat2). You can obtain the example code from the "Calling Example" section in [aclnnAddmm&aclnnInplaceAddmm.md](../../../matmul/mat_mul_v3/docs/aclnnAddmm&aclnnInplaceAddmm.md) and name the code file "test\_addmm.cpp".
	15	+
	16	+- CMakeLists File
	17	+
	18	+ The CMake file example is as follows. Please modify according to the actual situation:
	19	+
	20	+ ```bash
	21	+ # Copyright (c) Huawei Technologies Co., Ltd. 2025. All rights reserved.
	22	+
	23	+ # CMake lowest version requirement
	24	+ cmake_minimum_required(VERSION 3.14)
	25	+
	26	+ # Set project name
	27	+ project(ACLNN_EXAMPLE)
	28	+
	29	+ # Compile options
	30	+ add_compile_options(-std=c++11)
	31	+
	32	+ # Set compilation options
	33	+ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "./bin")
	34	+ set(CMAKE_CXX_FLAGS_DEBUG "-fPIC -O0 -g -Wall")
	35	+ set(CMAKE_CXX_FLAGS_RELEASE "-fPIC -O2 -Wall")
	36	+
	37	+ # Set executable file name (such as opapi_test) and specify the directory where the operator file *.cpp to be run is located
	38	+ add_executable(opapi_test
	39	+ test_addmm.cpp)
	40	+
	41	+ # Set ASCEND_PATH (CANN software package directory, please modify according to the actual path) and INCLUDE_BASE_DIR (header file directory)
	42	+ if(NOT "$ENV{ASCEND_CUSTOM_PATH}" STREQUAL "")
	43	+ set(ASCEND_PATH $ENV{ASCEND_CUSTOM_PATH})
	44	+ else()
	45	+ set(ASCEND_PATH "/usr/local/Ascend/cann")
	46	+ endif()
	47	+ set(INCLUDE_BASE_DIR "${ASCEND_PATH}/include")
	48	+ include_directories(
	49	+ ${INCLUDE_BASE_DIR}
	50	+ ${INCLUDE_BASE_DIR}/aclnn
	51	+ )
	52	+
	53	+ # Set linked library file path
	54	+ target_link_libraries(opapi_test PRIVATE
	55	+ ${ASCEND_PATH}/lib64/libascendcl.so
	56	+ ${ASCEND_PATH}/lib64/libnnopbase.so
	57	+ ${ASCEND_PATH}/lib64/libopapi_math.so
	58	+ ${ASCEND_PATH}/lib64/libopapi_nn.so)
	59	+
	60	+ # The executable file is in the bin directory under the CMakeLists file directory
	61	+ install(TARGETS opapi_test DESTINATION ${CMAKE_RUNTIME_OUTPUT_DIRECTORY})
	62	+ ```
	63	+
	64	+ For operators that combine collective communication and MatMul calculation, and run in parallel, they are collectively called MC2 operators (communication-computation fusion operators), including AllGatherMatmul, AlltoAllAllGatherBatchMatMul, BatchMatMulReduceScatterAlltoAll, MatmulAllReduce, MatmulAllReduceAddRmsNorm, MatmulReduceScatter, etc. When calling such operator APIs, multi-threading and HCCL (Huawei Collective Communication Library) are generally involved. Therefore, the CMake file needs to additionally import the following content, otherwise compilation will fail.
	65	+
	66	+ ```bash
	67	+ # Set linked library file path
	68	+ find_package(Threads REQUIRED)
	69	+ target_link_libraries(opapi_test PRIVATE
	70	+ ${ASCEND_PATH}/lib64/libascendcl.so
	71	+ ${ASCEND_PATH}/lib64/libnnopbase.so
	72	+ ${ASCEND_PATH}/lib64/libopapi_math.so
	73	+ ${ASCEND_PATH}/lib64/libopapi_nn.so
	74	+ ${ASCEND_PATH}/lib64/libhccl.so # Collective communication library file
	75	+ ${CMAKE_THREAD_LIBS_INIT}) # Library file that multi-threading depends on
	76	+ ```
	77	+
	78	+ Where "find_package(Threads REQUIRED)" is a CMake command used to find the thread library, which can automatically link the header files or indirectly dependent library files that the thread library depends on.
	79	+
	80	+## Compilation and Running
	81	+
	82	+ 1. Prepare the operator calling code (*.cpp) and compilation script (CMakeLists.txt) in advance.
	83	+ 2. Configure environment variables.
	84	+
	85	+ After installing the CANN software, log in to the environment as the CANN runtime user and execute the following command to make the environment variables effective.
	86	+
	87	+ ```bash
	88	+ source ${INSTALL_DIR}/set_env.sh
	89	+ ```
	90	+
	91	+ Where ${INSTALL_DIR} is the storage path after CANN software installation. Please replace according to the actual situation.
	92	+ 3. Compile and run.
	93	+ - Enter the directory where CMakeLists.txt is located and execute the following command to create a new build directory to store the generated compilation files.
	94	+
	95	+ ```bash
	96	+ mkdir -p build
	97	+ ```
	98	+
	99	+ - Enter the build directory, execute the cmake command to compile, and then execute the make command to generate the executable file.
	100	+
	101	+ ```bash
	102	+ cd build
	103	+ cmake ../ -DCMAKE_CXX_COMPILER=g++ -DCMAKE_SKIP_RPATH=TRUE
	104	+ make
	105	+ ```
	106	+
	107	+ After successful compilation, the opapi\_test executable file will be generated in the bin folder under the build directory.
	108	+
	109	+ - Enter the bin directory and run the executable file opapi_test.
	110	+
	111	+ ```bash
	112	+ cd bin
	113	+ ./opapi_test
	114	+ ```
	115	+
	116	+ Taking the running result of the AddMatMul operator as an example, the result after running is shown below:
	117	+
	118	+ ```bash
	119	+ result[0] is: 1.200000
	120	+ result[1] is: 2.200000
	121	+ result[2] is: 3.200000
	122	+ result[3] is: 5.400000
	123	+ result[4] is: 6.400000
	124	+ result[5] is: 7.400000
	125	+ result[6] is: 9.600000
	126	+ result[7] is: 10.600000
	127	+ ```
	128	+
	129	+ If the execution result reports an error and the expected result does not appear, you can use the aclGetRecentErrMsg interface to obtain the specific error information.
	130	+ Example of obtaining exception information when calling aclnnAddmmGetWorkspaceSize fails:
	131	+
	132	+ ```bash
	133	+ // self is nullptr
	134	+ ret = aclnnAddmmGetWorkspaceSize(self, mat1, mat2, beta, alpha, out, cubeMathType, &workspaceSize, &executor);
	135	+ CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnAddmmGetWorkspaceSize failed. ERROR: %d\n[ERROR msg]%s", ret, aclGetRecentErrMsg()); return ret);
	136	+ ```
	137	+
	138	+ The above null pointer construction problem obtains error information as shown below:
	139	+
	140	+ ```bash
	141	+ aclnnAddmmGetWorkspaceSize failed. ERROR: 161001
	142	+ [ERROR msg][PID:xxxx] xxx(timesamp) AclNN_Parameter_Error(EZ1001): Expected a proper Tensor but got null for argument addmmTennsor.self.
	143	+ ```

Adocs/en/context/conversion_relationship.md+15-0

@@ -0,0 +1,15 @@
	1	+# Type Conversion Relationships
	2	+
	3	+When the output aclTensor data type of an API (such as aclnnAdd, aclnnMul, etc.) is inconsistent with the calculation type after input data type promotion, the API internally converts the calculation result to the data type corresponding to the output type.
	4	+
	5	+Data type conversion must satisfy the following rules. Conversions that do not satisfy the rules cannot be performed, and parameter validation will fail when calling the API.
	6	+
	7	+ - Floating-point types: ACL\_FLOAT16, ACL\_FLOAT, ACL\_DOUBLE, ACL\_BF16.
	8	+ - Integer types: ACL\_INT8, ACL\_UINT8, ACL\_INT16, ACL\_UINT16, ACL\_INT32, ACL\_UINT32, ACL\_INT64, ACL\_UINT64.
	9	+ - Complex types: ACL\_COMPLEX64, ACL\_COMPLEX128.
	10	+ - Conversions between integer types are supported, as well as conversions to floating-point and complex types.
	11	+ - Conversions between floating-point types are supported, as well as conversions to complex types.
	12	+ - Conversions between complex types are supported.
	13	+ - BOOL supports conversion to integer, floating-point, and complex types.
	14	+
	15	+Except for the above scenarios, other conversion scenarios are not supported.

Adocs/en/context/data_format.md+36-0

@@ -0,0 +1,36 @@
	1	+# Data Formats
	2	+
	3	+Data format (format) is used to describe the business semantics of the axes of a multi-dimensional Tensor, representing the physical layout format of data, such as 1D, 2D, 3D, 4D, 5D, and so on. Generally, CNN (Convolutional Neural Networks) APIs require specific formats to be described.
	4	+
	5	+For the full range of data formats supported by aclTensor, refer to [ACL API (C)](https://www.hiascend.com/document/detail/en/canncommercial/latest/API/appdevgapi/aclcppdevg_03_0004.html) under "Data Types and Their Operation Interfaces > aclFormat".
	6	+
	7	+For an introduction to data format layout principles, refer to [Ascend C Operator Development Guide](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/programug/Ascendcopdevg/atlas_ascendc_map_10_0002.html) under "Concept Principles and Terminology > Neural Networks and Operators > Data Layout Formats".
	8	+
	9	+## Usage Instructions
	10	+
	11	+Currently, most operator APIs support the ND data format. For example, the aclnnAdd interface indicates that the supported data format is ND (that is, the rule of low-dimensional priority continuous layout for multi-dimensional Tensors). For aclnnConvolution, which is a CNN-type API, the input aclTensor is required to be set with a format that has business semantics, rather than the ND format. Such operators need to know the business semantics in the Tensor during the calculation process to perform the corresponding computation. For example, in 2D convolution, you need to know the correspondence between the Batch dimension, Channel dimension, Height dimension, Width dimension, and the Tensor dimensions.
	12	+
	13	+>Note:
	14	+>
	15	+>- For the parameter description of two-stage interfaces, to simplify the description, the original data format "ACL\_FORMAT\_XXXX_" is abbreviated as "_XXXX_".
	16	+>- The meaning of each dimension in the data format: N (Batch) represents the batch size, H (Height) represents the feature map height, W (Width) represents the feature map width, C (Channels) represents the feature map channels, D (Depth) represents the feature map depth, L (Length) represents the feature map length.
	17	+
	18	+## Common Data Formats
	19	+
	20	+When creating an aclTensor through the aclCreateTensor interface, you need to set the data format according to the API business requirements. The supported data formats are:
	21	+
	22	+ACL\_FORMAT\_ND, ACL\_FORMAT\_NCHW, ACL\_FORMAT\_NHWC, ACL\_FORMAT\_HWCN, ACL\_FORMAT\_NDHWC, ACL\_FORMAT\_NCDHW, ACL\_FORMAT\_NC, ACL\_FORMAT\_NCL.
	23	+
	24	+For non-ND Tensors, the Tensor dimension requirements are consistent with the format description. For example:
	25	+
	26	+- 5D Tensor: Requires ACL\_FORMAT\_NCDHW, ACL\_FORMAT\_NDHWC, or ACL\_FORMAT\_ND (if the API parameter description does not indicate support for ND, setting the ND format will result in an API validation error).
	27	+- 4D Tensor: Requires ACL\_FORMAT\_NCHW, ACL\_FORMAT\_NHWC, ACL\_FORMAT\_HWCN, or ACL\_FORMAT\_ND.
	28	+- 3D Tensor: Requires ACL\_FORMAT\_NCL or ACL\_FORMAT\_ND.
	29	+- 2D Tensor: Requires ACL\_FORMAT\_NC or ACL\_FORMAT\_ND.
	30	+- Other dimension Tensors: Require ACL\_FORMAT\_ND.
	31	+
	32	+## Private Data Formats
	33	+
	34	+In addition to the common data formats mentioned above, there are other data formats, such as ACL\_FORMAT\_NC1HWC0, ACL\_FORMAT\_FRACTAL\_Z, ACL\_FORMAT\_NC1HWC0\_C04, ACL\_FORMAT\_FRACTAL\_NZ, ACL\_FORMAT\_NDC1HWC0, ACL\_FORMAT\_FRACTAL\_Z\_3D, and so on.
	35	+
	36	+These formats are private formats of the NPU. Currently, most aclnn APIs do not support these formats. If an individual API declares supported data formats, refer to the actual description of that API.

Adocs/en/context/data_structure.md+79-0

@@ -0,0 +1,79 @@
	1	+# Data Structures
	2	+
	3	+This chapter provides the basic data structures required for calling CANN operator APIs. Developers do not need to focus on their internal implementation and can use them directly.
	4	+
	5	+Note that these basic data structures can be created through the "Public Interfaces" section in [Operator Library Interface](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/API/aolapi/operatorlist_00001.html), such as aclCreateTensor.
	6	+
	7	+- aclTensor
	8	+
	9	+ A structure defined by the framework to manage and store tensor data (such as multi-dimensional data like vectors and matrices). You can create this object through the aclCreateTensor interface.
	10	+
	11	+ ```bash
	12	+ typedef struct aclTensor aclTensor
	13	+ ```
	14	+
	15	+- aclScalar
	16	+
	17	+ A structure defined by the framework to manage and store scalar data (that is, a single value). You can create this object through the aclCreateScalar interface.
	18	+
	19	+ ```bash
	20	+ typedef struct aclScalar aclScalar
	21	+ ```
	22	+
	23	+- aclIntArray
	24	+
	25	+ An array structure defined by the framework to manage and store integer data. You can create this object through the aclCreateIntArray interface.
	26	+
	27	+ ```bash
	28	+ typedef struct aclIntArray aclIntArray
	29	+ ```
	30	+
	31	+- aclFloatArray
	32	+
	33	+ An array structure defined by the framework to manage and store float32 data. You can create this object through the aclCreateFloatArray interface.
	34	+
	35	+ ```bash
	36	+ typedef struct aclFloatArray aclFloatArray
	37	+ ```
	38	+
	39	+- aclBoolArray
	40	+
	41	+ An array structure defined by the framework to manage and store boolean data. You can create this object through the aclCreateBoolArray interface.
	42	+
	43	+ ```bash
	44	+ typedef struct aclBoolArray aclBoolArray
	45	+ ```
	46	+
	47	+- aclTensorList
	48	+
	49	+ An array structure defined by the framework to manage and store multiple tensor data. You can create this object through the aclCreateTensorList interface.
	50	+
	51	+ ```bash
	52	+ typedef struct aclTensorList aclTensorList
	53	+ ```
	54	+
	55	+- aclScalarList
	56	+
	57	+ An array structure defined by the framework to manage and store scalar data. You can create this object through the aclCreateScalarList interface.
	58	+
	59	+ ```bash
	60	+ typedef struct aclScalarList aclScalarList
	61	+ ```
	62	+
	63	+- aclOpExecutor
	64	+
	65	+ An executor data structure defined by the framework, which is a container used to execute operator calculations.
	66	+
	67	+ Typically, when calling the first-stage interface aclxxXxxGetWorkspaceSize, the framework automatically creates an aclOpExecutor; after calling the second-stage interface aclxxXxx, the object is automatically released.
	68	+
	69	+ ```bash
	70	+ typedef struct aclOpExecutor aclOpExecutor
	71	+ ```
	72	+
	73	+- aclrtStream
	74	+
	75	+ A stream processing data structure defined by the framework, used to manage and maintain the execution order of some asynchronous operations.
	76	+
	77	+ ```bash
	78	+ typedef void *aclrtStream
	79	+ ```

Adocs/en/context/data_type.md+37-0

@@ -0,0 +1,37 @@
	1	+# Data Types
	2	+
	3	+When creating an aclTensor through the aclCreateTensor interface, refer to [ACL API (C)](https://www.hiascend.com/document/detail/en/canncommercial/latest/API/appdevgapi/aclcppdevg_03_0004.html) for the full list of supported data types under "Data Types and Their Operation Interfaces > aclDataType".
	4	+
	5	+For the parameter description of two-stage interfaces, the supported data types will use the following abbreviated forms for convenience.
	6	+
	7	+Table 1 Data Type Abbreviations
	8	+
	9	+\| Original Data Type \| Abbreviation (case-insensitive) \|
	10	+\| :---------------: \| :----------------------: \|
	11	+\| ACL_FLOAT \| FLOAT or FLOAT32 \|
	12	+\| ACL_FLOAT16 \| FLOAT16 \|
	13	+\| ACL_INT8 \| INT8 \|
	14	+\| ACL_INT32 \| INT32 \|
	15	+\| ACL_UINT8 \| UINT8 \|
	16	+\| ACL_INT16 \| INT16 \|
	17	+\| ACL_UINT16 \| UINT16 \|
	18	+\| ACL_UINT32 \| UINT32 \|
	19	+\| ACL_INT64 \| INT64 \|
	20	+\| ACL_UINT64 \| UINT64 \|
	21	+\| ACL_DOUBLE \| DOUBLE or FLOAT64 \|
	22	+\| ACL_BOOL \| BOOL \|
	23	+\| ACL_STRING \| STRING \|
	24	+\| ACL_COMPLEX64 \| COMPLEX64 \|
	25	+\| ACL_COMPLEX128 \| COMPLEX128 \|
	26	+\| ACL_BF16 \| BF16 or BFLOAT16 \|
	27	+\| ACL_INT4 \| INT4 \|
	28	+\| ACL_UINT1 \| UINT1 \|
	29	+\| ACL_COMPLEX32 \| COMPLEX32 \|
	30	+\| ACL_HIFLOAT8 \| HIFLOAT8 \|
	31	+\| ACL_FLOAT8_E5M2 \| FLOAT8_E5M2 \|
	32	+\| ACL_FLOAT8_E4M3FN \| FLOAT8_E4M3FN \|
	33	+\| ACL_FLOAT8_E8M0 \| FLOAT8_E8M0 \|
	34	+\| ACL_FLOAT6_E3M2 \| FLOAT6_E3M2 \|
	35	+\| ACL_FLOAT6_E2M3 \| FLOAT6_E2M3 \|
	36	+\| ACL_FLOAT4_E2M1 \| FLOAT4_E2M1 \|
	37	+\| ACL_FLOAT4_E1M2 \| FLOAT4_E1M2 \|

Adocs/en/context/deduction_relationship.md+39-0

@@ -0,0 +1,39 @@
	1	+# Type Promotion Relationships
	2	+
	3	+## Promotion Rules
	4	+
	5	+When the input aclTensor data types of an API (such as aclnnAdd, aclnnMul, etc.) are inconsistent, the API internally deduces a data type and converts the input data to that data type for calculation.
	6	+
	7	+For the data types supported by aclTensor, refer to [Data Types](./data_type.md). Some of these types satisfy the following promotion rules, and the promotion principle is similar to PyTorch's [Type Promotion](https://pytorch.org/docs/stable/tensor_attributes.html#type-promotion-doc).
	8	+
	9	+> Note:
	10	+>
	11	+> - For convenience of description, the data types used in the table are abbreviated forms, representing: ACL\_FLOAT(f32), ACL\_FLOAT16(f16), ACL\_DOUBLE(f64), ACL\_BF16(bf16), ACL\_INT8(s8), ACL\_UINT8(u8), ACL\_INT16(s16), ACL\_UINT16(u16), ACL\_INT32(s32), ACL\_UINT32(u32), ACL\_INT64(s64), ACL\_UINT64(u64), ACL\_BOOL(bool), ACL\_COMPLEX32(c32), ACL\_COMPLEX64(c64), ACL\_COMPLEX128(c128).
	12	+> - The table header and the leftmost column represent the two input data types to be deduced, and the corresponding position in the table represents the deduced data type.
	13	+> - The cross mark (×) in the table indicates that these two types cannot perform promotion calculation.
	14	+
	15	+Table 1 Data Type Promotion Relationships
	16	+
	17	+\| Data Type \| f32 \| f16 \| f64 \| bf16 \| s8 \| u8 \| s16 \| u16 \| s32 \| u32 \| s64 \| u64 \| bool \| c32 \| c64 \| c128 \|
	18	+\| :------: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \|
	19	+\| f32 \| f32 \| f32 \| f64 \| f32 \| f32 \| f32 \| f32 \| × \| f32 \| × \| f32 \| × \| f32 \| c64 \| c64 \| c128 \|
	20	+\| f16 \| f32 \| f16 \| f64 \| f32 \| f16 \| f16 \| f16 \| × \| f16 \| × \| f16 \| × \| f16 \| c32 \| c64 \| c128 \|
	21	+\| f64 \| f64 \| f64 \| f64 \| f64 \| f64 \| f64 \| f64 \| × \| f64 \| × \| f64 \| × \| f64 \| c128 \| c128 \| c128 \|
	22	+\| bf16 \| f32 \| f32 \| f64 \| bf16 \| bf16 \| bf16 \| bf16 \| × \| bf16 \| × \| bf16 \| × \| bf16 \| c32 \| c64 \| c128 \|
	23	+\| s8 \| f32 \| f16 \| f64 \| bf16 \| s8 \| s16 \| s16 \| × \| s32 \| × \| s64 \| × \| s8 \| c32 \| c64 \| c128 \|
	24	+\| u8 \| f32 \| f16 \| f64 \| bf16 \| s16 \| u8 \| s16 \| × \| s32 \| × \| s64 \| × \| u8 \| c32 \| c64 \| c128 \|
	25	+\| s16 \| f32 \| f16 \| f64 \| bf16 \| s16 \| s16 \| s16 \| × \| s32 \| × \| s64 \| × \| s16 \| c32 \| c64 \| c128 \|
	26	+\| u16 \| × \| × \| × \| × \| × \| × \| × \| u16 \| × \| × \| × \| × \| × \| × \| × \| × \|
	27	+\| s32 \| f32 \| f16 \| f64 \| bf16 \| s32 \| s32 \| s32 \| × \| s32 \| × \| s64 \| × \| s32 \| c32 \| c64 \| c128 \|
	28	+\| u32 \| × \| × \| × \| × \| × \| × \| × \| × \| × \| u32 \| × \| × \| × \| × \| × \| × \|
	29	+\| s64 \| f32 \| f16 \| f64 \| bf16 \| s64 \| s64 \| s64 \| × \| s64 \| × \| s64 \| × \| s64 \| c32 \| c64 \| c128 \|
	30	+\| u64 \| × \| × \| × \| × \| × \| × \| × \| × \| × \| × \| × \| u64 \| × \| × \| × \| × \|
	31	+\| bool \| f32 \| f16 \| f64 \| bf16 \| s8 \| u8 \| s16 \| × \| s32 \| × \| s64 \| × \| bool \| c32 \| c64 \| c128 \|
	32	+\| c32 \| c64 \| c32 \| c128 \| c32 \| c32 \| c32 \| c32 \| × \| c32 \| × \| c32 \| × \| c32 \| c32 \| c64 \| c128 \|
	33	+\| c64 \| c64 \| c64 \| c128 \| c64 \| c64 \| c64 \| c64 \| × \| c64 \| × \| c64 \| × \| c64 \| c64 \| c64 \| c128 \|
	34	+\| c128 \| c128 \| c128 \| c128 \| c128 \| c128 \| c128 \| c128 \| × \| c128 \| × \| c128 \| × \| c128 \| c128 \| c128 \| c128 \|
	35	+
	36	+## Promotion Examples
	37	+
	38	+- When calling the aclnnAdd interface, if the data types of the input parameters are inconsistent, one is float16 and one is float32, the API internally converts the float16 data type to float32 data type and then performs the calculation.
	39	+- When calling the aclnnAdd interface, if the data types of the input parameters are inconsistent, one is float32 and one is bool, the API internally converts the bool data type to float32 data type and then performs the calculation.

Adocs/en/context/dir_structure.md+133-0

@@ -0,0 +1,133 @@
	1	+# Project Directory
	2	+
	3	+> Some directories listed in this chapter are optional. Please refer to the actual deliverables. Especially for single operator directories, the deliverables vary in different scenarios. The specific descriptions are as follows:
	4	+>
	5	+> - If the op_host directory is missing, it may be calling other operators' op_host implementations. For the calling logic, refer to the source code implementation in that operator's op_api or op_graph directory. It may also be that the Kernel has no Ascend C implementation. If needed, developers are welcome to contribute the operator by referring to the [Contribution Guide](../../../CONTRIBUTING_en.md).
	6	+> - If the op_kernel directory is missing, it may be calling other operators' op_kernel implementations. For the calling logic, refer to the source code implementation in that operator's op_api or op_graph directory. It may also be that the Kernel has no Ascend C implementation. If needed, developers are welcome to contribute the operator by referring to the [Contribution Guide](../../../CONTRIBUTING_en.md).
	7	+> - If the op_api directory is missing, it means the operator does not support aclnn invocation.
	8	+> - If the op_graph directory is missing, it means the operator does not support graph mode invocation.
	9	+
	10	+The full directory hierarchy of the project is introduced as follows:
	11	+
	12	+```text
	13	+├── cmake # Project engineering compilation directory
	14	+│ ├── aclnn_ops_nn.h.in # aclnn summary header file template
	15	+│ └── ...
	16	+├── common # Project common header files and common code
	17	+│ ├── CMakeLists.txt
	18	+│ ├── inc # Common header file directory
	19	+│ └── src # Common code directory
	20	+├── ${op_class} # Operator classification, such as activation, conv, matmul class operators
	21	+│ ├── ${op_name} # Operator engineering directory, ${op_name} represents the operator name (lowercase underscore form)
	22	+│ │ ├── CMakeLists.txt # Operator CMakeList entry
	23	+│ │ ├── README.md # Operator introduction document
	24	+│ │ ├── docs # Operator document directory
	25	+│ │ │ └── aclnn${OpName}.md # Operator aclnn interface introduction document, ${OpName} represents the operator name (CamelCase form)
	26	+│ │ ├── examples # Operator invocation example directory
	27	+│ │ │ ├── test_aclnn_${op_name}.cpp # Example of operator invocation through aclnn
	28	+│ │ │ └── test_geir_${op_name}.cpp # Example of operator invocation through geir
	29	+│ │ ├── op_graph # Graph fusion related implementation
	30	+│ │ │ ├── CMakeLists.txt # op_graph side CMakeList file
	31	+│ │ │ ├── ${op_name}_graph_infer.cpp # InferDataType file, implements operator data type deduction
	32	+│ │ │ ├── ${op_name}_proto.h # Operator prototype definition, used to identify operators during graph optimization and fusion stages
	33	+│ │ │ └── fusion_pass # Operator fusion rule directory
	34	+│ │ ├── op_host # Host side implementation
	35	+│ │ │ ├── CMakeLists.txt # Host side CMakeList file
	36	+│ │ │ ├── config # Optional, binary configuration file, automatically generated by the project if not configured
	37	+│ │ │ │ ├── ${soc_version} # Binary information configured by the operator on the NPU, ${soc_version} represents the NPU model
	38	+│ │ │ │ │ ├── ${op_name}_binary.json # Operator binary configuration file
	39	+│ │ │ │ │ └── ${op_name}_simplified_key.ini # Operator SimplifiedKey configuration information
	40	+│ │ │ │ └── ...
	41	+│ │ │ ├── ${op_name}_def.cpp # Operator information library, defines operator basic information such as name, input/output, data types, etc.
	42	+│ │ │ ├── ${op_name}_infershape.cpp # Optional, InferShape implementation, deduces output shape according to operator shape. If not configured, output shape is the same as input shape
	43	+│ │ │ ├── ${op_name}_tiling_${sub_case}.cpp # Optional, Tiling optimization for certain sub-scenarios, ${sub_case} represents the sub-scenario. For example, ${op_name}_tiling_arch35 is optimization for arch35 architecture. If this file does not exist, it indicates that the operator has no specific Tiling strategy for the corresponding sub-scenario
	44	+│ │ │ ├── ${op_name}_tiling_${sub_case}.h # Optional, header file used for Tiling implementation in ${sub_case} sub-scenario
	45	+│ │ │ ├── ${op_name}_tiling.cpp # Optional, if this file does not exist, it indicates that there is no Tiling implementation for the corresponding scenario (divides tensor into multiple small blocks, distinguishes data types for parallel computing)
	46	+│ │ │ ├── ${op_name}_tiling.h # Optional, header file used for Tiling implementation
	47	+│ │ │ └── op_api # Optional, operator aclnn implementation file directory, automatically generated by the project if not configured
	48	+│ │ │ ├── aclnn_${op_name}.cpp # Operator aclnn interface implementation file
	49	+│ │ │ ├── aclnn_${op_name}.h # Operator aclnn interface implementation header file
	50	+│ │ │ ├── ${op_name}.cpp # Operator l0 interface implementation file
	51	+│ │ │ ├── ${op_name}.h # Operator l0 interface implementation header file
	52	+│ │ │ └── CMakeLists.txt
	53	+│ │ │── op_kernel # AI Core operator Device side Kernel implementation
	54	+│ │ │ ├── ${sub_case} # Optional, directory used for ${sub_case} sub-scenario
	55	+│ │ │ │ ├── ${op_name}_${model}.h # Operator kernel implementation file, ${model} represents user-defined file name suffix, usually Tiling template name
	56	+│ │ │ │ └── ...
	57	+│ │ │ ├── ${op_name}_tiling_key.h # Optional, TilingKey file, defines the Key of Tiling strategy, identifies different partitioning methods. If not configured, it indicates that the operator has no corresponding Tiling strategy
	58	+│ │ │ ├── ${op_name}_tiling_data.h # Optional, TilingData file, stores Tiling strategy related configuration information such as block size, parallelism. If not configured, it indicates that the operator has no corresponding Tiling strategy
	59	+│ │ │ ├── ${op_name}.cpp # Kernel entry file, contains main function and scheduling logic
	60	+│ │ │ └── ${op_name}.h # Kernel implementation file, defines Kernel header file, contains function declarations, structure definitions, logic implementation
	61	+│ │ │── op_kernel_aicpu # Optional, AI CPU operator Device side Kernel implementation
	62	+│ │ │ ├── ${op_name}_aicpu.cpp # Kernel entry file, contains main function and scheduling logic
	63	+│ │ │ └── ${op_name}_aicpu.h # Kernel header file, contains function declarations, structure definitions, logic implementation
	64	+│ │ └── tests # Operator test case directory
	65	+│ │ ├── CMakeLists.txt
	66	+│ │ └── ut # Optional, UT test cases, develop corresponding cases according to actual situation
	67	+│ │ ├── CMakeLists.txt # UT case CMakeList file
	68	+│ │ ├── graph_plugin # graph_plugin test case directory
	69	+│ │ │ ├── CMakeLists.txt
	70	+│ │ │ └── fusion_pass # Fusion rule test case directory
	71	+│ │ │ └── CMakeLists.txt
	72	+│ │ ├── op_host # op_host test case directory
	73	+│ │ │ ├── CMakeLists.txt
	74	+│ │ │ ├── ${op_name}_regbase_tiling.h
	75	+│ │ │ ├── op_api # op_api test case directory
	76	+│ │ │ │ ├── CMakeLists.txt
	77	+│ │ │ │ └── test_aclnn_${op_name}.cpp # Operator aclnn test case file
	78	+│ │ │ ├── test_${op_name}_${sub_case}.cpp # op_host test case file in ${sub_case} sub-scenario
	79	+│ │ │ ├── test_${op_name}.cpp # op_host test case file
	80	+│ │ │ ├── test_${op_name}_infershape.cpp # Operator InferShape test case file
	81	+│ │ │ └── test_${op_name}_tiling.cpp # Operator Tiling test case file
	82	+│ │ └── op_kernel # op_kernel test case directory
	83	+│ │ ├── CMakeLists.txt
	84	+│ │ │── test_${op_name}.cpp # Operator Kernel test case file
	85	+│ │ └── ${op_name}_data # Optional, data comparison and generation scripts that op_kernel test cases depend on. If not configured, you need to manually implement in the corresponding case
	86	+│ │ ├── compare_data.py # Data script
	87	+│ │ └── gen_data.py # Data generation script
	88	+│ └── ...
	89	+├── docs # Project related document directory
	90	+├── examples # End-to-end operator development and invocation examples
	91	+│ ├── add_example # AI Core operator example directory
	92	+│ │ ├── CMakeLists.txt # Operator compilation configuration file
	93	+│ │ ├── examples # Operator usage example directory
	94	+│ │ ├── op_graph # Operator graph composition related directory
	95	+│ │ ├── op_host # Operator information library, Tiling, InferShape related implementation directory
	96	+│ │ ├── op_kernel # Operator Kernel directory
	97	+│ │ └── tests # Operator test case directory
	98	+│ ├── add_example_aicpu # AI CPU operator example directory
	99	+│ │ ├── CMakeLists.txt # Operator compilation configuration file
	100	+│ │ ├── examples # Operator usage example directory
	101	+│ │ ├── op_graph # Operator graph composition related directory
	102	+│ │ ├── op_host # Operator information library, InferShape related implementation
	103	+│ │ ├── op_kernel_aicpu # Operator Kernel directory
	104	+│ │ └── tests # Operator test case directory
	105	+│ ├── fast_kernel_launch_example # Lightweight, high-performance operator development engineering template
	106	+│ │ ├── ascend_ops # Example operator implementation directory
	107	+│ │ ├── CMakeLists.txt # Operator compilation configuration file
	108	+│ │ ├── README.md # Lightweight, high-performance operator development engineering documentation
	109	+│ │ ├── requirements.txt
	110	+│ │ └── setup.py # Build script
	111	+│ ├── CMakeLists.txt
	112	+│ └── README.md # Project example introduction document
	113	+├── experimental # User-defined operator storage directory
	114	+├── scripts # Script directory, contains custom operator, Kernel build related configuration files
	115	+├── tests # Project-level test directory
	116	+│ ├── requirements.txt # Third-party components that test cases depend on
	117	+│ └── ut # UT case engineering
	118	+│ ├── CMakeLists.txt # UT engineering CMakeList script
	119	+│ ├── common # Common code used in UT engineering
	120	+│ ├── op_api # op_api test engineering
	121	+│ ├── op_host # op_host test engineering
	122	+│ └── op_kernel # op_kernel test engineering
	123	+├── CMakeLists.txt # Project engineering CMakeList entry
	124	+├── CONTRIBUTING.md # Project contribution guide file
	125	+├── LICENSE # Project open source license information
	126	+├── OAT.xml # Configuration script, used by repository tools to check whether the License is standard
	127	+├── README.md # Project engineering general introduction document
	128	+├── SECURITY.md # Project security statement file
	129	+├── build.sh # Project engineering compilation script
	130	+├── install_deps.sh # Project installation dependency package script
	131	+├── requirements.txt # Project third-party dependency packages
	132	+└── version.info # Project version information
	133	+```

Adocs/en/context/non_contiguous_tensor.md+38-0

@@ -0,0 +1,38 @@
	1	+# Non-contiguous Tensor
	2	+
	3	+Currently, most operator APIs support "non-contiguous Tensor" as input aclTensor, that is, a Tensor can be represented by (shape, strides, offset).
	4	+
	5	+Note: You can create an aclTensor through the "Public Interfaces > aclCreateTensor" section in [Operator Library Interface](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/API/aolapi/operatorlist_00001.html).
	6	+
	7	+## Example 1
	8	+
	9	+For example, consider a Tensor with shape=(6, 5), strides=(10, 1), and offset=22. Its memory layout is as follows:
	10	+> a<sub>0,0</sub> , a<sub>0,1</sub> , a<sub>0,2</sub> , a<sub>0,3</sub> , a<sub>0,4</sub> , a<sub>0,5</sub> , a<sub>0,6</sub> , a<sub>0,7</sub> , a<sub>0,8</sub> , a<sub>0,9</sub>
	11	+> a<sub>1,0</sub> , a<sub>1,1</sub> , a<sub>1,2</sub> , a<sub>1,3</sub> , a<sub>1,4</sub> , a<sub>1,5</sub> , a<sub>1,6</sub> , a<sub>1,7</sub> , a<sub>1,8</sub> , a<sub>1,9</sub>
	12	+> a<sub>2,0</sub> , a<sub>2,1</sub> , a<sub>2,2</sub> , a<sub>2,3</sub> , a<sub>2,4</sub> , a<sub>2,5</sub> , a<sub>2,6</sub> , a<sub>2,7</sub> , a<sub>2,8</sub> , a<sub>2,9</sub>
	13	+> a<sub>3,0</sub> , a<sub>3,1</sub> , a<sub>3,2</sub> , a<sub>3,3</sub> , a<sub>3,4</sub> , a<sub>3,5</sub> , a<sub>3,6</sub> , a<sub>3,7</sub> , a<sub>3,8</sub> , a<sub>3,9</sub>
	14	+> a<sub>4,0</sub> , a<sub>4,1</sub> , a<sub>4,2</sub> , a<sub>4,3</sub> , a<sub>4,4</sub> , a<sub>4,5</sub> , a<sub>4,6</sub> , a<sub>4,7</sub> , a<sub>4,8</sub> , a<sub>4,9</sub>
	15	+> a<sub>5,0</sub> , a<sub>5,1</sub> , a<sub>5,2</sub> , a<sub>5,3</sub> , a<sub>5,4</sub> , a<sub>5,5</sub> , a<sub>5,6</sub> , a<sub>5,7</sub> , a<sub>5,8</sub> , a<sub>5,9</sub>
	16	+> a<sub>6,0</sub> , a<sub>6,1</sub> , a<sub>6,2</sub> , a<sub>6,3</sub> , a<sub>6,4</sub> , a<sub>6,5</sub> , a<sub>6,6</sub> , a<sub>6,7</sub> , a<sub>6,8</sub> , a<sub>6,9</sub>
	17	+> a<sub>7,0</sub> , a<sub>7,1</sub> , a<sub>7,2</sub> , a<sub>7,3</sub> , a<sub>7,4</sub> , a<sub>7,5</sub> , a<sub>7,6</sub> , a<sub>7,7</sub> , a<sub>7,8</sub> , a<sub>7,9</sub>
	18	+> a<sub>8,0</sub> , a<sub>8,1</sub> , a<sub>8,2</sub> , a<sub>8,3</sub> , a<sub>8,4</sub> , a<sub>8,5</sub> , a<sub>8,6</sub> , a<sub>8,7</sub> , a<sub>8,8</sub> , a<sub>8,9</sub>
	19	+> a<sub>9,0</sub> , a<sub>9,1</sub> , a<sub>9,2</sub> , a<sub>9,3</sub> , a<sub>9,4</sub> , a<sub>9,5</sub> , a<sub>9,6</sub> , a<sub>9,7</sub> , a<sub>9,8</sub> , a<sub>9,9</sub>
	20	+
	21	+That is, the Tensor is laid out in the dark positions shown above. This complete Tensor is non-contiguous in memory layout. Strides describe the interval between two adjacent elements in the Tensor dimension. If the stride in dimension 1 is 1, that dimension is contiguous; if the stride in dimension 0 is 10, then adjacent elements are separated by 10 elements, which is non-contiguous. Offset represents the offset of the first element of this Tensor relative to addr.
	22	+
	23	+## Example 2
	24	+
	25	+For example, consider a Tensor with shape=(4, 3), strides=(20, 2), and offset=22. Its memory layout is as follows:
	26	+
	27	+> a<sub>0,0</sub> , a<sub>0,1</sub> , a<sub>0,2</sub> , a<sub>0,3</sub> , a<sub>0,4</sub> , a<sub>0,5</sub> , a<sub>0,6</sub> , a<sub>0,7</sub> , a<sub>0,8</sub> , a<sub>0,9</sub>
	28	+> a<sub>1,0</sub> , a<sub>1,1</sub> , a<sub>1,2</sub> , a<sub>1,3</sub> , a<sub>1,4</sub> , a<sub>1,5</sub> , a<sub>1,6</sub> , a<sub>1,7</sub> , a<sub>1,8</sub> , a<sub>1,9</sub>
	29	+> a<sub>2,0</sub> , a<sub>2,1</sub> , a<sub>2,2</sub> , a<sub>2,3</sub> , a<sub>2,4</sub> , a<sub>2,5</sub> , a<sub>2,6</sub> , a<sub>2,7</sub> , a<sub>2,8</sub> , a<sub>2,9</sub>
	30	+> a<sub>3,0</sub> , a<sub>3,1</sub> , a<sub>3,2</sub> , a<sub>3,3</sub> , a<sub>3,4</sub> , a<sub>3,5</sub> , a<sub>3,6</sub> , a<sub>3,7</sub> , a<sub>3,8</sub> , a<sub>3,9</sub>
	31	+> a<sub>4,0</sub> , a<sub>4,1</sub> , a<sub>4,2</sub> , a<sub>4,3</sub> , a<sub>4,4</sub> , a<sub>4,5</sub> , a<sub>4,6</sub> , a<sub>4,7</sub> , a<sub>4,8</sub> , a<sub>4,9</sub>
	32	+> a<sub>5,0</sub> , a<sub>5,1</sub> , a<sub>5,2</sub> , a<sub>5,3</sub> , a<sub>5,4</sub> , a<sub>5,5</sub> , a<sub>5,6</sub> , a<sub>5,7</sub> , a<sub>5,8</sub> , a<sub>5,9</sub>
	33	+> a<sub>6,0</sub> , a<sub>6,1</sub> , a<sub>6,2</sub> , a<sub>6,3</sub> , a<sub>6,4</sub> , a<sub>6,5</sub> , a<sub>6,6</sub> , a<sub>6,7</sub> , a<sub>6,8</sub> , a<sub>6,9</sub>
	34	+> a<sub>7,0</sub> , a<sub>7,1</sub> , a<sub>7,2</sub> , a<sub>7,3</sub> , a<sub>7,4</sub> , a<sub>7,5</sub> , a<sub>7,6</sub> , a<sub>7,7</sub> , a<sub>7,8</sub> , a<sub>7,9</sub>
	35	+> a<sub>8,0</sub> , a<sub>8,1</sub> , a<sub>8,2</sub> , a<sub>8,3</sub> , a<sub>8,4</sub> , a<sub>8,5</sub> , a<sub>8,6</sub> , a<sub>8,7</sub> , a<sub>8,8</sub> , a<sub>8,9</sub>
	36	+> a<sub>9,0</sub> , a<sub>9,1</sub> , a<sub>9,2</sub> , a<sub>9,3</sub> , a<sub>9,4</sub> , a<sub>9,5</sub> , a<sub>9,6</sub> , a<sub>9,7</sub> , a<sub>9,8</sub> , a<sub>9,9</sub>
	37	+
	38	+That is, the Tensor is laid out in the dark positions shown above. This complete Tensor is non-contiguous in memory layout. Strides describe the interval between two adjacent elements in the Tensor dimension. If the stride in dimension 1 is 2, that dimension has an interval of 1 element; if the stride in dimension 0 is 20, then adjacent elements are separated by 20 elements, which is non-contiguous. Offset represents the offset of the first element of this Tensor relative to addr.

Adocs/en/context/quant_more_introduction.md+59-0

@@ -0,0 +1,59 @@
	1	+# Quantization Introduction
	2	+
	3	+Quantization is widely used in deep learning models, especially during inference. Through quantization, models can run more efficiently on hardware, reducing the consumption of computing resources and accelerating the inference process, while also lowering the storage requirements of the model.
	4	+
	5	+CANN operator quantization refers to the calculation process of converting the input Tensor of matrix (cube) operators such as Matmul in neural networks from high-bit to low-bit, while generating corresponding quantization parameters scale. After low-bit cube calculation is completed, the low-bit values can be converted back to high-bit values through the quantization parameter scale, thereby ensuring the correctness of the overall calculation result (the effect is approximately equivalent to direct high-bit calculation), and effectively improving calculation efficiency.
	6	+
	7	+- Static quantization: Uses pre-determined quantization parameters for quantization. In inference scenarios, quantization of weight is generally done using static quantization, which provides better quantization operator performance.
	8	+- Dynamic quantization: Uses input data to calculate quantization parameters online for quantization. In inference scenarios, quantization of activation is generally done using dynamic quantization, which can better adapt to data changes and has higher precision; in training scenarios, dynamic quantization is also generally used to improve quantization precision. Note that dynamic quantization has slightly worse quantization operator performance because quantization parameters are generated online.
	9	+
	10	+## Quantization Modes
	11	+
	12	+Quantization mode (also known as quantization granularity) refers to using different quantization calculation levels for different input Tensors of operators. Common quantization calculation modes include:
	13	+
	14	+>Note:
	15	+>
	16	+>- The m, n, and k variables represent the sizes of different axes in Tensor calculation.
	17	+>- Left matrix and right matrix refer to the two input Tensors used for matrix multiplication calculation in cube operators. Generally, the left matrix represents activation and the right matrix represents weight. Please understand and use them according to the actual situation.
	18	+
	19	+- pertensor quantization (abbreviated as T quantization): The quantization object can be either the left matrix or the right matrix, and each Tensor shares the same quantization parameter.
	20	+
	21	+ Assuming the left matrix shape is (m, k) and the right matrix shape is (k, n), where k is the reduce axis, the generated quantization parameter shape is (1, ).
	22	+
	23	+ <!--![Schematic](../figures/pertensor量化.png)-->
	24	+
	25	+- perchannel quantization (abbreviated as C quantization): The quantization object is the right matrix, and each channel uses independent quantization parameters.
	26	+
	27	+ Assuming the right matrix shape is (k, n), where k is the reduce axis, the generated quantization parameter shape is (n, ).
	28	+
	29	+ <!--![Schematic](../figures/perchannel量化.png)-->
	30	+
	31	+- pertoken quantization (abbreviated as K quantization): The quantization object is the left matrix, and each token uses independent quantization parameters.
	32	+
	33	+ Assuming the left matrix shape is (m, k), where k is the reduce axis, the generated quantization parameter shape is (m, ).
	34	+
	35	+ <!--![Schematic](../figures/pertoken量化.png)-->
	36	+
	37	+- pergroup quantization (abbreviated as G quantization): The quantization object can be either the left matrix or the right matrix. Data is grouped on the reduce axis, and each group uses independent quantization parameters.
	38	+ - Assuming the left matrix shape is (m, k), where k is the reduce axis, grouping on the k axis with group size gs, the generated quantization parameter shape is (m, k/gs).
	39	+ - Assuming the right matrix shape is (k, n), where k is the reduce axis, grouping on the k axis with group size gs, the generated quantization parameter shape is (k/gs, n).
	40	+
	41	+ <!--![Schematic](../figures/pergroup量化.png)-->
	42	+
	43	+- perblock quantization (abbreviated as B quantization): The quantization object can be either the left matrix or the right matrix. Data is blocked on all axes, and each block uses independent quantization parameters.
	44	+
	45	+ - Assuming the left matrix shape is (m, k), where k is the reduce axis, grouping data by (bs, bs) blocks on the m and k axes respectively, where bs is block size, the generated quantization parameter shape is (m/bs, k/bs).
	46	+ - Assuming the right matrix shape is (k, n), where k is the reduce axis, grouping data by (bs, bs) blocks on the k and n axes respectively, where bs is block size, the generated quantization parameter shape is (k/bs, n/bs).
	47	+
	48	+ <!--![Schematic](../figures/perblock量化.png)-->
	49	+
	50	+## Common Combined Quantization
	51	+
	52	+- Full quantization: Generally refers to the mode of quantizing both the left and right matrices, including:
	53	+ - pertensor-perchannel quantization mode (abbreviated as T-C quantization mode)
	54	+ - pertoken-perchannel quantization mode (abbreviated as K-C quantization mode)
	55	+ - pergroup-perblock quantization mode (abbreviated as G-B quantization mode)
	56	+ - pertensor-perchannel-pergroup quantization mode (abbreviated as T-CG quantization mode)
	57	+ - perblock-perblock quantization mode (abbreviated as B-B quantization mode)
	58	+- Pseudo quantization: Generally refers to the mode of quantizing the weight matrix, including perchannel quantization mode (abbreviated as C quantization mode).
	59	+- mx quantization: Essentially Microscaling quantization, which maintains model precision at very low bits (such as 1bit) by dynamically adjusting the scaling factor. Here it refers to pergroup-pergroup quantization mode (abbreviated as G-G quantization mode), which is a special case where the quantization parameter type is FLOAT8_E8M0 and the group size is 32.

Adocs/en/context/quick_install.md+190-0

@@ -0,0 +1,190 @@
	1	+# Environment Deployment
	2	+
	3	+Before performing [operator invocation](../invocation/quick_op_invocation.md) or [operator development](../develop/aicore_develop_guide.md) based on this project, complete the basic environment setup by following the steps below.
	4	+
	5	+Note that the meanings of compilation and runtime scenarios mentioned in this document are as follows. Install as needed:
	6	+
	7	+- Compilation scenario: For scenarios where only compilation without running this project is required, you only need to install the prerequisite dependencies and the CANN toolkit package.
	8	+- Runtime scenario: For scenarios where this project is run (compilation and running or pure running), in addition to installing the prerequisite dependencies and the CANN toolkit package, you also need to install the driver and firmware, and the CANN ops package.
	9	+
	10	+## Prerequisites
	11	+
	12	+Before using this project, ensure that the following basic dependencies, NPU driver, and firmware are installed.
	13	+
	14	+1. Install Dependencies
	15	+
	16	+ The dependencies used for source code compilation of this project are as follows. Please note the version requirements.
	17	+
	18	+ - python >= 3.7.0 (recommended version <= 3.10)
	19	+ - gcc >= 7.3.0
	20	+ - cmake >= 3.16.0
	21	+ - pigz (optional, installing it can improve packaging speed, recommended version >= 2.4)
	22	+ - dos2unix
	23	+ - gawk
	24	+ - make
	25	+
	26	+ The above dependency packages can be installed through the install\_deps.sh script in the project root directory. The command is as follows. If you encounter an unsupported system, refer to the file to adapt it yourself.
	27	+
	28	+ ```bash
	29	+ bash install_deps.sh
	30	+ ```
	31	+
	32	+2. Install Driver and Firmware (Runtime Dependency)
	33	+
	34	+ When running operators, you must install the driver and firmware. If you are only compiling operators, you can skip this operation.
	35	+
	36	+ Click [download link](https://www.hiascend.com/hardware/firmware-drivers/community) to obtain the corresponding `Ascend-hdk-<chip_type>-npu-driver_<version>_linux-<arch>.run` and `Ascend-hdk-<chip_type>-npu-firmware_<version>.run` packages according to the actual product model and environment architecture.
	37	+
	38	+ For installation instructions, refer to [CANN Software Installation Guide](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/softwareinst/instg/instg_0000.html?OS=openEuler&InstallType=netyum).
	39	+
	40	+## Environment Preparation (Choose One of Three)
	41	+
	42	+This project provides multiple ways to deploy CANN packages. Choose as needed.
	43	+
	44	+- WebIDE and Docker environment: Provides minimal environment setup, default installation of the latest commercial release CANN software package (currently CANN 8.5.0).
	45	+- Manual installation of CANN package: If you want to experience manual installation of CANN package or experience the latest master branch capabilities, manual installation is recommended.
	46	+
	47	+### Using WebIDE Environment
	48	+
	49	+For users without an environment, you can directly use the WebIDE development platform, that is, the "Operator One-stop Development Platform". This platform provides an online Ascend environment that can be run directly. The environment has installed the necessary software packages, and no manual installation is required. For more information about the development platform, refer to [LINK](https://gitcode.com/org/cann/discussions/54).
	50	+
	51	+1. Enter the open source project and click the "`Cloud Development`" button. Log in with a certified Huawei Cloud account. If you have not registered or certified, please register and certify according to the page prompts.
	52	+
	53	+ <!--<img src="../figures/cloudIDE.png" alt="Cloud Platform" width="750px" height="90px">-->
	54	+
	55	+2. Create and start the cloud development environment according to the page prompts. Click "`Connect > WebIDE`" to enter the operator one-stop development platform. The resources of the open source project are in the `/mnt/workspace` directory by default.
	56	+
	57	+ <!--<img src="../figures/webIDE.png" alt="Cloud Platform" width="1000px" height="150px">-->
	58	+
	59	+### Using Docker Deployment
	60	+
	61	+> Note:
	62	+>
	63	+> - Docker image is an efficient deployment method. Currently, it is only applicable to Atlas A2 series products and only adapted to the Ubuntu operating system.
	64	+> - The image file is relatively large, and downloading takes some time. Please wait patiently.
	65	+
	66	+#### 1. Download Image
	67	+
	68	+1. Log in to the host machine as the root user. Ensure that the Docker engine (version 1.11.2 or above) is installed on the host machine.
	69	+2. Pull the image with the CANN software package and `ops-nn` required dependencies pre-integrated from the [Ascend Image Repository](https://www.hiascend.com/developer/ascendhub/detail/17da20d1c2b6493cb38765adeba85884). The command is as follows. Choose according to the actual architecture:
	70	+
	71	+ ```bash
	72	+ # Example: Pull ARM architecture CANN development image
	73	+ docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops
	74	+ # Example: Pull X86 architecture CANN development image
	75	+ docker pull --platform=amd64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops
	76	+ ```
	77	+
	78	+#### 2. Run Docker
	79	+
	80	+After pulling the image, you need to start the container with specific parameters so that the container can access the host's Ascend device.
	81	+
	82	+```bash
	83	+docker run --name cann_container --device /dev/davinci0 --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 -it swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops bash
	84	+```
	85	+
	86	+\| Parameter \| Description \| Notes \|
	87	+\| :--- \| :--- \| :--- \|
	88	+\| `--name cann_container` \| Specifies a name for the container for easy management. \| Can be customized. \|
	89	+\| `--device /dev/davinci0` \| Core: Maps the host's NPU device card to the container. Multiple NPU device cards can be specified. \| Must be adjusted according to the actual situation: `davinci0` corresponds to the 0th NPU card in the system. Please execute the `npu-smi info` command on the host first, and modify this number according to the device number displayed in the output (such as `NPU 0`, `NPU 1`).\|
	90	+\| `--device /dev/davinci_manager` \| Maps the NPU device management interface. \| \|
	91	+\| `--device /dev/devmm_svm` \| Maps the device memory management interface. \| \|
	92	+\| `--device /dev/hisi_hdc` \| Maps the communication interface between host and device. \| \|
	93	+\| `-v /usr/local/dcmi:/usr/local/dcmi` \| Mounts the device container management interface (DCMI) related tools and libraries. \| \|
	94	+\| `-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi` \| Mounts the `npu-smi` tool. \| Enables running this command directly in the container to query NPU status and performance information.\|
	95	+\| `-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/` \| Key mount: Maps the host's NPU driver library to the container. \| \|
	96	+\| `-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info` \| Mounts the driver version information file. \| \|
	97	+\| `-v /etc/ascend_install.info:/etc/ascend_install.info` \| Mounts the CANN software installation information file. \| \|
	98	+\| `-it` \| Combination parameter of `-i` (interactive) and `-t` (allocate pseudo terminal). \| \|
	99	+\| `swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops` \| Specifies the Docker image to run. \| Please ensure that this image name and tag are exactly the same as the image you pulled through `docker pull`. \|
	100	+\| `bash` \| The command executed immediately after the container starts. \| \|
	101	+
	102	+### Manual Installation of CANN Package
	103	+
	104	+#### 1. Download Software Package
	105	+
	106	+Obtain `Ascend-cann-toolkit_${cann_version}_linux-${arch}.run` and `Ascend-cann-${soc_name}-ops_${cann_version}_linux-${arch}.run` according to the following scenarios.
	107	+
	108	+- Scenario 1: If you want to experience the officially released CANN package capabilities, visit the [CANN Official Download Center](https://www.hiascend.com/en/cann/download?versionId=731&ids=d806%2Ch0502%2Ch0601%2Ch0702), select the corresponding version of the CANN software package (only CANN 8.5.0 and later versions are supported). For installation instructions, refer to [CANN Software Installation Guide](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/softwareinst/instg/instg_0000.html?OS=openEuler&InstallType=netyum).
	109	+
	110	+- Scenario 2: If you want to experience the latest master branch capabilities, click [download link](https://ascend.devcloud.huaweicloud.com/artifactory/cann-run-release/software/master) to obtain.
	111	+
	112	+Note that the product model and environment architecture must correspond to the actual environment. In addition, the ops package is a runtime dependency. If you are only compiling operators, you can skip installing this package.
	113	+
	114	+#### 2. Install Software Package
	115	+
	116	+1. Install Community CANN Toolkit Package
	117	+
	118	+ ```bash
	119	+ # Ensure the installation package has executable permission
	120	+ chmod +x Ascend-cann-toolkit_${cann_version}_linux-${arch}.run
	121	+ # Installation command
	122	+ ./Ascend-cann-toolkit_${cann_version}_linux-${arch}.run --install --force --install-path=${install_path}
	123	+ ```
	124	+
	125	+ - $\{cann\_version\}: Represents the CANN package version number.
	126	+ - $\{arch\}: Represents the CPU architecture, such as aarch64, x86_64.
	127	+ - $\{install\_path\}: Represents the specified installation path. The default installation is in the `/usr/local/Ascend` directory.
	128	+
	129	+2. Install Community CANN Ops Package (Runtime Dependency)
	130	+
	131	+ When running operators, you must install this package. If you are only compiling operators, you can skip this operation.
	132	+
	133	+ ```bash
	134	+ # Ensure the installation package has executable permission
	135	+ chmod +x Ascend-cann-${soc_name}-ops_${cann_version}_linux-${arch}.run
	136	+ # Installation command
	137	+ ./Ascend-cann-${soc_name}-ops_${cann_version}_linux-${arch}.run --install --install-path=${install_path}
	138	+ ```
	139	+
	140	+ - $\{soc\_name\}: Represents the NPU model name.
	141	+ - $\{install\_path\}: Represents the specified installation path. It needs to be installed in the same path as the toolkit package. The default installation is in the `/usr/local/Ascend` directory.
	142	+
	143	+## Environment Verification
	144	+
	145	+After installing the CANN package, verify that the environment and driver are normal.
	146	+
	147	+- Check NPU Device:
	148	+
	149	+ ```bash
	150	+ # Run npu-smi. If device information is displayed normally, the driver is normal
	151	+ npu-smi info
	152	+ ```
	153	+
	154	+- Check CANN Installation:
	155	+
	156	+ ```bash
	157	+ # View CANN Toolkit version information (default path installation)
	158	+ cat /usr/local/Ascend/ascend-toolkit/latest/opp/version.info
	159	+ ```
	160	+
	161	+## Environment Variable Configuration
	162	+
	163	+Choose the appropriate command to make the environment variables effective as needed.
	164	+
	165	+```bash
	166	+# Default path installation, taking root user as an example (for non-root users, replace /usr/local with ${HOME})
	167	+source /usr/local/Ascend/cann/set_env.sh
	168	+# Specified path installation
	169	+# source ${install_path}/cann/set_env.sh
	170	+```
	171	+
	172	+## Source Code Download
	173	+
	174	+Download the project source code through the following command, and install other dependencies. Replace $\{tag\_version\} with the branch tag name. The matching relationship between this source code repository and the CANN version can be found in the [release repository](https://gitcode.com/cann/release-management).
	175	+
	176	+```bash
	177	+# Download the corresponding branch source code of the project
	178	+git clone -b ${tag_version} https://gitcode.com/cann/ops-nn.git
	179	+# Install root directory requirements.txt dependencies
	180	+cd ops-nn
	181	+pip3 install -r requirements.txt
	182	+```
	183	+
	184	+> [!NOTE] Note
	185	+> When using the HTTPS protocol on the gitcode platform, you need to configure and use a personal access token instead of the login password for cloning, pushing, and other operations.
	186	+
	187	+If your compilation environment cannot access the network and cannot download the code through the `git` command, you need to download the source code in a networked environment and manually upload it to the target environment.
	188	+
	189	+- In a networked environment, enter [this project homepage](https://gitcode.com/cann/ops-nn), and complete the source code download through the `Download ZIP` or `clone` button according to the instructions.
	190	+- Connect to the offline environment and upload the source code to your specified directory. If you downloaded a source code compressed package, you also need to decompress it.

Adocs/en/context/sparse_mode_introduction.md+153-0

@@ -0,0 +1,153 @@
	1	+# sparseMode Introduction
	2	+
	3	+In the large model field, sparseMode (sparse mode) usually refers to the sparsity design of parameters or activations in the model architecture or calculation formula, as opposed to the dense mode (DenseMode).
	4	+
	5	+This section introduces common sparseModes and their corresponding scenario descriptions.
	6	+
	7	+\| sparseMode \| Meaning \| Note \|
	8	+\| ---------- \| --------------------- \| ------------------ \|
	9	+\| 0 \| defaultMask mode. \| - \|
	10	+\| 1 \| allMask mode. \| - \|
	11	+\| 2 \| leftUpCausal mode. \| - \|
	12	+\| 3 \| rightDownCausal mode. \| - \|
	13	+\| 4 \| band mode. \| - \|
	14	+\| 5 \| prefix non-compressed mode. \| Not supported in varlen scenarios. \|
	15	+\| 6 \| prefix compressed mode. \| - \|
	16	+\| 7 \| varlen outer slice scenario, rightDownCausal mode. \| Only supported in varlen scenarios. \|
	17	+\| 8 \| varlen outer slice scenario, leftUpCausal mode. \| Only supported in varlen scenarios. \|
	18	+
	19	+The working principle of attenMask is to mask the value of the query (Q) and key (K) transpose matrix product at the position where Mask is True, as shown below:
	20	+
	21	+<!--![Schematic](../figures/QK转置图.png)-->
	22	+
	23	+The $QK^T$ matrix will be masked at the position where attenMask is True, with the following effect:
	24	+
	25	+<!--![Schematic](../figures/遮挡QK图.png)-->
	26	+
	27	+## sparseMode=0
	28	+
	29	+When sparseMode is 0, it represents the defaultMask mode.
	30	+
	31	+- No mask passed: If attenMask is not passed, no mask operation is performed. attenMask takes the value None, and preTokens and nextTokens values are ignored. The Masked $QK^T$ matrix is shown below:
	32	+
	33	+ <!--![Schematic](../figures/sparsemode为0遮挡矩阵.png)-->
	34	+
	35	+- nextTokens is 0, preTokens is greater than or equal to Sq, indicating a causal scenario sparse. attenMask should pass a lower triangular matrix. At this time, the part between preTokens and nextTokens needs to be calculated. The Masked $QK^T$ matrix is shown below:
	36	+
	37	+ <!--![Schematic](../figures/sparsemode为0遮挡矩阵1.png)-->
	38	+
	39	+ attenMask should pass a lower triangular matrix, as shown below:
	40	+
	41	+ <!--![Schematic](../figures/attenmask下三角.png)-->
	42	+
	43	+- preTokens is less than Sq, nextTokens is less than Skv, and both are greater than or equal to 0, indicating a band scenario. At this time, the part between preTokens and nextTokens needs to be calculated. The Masked $QK^T$ matrix is shown below:
	44	+
	45	+ <!--![Schematic](../figures/sparsemode为0遮挡矩阵2.png)-->
	46	+
	47	+ attenMask should pass a band-shaped matrix, as shown below:
	48	+
	49	+ <!--![Schematic](../figures/attenmask_band形状矩阵.png)-->
	50	+
	51	+- nextTokens is negative. Taking preTokens=9, nextTokens=-3 as an example, the part between preTokens and nextTokens needs to be calculated. The Masked $QK^T$ is shown below:
	52	+
	53	+ Note: When nextTokens is negative, preTokens must be greater than or equal to the absolute value of nextTokens, and the absolute value of nextTokens must be less than Skv.
	54	+
	55	+ <!--![Schematic](../figures/sparsemode为0遮挡矩阵3.png)-->
	56	+
	57	+- preTokens is negative. Taking nextTokens=7, preTokens=-3 as an example, the part between preTokens and nextTokens needs to be calculated. The Masked $QK^T$ is shown below:
	58	+
	59	+ Note: When preTokens is negative, nextTokens must be greater than or equal to the absolute value of preTokens, and the absolute value of preTokens must be less than Sq.
	60	+
	61	+ <!--![Schematic](../figures/sparsemode为0遮挡矩阵4.png)-->
	62	+
	63	+## sparseMode=1
	64	+
	65	+When sparseMode is 1, it represents allMask, that is, passing the complete attenMask matrix.
	66	+
	67	+In this scenario, nextTokens and preTokens values are ignored. The Masked $QK^T$ matrix is shown below:
	68	+
	69	+<!--![Schematic](../figures/sparsemode为1遮挡矩阵.png)-->
	70	+
	71	+## sparseMode=2
	72	+
	73	+When sparseMode is 2, it represents the leftUpCausal mode mask, corresponding to the lower triangular scenario divided by the upper-left vertex (parameter starting point is the upper-left corner).
	74	+
	75	+In this scenario, preTokens and nextTokens values are ignored. The Masked $QK^T$ matrix is shown below:
	76	+
	77	+<!--![Schematic](../figures/sparsemode为2遮挡矩阵.png)-->
	78	+
	79	+The passed attenMask is an optimized compressed lower triangular matrix (2048\*2048). The compressed lower triangular matrix is shown below (same below):
	80	+
	81	+<!--![Schematic](../figures/attenmask压缩下三角.png) -->
	82	+
	83	+## sparseMode=3
	84	+
	85	+When sparseMode is 3, it represents the rightDownCausal mode mask, corresponding to the lower triangular scenario divided by the lower-right vertex (parameter starting point is the lower-right corner).
	86	+
	87	+In this scenario, preTokens and nextTokens values are ignored. attenMask is an optimized compressed lower triangular matrix (2048\*2048). The Masked $QK^T$ matrix is shown below:
	88	+
	89	+<!--![Schematic](../figures/sparsemode为3遮挡矩阵.png)-->
	90	+
	91	+## sparseMode=4
	92	+
	93	+When sparseMode is 4, it represents the band scenario, that is, calculating the part between preTokens and nextTokens. The parameter starting point is the lower-right corner, and there must be an intersection between preTokens and nextTokens. attenMask is an optimized compressed lower triangular matrix (2048\*2048). The Masked $QK^T$ matrix is shown below:
	94	+
	95	+<!--![Schematic](../figures/sparsemode为4遮挡矩阵.png)-->
	96	+
	97	+## sparseMode=5
	98	+
	99	+When sparseMode is 5, it represents the prefix non-compressed scenario, that is, adding a matrix with length Sq and width N to the left on the basis of rightDownCausal. The value of N is obtained from the optional input prefix. For example, the figure below shows prefix passing array [4,5] in batch=2 scenario. The N value of each batch axis can be different. The parameter starting point is the upper-left corner.
	100	+
	101	+In this scenario, preTokens and nextTokens values are ignored. The attenMask matrix data format must be BNSS or B1SS. The Masked $QK^T$ matrix is shown below:
	102	+
	103	+<!--![Schematic](../figures/sparsemode为5遮挡矩阵.png)-->
	104	+
	105	+attenMask should pass a matrix as shown below:
	106	+
	107	+<!--![Schematic](../figures/attenmask矩阵.png)-->
	108	+
	109	+## sparseMode=6
	110	+
	111	+When sparseMode is 6, it represents the prefix compressed scenario, that is, in the prefix scenario, attenMask is an optimized compressed lower triangular + rectangular matrix (3072\*2048): the upper part is a [2048, 2048] lower triangular matrix, and the lower part is a [1024, 2048] rectangular matrix. The left half of the rectangular matrix is all 0, and the right half is all 1. attenMask should pass a matrix as shown below. In this scenario, preTokens and nextTokens values are ignored.
	112	+
	113	+<!--![Schematic](../figures/sparsemode为6遮挡矩阵.png)-->
	114	+
	115	+## sparseMode=7
	116	+
	117	+When sparseMode is 7, it indicates a varlen and long sequence outer slice scenario (that is, long sequences are multi-card sliced by query sequence length in the model script). You need to ensure that the scenario using sparseMode 3 was used before outer slicing. In the current mode, you need to set preTokens and nextTokens (starting point is the lower-right vertex), and you need to ensure that the parameters are correct, otherwise there will be precision issues.
	118	+
	119	+The Masked $QK^T$ matrix is shown below. In the second batch, the query is sliced, and the key and value are not sliced. The 4x6 mask matrix is sliced into 2x6 and 2x6 masks, which are calculated on card 1 and card 2 respectively:
	120	+
	121	+- The last mask block of card 1 is a band-type mask. Configure preTokens=6 (ensure it is greater than or equal to the last Skv), nextTokens=-2. actual_seq_qlen should pass {3,5}, and actual_seq_kvlen should pass {3,9}.
	122	+- The mask type of card 2 remains unchanged after slicing. sparseMode is 3. actual_seq_qlen should pass {2,7,11}, and actual_seq_kvlen should pass {6,11,15}.
	123	+
	124	+<!--![Schematic](../figures/sparsemode为7遮挡矩阵.png)-->
	125	+
	126	+Note:
	127	+
	128	+- sparseMode=7, band represents the sparse type of the last non-empty tensor Batch. If there is only one batch, you need to configure parameters according to the band mode requirements. For sparseMode=7, you need to input a 2048x2048 lower triangular mask as the input of this fusion operator.
	129	+- The sparse parameters of the band mode generated based on sparseMode=3 outer slicing should meet the following conditions:
	130	+ - preTokens >= last_Skv.
	131	+ - last_Sq-last_Skv <= nextTokens <= 0.
	132	+ - The current mode does not support the optional input pse.
	133	+- The non-band mode batch should satisfy: Sq <= Skv.
	134	+
	135	+## sparseMode=8
	136	+
	137	+When sparseMode is 8, it indicates a varlen and long sequence outer slice scenario. You need to ensure that the scenario using sparseMode 2 was used before outer slicing. In the current mode, you need to set preTokens and nextTokens (starting point is the lower-right vertex), and you need to ensure that the parameters are correct, otherwise there will be precision issues.
	138	+
	139	+The Masked $QK^T$ matrix is shown below. In the second batch, the query is sliced, and the key and value are not sliced. The 5x4 mask matrix is sliced into 2x4 and 3x4 masks, which are calculated on card 1 and card 2 respectively:
	140	+
	141	+- The mask type of card 1 remains unchanged after slicing. sparseMode is 2. actual_seq_qlen should pass {3,5}, and actual_seq_kvlen should pass {3,7}.
	142	+- The first mask block of card 2 is a band-type mask. Configure preTokens=4 (ensure it is greater than or equal to the first Skv), nextTokens=1. actual_seq_qlen should pass {3,8,12}, and actual_seq_kvlen should pass {4,9,13}.
	143	+
	144	+<!--![Schematic](../figures/sparsemode为8遮挡矩阵.png)-->
	145	+
	146	+Note:
	147	+
	148	+- sparseMode=8, band represents the sparse type of the first non-empty tensor Batch. If there is only one batch, you need to configure parameters according to the band mode requirements. For sparseMode=8, you need to input a 2048x2048 lower triangular mask as the input of this fusion operator.
	149	+- The sparse parameters of the band mode generated based on sparseMode=2 outer slicing should meet the following conditions:
	150	+ - preTokens >= first_Skv.
	151	+ - nextTokens >= first_Sq - first_Skv, configure according to the actual situation.
	152	+ - The current mode does not support the optional input pse.
	153	+

Adocs/en/context/tensor_scalar_deduction_relationship.md+40-0

@@ -0,0 +1,40 @@
	1	+# TensorScalar Promotion Relationships
	2	+
	3	+## Promotion Rules
	4	+
	5	+When the input Tensor data type and input Scalar data type of an API (such as aclnnAdds, aclnnMuls, etc.) are inconsistent, the API internally deduces a data type and converts the input data to that data type for calculation.
	6	+
	7	+The type promotion rules are as follows:
	8	+
	9	+> Note:
	10	+>
	11	+> - For convenience of description, the data types used in the table are abbreviated forms, representing: ACL\_FLOAT(f32), ACL\_FLOAT16(f16), ACL\_DOUBLE(f64), ACL\_BF16(bf16), ACL\_INT8(s8), ACL\_UINT8(u8), ACL\_INT16(s16), ACL\_UINT16(u16), ACL\_INT32(s32), ACL\_UINT32(u32), ACL\_INT64(s64), ACL\_UINT64(u64), ACL\_BOOL(bool), ACL\_COMPLEX32(c32), ACL\_COMPLEX64(c64), ACL\_COMPLEX128(c128).
	12	+> - The table header represents the input Tensor data type to be deduced, and the leftmost column represents the input Scalar data type to be deduced. The corresponding position in the table represents the deduced data type.
	13	+> - The cross mark (×) in the table indicates that these two types cannot perform promotion calculation.
	14	+
	15	+Table 1 Data Type Promotion Relationships
	16	+
	17	+\| Data Type \| f32 \| f16 \| f64 \| bf16 \| s8 \| u8 \| s16 \| u16 \| s32 \| u32 \| s64 \| u64 \| bool \| c32 \| c64 \| c128 \|
	18	+\| :------: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \| :--: \|
	19	+\| f32 \| f32 \| f16 \| f64 \| bf16 \| f32 \| f32 \| f32 \| × \| f32 \| × \| f32 \| × \| f32 \| c32 \| c64 \| c128 \|
	20	+\| f16 \| f32 \| f16 \| f64 \| bf16 \| f32 \| f32 \| f32 \| × \| f32 \| × \| f32 \| × \| f32 \| c32 \| c64 \| c128 \|
	21	+\| f64 \| f32 \| f16 \| f64 \| bf16 \| f32 \| f32 \| f32 \| × \| f32 \| × \| f32 \| × \| f32 \| c128 \| c128 \| c128 \|
	22	+\| bf16 \| f32 \| f16 \| f64 \| bf16 \| f32 \| f32 \| f32 \| × \| f32 \| × \| f32 \| × \| f32 \| c32 \| c64 \| c128 \|
	23	+\| s8 \| f32 \| f16 \| f64 \| bf16 \| s8 \| u8 \| s16 \| u16 \| s32 \| u32 \| s64 \| u64 \| s8 \| c32 \| c64 \| c128 \|
	24	+\| u8 \| f32 \| f16 \| f64 \| bf16 \| s8 \| u8 \| s16 \| u16 \| s32 \| u32 \| s64 \| u64 \| u8 \| c32 \| c64 \| c128 \|
	25	+\| s16 \| f32 \| f16 \| f64 \| bf16 \| s8 \| u8 \| s16 \| u16 \| s32 \| u32 \| s64 \| u64 \| s16 \| c32 \| c64 \| c128 \|
	26	+\| u16 \| f32 \| f16 \| f64 \| bf16 \| s8 \| u8 \| s16 \| u16 \| s32 \| u32 \| s64 \| u64 \| × \| c32 \| c64 \| c128 \|
	27	+\| s32 \| f32 \| f16 \| f64 \| bf16 \| s8 \| u8 \| s16 \| u16 \| s32 \| u32 \| s64 \| u64 \| s32 \| c32 \| c64 \| c128 \|
	28	+\| u32 \| f32 \| f16 \| f64 \| bf16 \| s8 \| u8 \| s16 \| u16 \| s32 \| u32 \| s64 \| u64 \| × \| c32 \| c64 \| c128 \|
	29	+\| s64 \| f32 \| f16 \| f64 \| bf16 \| s8 \| u8 \| s16 \| u16 \| s32 \| u32 \| s64 \| u64 \| s64 \| c32 \| c64 \| c128 \|
	30	+\| u64 \| f32 \| f16 \| f64 \| bf16 \| s8 \| u8 \| s16 \| u16 \| s32 \| u32 \| s64 \| u64 \| × \| c32 \| c64 \| c128 \|
	31	+\| bool \| f32 \| f16 \| f64 \| bf16 \| s8 \| u8 \| s16 \| u16 \| s32 \| u32 \| s64 \| u64 \| bool \| c32 \| c64 \| c128 \|
	32	+\| c32 \| c64 \| c32 \| c128 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c32 \| c64 \| c128 \|
	33	+\| c64 \| c64 \| c32 \| c128 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c32 \| c64 \| c128 \|
	34	+\| c128 \| c64 \| c32 \| c128 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c64 \| c32 \| c64 \| c128 \|
	35	+
	36	+## Promotion Examples
	37	+
	38	+ - If the input Tensor data type is float16 and the input Scalar data type is float32, the API internally converts the input Scalar float32 data type to float16 data type and then performs the calculation.
	39	+ - If the input Tensor data type is bool and the input Scalar data type is float32, the API internally converts the input Tensor bool data type to float32 data type and then performs the calculation.
	40	+

Adocs/en/context/two_phase_api.md+23-0

@@ -0,0 +1,23 @@
	1	+# Two-stage Interface
	2	+
	3	+When calling an operator API based on the single-operator API execution method, it is usually divided into "two stages", with the following pattern:
	4	+
	5	+```Cpp
	6	+aclnnStatus aclxxXxxGetWorkspaceSize(const aclTensor src, ..., aclTensor out, ..., uint64_t workspaceSize, aclOpExecutor *executor);
	7	+aclnnStatus aclxxXxx(void workspace, uint64_t workspaceSize, aclOpExecutor executor, aclrtStream stream);
	8	+```
	9	+
	10	+You must first call the first-stage interface aclxxXxxGetWorkspaceSize to calculate how much workspace memory is required during this API call. After obtaining the calculated workspaceSize, apply for NPU memory according to the workspaceSize, and then call the second-stage interface aclxxXxx to execute the calculation.
	11	+
	12	+Here, "aclxx" represents the operator interface prefix, such as aclnn; and "Xxx" represents the corresponding operator type, such as the Add operator.
	13	+
	14	+> Note:
	15	+>
	16	+> - workspace refers to the temporary memory required by the API to complete the calculation on the AI processor, in addition to input/output.
	17	+> - The second-stage interface aclxxXxx(...) cannot be called repeatedly. The following calling method will cause an exception:
	18	+>
	19	+> ```Cpp
	20	+> aclxxXxxGetWorkspaceSize(...)
	21	+> aclxxXxx(...)
	22	+> aclxxXxx(...)
	23	+> ```

Adocs/en/debug/cann_simulator.md+249-0

@@ -0,0 +1,249 @@
	1	+# Introduction
	2	+
	3	+CANN Simulator is a SoC-level chip simulation tool designed for operator development scenarios. It analyzes the accuracy and performance data (such as instruction execution status) of AI tasks running on the AI simulator at each stage. This tool helps users perform deep performance tuning, enabling developers to obtain verification results and performance feedback nearly consistent with real chips even when real chips are unavailable or chip resources are scarce.
	4	+
	5	+# Main Functions
	6	+
	7	+This tool maintains binary compatibility with on-board execution (the same kernel can be executed on both the simulator and the AI processor). The main uses are as follows:
	8	+
	9	+* Accuracy simulation: Outputs bit-level accuracy results, helping users complete operator accuracy verification.
	10	+* Performance simulation: Outputs instruction pipeline diagrams, helping users identify operator performance bottlenecks.
	11	+
	12	+# Preparation Before Use
	13	+
	14	+## Usage Constraints
	15	+
	16	+* Recommended tool environment configuration: CPU with 16 cores or more, memory of 32 GB or more.
	17	+* All paths mentioned in this document must ensure that the running user has read or read-write permissions.
	18	+* For security and minimal permissions, it is recommended to use regular user permissions to execute this tool. Avoid using root or other high-privilege accounts.
	19	+* This tool depends on the CANN software package. Before using it, install the CANN software package. Driver and firmware installation is not required. Execute the CANN set_env.sh environment variable file through the source command. For security, do not modify the environment variables involved in set_env.sh after executing the source command.
	20	+* Users should follow the principle of least privilege. For example, files input to the tool must not be writable by other users. In some more stringent security scenarios, ensure that input files are not writable by group users.
	21	+* This tool is a development tool and is not recommended for use in production environments.
	22	+* The simulation function of the tool only supports single-card scenarios and cannot simulate multi-card environments. Only card 0 can be set in the code. Modifying the visible card number will cause simulation failure.
	23	+* The simulation environment only supports AI Core computation-type operators (MC2 and HCCL type operators are not supported).
	24	+* The CANN Simulator tool is currently in the early-access version stage and only supports the Ascend950PR chip. It is recommended that the simulator running environment be configured with a 16-core CPU and 32 GB or more memory.
	25	+* ARM environment simulation is not supported at this time.
	26	+
	27	+## Environment Preparation
	28	+
	29	+CANN Simulator is integrated in the CANN toolkit package. Complete the software package installation by following [Environment Deployment](../context/quick_install.md).
	30	+
	31	+# Quick Start
	32	+
	33	+The following uses [add_examples](../../../examples/add_example/) as an example to describe operator simulation in detail.
	34	+
	35	+## Operator Compilation
	36	+
	37	+* Complete the add_example operator compilation and installation by following [Operator Invocation](../invocation/quick_op_invocation.md).
	38	+
	39	+```bash
	40	+# Note: Enter the project root directory and execute the following compilation command. The command is for reference only. For details, refer to the operator invocation instructions.
	41	+bash build.sh --pkg --soc=Ascend950 --vendor_name=custom --ops=add_example
	42	+# Install the custom operator package
	43	+./build_out/cann-ops-nn-${vendor_name}_linux-${arch}.run
	44	+```
	45	+
	46	+* Complete the compilation of test_aclnn_add_example.cpp by following [aclnn Invocation](../invocation/op_invocation.md#aclnn-invocation), and generate the executable file test_aclnn_add_example.
	47	+
	48	+## Execute Simulation Command
	49	+
	50	+```bash
	51	+cannsim record ./test_aclnn_add_example -s Ascend950 --gen-report
	52	+```
	53	+
	54	+The simulation tool execution log files are in the examples/add_example/examples/build/bin/cannsim_* directory. The execution log file is:
	55	+
	56	+```bash
	57	+cannsim.log
	58	+```
	59	+
	60	+From the simulation tool log file, you can see the print information in the sample:
	61	+
	62	+```bash
	63	+add_example first input[0] is: 1.000000, second input[0] is: 1.000000, result[0] is: 2.000000
	64	+add_example first input[1] is: 1.000000, second input[1] is: 1.000000, result[1] is: 2.000000
	65	+add_example first input[2] is: 1.000000, second input[2] is: 1.000000, result[2] is: 2.000000
	66	+add_example first input[3] is: 1.000000, second input[3] is: 1.000000, result[3] is: 2.000000
	67	+add_example first input[4] is: 1.000000, second input[4] is: 1.000000, result[4] is: 2.000000
	68	+add_example first input[5] is: 1.000000, second input[5] is: 1.000000, result[5] is: 2.000000
	69	+add_example first input[6] is: 1.000000, second input[6] is: 1.000000, result[6] is: 2.000000
	70	+```
	71	+
	72	+## View Performance Pipeline
	73	+
	74	+The simulation performance pipeline files are in the `examples/add_example/examples/build/bin/cannsim_*/report` directory of this project. The pipeline-related file is:
	75	+
	76	+```bash
	77	+trace_core0.json
	78	+```
	79	+
	80	+Enter "chrome://tracing" in the Chrome browser and drag the generated instruction pipeline diagram file (trace_core0.json) to the blank area to open it. For specific parameter descriptions, refer to the "Simulation Result Analysis" section.
	81	+
	82	+# Simulation Execution Instructions
	83	+
	84	+## Command Function
	85	+
	86	+Execute the application in the simulation environment.
	87	+
	88	+## Command Format
	89	+
	90	+cannsim record [options] user_app --user-options
	91	+
	92	+## Parameter Description
	93	+
	94	+Table 1 Simulation Execution Parameter Description
	95	+
	96	+\|Parameter\|Required/Optional\|Description\|
	97	+\| --- \| --- \| --- \|
	98	+\|-s or --soc-version [options] parameter \| Required \| Specify the target chip version for simulation (for example: Ascend950).\|
	99	+\|-o or --output [options] parameter \| Optional\| The path where the generated files are stored. It can be configured as an absolute path or a relative path, and the user executing the tool must have read-write permissions. If the path is not specified, data is saved in the current directory by default.\|
	100	+\|-g or --gen-report [options] parameter \| Optional \| Enable automatic analysis after simulation completion and generate an analysis report. By default, automatic analysis is not enabled.\|
	101	+\|user_app\|Required\|Operator executable file.\|
	102	+\|--user-options\|Optional\|Running parameters of the operator executable file.\|
	103	+
	104	+## Usage Example
	105	+
	106	+1. Complete operator development and compilation.
	107	+2. Execute the simulation command. Refer to the following usage examples:
	108	+
	109	+ ```text
	110	+ Method 1: Enable simulation and save the output to the ./output directory. /path/to/app is the operator program.
	111	+ $ cannsim record /path/to/app -o ./output -s Ascend950
	112	+
	113	+ Method 2: Enable simulation and generate a report for subsequent performance analysis.
	114	+ $ cannsim record /path/to/app -o ./output -s Ascend950 --gen-report
	115	+ ```
	116	+
	117	+3. After the command completes, a folder named "cannsim_{timestamp}_${user_app}" is generated in the default path or the specified "output" directory. The structure example is as follows:
	118	+
	119	+ ```text
	120	+ ├─cannsim_{timestamp}_${user_app}
	121	+ ├── cannsim.log
	122	+ ```
	123	+
	124	+4. You can obtain the operator execution results and compare the accuracy. The results are displayed in cannsim.log. An example is as follows:
	125	+
	126	+ The following output is only an example of the AscendC single-operator direct invocation accuracy comparison result. It may vary slightly depending on the version. Please refer to the actual output.
	127	+
	128	+ ```bash
	129	+ INFO:root:[INFO] compare data case[ case001]
	130	+ INFO:root:---------------RESULT---------------
	131	+ INFO:root:['case_name', 'wrong_num', 'total_num', 'result', 'task_duration']
	132	+ INFO:root:[' case001', 0, 65536, 'Success']
	133	+ ```
	134	+
	135	+5. View the operator instruction pipeline diagram. Refer to the simulation result analysis section.
	136	+
	137	+# Simulation Result Analysis Instructions
	138	+
	139	+## Command Function
	140	+
	141	+Generate a visualized instruction pipeline diagram.
	142	+
	143	+## Command Format
	144	+
	145	+cannsim report [options]
	146	+
	147	+## Parameter Description
	148	+
	149	+Table 1 Simulation Result Analysis Parameter Description
	150	+
	151	+\|Parameter \| Required/Optional \| Description\|
	152	+\| --- \| --- \| --- \|
	153	+\|-e or --export [options] parameter \| Required \| The original result file directory. It must be specified as the result directory generated after simulation execution, pointing to the cannsim_{timestamp}_${user_app} level. It can be configured as an absolute path or a relative path, and the tool execution user must have read-write permissions.\|
	154	+\|-o or --output [options] parameter \| Optional \| The analysis result output directory. It can be configured as an absolute path or a relative path, and the execution user must have read-write permissions. If the path is not specified, data is saved in the current directory by default. If the generated result file has the same name as an existing file, the existing file is overwritten.\|
	155	+\|-n or --core-id [options] parameter \| Optional \| Specify the core ID for generating the instruction pipeline. If not specified, the pipeline for core 0 is generated by default. The configuration format is as follows: To generate pipelines for all cores, configure 'all'. To specify a core ID range, for example: '0-1'. To specify a single core ID, for example: '5'.\|
	156	+
	157	+## Usage Example
	158	+
	159	+1. Execute operator simulation by following the simulation execution instructions, and compare the output example to ensure the corresponding results are correct.
	160	+2. Execute the simulation result analysis command. Refer to the following execution example.
	161	+
	162	+ ```bash
	163	+ Generate a performance analysis report in the current directory (default: analyze only core 0)
	164	+ cannsim report -e /path/to/cannsim_{timestamp}_${user_app}
	165	+
	166	+ Generate performance analysis reports for core 0, core 1, core 11, and core 12 in the specified directory
	167	+ cannsim report -e /path/to/cannsim_{timestamp}_${user_app} -o /path/to/report -n '0-1, 11-12'
	168	+ ```
	169	+
	170	+3. After the command execution completes, the corresponding pipeline files are generated in the output configured directory. The file format is JSON. The output result example is as follows:
	171	+
	172	+ ```bash
	173	+ trace_core0.json
	174	+ trace_core1.json
	175	+ ...
	176	+ ```
	177	+
	178	+4. View simulation results
	179	+ Enter "chrome://tracing" in the Chrome browser and drag the generated instruction pipeline diagram file (trace.json) to the blank area to open it. Use keyboard shortcuts (W: zoom in, S: zoom out, A: move left, D: move right) to view the results.
	180	+ <!--![Instruction Pipeline Diagram](../figures/指令流水图.png)-->
	181	+
	182	+ Table 2 Key Field Description
	183	+
	184	+ \|Field Name\|Field Meaning\|
	185	+ \| --- \| --- \|
	186	+ \|VECTOR\|Vector computation unit.\|
	187	+ \|SCALAR\|Scalar computation unit.\|
	188	+ \|Cube\|Matrix multiplication computation unit.\|
	189	+ \|MTE1\|Data transfer pipeline; data transfer direction: L1 ->{L0A/L0B, UBUF}.\|
	190	+ \|MTE2\|Data transfer pipeline; data transfer direction: {DDR/GM, L2} ->{L1, L0A/B, UBUF}.\|
	191	+ \|MTE3\|Data transfer pipeline; data transfer direction: UBUF -> {DDR/GM, L2, L1}, L1->{DDR/L2}.\|
	192	+ \|FIXP\|Data transfer pipeline; data transfer direction: FIXPIPE L0C -> OUT/L1.\|
	193	+ \|FLOWCTRL\|Control flow instruction.\|
	194	+ \|ICACHELOAD\|View ICache misses.\|
	195	+
	196	+# Query Help Information
	197	+
	198	+## Command Function
	199	+
	200	+Query tool help information.
	201	+
	202	+## Command Format
	203	+
	204	+Query tool help information:
	205	+
	206	+```bash
	207	+cannsim --help
	208	+```
	209	+
	210	+Query tool record subcommand help information:
	211	+
	212	+```bash
	213	+cannsim record --help
	214	+```
	215	+
	216	+Query tool report subcommand help information:
	217	+
	218	+```bash
	219	+cannsim report --help
	220	+```
	221	+
	222	+## Parameter Description
	223	+
	224	+None
	225	+
	226	+## Usage Example
	227	+
	228	+1. Log in to the Host-side server.
	229	+2. Execute the following command.
	230	+
	231	+ ```bash
	232	+ cannsim --help
	233	+ ```
	234	+
	235	+## Output Description
	236	+
	237	+```bash
	238	+usage: cannsim [-h] {record,report} ...
	239	+
	240	+Command-line tool for performance simulation analysis on Ascend hardware.
	241	+
	242	+positional arguments:
	243	+ {record,report} Available commands
	244	+ record Run user application in AscendOps simulation environment
	245	+ report Generate performance analysis reports
	246	+
	247	+options:
	248	+ -h, --help show this help message and exit
	249	+```

Adocs/en/debug/op_debug_prof.md+190-0

@@ -0,0 +1,190 @@
	1	+# Operator Debugging and Tuning
	2	+
	3	+## Debugging and Troubleshooting (AI Core Operators)
	4	+
	5	+If an operator execution failure or accuracy anomaly occurs during operator execution, you can print information at each stage, such as Kernel intermediate results, for problem analysis and troubleshooting.
	6	+
	7	+### 1. Host-Side Log Acquisition Method
	8	+
	9	+* plog acquisition
	10	+
	11	+ After program execution completes, you can view the logs by default in "$HOME/ascendc/log". The host log file storage path is as follows:
	12	+
	13	+ ```bash
	14	+ $HOME/ascend/log/debug/plog/plog-pid_*.log
	15	+ ```
	16	+
	17	+ Enable the environment variable ASCEND_SLOG_PRINT_TO_STDOUT to display log output directly on the screen (1: enable screen display, 0: disable screen display). The configuration example is as follows:
	18	+
	19	+ ```bash
	20	+ export ASCEND_SLOG_PRINT_TO_STDOUT=1
	21	+ ```
	22	+
	23	+ For log-related information, refer to [Log Reference](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/maintenref/logreference/logreference_0001.html). For environment variable information, refer to [Environment Variable Reference](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/maintenref/envvar/envref_07_0001.html).
	24	+
	25	+* aclnn exception error message acquisition
	26	+
	27	+ Obtain exception information during aclnn interface invocation through the aclGetRecentErrMsg interface (refer to [acl API (C)](https://www.hiascend.com/document/detail/en/canncommercial/latest/API/appdevgapi/aclcppdevg_03_0004.html)). The usage method is as follows:
	28	+
	29	+ ```bash
	30	+ printf(aclGetRecentErrMsg());
	31	+ ```
	32	+
	33	+ The printed error message example is as follows:
	34	+
	35	+ ```bash
	36	+ [PID:646612] 2026-01-24-11:53:44.671.727 AclNN_Parameter_Error(EZ1001): Expected a proper Tensor but got null for argument addmmTensor.self.
	37	+ ```
	38	+
	39	+### 2. Kernel Debugging
	40	+
	41	+Common debugging methods are as follows:
	42	+
	43	+* printf
	44	+
	45	+ This interface supports printing Scalar-type data, such as integers, characters, and Boolean values. For detailed information, refer to [Ascend C API](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/API/ascendcopapi/atlasascendc_api_07_0003.html) in "Operator Debugging API > printf".
	46	+
	47	+ ```c++
	48	+ blockLength_ = tilingData->totalLength / AscendC::GetBlockNum();
	49	+ tileNum_ = tilingData->tileNum;
	50	+ tileLength_ = blockLength_ / tileNum_ / BUFFER_NUM;
	51	+ // Print the current core computation Block length
	52	+ AscendC::PRINTF("Tiling blockLength is %llu\n", blockLength_);
	53	+ ```
	54	+
	55	+* DumpTensor
	56	+
	57	+ This interface supports dumping the content of a specified Tensor and also supports printing custom additional information, such as the current line number. For detailed information, refer to [Ascend C API](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/API/ascendcopapi/atlasascendc_api_07_0003.html) in "Operator Debugging API > DumpTensor".
	58	+
	59	+ ```c++
	60	+ AscendC::LocalTensor<T> zLocal = outputQueueZ.DeQue<T>();
	61	+ // Print zLocal Tensor information
	62	+ DumpTensor(zLocal, 0, 128);
	63	+ AscendC::DataCopy(outputGMZ[progress * tileLength_], zLocal, tileLength_);
	64	+ ```
	65	+
	66	+For troubleshooting in complex scenarios, such as operator hangs or GM/UB access out-of-bounds, you can use step-by-step debugging. For specific operations, refer to the [msDebug](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/devaids/optool/docs/en/quick_start/msdebug_quick_start.md) operator debugging tool.
	67	+
	68	+## Debugging and Troubleshooting (AI CPU Operators)
	69	+
	70	+If an operator execution failure or accuracy anomaly occurs during operator execution, you can print information at each stage, such as Kernel intermediate results, for problem analysis and troubleshooting.
	71	+
	72	+### 1. Host-Side Log Acquisition Method
	73	+
	74	+ Refer to the AI Core operator [Host-Side Log Acquisition Method](#1-host-side-log-acquisition-method)
	75	+
	76	+### 2. Kernel Debugging
	77	+
	78	+Common debugging methods are as follows:
	79	+
	80	+* KERNEL_LOG macro
	81	+
	82	+ You can print log information during operator execution through the following macros, including DEBUG, INFO, WARN, and ERROR level logs.
	83	+
	84	+ ```Cpp
	85	+ KERNEL_LOG_DEBUG(fmt, ...) // The fmt parameter represents the format control string
	86	+ KERNEL_LOG_INFO(fmt, ...)
	87	+ KERNEL_LOG_WARN(fmt, ...)
	88	+ KERNEL_LOG_ERROR(fmt, ...) // ERROR level logs are printed by default
	89	+ ```
	90	+
	91	+ To print logs at non-ERROR levels, you need to configure the environment variable `ASCEND_GLOBAL_LOG_LEVEL` in advance. For specific usage, refer to [Environment Variable Reference](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/maintenref/envvar/envref_07_0001.html).
	92	+
	93	+ The printing example is as follows:
	94	+
	95	+ ```c++
	96	+ Tensor* input0 = ctx.Input(kFirstInputIndex);
	97	+ Tensor* input1 = ctx.Input(kSecondInputIndex);
	98	+ Tensor* output = ctx.Output(0);
	99	+
	100	+ if (input0 == nullptr \|\| input1 == nullptr \|\| output == nullptr) {
	101	+ // Print error information
	102	+ KERNEL_LOG_ERROR("Invalid argument");
	103	+ return kParamInvalid;
	104	+ }
	105	+
	106	+ int64_t num_elements = input0->NumElements();
	107	+ // Print the number of input elements
	108	+ KERNEL_LOG_INFO("Num of elements is %ld", data_size);
	109	+ ```
	110	+
	111	+## Performance Tuning
	112	+
	113	+### Method 1 (For Atlas A2/A3 Series Products)
	114	+
	115	+If execution accuracy degradation or abnormal memory usage occurs during operator execution, you can use the [msProf](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/devaids/optool/docs/en/quick_start/msopprof_quick_start.md) performance analysis tool to analyze the operator's performance metrics at each execution stage (such as throughput, memory usage, and latency), thereby identifying the root cause and performing targeted optimization.
	116	+
	117	+This chapter uses the [AddExample custom operator](../../../examples/add_example/) as an example to introduce the two commonly used methods in operator tuning: on-board performance collection and pipeline simulation. By collecting the on-board running pipeline metrics of the operator, you can analyze the operator's Bound scenario. Understanding the simulation pipeline diagram helps optimize the operator's internal pipeline.
	118	+
	119	+1. Prerequisites.
	120	+
	121	+ After completing operator development and compilation, assuming the aclnn interface invocation method is used, the generated operator executable file (test_aclnn_add_example) is located in the `examples/add_example/examples/build/bin/` directory of this project.
	122	+
	123	+2. Collect performance data.
	124	+
	125	+ When you need to collect the on-board running pipeline metrics of the operator, navigate to the directory where the operator executable file is located and execute the following command:
	126	+
	127	+ ```bash
	128	+ msprof op ./test_aclnn_add_example
	129	+ ```
	130	+
	131	+ The collection results are in the `examples/add_example/examples/build/bin/OPPROF_*` directory of this project. After collection completes, the following information is printed:
	132	+
	133	+ ``` text
	134	+ Op Name: AddExample_a1532827238e1555db7b997c7bce2928_high_performance_1
	135	+ Op Type: vector
	136	+ Task Duration(us): 97.861954
	137	+ Block Dim: 8
	138	+ Mix Block Dim:
	139	+ Device Id: 0
	140	+ Pid: 2776181
	141	+ Current Freq: 1800
	142	+ Rated Freq: 1800
	143	+ ```
	144	+
	145	+ Task Duration is the current operator Kernel execution time, and Block Dim is the current operator execution core count.
	146	+
	147	+ For detailed pipeline metrics of the operator, refer to the `ArithmeticUtilization` file under `OPPROF_*`, which contains the proportion of each pipeline. For specific descriptions, refer to the [msProf](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/latest/devaids/optool/docs/en/quick_start/msopprof_quick_start.md) section "Performance Data Files > msprof op > ArithmeticUtilization (cube and vector type instruction latency and proportion)".
	148	+
	149	+3. Collect simulation pipeline diagrams.
	150	+
	151	+ Before using the msProf tool for operator simulation tuning, execute the following command to configure the environment variable.
	152	+
	153	+ ```bash
	154	+ export LD_LIBRARY_PATH=${INSTALL_DIR}/tools/simulator/Ascendxxxyy/lib:$LD_LIBRARY_PATH
	155	+ ```
	156	+
	157	+ Modify the above environment variable according to the actual CANN software package installation path and AI processor model.
	158	+
	159	+ Then navigate to the directory where the operator executable file is located and execute the following command:
	160	+
	161	+ ```bash
	162	+ msprof op simulator --output=$PWD/pipeline_auto --kernel-name"AddExample" ./test_aclnn_add_example
	163	+ ```
	164	+
	165	+ The collection results are in the `$PWD/pipeline_auto/OPPROF_**` directory of this project.
	166	+ The pipeline-related file path is `OPPROF**/simulator/visualize_data.bin`, which can be viewed using the [mindStudio Insight](https://www.hiascend.com/document/detail/en/mindstudio/latest/visualization_tool/MindStudioInsight/docs/en/user_guide/overview.md) tool.
	167	+
	168	+### Method 2 (For Ascend 950PR)
	169	+
	170	+If execution accuracy degradation or abnormal memory usage occurs during operator development, you can use the [CANN Simulator](./cann_simulator.md) simulation tool to analyze the operator's instruction pipeline situation, thereby identifying the root cause and performing targeted optimization.
	171	+
	172	+This chapter uses the [AddExample custom operator](../../../examples/add_example/) as an example to introduce the use of the simulation tool. It describes how to perform accuracy and performance tuning through the simulation tool.
	173	+
	174	+1. Prerequisites.
	175	+
	176	+ After completing operator development and compilation, assuming the aclnn interface invocation method is used, the generated operator executable file (test_aclnn_add_example) is located in the `examples/add_example/examples/build/bin/` directory of this project.
	177	+
	178	+2. Execute the simulation command to generate simulation data.
	179	+
	180	+ ```text
	181	+ cannsim record ./test_aclnn_add_example -s Ascend950 --gen-report
	182	+ ```
	183	+
	184	+ The simulation results are in the `examples/add_example/examples/build/bin/cannsim_*` directory of this project. The pipeline-related file is:
	185	+
	186	+ ```text
	187	+ trace_core0.json
	188	+ ```
	189	+
	190	+3. Enter "chrome://tracing" in the Chrome browser and drag the generated instruction pipeline diagram file (trace_core0.json) to the blank area to open it. For specific parameter descriptions, refer to the [Simulation Result Analysis](./cann_simulator.md#simulation-result-analysis-instructions) section in CANN Simulator.

Adocs/en/develop/aicore_develop_guide.md+759-0

Adocs/en/develop/aicpu_develop_guide.md+247-0

Adocs/en/develop/graph_develop_guide.md+118-0

Adocs/en/invocation/op_invocation.md+383-0

Adocs/en/invocation/quick_op_invocation.md+368-0

Mdocs/zh/debug/op_debug_prof.md+12-12