ascendc-operator-code-gen

Files (21)

• SKILL.md
• GUIDE.md · references/
• basic-data-structures-api.md · references/
• data-copy-api.md · references/
• kernel-constraints.md · references/
• resource-management-api.md · references/
• sort_topk-api.md · references/
• sync-control-api.md · references/
• vector-compute-api.md · references/
• elementwise_op_host.cpp · templates/
• elementwise_op_kernel.cpp · templates/
• index_op_host.cpp · templates/
• index_op_kernel.cpp · templates/
• index_op_per_elem_host.cpp · templates/
• index_op_per_elem_kernel.cpp · templates/
• pool_ndhwc_op_host.cpp · templates/
• pool_ndhwc_op_kernel.cpp · templates/
• row_op_host.cpp · templates/
• row_op_kernel.cpp · templates/
• sort_op_host.cpp · templates/
• sort_op_kernel.cpp · templates/

SKILL.md (first lines)

# AscendC 算子代码生成与框架适配

根据设计文档生成 op_host + op_kernel 代码，注册到 PyTorch 框架，调用 `ascendc-operator-compile-debug` skill 完成编译安装和精度测试。

**前置条件**: 设计文档 `ascend-kernel/csrc/ops/<op_name>/design.md` 已就绪，目录结构已创建。

## 工作流程总览

```
读取设计文档 → 加载 reference → 选择模板 → 生成 op_host + op_kernel
    → 框架适配 (ops.h + register.cpp + csrc/CMakeLists.txt)
    → 调用 ascendc-operator-compile-debug skill (编译 + 安装 + 测试)
```

---

## 阶段 1: 加载参考文档

**MANDATORY — READ BEFORE CODING**: 读取 [`references/GUIDE.md`](references/GUIDE.md)，根据设计文档中的算子类型，加载对应的 reference 文件。**绝对不要跳过此步骤。**

## 阶段 2: 读取设计文档

从 `ascend-kernel/csrc/ops/<op_name>/design.md` 提取：

| 提取项 | 设计文档章节 | 用途 |
|--------|------------|------|
| 函数签名 + 支持的数据类型 | 原型设计 | op_host 函数原型、kernel 模板参数 |
| 算子类型 | Tiling 切分 → 步骤1 | 选择模板 (elementwise / row) |
| UB 分配表 | UB 空间分配 | 推导 bufferCoefficient、InitBuffer 大小 |
| 计算伪代码 | Kernel 实现 | Compute 函数逻辑 |

---

## 阶段 3: 选择模板并生成代码

根据算子类型选择对应模板，复制到工程目录后修改。

### 模板选择

| 算子类型 | op_host 模板 | op_kernel 模板 |
|---------|-------------|---------------|
| Elementwise (ReLU, GELU, Add...) | [`templates/elementwise_op_host.cpp`](templates/elementwise_op_host.cpp) | [`templates/elementwise_op_kernel.cpp`](templates/elementwise_op_kernel.cpp) |
| 行处理 (LayerNorm, Softmax...) | [`templates/row_op_host.cpp`](templates/row_op_host.cpp) | [`templates/row_op_kernel.cpp`](templates/row_op_kernel.cpp) |
| Index-PerRow (IndexSelect, 共享1D索引) | [`templates/index_op_host.cpp`](templates/index_op_host.cpp) | [`templates/index_op_kernel.cpp`](templates/index_op_kernel.cpp) |
| Index-PerElem (Gather, Scatter, 逐行索引) | [`templates/index_op_per_elem_host.cpp`](templates/index_op_per_elem_host.cpp) | [`templates/index_op_per_elem_kernel.cpp`](templates/index_op_per_elem_kernel.cpp) |
| Sort (Sort, TopK...) | [`templates/sort_op_host.cpp`](templates/sort_op_host.cpp) | [`templates/sort_op_kernel.cpp`](templates/sort_op_kernel.cpp) |
| Pool (MaxPool, AvgPool...) | [`templates/pool_ndhwc_op_host.cpp`](templates/pool_ndhwc_op_host.cpp) | [`templates/pool_ndhwc_op_kernel.cpp`](templates/pool_ndhwc_op_kernel.cpp) |

**MANDATORY**: 读取对应模板文件的完整内容，复制到目标路径后修改。

### 生成步骤

1. 读取选中的 op_host 和 op_kernel 模板的完整内容
2. 将内容写入 `ascend-kernel/csrc/ops/<op_name>/op_host/<op_name>.cpp` 和 `op_kernel/<op_name>.cpp`（覆盖骨架占位文件）
3. 替换所有占位符（`<op_name>`, `<OpName>` 等）
4. 根据设计文档修改：
   - **op_host**: 函数签名、输入校验、`bufferCoefficient`、EXEC_KERNEL_CMD 参数
   - **op_kernel**: Init 的 GM 参数、InitBuffer 大小、Compute 计算逻辑

### FP16/FP32 模板分支

Kernel 模板使用 `template <typename T>` 泛型 + `if constexpr` 分支处理不同数据类型：

```cpp
if constexpr (sizeof(T) == sizeof(float)) {
    // float32 直接计算
} else {
    // fp16/bf16: Cast 升精度 → fp32 计算 → Cast 降精度
}
```

AscendC 编译器支持 C++17 `if constexpr`，可安全用于模板分支。如需兼容旧编译器，也可用 `sizeof(T) == 4` 的普通 if（编译器会优化掉死分支）。

### 模板修改要点

#### 硬件参数获取（模板已内置）

模板使用平台 API 动态获取硬件参数，不再硬编码：

```cpp
#include "tiling/platform/platform_ascendc.h"

auto ascendc_platform = platform_ascendc::PlatformAscendCManager::GetInstance();
int64_t coreNum = static_cast<int64_t>(ascendc_platform->GetCoreNumAiv());
uint64_t ubSize;
ascendc_platform->GetCoreMemSize(platform_ascendc::CoreMemType::UB, ubSize);
// 需要 workspace 时:
// uint64_t sysWorkspaceSize = ascendc_platform->GetLibApiWorkSpaceSize();
```

#### bufferCoefficient 推导

从设计文档 UB 分配表推导——所有 Buffer 总大小 = `bufferCoefficient * tileLength`：
- 将 UB 分配表中所有 Buffer 的"总大小"列加和
- 结果形如 `tileLength * N`，则 `bufferCoefficient = N`
- 不同 dtype 系数不同时用 `if (dtypeSize == 2) {...} else {...}` 分支

#### FP16/BF16 升精度

**FP16 和 BF16 都必须升精度到 FP32 计算再转回**。模板中已标注升精度代码的插入位置，取消注释并填充计算逻辑即可。

#### GM ↔ UB 搬运（DataCopyPad）

**生产代码必须使用 DataCopyPad**（不要使用 DataCopy 进行 GM↔UB 搬运）：

```cpp
// CopyIn: GM → UB
AscendC::DataCopyExtParams copyInParams{1,
    static_cast<uint32_t>(curTileLength * sizeof(T)), 0, 0, 0};
AscendC::DataCopyPadExtParams<T> padParams{false, 0, 0, static_cast<T>(0)};
AscendC::DataCopyPad(xLocal, xGm[progress * tileLength], copyInParams, padParams);

// CopyOut: UB → GM
AscendC::DataCopyExtParams copyOutParams{1,
    static_cast<uint32_t>(curTileLength * sizeof(T)), 0, 0, 0};
AscendC::DataCopyPad(yGm[progress * tileLength], yLocal, copyOutParams);
```

> **注意**: 模板文件中可能使用 DataCopy 以简化示例，生产代码应替换为 DataCopyPad。

From Ascend/agent-skills, MulanPSL-2.0.

More from Ascend/agent-skills