profile-kernel

GPU カーネルのプロファイリング

GPU クロックのプロトコル

プロファイリングの前には、必ずクロックを固定してください。プロファイリングは一度に1つだけ実行してください。

bash scripts/lock-gpu-clock.sh           # before profiling
bash scripts/reset-gpu-clock.sh          # after done

デバイスのピーク性能

共有するプロファイリングのガイダンスでは、特定のデバイスを1つに固定しないでください。アクティブなデバイスのコンテキストは、params.json、実行時のプロファイリング成果物、および src/mla_var3/conf/devices.json で設定されたピーク仕様のソースから読み取ってください。

測定コンテキストが重要な場合に限り、docs/devices/ のデバイス固有の参照ファイルを使用してください。リッジポイントは次のとおりです。

ridge_point = peak_tflops / peak_gbps

プロファイリングモードの判断ツリー

モード	--prof_type	使用する場面	出力ルート
アノテーション	annotation	最初のパスではデフォルトです。 ルーフライン + NCU メトリクス + 比較表	out/profiles/annotation/
イベント	event	素早い反復計測（Python のオーバーヘッドを含みます）	out/profiles/event/
NCU	ncu	詳細な調査：NCU の全セクション、ソースへの注釈、最適化の提案	out/profiles/ncu/
NSYS	nsys	パイプラインのオーバーラップ、ストリームの並行性、起動順序	out/profiles/nsys/

選択ルール：まず annotation を使用してください。高速な A/B 比較には event を使用してください（KernelPipeline/ConcurrentKernels には適していません）。ソースレベルの分析、Nsight Compute による最適化の提案、または CUDA に関する知見が必要な場合は ncu を使用してください。ConcurrentKernels のオーバーラップとストリームの並行性を分析する場合は nsys を使用してください。

プロファイリングコマンド

CLI エントリポイント（すべてのモード）

python -m mla_var3.kernel <kernel_package> [<version>] \
    --b=32 --s=16 --t=4096 --prof_type=<mode>

# Language-specific path when needed:
python -m mla_var3.kernel.<language_python_package>.mla.<kernel_package> [<version>] \
  --b=32 --s=16 --t=4096 --prof_type=<mode>

Python API

# Annotation
from mla_var3.runtime.profiling.annotation import annotation_profile_plan
prof_result = annotation_profile_plan(plan, out_dir=..., version=..., bench_runs=...)

# NCU
from mla_var3.runtime.profiling.ncu import ncu_profile_plan
prof_result = ncu_profile_plan(plan, out_dir=..., version=..., bench_runs=...)

# NSYS
from mla_var3.runtime.profiling.nsys import nsys_profile_plan
prof_result = nsys_profile_plan(plan, out_dir=..., version=..., bench_runs=...)

バージョンは省略可能で、カスタムバージョンを指定できます。指定したバージョンの適切な KernelPlan を取得して使用し、関数に渡された plan は使用しません。これは、バージョンのプロファイリングを自動化するための便宜的な機能です。 または、プロファイリング対象のバージョンのクラスを使ってプランオブジェクトを直接構築し、バージョン引数を省略することもできます。 重要：オートチューニング後にエラーが発生することがあります。その場合は、コマンドを再実行してください。最適なオートチューニング設定はすでにキャッシュされているため、正常に動作するはずです。

ベンチマークスクリプト

tests/benchmark/ のベンチマークスクリプトは、厳選された実験用ドライバーです。CLI 引数を受け付けるものもあれば、コピーして編集する固定スクリプトもあります。

python -m tests.benchmark.bench_mla_var6_plus       # base version
python -m tests.benchmark.bench_mla_var6_plus_v4    # specific version
python -m tests.benchmark.bench_all_mla             # compare all kernels (slow)

出力成果物

出力ディレクトリが指定されていない場合、すべてのモードで out/profiles/<mode>/<kernel>/<params>/<timestamp>/ に出力されます。

共通の成果物（すべてのモード）

• params.json — カーネルのパラメーター一式（dtype、b、s、t、h、d、k、p）。プロファイリング設定を確認するために、必ずこれを読み取ってください。特に、report.md にパラメーターが含まれない NCU モードと NSYS モードでは重要です。
• tiling/<stage>.json — ステージごとのオートチューニング済みタイル設定
• tiling/<stage>/autotuning.json — .cache/kernel-autotune/... からコピーされたオートチューニング履歴。選択されたタイル設定と同じ場所に保存されるため、プロファイリング出力ディレクトリを離れずに探索済みの設定を確認できます。
• compiled/<stage>/ — MLIR およびバイトコードのコンパイル成果物

モードごとの成果物

モードごとに異なる成果物が生成されます。詳細は各モードのリファレンスを参照してください。

• mode-annotation.md — カーネルごとの NCU メトリクス、ルーフライン比較、タイル設定を含む report.md。
• mode-event.md — エンドツーエンドのルーフライン概要を含む report.md。
• mode-ncu.md — report.md（簡潔な診断 + NCU による推奨事項）、report-verbose.md（NCU の全セクション）、注釈付きソース、カーネルごとの SASS メトリクス、PTX ソースファイル。
• mode-nsys.md — タイムラインとオーバーラップ分析を含む report.md。

メトリクスの解釈

メトリクス	正常な値	異常な場合 → 問題	最適化のヒント
TC Util	>60%	メモリまたはレイテンシがボトルネック	DRAM%、占有率を確認
DRAM Throughput	>70%	計算またはレイテンシがボトルネック	TC%、占有率を確認
Achieved Occupancy	>25%	レジスター／smem の圧迫	タイルサイズを小さくする、占有率のヒントを確認
L2 Hit Rate	>80%	データ再利用が不十分	Swizzle、より大きなタイル、データレイアウト
Local Spilling	0 bytes	レジスターのオーバーフロー	タイルを小さくする、アキュムレーターを減らす
Waves/SM	>1.0	GPU の稼働率が不足	ブロックを増やす、ブロックあたりのリソースを減らす

ボトルネックの分類

パターン	分類	注目点
DRAM% が高い + TC% が低い	メモリがボトルネック	データ再利用、TMA のヒント、ヘッドのグループ化
TC% が高い + DRAM% が低い	計算がボトルネック	カーネルの効率、タイルサイズ
両方とも低い	レイテンシがボトルネック	占有率、スピリングの削減、ブロック数の増加
L2 hit < 80%	局所性の問題	Swizzle のスケジューリング、タイルサイズの調整

プロファイラー出力の形式

プロファイリング後、結果を次の厳密な形式でオーケストレーターに返します。 構成フィールドに正確な値を設定するため、必ず params.json を読み取ってください。

## Profile: [kernel] [version]

### Configuration
| b | s | t | dtype |
|---|---|---|-------|
| X | X | X | bfloat16 |

### Stages
| Stage | Duration (us) | TC% | DRAM% | Occ% | Bottleneck | Key Issue |
|-------|---------------|-----|-------|------|------------|-----------|

### Bottleneck: [Memory/Compute/Latency]-bound
Root cause: [2 sentences max]

### Top 3 Opportunities (ranked by estimated impact)
1. [name] — est. X% gain — trigger: [metric=value]
2. ...
3. ...

### vs Baseline (if applicable)
| Metric | Previous | Current | Change |
|--------|----------|---------|--------|

開発ログのパフォーマンステンプレート

カーネルの開発ログ（例：docs/kernels/mla-var6-plus.md）を次の内容で更新します。

**Performance** (<device>, locked clocks if applicable, bfloat16, b=X, s=X, t=X):

| Metric            | Value   | vs Previous |
| ----------------- | ------- | ----------- |
| Duration          | X.XX μs | Y% faster   |
| Achieved TFLOPs/s | X.XX    | +Z%         |
| Achieved GB/s     | X.XX    | +Z%         |
| Occupancy         | XX%     | --          |
| TC Util           | XX%     | --          |

**Bottleneck**: [Memory-bound / Compute-bound / Latency-bound]

**Issues**:
- [Remaining problems]

**Insights**:
- [Key lessons — why optimization worked or didn't]
- [Guidance for next iteration]

詳細なリファレンス

• アノテーションモード：references/mode-annotation.md — 成果物、レポート構成、読み方ガイド
• イベントモード：references/mode-event.md — 成果物、制限事項、読み方ガイド
• NCU モード：references/mode-ncu.md — 成果物、注釈付きソース、カーネルごとの SASS メトリクスと PTX ソースファイル、読み方ガイド
• NSYS モード：references/mode-nsys.md — 成果物、CSV、可視化、読み方ガイド