ascendc-operator-design

Files (9)

• SKILL.md
• elementwise-tiling.md · references/
• general-tiling-principles.md · references/
• hardware-architecture.md · references/
• index-tiling.md · references/
• pooling-tiling.md · references/
• reduction-tiling.md · references/
• sort-tiling.md · references/
• design-template.md · templates/

SKILL.md (first lines)

---
name: ascendc-operator-design
description: 完成AscendC算子设计 - 帮助用户完成算子的架构设计、接口定义和性能规划。当用户提到算子设计、算子开发、tiling策略、内存规划、AscendC kernel设计、两级tiling、核间切分、核内切分时，使用此skill。
---

# AscendC Operator Design Skill

根据算子需求生成完整的设计文档（design.md），供后续 code-gen skill 消费。

## 使用场景

在 `ascendc-operator-project-init` 创建骨架后、`ascendc-operator-code-gen` 生成代码之前调用。

## 设计流程

### 1. 算子需求分析

**如果由调度 skill 调用**，算子名称和功能描述已确定，直接进入步骤 2。

**如果独立调用**，与用户确认以下信息：

| 信息 | 必填 | 说明 |
|------|------|------|
| 算子名称（snake_case） | 是 | 如 `acosh`, `rms_norm` |
| 功能描述 / 数学公式 | 是 | 如 "acosh(x) = ln(x + sqrt(x²-1))" |
| 支持的数据类型 | 否 | 默认 float16 + float32 |

**MANDATORY**: 检查 PyTorch / NumPy 是否存在同名接口。如果存在，接口签名和语义 **必须** 与之对齐（如 `torch.acosh`、`torch.softmax`）。

### 2. 选择实现路径

根据算子特性，推荐合适的实现方式：

| 实现路径 | 适用场景 | 判断标准 |
|----------|---------|---------|
| **AscendC Kernel** | 纯 vector 算子 | 不涉及矩阵乘法 |
| **CATLASS 模板库** | GEMM / FlashAttention | 含 cube 矩阵计算 |
| **ACLNN 封装** | CANN 已有内置算子 | 无需自定义 kernel |

> **新算子默认使用 AscendC Kernel 路径**，除非明确涉及矩阵乘法。

### 3. 详细设计文档生成

**MANDATORY**: 在生成设计文档之前，必须读取以下参考文档：

1. **必读**: `templates/design-template.md` — 设计文档模板
2. **按算子类型选读**:
   - 逐元素操作（add/relu/acosh/sigmoid...）→ `references/elementwise-tiling.md`
   - 归约操作（softmax/layernorm...）→ `references/reduction-tiling.md`
   - 索引操作（gather/index_select/scatter...）→ `references/index-tiling.md`
   - 排序操作（sort/topk...）→ `references/sort-tiling.md`
   - 池化操作（avgpool/maxpool/...）→ `references/pooling-tiling.md`
3. **通用参考**: `references/general-tiling-principles.md`

**绝对不要跳过参考文档的阅读。**

#### 3.1 设计文档结构

设计文档包含以下核心章节：

1. **算子接口定义** — 函数签名、参数说明、支持的数据类型
2. **计算逻辑设计** — 算法描述、**AscendC API 调用伪代码**、实现路径选择
3. **Tiling策略** — 两级Tiling设计（Block级 + UB级）、UB分配表、tileLength计算
4. **Workspace需求** — workspace大小计算
5. **性能优化** — 关键优化点、算子特性分析
6. **Kernel端实现要点** — 偏移计算、执行流程、**FP16/BF16 升精度流程**
7. **实现检查清单** — 文件结构、代码要点、测试要点

#### 3.2 计算逻辑伪代码（关键产出）

**必须** 将数学公式分解为 AscendC API 调用序列。这是 code-gen skill 的直接输入。

**常见数学函数到 AscendC API 映射**：

| 数学运算 | AscendC API | 备注 |
|----------|-------------|------|
| x + y | `Add(dst, src0, src1, len)` | 双输入 |
| x - y | `Sub(dst, src0, src1, len)` | 双输入 |
| x * y | `Mul(dst, src0, src1, len)` | 双输入 |
| x / y | `Div(dst, src0, src1, len)` | 双输入 |
| x + scalar | `Adds(dst, src, scalar, len)` | 标量运算，优先使用 |
| x * scalar | `Muls(dst, src, scalar, len)` | 标量运算，优先使用 |
| abs(x) | `Abs(dst, src, len)` | |
| exp(x) | `Exp(dst, src, len)` | |
| ln(x) | `Ln(dst, src, len)` | |
| sqrt(x) | `Sqrt(dst, src, len)` | |
| 1/x | `Reciprocal(dst, src, len)` | |
| 1/sqrt(x) | `Rsqrt(dst, src, len)` | |
| tanh(x) | `Tanh(dst, src, len)` | |
| relu(x) | `Relu(dst, src, len)` | |
| max(x,y) | `Max(dst, src0, src1, len)` | |
| min(x,y) | `Min(dst, src0, src1, len)` | |
| fp16→fp32 | `Cast(dst, src, CAST_NONE, len)` | 升精度无损 |
| fp32→fp16 | `Cast(dst, src, CAST_ROUND, len)` | 降精度有损 |

**示例 — acosh(x) 的 API 调用序列**：
```cpp
Mul(tmp, x, x, len);        // tmp = x²
Adds(tmp, tmp, -1.0f, len); // tmp = x² - 1
Sqrt(tmp, tmp, len);         // tmp = sqrt(x² - 1)
Add(tmp, tmp, x, len);      // tmp = x + sqrt(x² - 1)
Ln(y, tmp, len);             // y = ln(x + sqrt(x² - 1))
```

> **注意**：如果计算序列中某步的 dst 与 src 相同（原地操作），大部分 AscendC API 支持，但需确认具体 API。

#### 3.2 Tiling 策略

**重要**: AscendC 算子采用两级 Tiling 策略，根据算子类型参考相应文档：

```
┌─────────────────────────────────────────────────────────────┐
│                    全局内存 (GM)                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              totalLength 元素数据                     │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼

From Ascend/agent-skills, MulanPSL-2.0.

More from Ascend/agent-skills