version: "1.0.0" name: ascendc-direct-invoke-template description: Kernel直调工程模板，用于创建 Ascend C Kernel 直调工程项目。提供经过验证的 Vector 样例工程（add_custom）和 mxfp8 matmul+eltwise 融合工程，含清晰的修改指南。触发：当用户需要创建 Kernel 直调工程、学习 Ascend C 编程、快速原型验证、或提及"Kernel直调"、"<<<>>>内核调用"、"mxfp8 融合"时使用本 skill。

Ascend C Kernel 直调工程

先按算子类型路由到模板，再按 [MODIFY] 注释改造。

场景路由

不支持的场景：纯 Matmul/Cube（非融合）、其他 Cube+Vector 混合（如 matmul+softmax）不在此覆盖范围。

使用方法

A. Vector 算子（Add 分支）

1. 复制样例目录：

``bash # 若算子目录 <your_op> 未创建 cp -r references/add_custom <your_op> # 若算子目录 <your_op> 已存在 cp -r references/add_custom/* <your_op> cd <your_op> ``

1. 全局替换算子名：add_custom → <your_op>（add_custom 是整体算子名，_kernel/_torch/_tiling 是固定后缀）
2. 按 `[MODIFY]` 标记改造：

• 类名和 kernel 函数名
• Tiling 结构体（add_custom_tiling.h）
• 计算逻辑（add_custom_kernel.asc）
• 输入/输出数量
• CMakeLists.txt 中的目标名

1. 编译运行：

``bash # 完整流程（含编译） bash run.sh # 仅运行测试，复用已有编译产物 bash run.sh --skip-build ` > run.sh 在运行 kernel 前会自动删除旧的 output/output.bin`，确保精度验证读取的是本次运行的新鲜输出。

B. mxfp8 matmul + eltwise 融合

见 references/matmul_fusion_guide.md（独立自洽）：复制 references/matmul_fusion_kernel/ 工程后按指南改 Epilogue。

C. Kirin Vector 算子（Add 分支）

见 references/kirin_vector_guide.md（独立自洽）：复制 references/kirin_add_template/ 工程后按 guide 进行修改。

文件结构（Add 分支）

├── op_kernel/               NPU 计算层
│   ├── add_custom_tiling.h      Tiling 常量 + 结构体（kernel 和 host 共用）
│   └── add_custom_kernel.asc    纯 kernel 代码（KernelAdd 类 + add_custom_kernel 核函数入口）
├── op_host/                 Host 直调层
│   ├── add_custom.asc           Host + main 入口（#include "add_custom_kernel.asc"）
│   └── data_utils.h             数据读写工具
├── op_extension/            PyTorch 接入层
│   ├── add_custom_torch.cpp     PyTorch host 实现（Tiling 计算 + kernel launch）
│   ├── register.cpp             TORCH_LIBRARY 注册（含 Meta backend）
│   └── ops.h                    函数声明
├── scripts/                 测试脚本
│   ├── gen_data.py               生成输入数据
│   ├── golden.py                 Golden 计算函数（直调 & PyTorch 双通路共用）
│   ├── verify_result.py          直调通路精度验证
│   └── test_torch.py             PyTorch 通路测试
├── CMakeLists.txt           双 target：可执行文件 + libadd_custom_ops.so
├── run.sh                   一键运行（支持 --torch 跑 PyTorch 通路）
└── README.md

Add 代码关键模式（速查）

在 add_custom_kernel.asc 和 add_custom.asc 中可直接学习：

• 内存分配: TPipe + TQue 管理 UB Buffer
• 数据流: CopyIn → Compute → CopyOut 三段模式
• 同步: EnQue/DeQue 确保操作顺序
• Host 流程: ACL 初始化 → KernelCall → 资源释放

PyTorch 对接

模板已内置 PyTorch 对接，编译后即可使用：

import torch; import torch_npu
torch.ops.load_library("build/libadd_custom_ops.so")
y = torch.ops.npu.add_custom(x1, x2)

参考资源

• Ascend C 示例代码
• NPU 架构配置详见 npu-arch skill
• PyTorch 对接详见 torch-ascendc-op-extension skill