profile-kernel

GPU 内核性能分析

GPU 时钟协议

性能分析前始终锁定时钟。始终一次只运行一项性能分析。

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

设备峰值

共享的性能分析指南不应将设备硬编码为某一种型号。请从 params.json、运行时性能分析产物以及 src/mla_var3/conf/devices.json 中配置的峰值规格来源读取当前设备上下文。

仅当测量上下文相关时，才使用 docs/devices/ 中的设备专属参考文件。拐点仍为：

ridge_point = peak_tflops / peak_gbps

性能分析模式决策树

模式	--prof_type	适用场景	输出根目录
Annotation	annotation	默认的第一步。 Roofline + NCU 指标 + 对比表	out/profiles/annotation/
Event	event	快速迭代计时（包含 Python 开销）	out/profiles/event/
NCU	ncu	深入调查：完整 NCU 部分、源代码注释、优化建议	out/profiles/ncu/
NSYS	nsys	流水线重叠、流并发、启动顺序	out/profiles/nsys/

选择规则：从 annotation 开始。使用 event 进行快速 A/B 对比（不适用于 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=...)

注意，version 是可选的，可用于指定自定义版本。它会获取指定版本对应的 KernelPlan 并使用该计划，而不是传入函数的 plan。这只是为了方便自动执行版本性能分析。 或者，你也可以直接使用待分析版本的类来构建计划对象，并忽略 version 参数。 重要：自动调优后有时可能会出现错误。此时只需重新运行命令；最佳自动调优配置已经缓存，之后应该一切正常。

基准测试脚本

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）。务必读取此文件以确认性能分析配置，尤其是 NCU 和 NSYS 模式，因为它们的 report.md 不会嵌入参数。
• tiling/<stage>.json — 每个阶段经过自动调优的平铺配置
• tiling/<stage>/autotuning.json — 从 .cache/kernel-autotune/... 复制的自动调优历史，与所选平铺配置放在一起，方便你无需离开性能分析输出目录即可检查探索过的配置
• compiled/<stage>/ — MLIR 和字节码编译产物

各模式产物

每种模式都会生成不同的产物。完整详情请参阅各模式的参考文档：

• mode-annotation.md — report.md，包含每个内核的 NCU 指标、roofline 对比和平铺配置；
• mode-event.md — report.md，包含端到端 roofline 摘要；
• mode-ncu.md — report.md（精简诊断 + NCU 建议）、report-verbose.md（完整 NCU 部分）、带注释的源代码、每个内核的 SASS 指标、PTX 源文件；
• mode-nsys.md — report.md，包含时间线和重叠分析；

指标解读

指标	健康状态	若状态不佳 → 问题	优化提示
TC 利用率	>60%	受内存或延迟限制	检查 DRAM%、占用率
DRAM 吞吐量	>70%	受计算或延迟限制	检查 TC%、占用率
实际占用率	>25%	寄存器/smem 压力	减小 tile 大小，设置占用率提示
L2 命中率	>80%	数据复用不佳	Swizzle、增大 tile、调整数据布局
本地溢出	0 字节	寄存器溢出	减小 tile、减少累加器
Waves/SM	>1.0	GPU 未充分利用	增加 block 数量，减少每个 block 的资源

瓶颈分类

模式	分类	重点
DRAM% 高 + TC% 低	内存受限	数据复用、TMA 提示、head 分组
TC% 高 + DRAM% 低	计算受限	Kernel 效率、tile 大小
两者都低	延迟受限	占用率、减少溢出、增加 block 数量
L2 命中率 < 80%	局部性问题	Swizzle 调度、调整 tile 大小

Profiler 输出规范

完成性能分析后，按此确切格式向编排器返回结果。 务必读取 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 |
|--------|----------|---------|--------|

开发日志性能模板

使用以下内容更新 kernel 的开发日志（例如，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]

详细参考资料

• Annotation 模式：references/mode-annotation.md — 产物、报告结构、阅读指南
• Event 模式：references/mode-event.md — 产物、限制、阅读指南
• NCU 模式：references/mode-ncu.md — 产物、带注释的源代码、每个 kernel 的 SASS 指标和 PTX 源文件、阅读指南
• NSYS 模式：references/mode-nsys.md — 产物、CSV、可视化、阅读指南