design-kernel

Kernel 设计 — 通用工作流

本技能包含所有受支持 DSL 的通用内容。确定实现语言后，还要加载匹配的语言专属设计技能，以了解该 DSL 特有的运行时模式、易错点和 API 指南。

语言选择

语言键	Python 包路径	设计技能	API 参考技能	适用场景
cutile-dsl	cutile	/design-cutile-dsl-kernel	/cutile-dsl-ref	块级控制、分块、CTA 重映射和编译器提示已足够
cute-dsl	cute_python	/design-cute-dsl-kernel	/cute-dsl-ref	需要显式线程/warp 调度、TMA 流水线、共享内存控制

---

命名约定

• 面向公众的名称、文档、技能和知识库条目使用 kebab-case 语言键（例如 cute-dsl）。
• Python 包在需要时使用 下划线（例如 cute_python）。
• Kernel 包嵌套路径：src/mla_var3/kernel/<lang_pkg>/mla/<design>/...。
• 快捷 CLI python -m mla_var3.kernel <kernel> [<version>] 是首选的用户入口。

Kernel 结构与版本管理

我们在 kernel 子包中使用嵌套结构来组织 kernel 包：

1. 语言层级：kernel 的实现 DSL（例如 kernel.cutile、kernel.cute_python）。
2. 层级：kernel 针对的模型层（例如 kernel.cutile.mla）。
3. 设计层级：kernel 设计（例如 kernel.cutile.mla.flash_mla）。
4. 版本层级：kernel 版本（例如 kernel.cutile.mla.flash_mla.flash_mla_v2）。第一个版本没有后缀，称为“基础版本”。
5. 入口模块：版本包内必须包含一个以版本完整名称命名的模块（例如 flash_mla_v2.py），其中包含 KernelPlan 子类。

包嵌套模式

kernel.<lang_pkg>.mla.<design>.<design>[_v<N>].<design>[_v<N>].py

规则

• 基础版本：<design>/<design>/（无后缀，别名为 v0）
• 版本 N：<design>/<design>_vN/
• Kernel 入口函数名称必须与模块文件名一致
• 每个版本都是设计包下的同级包

CLI 用法

# Full path
python -m mla_var3.kernel.<lang_pkg>.mla.<design> [<version>] [args]
# Shortcut (discovers across all languages)
python -m mla_var3.kernel <design> [<version>] [args]

# Examples
python -m mla_var3.kernel.cutile.mla.mla_var6_plus v4 --b=32 --s=16 --t=4096
python -m mla_var3.kernel mla_var6_plus v4 --b=32 --s=16 --t=4096

---

创建版本检查清单

1. 克隆上一版本：

   source .venv/bin/activate
   python ./scripts/clone-kernel.py <kernel_full_name> <new_suffix>
   

2. 脚本会自动重写带版本号的符号：
   • Python 模块文件名
   • 装饰后的 kernel 函数名（@ct.kernel、@cute.kernel、@cute.jit）
   • KernelPlan 子类名称
   • Tiling 子类名称
   • 包内导入
   • 带引号的前向引用和嵌入的包名字符串字面量
3. 修改克隆的文件以实现新的优化。
4. 如果脚本不可用，可手动执行以下操作：
   • 复制最新版本目录
   • 重命名带版本号的模块文件
   • 手动更新类名、函数名、导入和流水线名称字符串
5. 验证正确性：

   source .venv/bin/activate
   python -m mla_var3.kernel.<lang_pkg>.mla.<design> <version> --prof_type=disabled --check
   

6. 在开发日志中添加“变更内容”部分。

---

KernelPlan 结构

每个 kernel 版本都必须实现一个 KernelPlan 子类。plan() 方法会返回一个 DSL 专属的运行时包装器（具体类型请参阅语言专属技能）。

@dataclass
class MyKernel(KernelPlan):
    b: int = 64; s: int = 1; t: int = 4096  # problem dimensions
    tiling: MyTiling = field(default_factory=MyTiling)

    def prepare_inputs(self, device) -> tuple:
        # Allocate and return input tensors

    def reference_fn(self, *inputs) -> tuple:
        # Reference implementation for --check

    def _autotune_configs(self) -> list[MyTiling]:
        # Candidate tiling configs for autotuner search

    def _algorithmic_flops_bytes(self, tiling) -> tuple[int, int]:
        # Analytical (FLOPs, bytes) for roofline

    def plan(self, *inputs) -> BenchmarkFn:
        # Build executable runtime object (DSL-specific)

    def plan_empty(self, peak_tflops, peak_gbps) -> BenchmarkFn:
        # Roofline-only prediction (no real tensors)

Tiling 数据类

@dataclass
class MyTiling(Tiling):
    # DSL-specific fields — see the language-specific skill for examples

    def validate(self, pd: "MyKernel") -> bool:
        # Return True if this tiling is valid for the given problem dimensions
        ...

组合模式

顺序流水线

def plan(self, *inputs) -> KernelPipeline:
    stage1 = stage1_plan.plan(...)
    stage2 = stage2_plan.plan(...)
    return KernelPipeline(_name="my_pipeline", stages=[stage1, stage2])

并发阶段 + 顺序合并

def plan(self, *inputs) -> KernelPipeline:
    a = plan_a.plan(...)
    b = plan_b.plan(...)
    concurrent = ConcurrentKernels(
        _name="overlap_group", concurrent_kernels=[a, b],
        validate_joint_tiling_fn=validate_fn,
    )
    combine = combine_plan.plan(...)
    return KernelPipeline(_name="pipeline", stages=[concurrent, combine])

实现工作流

1. 阅读当前内核源码 — 了解现有实现
2. 阅读编排器提供的优化说明（需要应用的具体优化）
3. 加载 DSL API 参考技能 — 不要臆造 API
4. 在实现前检查 DSL 适用性门槛（位于特定语言的技能中）
5. 使用 python ./scripts/clone-kernel.py 克隆当前版本
6. 阅读 docs/knowledge/ 中的优化详情文件，了解实现模式
7. 在新版本文件中实现更改
8. 测试正确性：--prof_type=disabled --check
9. 更新开发日志，填写“What changed”和“High-level description”
10. 如需提交，使用 Conventional Commits 格式的提交信息

---

知识库链接

• 将可复用的算法／设备／硬件相关发现放入 docs/knowledge/optimizations/ 或 docs/knowledge/anti-patterns/。
• 将特定于 DSL 的实现发现放入 docs/knowledge/languages/<language>/...。
• 将特定语言的优化目录技能与特定语言的设计技能结合使用。

开发日志条目模板

添加到 docs/kernels/<kernel>.md 中的 ## Development log 下方：

### V<N>: [Brief Description]

**Location**: `src/mla_var3/kernel/<lang_pkg>/mla/<kernel>/<kernel>_v<N>/`

**What changed**:
- [Bullet list of changes]

**High-level description of main code changes**:
- [Description of optimizations and how they relate to profiling insights]

性能指标、瓶颈分析、问题和见解由性能分析 Agent 在分析后填写。

设计者输出约定

按以下格式向编排器返回结果：

## New Version: [kernel] [version]

### Changes Applied
1. [change + rationale]

### Files
- Created: [paths]
- Modified: [paths]

### Correctness: [PASS/FAIL]

### Devlog Entry Written: [path]

参考资料

• 优化模式：docs/knowledge/optimizations/
• 反模式：docs/knowledge/anti-patterns/
• 内核开发日志：docs/kernels/<kernel>.md