Feature: variable seq length, ring buffer flow control, configurable task window, and swimlane tooling

docs/batch_paged_attention_perf_summary.md

@@ -0,0 +1,94 @@
+# Batch Paged Attention 性能对比总结
+
+## 测试用例一览
+
+所有用例参数一致（num_heads=16, head_dim=16, block_size=16, context_len=33, max_model_len=256），仅 batch 大小不同。
+
+| 用例 | Batch |
+|------|-------|
+| Case1 | 1 |
+| CaseBatch2 | 2 |
+| CaseBatch4 | 4 |
+| CaseBatch8 | 8 |
+| CaseBatch16 | 16 |
+| CaseBatch32 | 32 |
+| CaseBatch64 | 64 |
+| CaseBatch128 | 128 |
+| CaseBatch256 | 256 |
+
+## 架构对比
+
+### 旧架构（paged_attention/）
+
+- 编排器为每个 batch 生成一组独立任务（QK、SF、PV、UP × batch × block 数）
+- 任务数 = `1 + batch × num_blocks × 4`
+- batch=8 时产生 104 个任务，batch=16 时产生 208 个任务，**导致 AICPU 调度器 hang**
+
+### 新架构（batch_paged_attention/）
+
+- 将 batch 循环下放到 kernel 内部，每个 kernel 在一次任务中处理所有 batch
+- 任务数恒定为 **13 个**（1 HUB + num_blocks × 4 kernels），与 batch 大小无关
+- batch=256 仍然只有 13 个任务，彻底消除任务数爆炸问题
+
+## 性能数据
+
+| 用例 | Batch | 输出元素数 | 总 Exec (us) | 总 Sched (us) | 端到端 (us) | Avg Exec/task (us) | Avg Sched/task (us) | Exec/Sched % |
+|------|-------|-----------|-------------|--------------|------------|-------------------|-------------------|-------------|
+| Case1 | 1 | 256 | 38.48 | 262.50 | 160.64 | 2.96 | 20.19 | 14.66% |
+| CaseBatch2 | 2 | 512 | 53.64 | 239.38 | 163.92 | 4.13 | 18.41 | 22.41% |
+| CaseBatch4 | 4 | 1,024 | 85.10 | 327.60 | 206.26 | 6.55 | 25.20 | 25.98% |
+| CaseBatch8 | 8 | 2,048 | 122.24 | 346.02 | 198.28 | 9.40 | 26.62 | 35.33% |
+| CaseBatch16 | 16 | 4,096 | 233.72 | 459.14 | 259.96 | 17.98 | 35.32 | 50.90% |
+| CaseBatch32 | 32 | 8,192 | 442.74 | 729.48 | 386.68 | 34.06 | 56.11 | 60.69% |
+| CaseBatch64 | 64 | 16,384 | 870.38 | 1,104.70 | 562.80 | 66.95 | 84.98 | 78.79% |
+| CaseBatch128 | 128 | 32,768 | 1,719.82 | 1,942.32 | 949.16 | 132.29 | 149.41 | 88.54% |
+| CaseBatch256 | 256 | 65,536 | 3,470.28 | 3,720.64 | 1,763.20 | 266.94 | 286.20 | 93.27% |
+
+> 任务数在所有用例中均为 **13**。
+
+## 关键发现
+
+### 1. 调度效率随 batch 增大显著提升
+
+Exec/Sched 比率从 batch=1 的 14.66% 攀升到 batch=256 的 93.27%：
+
+```
+batch=1   ██░░░░░░░░░░░░░░░░░░  14.66%
+batch=2   ████░░░░░░░░░░░░░░░░  22.41%
+batch=4   █████░░░░░░░░░░░░░░░  25.98%
+batch=8   ███████░░░░░░░░░░░░░  35.33%
+batch=16  ██████████░░░░░░░░░░  50.90%
+batch=32  ████████████░░░░░░░░  60.69%
+batch=64  ███████████████░░░░░  78.79%
+batch=128 █████████████████░░░  88.54%
+batch=256 ██████████████████░░  93.27%
+```
+
+这说明调度开销（Head OH + Tail OH）是近似固定的，当 kernel 执行时间随 batch 增大而增长时，调度开销被有效摊销。
+
+### 2. 端到端延迟线性增长远低于 batch 增长倍数
+
+| 对比 | Batch 增长倍数 | 端到端增长倍数 |
+|------|--------------|--------------|
+| 1 → 16 | 16× | 1.6× |
+| 1 → 64 | 64× | 3.5× |
+| 1 → 256 | 256× | 11.0× |
+
+batch 增大 256 倍时，端到端延迟仅增加约 11 倍，体现了批处理架构对调度开销的高效摊销。
+
+### 3. 每任务平均调度时间基本稳定
+
+Avg Sched/task 从 20.19 us (batch=1) 缓慢增长到 286.20 us (batch=256)，其中增长部分几乎全部来自 kernel 执行时间的增加（Avg Exec 从 2.96 us 增长到 266.94 us），实际调度开销（Sched - Exec ≈ 17~19 us）保持相对稳定。
+
+### 4. 浮点非确定性
+
+大 batch 下偶现少量元素不匹配（<0.2%），为硬件浮点特性导致的间歇性行为，在 rtol=1e-2, atol=1e-2 容差下属于边界情况。重跑可通过。
+
+## 结论
+
+新的 batch_paged_attention 架构通过将 batch 循环下放到 kernel 内部，成功实现了：
+
+1. **任务数恒定**：消除了旧架构中任务数随 batch 线性增长的问题
+2. **支持大 batch**：从旧架构 batch=16 即 hang，到新架构 batch=256 正常运行
+3. **高效利用计算资源**：batch=256 时 93.27% 的时间用于实际计算
+4. **调度开销摊销**：固定的调度开销在大 batch 下被充分摊销