Skills

ascendc-operator-design

Installation
SKILL.md

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 调用序列：

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 元素数据                     │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
    ┌──────────┐     ┌──────────┐     ┌──────────┐
    │  Core 0  │     │  Core 1  │ ... │ Core 39  │   ← Block级Tiling (核间切分)
    └──────────┘     └──────────┘     └──────────┘
          │                │                │
          ▼                ▼                ▼
    ┌──────────┐     ┌──────────┐     ┌──────────┐
    │   UB 0   │     │   UB 1   │     │  UB 39   │   ← UB级Tiling (核内切分)
    └──────────┘     └──────────┘     └──────────┘

Block级Tiling（核间切分）:

  • 将数据分配到多个 AI Core 并行处理
  • 负载均衡: 整核/尾核策略，尾核处理数据量小于等于整核

UB级Tiling（核内切分）:

  • 每个 Core 内部分块处理数据
  • UB 对齐: 32 字节
  • UB 容量: 不超过 UB_SIZE_LIMIT（实际编码时通过接口获取，示例值 192KB）

参考文档:

  • 逐元素操作: 阅读 references/elementwise-tiling.md（包含完整两级 Tiling 实现）
  • 归约操作: 阅读 references/reduction-tiling.md
  • 索引操作: 阅读 references/index-tiling.md
  • 排序操作: 阅读 references/sort-tiling.md
  • 池化操作: 阅读 references/pooling-tiling.md
  • 通用原则: 参考 references/general-tiling-principles.md

3.3 硬件约束说明

  • UB 缓冲区: 必须按 32 字节对齐，即使逻辑上只需要存储少量数据
  • 归约类算子: 单值缓冲区需要开辟 32B 空间
  • 精度处理:
    • FP32 输入: 无需升精度，直接计算
    • FP16 输入: 必须升精度到 FP32 计算，保证计算精度
    • BF16 输入: 必须升精度到 FP32 计算，vector 计算单元不支持 bfloat16 直接计算
  • Workspace 需求:
    • elementwise 类: SYSTEM_WORKSPACE_SIZE（通常为 16MB）
    • 其他类算子: 根据实际 tiling data 大小计算

3.4 常见算子类型的 UB 分配速查表

根据算子输入数量和数据类型，快速确定 bufferCoefficient：

单输入单输出 elementwise（acosh, relu, sigmoid, exp, ln, sqrt, abs...）：

数据类型 UB 布局 bufferCoefficient
float32 inQ(2×4) + outQ(2×4) + tmpBuf(1×4) = 20 20
float16 inQ(2×2) + outQ(2×2) + tmpBuf1(1×4) + tmpBuf2(1×4) = 16 16

双输入单输出 elementwise（add, mul, sub, div...）：

数据类型 UB 布局 bufferCoefficient
float32 inQ_X(2×4) + inQ_Y(2×4) + outQ(2×4) + tmpBuf(2×4) = 32 32
float16 inQ_X(2×2) + inQ_Y(2×2) + outQ(2×2) + tmpBuf(3×4) = 24 24

实战经验：bufferCoefficient 是 code-gen 阶段最关键的参数。设计文档中 必须 明确给出每种 dtype 的值，否则代码生成无法正确计算 tileLength。

3.5 生成设计文档

基于收集的信息，读取 templates/design-template.md 模板，填充所有章节，输出到 csrc/ops/<op_name>/design.md。

输出位置: ascend-kernel/csrc/ops/<op_name>/design.md（覆盖初始化阶段的占位文件）

交互流程

被调度 skill 调用时（推荐流程）：

  1. 接收算子名称和功能描述
  2. 自动选择实现路径
  3. 读取参考文档，生成完整设计文档
  4. 输出到 design.md

独立调用时：

  1. 需求收集: 通过对话了解算子需求
  2. 方案推荐: 基于需求推荐实现路径
  3. 详细设计: 生成完整的设计文档
  4. 检查确认: 与用户确认设计要点
  5. 移交开发: 生成检查清单，准备进入编码阶段

注意事项

Tiling 参数设计原则

  1. 参数结构化:

    // 好的做法：使用结构体
struct MyOperatorTilingData {
    int64_t totalLength;        // 总数据长度

    int64_t formerNum;          // 整核数量
    int64_t formerLength;       // 整核数据长度
    int64_t tailNum;            // 尾核数量
    int64_t tailLength;         // 尾核数据长度

    int64_t tileLength;         // UB单次处理长度
};

// 避免：使用大量独立参数
void KernelFunc(int64_t totalLength, int64_t tileNum, int64_t tileLength, ...);

  2. 两级对齐:

    // Block级: Cache Line 对齐 (512字节)
constexpr int64_t CACHE_LINE_BYTE_LENGTH = 512;
int64_t totalLengthCoreAlign = ((totalLengthCore + CACHE_LINE_BYTE_LENGTH - 1) / CACHE_LINE_BYTE_LENGTH) * CACHE_LINE_BYTE_LENGTH;

// UB级: 32字节对齐
int64_t ubAlignElements = 32 / dtypeSize;
int64_t tileLengthAligned = ((tileLength + ubAlignElements - 1) / ubAlignElements) * ubAlignElements;

  3. UB 分配表: 每个算子设计必须包含 UB 分配表，明确列出：

    • 所有 buffer 名称和用途
    • 每个 buffer 的大小（字节）
    • buffer 数量（单 buffer 或 double buffer）
    • 总 UB 使用量和约束验证

  4. Double Buffer: 使用 BUFFER_NUM=2 实现 double buffer，隐藏内存延迟

其他注意事项

  1. 数据类型对齐: 确保PyTorch tensor类型和AscendC kernel类型匹配（half ↔ float16, float ↔ float32）
  2. 内存对齐: AscendC要求内存地址对齐（UB 32B, Cache Line 512B）
  3. Shape约束: 某些算子对shape有特殊要求（如需要被tile size整除）
  4. 性能权衡: 在代码复杂度和性能之间找到平衡点
  5. 接口定义: 检查PyTorch/Numpy等库是否存在类似算子接口，如果存在，接口定义参考PyTorch/Numpy等库
  6. 测试输入范围: 在设计文档中注明算子的有效输入范围（如 acosh 要求 x >= 1），测试用例需据此生成数据

交付标准（DoD）

设计文档生成后，必须包含以下关键产出物（供 code-gen skill 直接消费）：

  • 函数签名: at::Tensor op_name(const at::Tensor &self, ...) 完整声明
  • 支持的数据类型: 明确列出（如 float16, float32）
  • AscendC API 调用伪代码: 每步计算映射到具体 API
  • UB 分配表: 每种 dtype 的 buffer 布局和 bufferCoefficient
  • Tiling 参数结构体: 字段定义和计算公式
  • FP16/BF16 升精度流程: 如支持半精度，必须描述 Cast 路径

下一步

设计完成后，使用 ascendc-operator-code-gen skill 生成具体代码实现。

Related skills

More from ascend/agent-skills

Installs
55
Repository
ascend/agent-skills
GitHub Stars
13
First Seen
Apr 3, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass