ascendc

AscendC 算子开发（全流程）

此技能可在 ascend-kernel 项目中，将一个全新的 AscendC 自定义算子从规格开发为可用于生产环境且经过基准测试的算子（这是一个 PyTorch 自定义算子项目，通过 csrc/ops/、csrc/register.cpp 和 build.sh 将算子暴露为 torch.ops.npu.<op>）。此技能自包含：所有阶段、模板和参考资料都位于此技能目录下。

范围说明：此技能面向 ascend-kernel / csrc/ops PyTorch 自定义算子 工作流（向量 / 行 / 索引 / 排序 / 池化算子、FP16/BF16 转换为更高精度、两级分块）。此技能不适用于 ops-transformer aclnn/genop 流程。

如何使用此技能

1. 首先完整阅读此 SKILL.md（生命周期、关卡、反模式）。
2. 对于每个阶段，执行前必须打开对应的 references/NN-*.md。
3. 复用随附的 templates/、examples/ 和 scripts/；不要自行设计项目结构或 API。
4. 遵守阶段关卡：上一阶段的检查清单未通过前，绝不开始下一阶段。绝不跳过聊天中的结果展示规则。

适用场景

• “开发 / 实现 / 创建一个名为 <name> 的新 AscendC 算子”（例如 acosh、rms_norm）。
• “继续算子开发” → 根据产物检测当前阶段并继续。
• 对现有算子执行任一单独阶段：仅设计、仅生成代码、仅评估精度、仅进行性能基准测试、仅优化或仅代码审查。

生命周期概览

Phase 0  Environment + requirements
Phase 1  Project init        -> references/01-project-init.md
Phase 2  Design (design.md)  -> references/02-design.md
Phase 3  Test cases          -> references/03-testcase-gen.md
Phase 4  Code generation     -> references/04-code-gen.md (+ 04a-kernel-api.md)
Phase 5  Compile / debug     -> references/05-compile-debug.md
Phase 6  Interface docs      -> references/06-doc-gen.md
Phase 7  Precision eval      -> references/07-precision-eval.md (fail -> 07b-precision-debug.md)
Phase 8  Performance eval    -> references/08-performance-eval.md
Phase 9  Performance optim   -> references/09-performance-optim.md
Phase 10 Code review         -> references/10-code-review.md
(opt)    Memory check        -> references/11-mssanitizer.md

输入：算子名称（snake_case）+ 功能 / 数学规格。 输出：已构建并安装的算子、design.md、统一测试用例文档、PyTorch 风格的 README、精度报告、性能报告（如执行了优化 / 审查，还包括相应报告）。

阶段 0 — 环境和需求

在进行任何开发操作之前确认构建 / 运行环境。

• CANN：运行 echo $ASCEND_HOME_PATH。如果已设置，将其用作 CANN_PATH。如果未设置，必须 向用户询问 CANN 安装路径。每个 shell 中运行 source ${CANN_PATH}/*/set_env.sh 进行激活。
• Conda：运行 echo $CONDA_DEFAULT_ENV。如果结果非空且不是 base，则使用该环境。否则 必须向用户询问 conda 环境名称；使用 conda activate <env> 激活。
• 需求：算子名称（snake_case，必填）、功能规格 / 数学公式 （必填）、支持的数据类型（可选，默认为 float16, float32，可添加 bfloat16）、 SoC（可选，默认为 ascend910b，运行时通过平台 API 获取）。

详情和决策树：references/00-environment.md。

关卡：已确定 CANN 路径且可激活；已确定 conda 环境且可激活；已确认算子 名称和功能规格。

阶段 1 — 项目初始化

定位或创建 ascend-kernel 项目，然后搭建 csrc/ops/<op>/ 的初始结构。

• 使用 scripts/detect_ascend_kernel_project.sh 检测。如果未找到，则复制随附的 模板 templates/ascend-kernel/ 并运行 chmod +x build.sh。
• 创建 csrc/ops/<op>/{op_host/<op>.cpp, op_kernel/<op>.cpp, CMakeLists.txt, design.md} （占位文件）。
• 标记供后续阶段更新的三个注册点：csrc/ops.h、 csrc/register.cpp、csrc/CMakeLists.txt。

阅读 references/01-project-init.md。

关卡：项目已存在（含 build.sh、CMakeLists.txt、csrc/）；已创建 包含四个文件的 csrc/ops/<op>/ 骨架。

阶段 2 — 设计（design.md）

编写完整的设计文档，作为代码生成的直接输入。

• 选择实现路径（默认使用 AscendC Kernel；仅矩阵乘法／Cube 使用 CATLASS）。
• 将数学运算映射为一系列 AscendC API 调用；设计两级切分（块级跨核切分 + UB 级核内切分）；填写 UB 分配表，并按 dtype 推导 bufferCoefficient；描述 FP16/BF16 → FP32 升精度路径。
• 填写 templates/design-template.md → 写入 csrc/ops/<op>/design.md。

阅读 references/02-design.md（按运算类型切分、UB 分配、API 映射、硬件约束）。

门槛：design.md 包含函数签名、支持的 dtype、API 伪代码、包含各 dtype 对应 bufferCoefficient 的 UB 分配表、切分结构体和升精度路径。

阶段 3 — 测试用例

生成一份统一的测试用例文档，供后续精度和性能测试复用。

• 阅读 design.md；生成 SUPPORTED_DTYPES、TEST_SHAPES、GENERAL_SHAPES、BOUNDARY_VALUES 和算子基准（CPU 参考实现 + NPU 调用）。
• 用例总数 (TEST_SHAPES + GENERAL_SHAPES) x SUPPORTED_DTYPES >= 30；单个形状的元素数量应合理（常规用例不超过约 200K）。
• 填写 templates/test-cases-template.md → 写入 csrc/ops/<op>/test/<op>-test-cases.md。

阅读 references/03-testcase-gen.md。

门槛：测试用例文档存在，包含 dtype、形状、边界值和基准；取值符合 design.md 中的约束。

阶段 4 — 代码生成 + 框架适配

生成 op_host 和 op_kernel，然后将其接入框架。

• 根据算子类型（逐元素／行／索引／逐元素索引／排序／池化）从 templates/code-gen/ 中选择一对模板；复制到 csrc/ops/<op>/ 并进行适配。
• op_host：函数签名、输入检查、用于获取 coreNum／ubSize 的平台 API（不得硬编码）、bufferCoefficient、左值形式的 EXEC_KERNEL_CMD 参数。
• op_kernel：BUFFER_NUM=2、初始化核偏移量、InitBuffer 大小、计算逻辑、尾块对齐、FP16/BF16 升精度到 FP32、GM↔UB 使用 DataCopyPad、Reduce 前备份。
• 框架：在 csrc/ops.h 中添加声明，在 csrc/register.cpp 中添加 m.def+m.impl，在 csrc/CMakeLists.txt 中添加 host+kernel 源文件。

阅读 references/04-code-gen.md 和 references/04a-kernel-api.md 中的 API 要点。

门槛：生成两个源文件；更新三个注册位置；满足参考文档中的检查清单。

阶段 5 — 编译、安装、测试、调试

构建项目、安装 wheel、生成基础测试、运行并调试。

• 执行 chmod +x build.sh && bash build.sh；确认生成了 output/ascend_kernel*.whl。
• 执行 pip install output/ascend_kernel*.whl --force-reinstall --no-deps。
• 生成 tests/test_<op>.py；先运行功能测试（python ...），再运行精度测试（pytest -v）。每次执行 shell 命令前都要加载环境。
• 若失败，使用错误决策树运行调试循环（最多尝试 3 次）。

阅读 references/05-compile-debug.md。

门槛：wheel 已构建并安装；功能测试以 0 退出；精度 pytest 全部通过。

阶段 6 — 接口文档

从源代码中提取接口信息，并生成 PyTorch 风格的 README。

• 从 register.cpp（m.def）提取 schema，从 ops.h 提取 C++ 签名，从 design.md 提取算法／dtype／约束，从 op_host 提取 TORCH_CHECK，从测试文件提取示例。
• 组装固定章节并写入 csrc/ops/<op>/README.md。默认使用英文；按需切换为中文。
• 必须在聊天中展示 README 的完整内容，不能只提供路径。

阅读 references/06-doc-gen.md。

门槛：README 包含签名、参数、dtype、形状、约束、示例和返回值；与 register.cpp 中的 schema 一致；并已在聊天中展示。

阶段 7 — 精度评估

运行全面的精度测试套件并生成报告。

• 加载阶段 3 的测试用例文档；调整为 (形状 + 边界) x 数据类型 >= 30。
• 从 templates/precision/ 生成 test_<op>_precision.py 和 run_<op>_precision_report.py；运行 pytest，然后运行报告生成器。
• 通过规则（MERE/MARE，生态系统开源标准）：MERE < Threshold 且 MARE < 10 x Threshold。标准表见 references/07a-precision-standards.md。
• 如果精度失败且无法通过阈值解决，请根据 references/07b-precision-debug.md 进行根因调试。
• 必须在聊天中展示：概览（总数 + 通过率）、所有失败项，以及 >=3 个关键发现，然后给出报告路径。

阅读 references/07-precision-eval.md。

门槛：pytest 全部通过；已写入 JSON + Markdown 报告；已在聊天中展示结果。

阶段 8 — 性能评估

使用 torch_npu.profiler 对自定义算子与基线进行基准测试。

• 根据测试用例文档 + design.md 构建 JSONL 用例文件（>= 8 个用例）；始终运行双路径对比（自定义算子与基线；基线必须在 NPU 上运行——如果没有等效 API，则使用小算子组合）。
• 固定调度为 warmup=5, active=5；从 ASCEND_PROFILER_OUTPUT/op_statistic.csv 汇总 Total Time(us)。复制 examples/layer_norm_profiler_reference/ 作为起点。
• 必须在聊天中展示：统一对比表（含 DType 列）、总结，以及 >=3 条简短结论，然后给出报告路径。

阅读 references/08-performance-eval.md、 references/08a-profiler-and-metrics.md 和 references/08b-perf-case-jsonl.md。

门槛：已写入双路径报告；已在聊天中展示表格 + 总结 + 结论。

阶段 9 — 性能优化（可选，闭环）

调查、修改并验证，最多 3 轮。

• 从 5 个维度（切分、数据拷贝、API 使用、内存、流水线）进行调查并生成排序报告；保存基线快照。
• 遵循反模式清单应用更改；重新运行精度评估（必须通过），然后运行相同的性能用例；与基线对比并迭代。

阅读 references/09-performance-optim.md。

门槛：精度仍然通过；性能已与基线对比；已在聊天中展示结果。

阶段 10 — 代码审查（可选）

针对编码红线进行假设检验式安全审查（数值、内存/指针、资源、输入验证、并发、算子接口、ABI 兼容性）。

阅读 references/10-code-review.md。

可选 — 内存检查

运行 mssanitizer，以检测非法访问、泄漏和越界未定义行为（UB）。 阅读 references/11-mssanitizer.md。

统一反模式（绝不可触犯）

• 绝不可跳过设计直接编写代码；代码生成会读取 design.md。
• 绝不可让 FP16/BF16 直接进行复杂数学运算——先提升为 FP32。
• 绝不可将 DataCopy 用于 GM↔UB——请使用 DataCopyPad。
• 绝不可将右值（临时值/字面量/表达式）传入 EXEC_KERNEL_CMD。
• 绝不可硬编码核心数或 UB 大小——请查询平台 API。
• 绝不可修改 cmake/ 或 csrc/utils/ 下的文件。
• 绝不可在 ReduceSum/ReduceMax 后立即复用源张量（归约可能会修改它）。
• 绝不可在内核中使用 std::min/max/abs/sqrt/exp 等函数。
• 绝不可向高维切分 API 传入 repeatTime > 255（会静默截断为 uint8）。
• 绝不可使用非 profiler 计时方法得出性能结论。
• 绝不可只报告精度/性能/优化的文件路径——请在聊天中展示表格和结论。

从中断处恢复

检测到的状态	未完成的阶段	从以下阶段恢复
csrc/ops/<op>/ 缺失	1	阶段 1
design.md 是占位文件/为空	2	阶段 2
<op>-test-cases.md 缺失	3	阶段 3
op_host 仍是骨架	4	阶段 4
wheel 未构建 / 基本测试失败	5	阶段 5
README.md 缺失	6	阶段 6
没有精度报告 / 精度测试失败	7	阶段 7
已有精度报告，但没有性能报告	8	阶段 8

状态跟踪器

阶段	前置条件	参考资料	关键产物
0 环境 + 需求	—	00-environment	CANN + conda + 名称 + 规格
1 初始化	0	01-project-init	csrc/ops/<op>/ 骨架
2 设计	1	02-design	design.md
3 测试用例	2	03-testcase-gen	<op>-test-cases.md
4 代码生成	3	04-code-gen	op_host + op_kernel + 注册
5 编译/调试	4	05-compile-debug	已安装的 wheel + 全部通过的测试
6 文档	5	06-doc-gen	README.md
7 精度	6	07-precision-eval	精度报告
8 性能	7	08-performance-eval	性能报告
9 优化	8	09-performance-optim	优化摘要
10 审查	4+	10-code-review	审查报告

依赖项

此技能是自包含的（已打包模板、参考资料、示例和脚本）。 要编译和运行算子，只需在搭载 Ascend NPU 的主机上配备可用的 CANN 工具包以及 PyTorch + torch_npu conda 环境。