external-cannbot-ops-ascendc-direct-invoke-template

Ascend C Kernel direct-call project

First route to the template by operator type, then modify according to the [MODIFY] comments.

Scenario routing

Operator type	Entry	Typical operators
Vector(branch A)	`references/add_custom/`	elementwise/reduction operators such as add, mul, relu, softmax, layernorm
mxfp8 matmul + eltwise fusion	`references/matmul_fusion_kernel/` + `references/matmul_fusion_guide.md`	Dedicated variant for Cube+Vector fusion; this guide is self-contained, so after entering it there is no need to return to this page

Unsupported scenarios: pure Matmul/Cube (non-fused) and other Cube+Vector hybrids (such as matmul+softmax) are not covered here.

Usage

A. Vector operators (Add branch)

Copy the sample directory：

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

Globally replace the operator name：add_custom → <your_op>(add_custom is the overall operator name; _kernel/_torch/_tiling are fixed suffixes)
Modify according to the [MODIFY] markers：
- class name and kernel function name
- Tiling struct (add_custom_tiling.h）
- computation logic (add_custom_kernel.asc）
- number of inputs/outputs
- CMakeLists.txt target name in
Compile and run：
```
# 完整流程（含编译）
bash run.sh
# 仅运行测试，复用已有编译产物
bash run.sh --skip-build
```
run.sh automatically deletes the old output/output.binbefore running the kernel, ensuring that precision verification reads fresh output from the current run.

B. mxfp8 matmul + eltwise fusion

See references/matmul_fusion_guide.md(self-contained): copy the references/matmul_fusion_kernel/ project, then modify the Epilogue according to the guide.

File structure (Add branch)

├── 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

Key Add code patterns (quick reference)

In add_custom_kernel.asc and add_custom.asc , you can learn directly:

Memory allocation: TPipe + TQue manages UB Buffer
Data flow: CopyIn → Compute → CopyOut three-stage pattern
Synchronization: EnQue/DeQue ensures operation order
Host flow: ACL initialization → KernelCall → resource release

PyTorch integration

The template has built-in PyTorch integration and can be used after compilation:

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

Reference resources

File	Description
`references/matmul_fusion_guide.md`	mxfp8 matmul + eltwise fusion Epilogue specification
`references/kernel_launch_details.md`	Advanced (general): memory hierarchy/Double Buffer/synchronization mechanisms/multiple I/O

Ascend C sample code
For NPU architecture configuration, see npu-arch skill
For PyTorch integration, see torch-ascendc-op-extension skill