Merged
docs(zh): 算子工程指南改用手写 CMakeLists.txt #6997
docs(zh): 算子工程指南改用手写 CMakeLists.txt #6997
Merged
zhugexun_sjtuAdd on 27 days ago
zhugexun_sjtu
zhugexun_sjtuCollaborators
27 days ago

描述

将自定义算子工程的编程指南改为从零创建目录、编写源文件和 CMakeLists.txt,再通过 CANN 提供的 npu_op_* 接口完成编译、打包、部署和调用验证。

  • 快速入门按共享 Tiling 头文件、Kernel、完整 Host 实现、三个 CMakeLists.txt、编译部署和独立调用工程的顺序展开;恢复 Python 构建依赖说明。
  • 区分设备 soc_version 与构建目标标识,补充常见型号映射,统一 CMake 与 AddConfig 配置,并在加载 ASC 前设置可被命令行/preset 覆盖的默认值。
  • 修复 CMake 框架真实 bug:ASCEND_SOC_SERIES 在 find_package(ASC) 之后设置会被静默忽略,现通过 _asc_ensure_build_target() 宏在首次实际使用时重新解析,与 ASCEND_COMPUTE_UNIT 的顺序无关行为保持一致。
  • 去掉文档和示例代码中为兼容旧顺序要求而写的 if(NOT DEFINED ASCEND_COMPUTE_UNIT) 判断;统一构建目录命名为 build,去掉编译调试/加速/动静态库等文档对 CMakePresets.json 的隐性依赖。
  • 修复不可执行的 CMake 二选一写法,保留完整可用的可选 preset,统一无 preset 的交叉编译和调用路径;补充 CMAKE_CROSS_LIBRARY_PATH 变量说明。
  • 补齐 TensorFlow、ONNX 插件的目录创建、各层 CMake 接入和打包步骤,以及入图所需的 GRAPH 原型库配置(该配置示例现统一放在编译与部署基本流程文档中,概述文档不再重复)。
  • 补充 CMake 函数参考中全局构建目标变量与函数级 SOC_SERIES/COMPUTE_UNIT 参数的层次关系说明及按系列分流核函数的场景示例。
  • 核对文档中的示例代码与 examples/ 下的真实样例,修正若干漂移:Tiling 下沉核函数的任务类型/模板参数、TensorFlow CPU 核函数宏、ONNX 插件 json.hpp 获取方式、单算子图执行样例的构建命令等,均已对齐真实样例。
  • 修复 opbuild 的 SOC 白名单遗漏:mc32dm11a 此前只存在于 CMake 侧白名单,opbuild 侧缺失会导致该型号被静默判定为非法值(仅告警不报错),现已补齐。
  • 清理中文文档中的 msOpGen 描述和自动生成目录假设,移除通算融合实践中已过时的工具流程和目录树;保留一条指向 msOpGen 快速入门的简短说明作为备选工具路径。外部样例的构建命令以其维护方 README 为准。

关联的Issue

无。

测试

  • 38 个 CMake 代码块通过语法解析,快速入门的 8 个 shell 代码块通过 bash -n。
  • 使用仓内实际 ASC 配置模块验证默认目标、命令行覆盖、ASCEND_SOC_SERIES 初始化以及 preset 配置和覆盖行为;额外验证 _asc_ensure_build_target() 宏在 7 种设置顺序/冲突场景下的行为。
  • 11 个设备型号到构建目标的映射与仓内实现一致。
  • 大文件、冲突标记、私钥和 codespell 检查通过;仓库 Markdown 检查脚本以离线模式检查修改页及其引用页,通过。
  • 同版本 OAT 检查入口执行通过;按仓库规则,Markdown 文档无待扫描文件。自动隔离环境的依赖下载超时,未用于本次 OAT 执行。
  • git diff --check 通过;中文 Markdown 文档无 msopgen 残留(除保留的备选工具说明外)。快速入门 C++ 示例与 examples/custom_op 逐行对齐。
  • 系统性核对了 aclnn_operator_development、ai_framework_adaptation、operator_graph_development 下文档的示例代码与 examples/ 真实源码的一致性,修正发现的漂移项。
  • 本次为文档及 CMake/opbuild 配置变更,未执行 Linux/CANN/NPU 环境的端到端编译运行。

文档更新

更新中文算子工程快速入门、编译部署、CMake 函数参考、框架适配、入图开发、原型注册及相关实践与 API 说明。PR 共涉及 24 个文档文件、3 个 CMake 框架/脚本文件、2 个样例 CMakeLists.txt 文件、2 个 opbuild 工具文件。

类型标签

likedislike
Pull Request has been successfully merged by CANN-robot.
(Thank you for zhugexun_sjtu's contribution.)
zhugexun_sjtuzhugexun_sjtuCollaborators
27 days ago Created pull request, commit 4186f3cd
atomgit-bot
atomgit-bot
27 days ago Comments:

变更摘要

本 PR 是面向中文文档的去 msOpGen 化改造:将 docs/zh 中以 msOpGen 工具生成算子工程为主线的说明,改为引导开发者直接创建目录、编写 CMakeLists.txt,并通过 CANN 提供的 npu_op_* 系列 CMake 接口完成算子包声明、aclnn 代码生成与 Host/核函数侧库编译。改写内容与 examples/01_simd_cpp_api/02_features/99_acl_based/00_acl_compilation 样例保持一致,同时统一了 ASCEND_COMPUTE_UNIT 配置位置与核函数命名等表述。

主要改动

  • 快速入门改为手写 CMake 工程:aclnn_quick_start.md 删除 msOpGen JSON 原型与 msopgen gen 命令,改为创建 op_host/op_kernel 目录并给出顶层、op_host、op_kernel 三层 CMakeLists.txt,使用 find_package(ASC)、npu_op_package、npu_op_code_gen、npu_op_library、npu_op_kernel_sources、npu_op_kernel_library、npu_op_package_add 等接口。
  • 编译部署流程调整:basic_process.md 将 CMakeLists.txt 内设置变量作为推荐方式(方式一),CMakePresets.json 降为可选的解耦方式(方式二);编译命令由 ./build.sh 改为 cmake .. 与 make -j binary package,产物目录由 build_out 改为 build。
  • 配置项引用口径统一:AddConfig.md、HcclServerType.md、op_compilation_migration.md、operator_prototype_definition.md 中,ASCEND_COMPUTE_UNIT 的取值说明由“CMakePresets.json 中由 msOpGen 自动生成”改为“与 CMakeLists.txt 中设置的变量或 CMakePresets.json 中的字段一致”。
  • 框架适配与术语表述更新:tensorflow_framework.md 移除 msopgen ... -f tf 命令,改为在 framework/tf_plugin 下编写插件并通过 npu_op_library 的 TF_PLUGIN 类型编译;glossary.md、overview.md 将“自定义算子工程”定义改为基于 CMake 组织编译、由开发者直接编写。
  • 辅助说明与示例清理:external_sample_links.md 删除 msOpGen 样例链接;naming_conversion_table.md 改为按命名规则编写文件即可免于在 npu_op_kernel_sources 中指定 KERNEL_FILE;kernel_operator_implementation.md 与 kernel_tiling_info_incorrect.md 将自动生成模板/ref 后缀等描述改为开发者编写时的约定。

变更摘要

本 PR 对 docs/zh 下 15 个文档进行去 msOpGen 化改造:不再以 msOpGen 工具生成算子工程为主线,改为引导开发者直接创建工程目录并编写 CMakeLists.txt,使用 CANN 提供的 npu_op_* 系列 CMake 接口声明算子包、生成 aclnn 单算子调用代码、编译 Host 侧与核函数(Kernel)侧库,写法与 examples/01_simd_cpp_api/02_features/99_acl_based/00_acl_compilation 样例保持一致。

主要改动

  • 快速入门改为手写工程与 CMake:aclnn_quick_start.md 移除 add_custom.json 原型文件与 msopgen gen -i ... -c ... -lan cpp -out ... 命令,改为 mkdir -p AddCustom/op_host AddCustom/op_kernel 建目录,并给出顶层、op_host、op_kernel 三份 CMakeLists.txt,涉及 find_package(ASC)、npu_op_package、npu_op_code_gen、npu_op_library、npu_op_kernel_sources、npu_op_kernel_library、npu_op_package_add。
  • 编译部署流程改用 cmake/make:basic_process.md 将“在 CMakeLists.txt 中设置变量”提为推荐的方式一,CMakePresets.json 降为可选的方式二;编译步骤由 ./build.sh 改为 mkdir -p build && cd build + cmake .. + make -j binary package,安装包路径由 build_out 改为 build。
  • ASCEND_COMPUTE_UNIT 取值规则统一:AddConfig.md、HcclServerType.md、2201_to_3510_guide/op_compilation_migration.md、operator_prototype_definition.md 中,将该字段的填写规则从“CMakePresets.json 中由 msOpGen 自动生成”改为“与 CMakeLists.txt 中设置的变量或 CMakePresets.json 中的字段一致”。
  • 框架适配与术语描述调整:tensorflow_framework.md 删除 msopgen ... -f tf 命令,改为在 framework/tf_plugin 目录编写适配插件并通过 npu_op_library 的 TF_PLUGIN 类型编译;glossary.md、overview.md 将“自定义算子工程”重新定义为开发者直接编写、基于 CMake 组织编译的工程。
  • 辅助文档同步清理:external_sample_links.md 去掉 msOpGen 样例条目;naming_conversion_table.md 改为遵循命名规则即可省略 npu_op_kernel_sources 的 KERNEL_FILE;kernel_operator_implementation.md、kernel_tiling_info_incorrect.md 将“msOpGen 自动生成模板/ref 后缀”改为开发者编写时的约定,cmake_function_reference.md 概述同步改为开发者自行编写 CMakeLists.txt。
likedislike
Incorrect?
atomgit-bot
atomgit-bot
27 days ago Comments:

代码审查

审查结论

本次改动是纯文档变更(15 个文件),不涉及代码与构建脚本本身的可执行逻辑;整体方向(去 msOpGen 化、引导直接编写 CMakeLists.txt)内部基本自洽,但存在若干“只改了一半”的残留与示例不完整问题。

发现清单(按严重度)

优先级 文件:行 问题
P2 aclnn_quick_start.md:136-140 新增 op_host/CMakeLists.txt 样例未编译 cust_op_proto(GRAPH),与同文档部署目录结构(op_proto)、basic_process.md 的“run 包包含算子原型库”说明不一致,入图/框架适配场景会缺原型库
P3 basic_process.md:63 set(A ..) | set(B ..) 不是合法 CMake,被提升为“推荐默认方式”后复制即配置失败
P3 operator_prototype_definition.md:204 句子缺谓语“保持一致”,且仍残留“使用 msOpGen 创建工程时自动生成”的旧表述
P3 tensorflow_framework.md:17 单向改动:“会在算子工程目录下生成 framework/tf_plugin”(第 30 行)与第 32–46 行 msOpGen 目录结构未同步,且未说明 add_subdirectory(framework) 的构建接入
P3 tensorflow_framework.md:17 链接“TF_PLUGIN 库编译样例”指向的章节内并无 TF_PLUGIN 示例(仅参数枚举)
P3 basic_process.md:129 新增页内跳转依赖中文+全角冒号的自动锚点,与本文件统一使用显式 <a id> 的约定不符,存在死链风险
P3 aclnn_quick_start.md:368 编译步骤的 cd AddCustom 与新增“创建工程”步骤中的 cd AddCustom 叠加,顺序执行会报目录不存在

逐文件复核结果

  • docs/zh/api/.../AddConfig.md、.../HcclServerType.md:表述已与新 CMake 流程一致,no issues。
  • docs/zh/guide/cross_gen_migration_guide/.../op_compilation_migration.md:no issues。
  • aclnn_operator_development/aclnn_quick_start.md:2 条(P2 缺 GRAPH 原型库;P3 重复 cd)。
  • aclnn_operator_development/appendix/cmake_function_reference.md:no issues(概述改写正确)。
  • aclnn_operator_development/appendix/external_sample_links.md:删除 msOpGen 样例后列表结构完好,no issues。
  • aclnn_operator_development/appendix/naming_conversion_table.md:与 KERNEL_FILE 可选语义一致,no issues。
  • aclnn_operator_development/compilation_and_deployment/basic_process.md:2 条(P3 非法 CMake 写法;P3 锚点约定)。
  • aclnn_operator_development/design_and_implementation/kernel_operator_implementation.md:no issues。
  • aclnn_operator_development/design_and_implementation/operator_prototype_definition.md:1 条(P3 残句+ msOpGen 残留)。
  • aclnn_operator_development/overview.md:no issues(与样例工程的偏差已在 P2 中作为证据引用)。
  • ai_framework_adaptation/tensorflow_framework.md:2 条(均为 P3)。
  • operator_graph_development/overview.md、appendix/faq/kernel_tiling_info_incorrect.md、technical_appendix/concepts_and_terms/glossary.md:no issues。

总体风险判断

无 P0/P1。主要风险集中在“快速入门示例工程不完整”(缺 GRAPH 原型库)与两处“只改一半”的残留表述(TF 插件目录的自动生成说明、原型定义处的 msOpGen 断言),会影响按文档新建工程的开发者(尤其入图/框架适配路径);其余为示例可用性与锚点一致性级别的低风险问题,建议一并修正后合入。

类型 数量
🔴 阻塞 0
🟡 建议 1

💬 仅评论

likedislike
Incorrect?
CANN-robotCANN-robotCollaborators
27 days ago Added label: cann-cla/yes
CANN-robot
CANN-robotCollaborators
27 days ago Comments:

Thanks for your pull-request.
The full list of commands accepted by me can be found at here.
You can get sig-info at here.
You can self-configure the PR merge rules for this repository. For more details, please refer to Here.
For more, you also can visit HICANN.


PR Approval Progress

✅ Congratulations! All modules have met the lgtm and approve requirements.

Module Approval Details

module lgtm status approve status
cmake ✅ chentianyu19, hujiawen_kaven (2/2) ✅ chentianyu19 (1/1)
docs ✅ ai_xin, chentianyu19, hujiawen_kaven (3/2) ✅ ai_xin (1/1)
examples ✅ ai_xin, hujiawen_kaven, chentianyu19 (3/2) ✅ ai_xin (1/1)
tools/build ✅ hujiawen_kaven, chentianyu19 (2/2) ✅ hujiawen_kaven (1/1)

💡 Tip:

  • Committer can comment /approve or /lgtm
  • Commenting /approve implies both code review (lgtm) and intent to merge (approve)

CLA Signature Pass

xun_zhuge, thanks for your pull request. All authors of the commits have signed the CLA. 👍

likedislike
226 messages are collapsed here。 See more
chentianyu19
chentianyu19Collaborators
12 days ago Comments:

/lgtm
/approve

likedislike
CANN-robotCANN-robotCollaborators
12 days ago Added label: lgtmapproved
CANN-robot
CANN-robotCollaborators
12 days ago Comments:

The MR can not be merged, because of CodeReview discussion not resolved

If you want to solve this problem, you can click here to do it in the FAQs.

likedislike
WeijieWangWeijieWangCollaborators
12 days ago Resolved final issue
CANN-robotCANN-robotCollaborators
12 days ago Merged pull request