design-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	明示的なスレッド／ワープのスケジューリング、TMA パイプライン、共有メモリの制御が必要な場合

---

命名規則

• 公開向けの名前、ドキュメント、スキル、ナレッジベースのエントリーには、kebab-case の言語キー（例：cute-dsl）を使用します。
• Python パッケージでは、必要に応じて underscores を使用します（例：cute_python）。
• カーネルパッケージの入れ子構造：src/mla_var3/kernel/<lang_pkg>/mla/<design>/...。
• ショートカット CLI python -m mla_var3.kernel <kernel> [<version>] を、ユーザー向けの推奨エントリーポイントとします。

カーネルの構造とバージョン管理

kernel サブパッケージ内のカーネルパッケージには、次の入れ子構造を使用します。

1. 言語レベル：カーネルが実装されている DSL（例：kernel.cutile、kernel.cute_python）。
2. レイヤーレベル：カーネルが対象とするモデルレイヤー（例：kernel.cutile.mla）。
3. 設計レベル：カーネルの設計（例：kernel.cutile.mla.flash_mla）。
4. バージョンレベル：カーネルのバージョン（例：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/
• カーネルのエントリー関数名は、モジュールのファイル名と必ず一致させます
• 各バージョンは、設計パッケージ内の兄弟パッケージにします

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 モジュールのファイル名
   • デコレートされたカーネル関数名（@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. devlog に「変更内容」セクションを追加します。

---

KernelPlan の構造

各カーネルバージョンは、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. 「変更内容」と「概要の説明」を記載して開発ログを更新する
10. コミットする場合は、Conventional Commits 形式のメッセージを使用します

---

ナレッジベースへのリンク

• 再利用可能なアルゴリズム／デバイス／ハードウェアに関する知見は、docs/knowledge/optimizations/ または docs/knowledge/anti-patterns/ に記載してください。
• DSL 固有の実装に関する知見は、docs/knowledge/languages/<language>/... に記載してください。
• 言語固有の最適化カタログスキルを、言語固有の設計スキルと併用してください。

開発ログのエントリーテンプレート

## Development log の下にある docs/kernels/<kernel>.md に追加します。

### 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]

パフォーマンス指標、ボトルネック分析、問題、知見は、プロファイリング後にプロファイラーエージェントが記入します。

デザイナー出力の仕様

次の形式で結果をオーケストレーターに返します。

## 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