catlass-operator-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CATLASS 算子设计

CATLASS Operator Design

核心工作流

Core Workflow

需求分析 → 阅读 catlass 仓库 → 组件选型 → 输出设计文档

Requirement Analysis → Read catlass Repository → Component Selection → Output Design Document

前置条件

Prerequisites

检查项	说明
catlass 仓库	须在 OPS_PROJECT_ROOT 下可访问 `catlass/` （含 `include/` 、 `examples/` ）
必读参考	设计前必须阅读本 skill 的 `references/` 文件

Check Item	Description
catlass Repository	Must be able to access `catlass/` (including `include/` and `examples/` ) under OPS_PROJECT_ROOT
Mandatory References	Must read the `references/` files of this skill before design

必读参考

Mandatory References

文件	用途
design-document.md	设计文档模板
matmul-templates.md	模板清单与选型指南
epilogue-components.md	Epilogue 组件分类与组合模式
custom-epilogue.md	自定义 Epilogue 契约

File	Purpose
design-document.md	Design document template
matmul-templates.md	Template list and selection guide
epilogue-components.md	Epilogue component classification and combination mode
custom-epilogue.md	Custom Epilogue contract

算子命名（强制）

Operator Naming (Mandatory)

op_name
（snake_case）必须包含子串
catlass
，例如：

catlass_matmul_add

、

catlass_fused_gemm_bias

禁止单独使用易与框架或其它厂商算子冲突的短名（如
```
matmul_add
```
、
```
gemm_add
```
）
OpDef / 类名（CamelCase） 与目录名一致映射，如
```
CatlassMatmulAdd
```
、
```
ops/catlass_matmul_add/
```

op_name
(snake_case) must contain the substring
catlass
, e.g.:

catlass_matmul_add

catlass_fused_gemm_bias

Prohibited to use short names that easily conflict with frameworks or other vendors' operators alone (such as
```
matmul_add
```
,
```
gemm_add
```
)
OpDef / Class Name (CamelCase) must map consistently with the directory name, e.g.:
```
CatlassMatmulAdd
```
,
```
ops/catlass_matmul_add/
```

选型与适配原则

Selection and Adaptation Principles

从 catlass example 和 include 中确定要用的模板，不是把 example 整份粘贴到算子工程
大部分算子工程基于 msopgen 小工程，example 中的 Host 调用代码需要改写为工程中的 op_host/op_kernel 分离结构
设计阶段只产出选型决策，代码由 code-gen 生成

Determine the template to use from catlass example and include, do not copy the entire example into the operator project
Most operator projects are based on msopgen small projects, and the Host call code in examples needs to be rewritten into the op_host/op_kernel separation structure in the project
Only output selection decisions during the design phase; code is generated by code-gen

NEVER / ALWAYS

NEVER：使用不含

catlass

的算子名定稿设计；把 example 整份照抄；设计文档中写大量代码块；在信息不足时臆测需求

ALWAYS：算子名含

catlass

，目录名与类名一致映射；条件不明则追问；设计前存在 catlass 仓库并阅读其文档与代码；设计文档用选型表格描述组件

NEVER: Finalize the design with an operator name that does not contain

catlass

; copy the entire example verbatim; write large code blocks in the design document; speculate on requirements when information is insufficient

ALWAYS: The operator name contains

catlass

, and the directory name maps consistently with the class name; ask questions if conditions are unclear; ensure the catlass repository exists and read its documents and code before design; use selection tables to describe components in the design document

需求输入

Requirement Input

用户可能直接说出需求，也可能不说。执行本 skill 时：若认为信息不足，则继续追问。

需确认的信息：

op_name

（须含 catlass）、功能要点、I/O 与 dtype、布局、目标 SoC、参考 example（如有）、约束条件。

Users may state their requirements directly or not. When executing this skill: If you believe information is insufficient, continue to ask questions.

Information to confirm:

op_name

(must contain catlass), functional key points, I/O and dtype, layout, target SoC, reference example (if any), constraints.

需求分析

Requirement Analysis

确定 op_name
：须含
catlass
提取：算子功能、数学公式、I/O、dtype、布局、目标 SoC、约束

Confirm op_name
: must contain
catlass
Extract: operator function, mathematical formula, I/O, dtype, layout, target SoC, constraints

阅读 catlass 并选型

Read catlass and Select Components

阅读 catlass 仓库：
```
examples/
```
、
```
include/
```
下的文档与代码
在
```
examples/
```
中按功能找相似示例，在设计文档中写明：选中的 example 路径、选型理由
若无完全匹配：基于 matmul-templates.md 与仓库中现有样例，说明变通方案
Epilogue：在 epilogue-components.md 与
```
catlass/include/catlass/epilogue/tile/
```
中检索；无现成 Tile 时按 custom-epilogue.md 先写设计契约

Read the catlass repository: documents and code under
```
examples/
```
and
```
include/
```
Find similar examples by function in
```
examples/
```
, and specify in the design document: the path of the selected example and the reason for selection
If there is no exact match: based on matmul-templates.md and existing samples in the repository, explain the workaround
Epilogue: Search in epilogue-components.md and
```
catlass/include/catlass/epilogue/tile/
```
; when there is no existing Tile, write the design contract first according to custom-epilogue.md

组件选型

Component Selection

选型结果用概念表格记录在设计文档中，不写代码。

设计文档须显式写出选型表格：ArchTag、BlockMmad（L1/L0 TileShape、数据类型）、BlockEpilogue（各环节 Tile/Block 组件）、BlockScheduler、Kernel 类型。

Record the selection results in the design document using a concept table, do not write code.

The design document must explicitly include the selection table: ArchTag, BlockMmad (L1/L0 TileShape, data type), BlockEpilogue (Tile/Block components for each link), BlockScheduler, Kernel type.

输出设计文档

Output Design Document

文档章节要求

Document Chapter Requirements

概述：功能、场景、数学公式
输入输出信息表：变量名、数据类型、Shape、布局、描述
核心组件选型：用选型表格描述各层组件
参考 Example 与模板选型：选中的 example、选型理由
TilingKey 分支设计：各 key 对应的条件和 Kernel 分支内容
Workspace：大小计算逻辑来源
接口与使用：aclnn 接口、Host Tiling 流程、Kernel 入口概念
扩展性：可替换的组件
实现方案纲要：Host 侧与 Kernel 侧要点

Overview: Function, scenario, mathematical formula
Input/Output Information Table: Variable name, data type, Shape, layout, description
Core Component Selection: Describe components at each layer using the selection table
Reference Example and Template Selection: Selected example, reason for selection
TilingKey Branch Design: Conditions corresponding to each key and content of Kernel branches
Workspace: Source of size calculation logic
Interface and Usage: aclnn interface, Host Tiling process, Kernel entry concept
Scalability: Replaceable components
Implementation Outline: Key points on Host side and Kernel side

输出格式

Output Format

设计文档须为独立 Markdown 文件，命名建议

design_<op_name>.md

，存放于 USER_OP_PROJECT 或用户指定路径。

The design document must be an independent Markdown file, recommended to be named

design_<op_name>.md

, and stored in USER_OP_PROJECT or the path specified by the user.

质量验证

Quality Verification

设计文档检查清单

Design Document Checklist

算子名含
```
catlass
```
，snake_case 目录名与 CamelCase 类名一致
含完整的输入输出信息表
核心组件选型已明确：ArchTag、BlockMmad、BlockEpilogue、BlockScheduler、Kernel
参考 example 已写明，选型理由清晰
TilingKey 分支设计已列出
交付路径 USER_OP_PROJECT 已明确

The operator name contains
```
catlass
```
, and the snake_case directory name matches the CamelCase class name
Contains a complete input/output information table
Core component selection is clear: ArchTag, BlockMmad, BlockEpilogue, BlockScheduler, Kernel
Reference example is specified, and the reason for selection is clear
TilingKey branch design is listed
Delivery path USER_OP_PROJECT is clear

参考资料

Reference Materials

文件	用途
design-document.md	设计文档模板与章节规范
matmul-templates.md	模板清单与选型指南
epilogue-components.md	Epilogue 组件分类与选型
custom-epilogue.md	自定义 Tile Epilogue 的设计契约
catlass/examples/	开发形式与多种模板参考
catlass/docs/3_API/gemm_api.md	Gemm API 分层模型、组件对照表

File	Purpose
design-document.md	Design document template and chapter specifications
matmul-templates.md	Template list and selection guide
epilogue-components.md	Epilogue component classification and selection
custom-epilogue.md	Design contract for custom Tile Epilogue
catlass/examples/	Development forms and references for various templates
catlass/docs/3_API/gemm_api.md	Gemm API layered model, component comparison table