cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-ops-tune/ops-family/references/matmul/scale_coalescing_design.md

@@ -0,0 +1,282 @@
+# matmul 小数据块合并载入（Scale / 小矩阵 Access Coalescing）优化设计
+
+## 1. 优化目标
+
+解决 matmul 族（尤其是 **MXFP4 / MXFP8 量化变体**）在 L1 搬入路径上 **单次 MTE2 搬运量过小（< 20 KB）** 导致的 **访存带宽利用不足** 问题。将 K 方向上被 `baseK`/`kL1` 切碎的若干片 Scale（或其他小侧随路数据）**合并成一次大搬运**，使 MTE2 的**带宽利用率**从典型的 50%–70% 拉回到 80%+ 的健康区间，同时削减等价指令条数与 MTE2 段气泡。
+
+适用面比"仅 Scale"更广：任何在 kernel 内被反复从 GM 搬进 L1、单次数据量显著小于 20 KB、且在 K 方向上"内容相邻 + 读模式一致"的侧输入（Scale、Bias、小 LUT、少量常量张量等）都可以套同一思路（本文档统一称"**小数据块合并载入**"，英文 *small-block MTE2 coalescing* 或 *access coalescing*）。
+
+> **20 KB 物理根因**：昇腾 AI Core 的 MTE2 发射单元对 "发起一次 GM→L1 搬运" 有固定头开销（地址建立、Burst 描述符、DMA 通道配置）。单次搬运量达到约 20 KB 左右时，头开销被数据时间摊薄到 < 5%；若单次低于 20 KB，头开销占比显著拉高，表现为 *cycles/byte* 远高于 HBM 理论峰值。
+
+---
+
+## 2. 架构概览
+
+### 2.1 未优化路径（每 `kL1` 轮都搬一块 scale）
+
+```
+for iter0 in range(kL1Iter):                    # K 轴外层
+    MTE2: GM → L1  A[kL1]             (baseM·kL1 bytes)     ~ 32 KB  ✔ 够大
+    MTE2: GM → L1  B[kL1]             (kL1·baseN bytes)     ~ 32 KB  ✔ 够大
+    MTE2: GM → L1  scaleA[baseK]      (baseM·kL1/32 bytes)  ~  2 KB  ✘ 太小
+    MTE2: GM → L1  scaleB[baseK]      (kL1/32·baseN bytes)  ~  2 KB  ✘ 太小
+    MTE1: L1 → L0 + CUBE
+```
+
+每个 `kL1` 迭代都发一次小 scale 搬运，`kL1Iter = K / kL1` 轮下总计发出 `2 × kL1Iter` 次小搬运。MTE2 段有大量短指令 + 指令间小气泡，带宽利用率拉低。
+
+### 2.2 优化路径（合并 `scaleKL1Ratio` 个 kL1 的 scale 一次性载入）
+
+```
+scaleKL1 = scaleKL1Ratio × kL1        # 例如 16 × BASE_K，或直接置为 K
+for iter0 in range(kL1Iter):
+    if iter0 % scaleKL1Ratio == 0:             # 每 scaleKL1Ratio 轮才发一次 scale
+        MTE2: GM → L1 scaleA[scaleKL1]   (baseM·scaleKL1/32 bytes)  ~ 32 KB  ✔ 够大
+        MTE2: GM → L1 scaleB[scaleKL1]   (scaleKL1/32·baseN bytes)  ~ 32 KB  ✔ 够大
+    MTE2: GM → L1 A[kL1]
+    MTE2: GM → L1 B[kL1]
+    MTE1: L1 → L0 + CUBE
+    # L0 侧按 scaleKL1IterOffset = (iter0 % scaleKL1Ratio) × kL1 从同一块 scaleL1 里取
+```
+
+极端情形（`scaleKL1 = K` 且 L1 放得下）下整段 kernel 只在 `iter0=0` 发一次 scale，后续所有迭代只有 A/B 的大 MTE2。等价地把原来 `2 × kL1Iter` 次小 MTE2 压缩成 `2 × kL1Iter / scaleKL1Ratio` 次大 MTE2；单位数据量不变，但单次负载翻倍到 20 KB 以上。
+
+### 2.3 事件同步模型
+
+在 pingpong 事件模型（`pingpong_design.md` §2.3）基础上新增一对 "scale 独立 pingpong" 事件，与 A/B 的 L1 pingpong **事件 ID 分离**：
+
+| 事件类型 | 含义 | 新增用途（scale 合并） |
+|---------|------|------------------|
+| `MTE1_MTE2(SCALE_BUFFER_FLAG_0)` | scaleA/B 在 L1 双缓冲 ping 释放 | 当前 L0 已消费完前一份 merged scale，准许 MTE2 覆写 ping |
+| `MTE1_MTE2(SCALE_BUFFER_FLAG_1)` | scaleA/B 在 L1 双缓冲 pong 释放 | 同上，pong |
+| `MTE2_MTE1`（仍复用 A/B 轨） | A/B 搬入就绪 → L1→L0 | 合并后不变 |
+
+关键点：**scale 的 pingpong 周期拉长到 `scaleKL1Ratio × kL1Iter` 而非 `kL1Iter`**。只要 `SCALE_BUFFER_NUM = 2`（ping/pong）就足够覆盖所有稳态轮次。
+
+---
+
+## 3. 关键参数配置
+
+```cpp
+constexpr uint32_t BASE_M              = 128;    // 典型量化 matmul baseM
+constexpr uint32_t BASE_N              = 128;
+constexpr uint32_t BASE_K              = 512;
+constexpr uint32_t L1_BUFFER_NUM       = 2;      // A/B 的 K 覆盖倍数（沿用 pingpong）
+constexpr uint32_t PINGPONG_NUM        = 2;      // A/B 的 L1 pingpong
+constexpr uint32_t SCALE_L1_BUFFER_NUM = 16;     // *** 本优化核心 *** scale 相对 A/B 的 K 覆盖倍数
+constexpr uint32_t SCALE_BUFFER_NUM    = 2;      // scale 的 L1 pingpong 仍是 2
+
+// Host Tiling
+params.l1Params.kL1       = BASE_K * L1_BUFFER_NUM;            // A/B 的 kL1
+params.l1Params.scaleKL1  = BASE_K * SCALE_L1_BUFFER_NUM;      // scale 的 scaleKL1 = 16 × BASE_K
+params.l1Params.l1BufNum  = PINGPONG_NUM;
+// 要求：scaleKL1 是 kL1 的整数倍（scaleKL1Ratio_ = scaleKL1 / kL1 ≥ 2 整数）
+```
+
+### 3.1 `SCALE_L1_BUFFER_NUM` 的选取规则
+
+`scaleKL1` 过小则带宽没救回来；过大则 L1 放不下或把 A/B 的 pingpong 空间吃掉。按以下顺序搜索：
+
+1. **计算单次 scale 合并搬运量**：
+   $$ \text{Bytes}_{\text{scaleA}} = \text{baseM} \times \frac{\text{scaleKL1}}{32} \times |\text{dtype}_{\text{scale}}| $$
+   目标：`Bytes_scaleA ≥ 20 KB`（带宽拐点）。以 `baseM = 128, |dtype_scale| = 1 B` 为例：
+   - `scaleKL1 = 512`（即 `SCALE_L1_BUFFER_NUM = 1`）：2 KB ✘
+   - `scaleKL1 = 1024`（`=2`）：4 KB ✘
+   - `scaleKL1 = 5120`（`=10`）：20 KB ✔（**最低门槛**）
+   - `scaleKL1 = 8192`（`=16`）：32 KB ✔（**推荐**，兼容 K=8192 的整块覆盖）
+   - `scaleKL1 = K`（"一次装完"）：理想值；L1 容得下时首选
+
+2. **L1 预算校验**：
+   $$
+   \text{L1 used} = \underbrace{(\text{aL1OneBuffer}+\text{bL1OneBuffer}) \times L_1\text{BufferNum} \times \text{PINGPONG\_NUM}}_{\text{A/B 正常 pingpong}}
+   + \underbrace{(\text{scaleAL1OneBuffer}+\text{scaleBL1OneBuffer}) \times \text{SCALE\_BUFFER\_NUM}}_{\text{scale 合并后 pingpong}}
+   \le L1\text{Size} \ (524288\ B)
+   $$
+   `scaleXL1OneBuffer = baseX × CeilDiv(scaleKL1, MXFP_DIVISOR_SIZE_LOCAL) × MXFP_MULTI_BASE_SIZE_LOCAL`。溢出时回退 `SCALE_L1_BUFFER_NUM`（通常 16 → 8 → 4 → 2）直到成立。
+
+3. **`scaleKL1` 必须是 `kL1` 的整数倍**（`scaleKL1Ratio_ = scaleKL1 / kL1`）。否则 `iter0 % scaleKL1Ratio_ == 0` 的判定会丢 scale 对齐，精度出错。
+
+### 3.2 `scaleKL1Ratio_` 字段
+
+Device 侧新增私有状态：
+
+```cpp
+uint64_t scaleKL1Ratio_;   // = scaleKL1_ / kL1_
+
+// Init()
+scaleKL1Ratio_ = scaleKL1_ / kL1_;
+```
+
+用于两个关键判定：
+- **Scale 搬运触发**：`if (iter0 % scaleKL1Ratio_ == 0) { 发一次 scale MTE2; }`
+- **Scale L0 取数偏移**：`scaleKL1IterOffset = (iter0 % scaleKL1Ratio_) × kL1_`；L0 侧按该偏移从 merged scaleL1 中切对应片给 MMAD。
+
+### 3.3 L1 布局（与 pingpong 布局解耦）
+
+```
+L1 地址空间（L1_SIZE = 524 KB）:
+┌───────────────────────────────────────────────────────────────────────────┐
+│ A_ping │ A_pong │ B_ping │ B_pong │ scaleA_ping │ scaleA_pong │ scaleB_ping │ scaleB_pong │
+│ (kL1)  │ (kL1)  │ (kL1)  │ (kL1)  │ (scaleKL1)  │ (scaleKL1)  │ (scaleKL1)  │ (scaleKL1)  │
+└───────────────────────────────────────────────────────────────────────────┘
+       ↑                                       ↑
+   A/B 每 iter0 轮换                 scaleA/B 每 scaleKL1Ratio_ × iter0 轮换
+```
+
+- A/B 的 pingpong 周期仍然是 `kL1` 粒度（保留 pingpong 重叠 MTE2 / MTE1+CUBE）
+- scaleA/B 的 pingpong 周期被**拉长到** `scaleKL1Ratio_ × kL1`；L1 pingpong 同样是 2 份就够
+
+偏移公式（见 `block_mmad_mx_base.h::Init`）：
+
+```cpp
+l1BufferAOffset_[bufferId] = halfOffset + aL1OneBuffer_ * (bufferId >> 1);
+l1BufferBOffset_[bufferId] = halfOffset + aL1OneBuffer_ * (l1BufNum_ >> 1)
+                           + bL1OneBuffer_ * (bufferId >> 1);
+l1BufferScaleAOffset_[bufferId] = l1BufferBOffset_[bufferId] + bL1OneBuffer_ * (l1BufNum_ >> 1);
+l1BufferScaleBOffset_[bufferId] = l1BufferScaleAOffset_[bufferId] + scaleAL1OneBuffer_;
+```
+
+---
+
+## 4. 关键代码实施点
+
+本节给出从 pingpong（`kL1 = scaleKL1`）基线演进到 scale 合并载入需要改的**五处**：
+
+### 4.1 Host launcher：导出 `scaleKL1 = BASE_K × SCALE_L1_BUFFER_NUM`
+
+```cpp
+constexpr uint32_t SCALE_L1_BUFFER_NUM = 16;   // 新增
+params.l1Params.scaleKL1 = BASE_K * SCALE_L1_BUFFER_NUM;   // 原先 = BASE_K × L1_BUFFER_NUM
+```
+
+### 4.2 BlockMmad::Init：缓存 `scaleKL1Ratio_`
+
+```cpp
+scaleKL1Ratio_ = scaleKL1_ / kL1_;   // 新增私有成员
+// L1 偏移计算改为按 scaleKL1 而非 kL1 来算 scaleXL1OneBuffer
+scaleAL1OneBuffer_ = baseM_ * CeilDiv(scaleKL1_, MXFP_DIVISOR_SIZE_LOCAL) * MXFP_MULTI_BASE_SIZE_LOCAL;
+scaleBL1OneBuffer_ = baseN_ * CeilDiv(scaleKL1_, MXFP_DIVISOR_SIZE_LOCAL) * MXFP_MULTI_BASE_SIZE_LOCAL;
+```
+
+### 4.3 scale MTE2 搬运由"每轮"改为"每 ratio 轮"
+
+```cpp
+for (uint64_t iter0 = 0; iter0 < kL1Iter_; ++iter0) {
+    // ...
+    if (iter0 % scaleKL1Ratio_ == 0) {                 // 原先无此判定
+        uint64_t scaleKL1Offset = iter0 * kL1_;
+        uint64_t curScaleKL1 = scaleKL1_;
+        if (scaleKL1Offset + curScaleKL1 > k_) {       // 末段裁剪
+            curScaleKL1 = k_ - scaleKL1Offset;
+        }
+        // 发一次合并后的 scaleA MTE2
+        AscendC::Te::Copy(CopyScaleGM2L1, tensorScaleAL1Buf, gmBlockScaleA);
+        // 发一次合并后的 scaleB MTE2
+        AscendC::Te::Copy(CopyScaleGM2L1, tensorScaleBL1Buf, gmBlockScaleB);
+    }
+    // A/B 的 MTE2 每轮都发（不变）
+    // ...
+}
+```
+
+### 4.4 L0 取数按合并后的 scaleL1 加偏移
+
+`IterateL0()` 内部 scale → L0 拷贝的起点由 `(0, kL0Offset)` 改为 `(0, scaleKL1IterOffset + kL0Offset)`，其中：
+
+```cpp
+uint64_t scaleKL1IterOffset = (iter0 % scaleKL1Ratio_) * kL1_;
+
+AscendC::Te::Copy(
+    CopyL12L0MxScaleA, tensorScaleAL0, tensorBlockScaleAL1,
+    AscendC::Te::MakeCoord(0, scaleKL1IterOffset + kL0Offset));   // 关键偏移
+```
+
+B 侧同理（坐标维度反过来）。**漏加这个偏移会直接导致精度错误**（不同 K 段用同一份 scale 反量化）。
+
+### 4.5 Scale pingpong 释放条件
+
+`SetFlag<MTE1_MTE2>(SCALE_BUFFER_FLAG_*)` 不再每轮发，而是仅在"本 merged scaleL1 的所有 `scaleKL1Ratio_` 轮 L0 拷贝都完成后"发：
+
+```cpp
+AscendC::SetFlag<AscendC::HardEvent::MTE1_MTE2>(l1BufId);   // A/B 的每轮释放（不变）
+if ((iter0 + 1) % scaleKL1Ratio_ == 0 || iter0 == kL1Iter_ - 1) {
+    AscendC::SetFlag<AscendC::HardEvent::MTE1_MTE2>(SCALE_BUFFER_FLAG_0 + scaleL1BufId);
+    scaleLoopCnt_++;
+}
+```
+
+**漏掉"末轮强制释放"（`iter0 == kL1Iter_ - 1`）会导致 K 不是 `scaleKL1` 整数倍时 AIV 永远 Wait**。
+
+---
+
+## 5. 适用场景与适用性校验
+
+### 5.1 典型 Shape 特征（由策略专家判定）
+
+- **短 `baseK` 侧量化**：`baseM × baseK / 32 × |dtype_scale| < 20 KB`。最典型是 MXFP4 + `baseM=128, baseK=512` → scale 段 2 KB。
+- **K 向循环次数较多**：`kL1Iter = K / kL1 ≥ 4`。否则根本没有足够的重复次数让合并收益显现。
+- **L1 预算尚有余裕**：A/B pingpong 占完后剩余空间可容下 `SCALE_BUFFER_NUM × (scaleAL1OneBuffer + scaleBL1OneBuffer)`（以 `scaleKL1 = 16 × baseK` 计通常 < 65 KB，远小于 L1 余量）。
+
+### 5.2 不适用的情形（禁用条件）
+
+- `baseM × scaleKL1 / 32` 已经 ≥ 20 KB 但搬运仍不快：此时瓶颈在 B/B_scale 侧或 HBM 通道，合并 scale 救不动，需改查 HBM 带宽或改走 A-Full-Load。
+- 量化 group size 非 32 且使单份 scale 已经足够大：合并无收益。
+- L1 容不下 `SCALE_BUFFER_NUM × scaleXL1OneBuffer`：先回退 `SCALE_L1_BUFFER_NUM`（16→8→4→2），到 2 仍放不下说明 A/B pingpong 本身已经吃满 L1，此时本优化不可用。
+- StreamK 分支：StreamK 已经把 K 切成 `kCnt` 段分给不同核，每段的 `skSingleCoreK` 通常已经 ≥ 2048，scale 段天然不再小；且 StreamK 的 `l1BufferNum` 固定为 2、`scaleKL1` 受 workspace 拓扑约束，**不与本优化叠加**。
+
+### 5.3 与其他优化的关系
+
+| 叠加对象 | 是否兼容 | 说明 |
+|---------|----------|------|
+| pingpong 双缓冲（`pingpong_design.md`） | ✅ **强兼容** | scale 合并只改 scale 那对 buffer 的 pingpong 周期，A/B pingpong 不动 |
+| SWAT 负载均衡（`swat_design.md`） | ✅ 兼容 | SWAT 改的是 GetTileIdx 调度，不动 K 方向的 scaleKL1 |
+| StreamK（`streamk_design.md`） | ❌ **互斥** | StreamK 强制 `l1BufferNum=2`、切 K 分段后 scale 段已经够大 |
+| A-Full-Load（`modeling_reference.md` §2.2）| ✅ 兼容 | A 全载只影响 A 的 L1 布局，scale 段仍然在 K 方向被重复搬运，合并同样受益 |
+| L1 bank 冲突对半布局（step 5） | ✅ 兼容 | 本优化在同一对半布局下只改 scale 的 buffer 数量与偏移 |
+
+---
+
+## 6. 常见问题与解决方案
+
+| 问题 | 现象 | 解决 |
+|------|------|------|
+| **精度错误（最常见）** | 输出 C 局部明显偏离 golden；尾部 K 段错得更严重 | 检查 `scaleKL1IterOffset = (iter0 % scaleKL1Ratio_) × kL1_` 是否在 L0 拷贝的 `MakeCoord` 里加上；尾轮 `curScaleKL1 = k_ - scaleKL1Offset` 是否正确裁剪 |
+| **AIV/AIC hang** | K 不是 `scaleKL1` 整数倍时卡死 | 检查末轮 flag 释放：`if ((iter0+1) % scaleKL1Ratio_ == 0 || iter0 == kL1Iter_ - 1)` 的 `||` 必须保留 |
+| **L1 溢出** | 编译期或运行期报 L1 overflow | 回退 `SCALE_L1_BUFFER_NUM`（16→8→4→2）；或先校验 §3.1 的 L1 预算公式 |
+| **合并后性能反而劣化** | MTE2 时间下降有限甚至上升 | 检查是否 MTE2 总量本来就够大（A/B 已 32 KB+）；合并只对 <20KB 的小块有效 |
+| **`scaleKL1 % kL1 ≠ 0`** | `iter0 % scaleKL1Ratio_` 永远非 0 或错位 | 强制 `scaleKL1 = ratio × kL1`，Host Tiling 在搜索 `SCALE_L1_BUFFER_NUM` 时保证整除 |
+
+---
+
+## 7. 预期收益
+
+| 指标 | 优化前（SCALE_L1_BUFFER_NUM=2）| 优化后（SCALE_L1_BUFFER_NUM=16）| 变化 |
+|------|------|------|------|
+| 单次 scale MTE2 搬运量 | 1024 B | 8192–32768 B | +10× |
+| scale MTE2 次数 | `2 × kL1Iter` | `2 × kL1Iter / 16` | ÷16 |
+| MTE2 段时间（`[128, 8192, 4096]`）| 34.4 μs | 31.27 μs | **−9%** |
+| Task 总时间 | 39.53 μs | 36.76 μs | **−7%** |
+| MTE2 带宽利用率 | ~50–60% | ~80%+ | **+25 pp** |
+
+典型收益区间：**5%–15% 端到端 Task 时间缩短**，受 K 长度、`baseK`/`baseM`、Scale dtype 大小影响。K 越长、`baseK` 越小、scale 在 L1 的占比越低时收益越大。
+
+---
+
+## 8. 泛化：不止 Scale —— 小数据块合并载入的一般化
+
+以下场景可套同一模板（`合并 ratio × 原始覆盖`）：
+
+| 场景 | 小数据来源 | 合并后字段 | 预期收益 |
+|------|------|------|------|
+| MXFP4/MXFP8 量化 matmul 的 scaleA/scaleB | group_size=32 下，单 baseK 段 scale 只有 2 KB | `scaleKL1 = SCALE_L1_BUFFER_NUM × kL1` | 本文主体场景 |
+| Matmul with bias（小 bias 向量）| bias 大小 `N` 或 `M`，单次切片可能 < 4 KB | 一次性全载 bias 到 L1 | 1–5% 次要 |
+| 分组量化 GroupMatmul / MoE 专家权重的小 LUT | 每组的 routing 索引表 < 1 KB | 一次性载入 expert-routing 表 | 若 LUT 访问频繁，2–5% |
+| RNN / Attention 的 mask / pos_embed 小张量 | 切片后单次 < 8 KB | 合并到一次 MTE2 | 视 K 循环次数 |
+| 动态 shape 算子的 "尾片" 搬运 | 尾片普遍短 | Host 端融合尾片，kernel 端一次搬完 | 5–10%（尾部分带宽型场景）|
+
+共用前提：
+1. 小块数据在 K 向（或主循环轴）上**内容相邻、模式一致**（否则合并不能复用）；
+2. L1 / UB 有余量；
+3. 小块数据是**只读**或**累加型**（不存在写竞争）。
+
+在"是否启用合并"门禁校验阶段，**只需验证第 2 与第 3 条 + 单次原始搬运量 < 20 KB**；第 1 条通常由算子结构自然保证。

package/skills/asc-tools/tool-ops-tune/ops-family/references/matmul/streamk_design.md

@@ -0,0 +1,374 @@
+# matmul StreamK 调度模式技术文档
+
+## 1. 背景
+
+在昇腾 AI 处理器上执行矩阵乘（MatMul）时，传统的 Data-Parallel（DP）分核只在 M、N 两个维度切块，把 `mCnt × nCnt` 个基块分给 `aicNum` 个核。这种切分在以下两类场景会出现明显的核间负载不均：
+
+1. **MN 欠并行（小 M、小 N、长 K）**：当 `mCnt × nCnt` 明显小于 `aicNum` 时，相当多的核根本没有原 tile 可分，整个 kernel 被少数几个核拖到 K 向串行耗时。例如 `M=N=512, K=16384, baseM=baseN=256`：`mCnt·nCnt = 4`，而 24 个核只有 4 个在工作。
+2. **末轮空闲核（MN 不整除 aicNum）**：`totalCnt = mCnt·nCnt` 不是 `aicNum` 的整数倍时，稳态区各核均匀跑，但最后一轮只有前 `tailMNCnt = totalCnt % aicNum` 个核有活。SWAT 的「末轮二维再切分」在末轮 tile 数量少、或 `baseM/baseN` 已经接近 CUBE 单元粒度时会失去收益（子块太小、CUBE 启动开销反超），此时需要另一条思路。
+
+**StreamK** 就是为这两类场景设计的调度策略：**把空闲的核拉去参与 K 维累加**，让原本不参与计算的核也分担 `k` 方向的一部分 MMA，然后通过一块 workspace 做跨核 K 累加归约。结果是：**原本 4 个核的活被拆成 `4 × (K 切分数)` 份，接近满核利用率**。
+
+StreamK 有两种子模式，由 host tiling 根据 shape 自动选择：
+
+| 子模式 | 触发条件（简化） | 切分方式 |
+|---|---|---|
+| **Stream-K (SK)** | `mCnt·nCnt ≤ aicNum/2` 且 `K ≥ 4096 (FP16 列)` | 所有 MN 块都做 K 切分（`kCnt = aicNum / (mCnt·nCnt)`） |
+| **DP + Stream-K (DP+SK)** | `mCnt·nCnt ≥ aicNum` 且 `mCnt·nCnt % aicNum ≠ 0` 且余数 ≤ `aicNum/2` 且 `K ≥ 8192/FP16` | 稳态轮按 DP 走（K 不切）；仅**最后一整轮**的 tail tile 做 K 切分 |
+
+两种模式共用一套 kernel 实现（`matmul_a16w16_kernel_streamk.h`）和 scheduler（`matmul_a16w16_block_scheduler_streamk.h`），只靠 tiling 参数与 `CheckIsSkScene(tileIdx)` 区分。
+
+## 2. 架构概览
+
+### 2.1 存储层级与数据流
+
+```
+GM (A, B)
+  │
+  │ MTE2 (AIC 核，按本核分到的 {mIdx, nIdx, kIdx} 子片)
+  ▼
+L1 Buffer [A_ping | A_pong | B_ping | B_pong]         ← L1_BUFFER_NUM = 2
+  │
+  │ MTE1 (L1 → L0A/L0B，按 L0 pingpong 切半)
+  ▼
+L0A / L0B Buffer [half_0 | half_1]
+  │
+  │ CUBE (MMA 累加 L0A × L0B → L0C，unitFlag 控制是否 FINAL_ACCUMULATION)
+  ▼
+L0C Buffer
+  │
+  ├── SK 场景（本核只是 K 的一段）：CopyL0C2GM → Workspace[tileIdx-based offset]
+  │                                      (FP32，避免中间累加精度损失)
+  └── DP 场景（本核拿到完整 K）：CopyL0C2GM → GM[C]
+
+               ↓ CrossCoreSetFlag<AIC_SYNC_AIV_MODE_4>
+               ↓ (SK 的 tile 写完 workspace 后通知 AIV)
+               ↓
+AIV 核
+  │
+  │ MTE2：把 workspace 上同一 tile 的 K 各段 (共 kCnt 段) 搬到 UB
+  │ Vector：逐段 Add 累加到第 0 段
+  │ Cast：FP32 → FP16/BF16
+  │ MTE3：写回 GM[C]
+  ▼
+GM (C)
+```
+
+### 2.2 SK 与 DP+SK 的区别
+
+```
+SK  (mCnt·nCnt ≤ aicNum/2)                 DP+SK (mCnt·nCnt ≥ aicNum, 非整除)
+
+每个 MN tile 都被 kCnt 个核切 K 累加         稳态轮：MN tile 完整落到单核（DP 路径）
+                                            末轮  ：剩余 tailMNCnt 个 tile 各自被 kCnt 切 K
+ ┌──── tile0 (K 被切 kCnt 段) ────┐          ┌ 稳态 ┐┌ 稳态 ┐ ... ┌ SK末轮 ┐
+ │ core0 core1 ... core_{kCnt-1} │          │core0 ││core1 │ ... │ 切K   │
+ └───────────────────────────────┘          └──────┘└──────┘     └───────┘
+```
+
+### 2.3 事件同步模型（共用）
+
+| 事件类型 | 含义 | 用途 |
+|---------|------|------|
+| `MTE1_MTE2`(id 0/1) | MTE1 完成 → 允许 MTE2 覆写 L1[A_buf] | A 侧 L1 pingpong 释放 |
+| `MTE1_MTE2`(id 2/3) | 同上 | B 侧 L1 pingpong 释放（与 A 分离 event id 避免紧耦合） |
+| `MTE2_MTE1` | MTE2 完成 → 允许 MTE1 读 L1 | A、B 数据就绪 |
+| `M_MTE1` | CUBE 完成 → 允许 MTE1 覆写 L0 | L0 pingpong 释放 |
+| `MTE1_M` | MTE1 完成 → 允许 CUBE | L0 数据就绪 |
+| `AIC_SYNC_AIV_MODE_4`（PIPE_FIX）| AIC 写完 workspace → 通知 AIV 累加 | **StreamK 专用**：跨 AIC/AIV 同步，让 AIV 等所有 K 分段都写完再开始归约 |
+| `MTE3_MTE2`（ZERO_FLAG） | DP 场景 AIV 复用 UB 前等 MTE3 完成 | 避免 UB 数据竞争 |
+
+**关键差异**：StreamK 的同步比 pingpong/SWAT 多一层 **跨核 AIC→AIV 的 CrossCoreSetFlag**，因为 SK 的最终输出（FP16/BF16 的 C 矩阵）必须等所有 K 分段的 FP32 部分和全部写入 workspace 后由 AIV 完成归约+cast。
+
+## 3. 关键参数配置
+
+```cpp
+// 核心常量（matmul_a16w16_block_mmad_streamk.h & scheduler）
+constexpr uint64_t L1_BUFFER_NUM = 2;                         // L1 双缓冲
+constexpr uint64_t HALF_L0_SIZE  = L0A_SIZE / DOUBLE_BUFFER_COUNT;
+constexpr uint16_t L1_EVENT_ID_OFFSET = 2;                    // A、B 用不同 event id 区间
+constexpr uint16_t BLOCK_BASE_M = 256;                        // L0/workspace 对齐粒度
+constexpr uint16_t BLOCK_BASE_N = 256;
+constexpr uint64_t WINDOW_LEN   = 4;                          // serpentine 行窗口（与 SWAT 共享）
+
+// Host tiling 侧（matmul_a16w16_tiling_streamk.h）决定：
+struct RunInfo {
+    uint64_t usedCoreNum;   // 实际使用的 AIC 核数 = aicNum
+    uint64_t baseM, baseN;  // 通常 = 256
+    uint64_t baseK;         // = 128 / sizeof(FP16) = 64，受 L0A 容量约束
+    uint64_t kL1;           // = baseK * stepKa，被 STEPKA_THRESHOLD=4 截断
+    uint64_t skSingleCoreK; // ★ StreamK 核心：单核 K 维负责的长度
+    uint64_t tailInfo.kCnt; // ★ K 切分数 = aicNum / (mCnt·nCnt)  或  = aicNum / tailMNCnt
+    uint64_t depthA1, depthB1; // L1 深度，depthA1 = stepKa * DB_SIZE
+    uint64_t stepKa, stepKb;   // 互相倍数对齐，上限 4
+};
+```
+
+### 3.1 L1 内存布局
+
+```
+L1 地址空间（FP16 路径）:
+[A_ping | A_pong | B_ping | B_pong]
+
+偏移计算（见 block_mmad_streamk.h::operator()）:
+aL1OneBuffer_ = mL1 * kL1
+bL1Init_      = aL1OneBuffer_ * L1_BUFFER_NUM        // B 区起点
+bL1OneBuffer_ = nL1 * kL1
+
+offsetAL1 = aL1OneBuffer_ * l1BufId * sizeof(TypeA)
+offsetBL1 = (bL1Init_ + bL1OneBuffer_ * l1BufId) * sizeof(TypeB)
+```
+
+注意：StreamK 与 pingpong 的 L1 布局**一致**（都是 A_ping/A_pong/B_ping/B_pong），差别仅在 kL1 取值与 K 的切片长度。
+
+### 3.2 Workspace 布局
+
+```
+GetWorkSpace() = aicNum * BLOCK_BASE_M * BLOCK_BASE_N * sizeof(FP32)   // 部分和累加空间
+               + RPC_WORKSIZE * MB_SIZE                                // 跨核通信
+```
+
+每个核在 SK 场景下写入的 workspace 偏移：
+
+```cpp
+offsetWorkspace = (((tileIdx % usedCoreNum) / skKTileNum) * skKTileNum
+                  + Get<MNK_K>(singleCoreCoord))
+                  * BLOCK_BASE_M * BLOCK_BASE_N;
+```
+
+- `(tileIdx % usedCoreNum) / skKTileNum` → 本 tile 在末轮里的 MN 序号（用作归约基址）
+- `Get<MNK_K>(singleCoreCoord)` → 本核负责的 K 段序号（0..kCnt-1）
+
+AIV 归约时按「同一 MN 基址下 kCnt 段连续 FP32 存储」读取，Add 累加后 cast 回 FP16/BF16 写入 C。
+
+### 3.3 SK Preload（DP+SK 专属优化）
+
+DP+SK 模式下，最后一轮的 SK 子任务依赖 workspace 写入 + AIV 归约，延迟较长。Preload 机制把**末轮某些 tile 的 AIC 工作提前到倒数第二轮**执行（交换 `tileIdx` 与 `tileIdx + usedCoreNum`），使得 AIC 在末轮时同时写 workspace（for 本轮 tile）和前一轮已写好 workspace 的 tile 正好在归约完成，掩盖归约延迟：
+
+```cpp
+// see matmul_a16w16_kernel_streamk.h::operator()
+if (!bs.CheckIsSkScene(0)) {  // 仅 DP+SK 启用（纯 SK 不需要）
+    int64_t tailSKTotalTileNum = ((mTileNum * nTileNum) % usedCoreNum) * skKTileNum;
+    // 条件：末轮前一轮的 tailSK 数量内
+    if (前一轮后段属于 tail) swap(tileIdx, tileIdx ± usedCoreNum);
+}
+```
+
+## 4. 核心计算循环
+
+### 4.1 外层调度（kernel 顶层）
+
+```cpp
+// matmul_a16w16_kernel_streamk.h
+for (tileIdx = curBlockIdx; tileIdx < tileNum; tileIdx += usedCoreNum) {
+    // [DP+SK 才执行] SK Preload 交换
+    tmpTileIdx = SkPreloadSwap(tileIdx);
+
+    singleCoreShape = bs.GetSingleCoreShape(tmpTileIdx);   // serpentine + 尾修正
+    singleCoreCoord = bs.GetSingleCoreCoord(tmpTileIdx);
+    kSingleCore     = bs.GetCurKSingleCore(tmpTileIdx);    // SK 场景返回 skSingleCoreK，DP 返回 k
+
+    gmBlockA = gmA[mPos * mL1 : +mL1, kPos * kSingleCore : +kSingleCore];
+    gmBlockB = gmB[kPos * kSingleCore : +kSingleCore, nPos * nL1 : +nL1];
+    gmBlockC = gmC[mPos * mL1 : +mL1, nPos * nL1 : +nL1];
+    gmWorkSpace = workspace[offsetWorkspace ...];
+
+    blockMmadOp(gmBlockC, gmBlockA, gmBlockB, gmWorkSpace,
+                singleCoreShape, kIdx, bs.CheckIsSkScene(tmpTileIdx));
+    //                                 ↑ 决定落 workspace (SK) 还是落 C (DP)
+
+    if (tmpTileIdx + usedCoreNum >= tileNum) {
+        AscendC::CrossCoreSetFlag<AIC_SYNC_AIV_MODE_4, PIPE_FIX>(AIC_SYNC_AIV_FLAG);
+        AscendC::CrossCoreSetFlag<..>(AIC_SYNC_AIV_FLAG + FLAG_ID_MAX);
+        // ↑ 最后一轮结束，通知 AIV 可以开始归约
+    }
+}
+```
+
+### 4.2 内层 K 流水（block_mmad）
+
+```cpp
+// block_mmad_streamk.h::operator()（伪代码）
+for (iter0 = 0; iter0 < curKL1Iter; ++iter0) {    // K 在 L1 级的迭代
+    l1BufId = abL1LoopCnt_ & 1;
+
+    // A 侧（event id 0/1）
+    WaitFlag<MTE1_MTE2>(l1BufId);
+    CopyGM2L1(A → L1[offsetAL1]);
+    SetFlag<MTE2_MTE1>(l1BufId);
+    WaitFlag<MTE2_MTE1>(l1BufId);
+
+    // B 侧（event id 2/3，独立于 A 避免紧耦合）
+    WaitFlag<MTE1_MTE2>(l1BufId + L1_EVENT_ID_OFFSET);
+    CopyGM2L1(B → L1[offsetBL1]);
+    SetFlag<MTE2_MTE1>(l1BufId + L1_EVENT_ID_OFFSET);
+
+    // 内层 L0 pingpong
+    for (iter1 = 0; iter1 < kL0Iter; ++iter1) {
+        l0Offset = HALF_L0_SIZE * (l0PingPong_ & 1);
+        WaitFlag<M_MTE1>(l0PingPong_ & 1);
+        CopyL12L0(A → L0A[l0Offset]);
+        if (iter1 == 0) WaitFlag<MTE2_MTE1>(l1BufId + L1_EVENT_ID_OFFSET);  // B 只等一次
+        CopyL12L0(B → L0B[l0Offset]);
+        SetFlag<MTE1_M>(l0PingPong_ & 1);
+        WaitFlag<MTE1_M>(l0PingPong_ & 1);
+
+        unitFlag = (iter0+1==curKL1Iter && iter1+1==kL0Iter)
+                   ? FINAL_ACCUMULATION : NON_FINAL_ACCUMULATION;
+        cmatrixInitVal = (iter0==0 && iter1==0);       // 首次累加初始化 L0C
+        Mmad(tensorL0C, tensorAL0, tensorBL0, unitFlag, cmatrixInitVal);
+
+        SetFlag<M_MTE1>(l0PingPong_ & 1);
+        l0PingPong_++;
+    }
+
+    if (iter0 + 1 == curKL1Iter) {
+        // 根据 checkIsSkScene 决定输出目的地
+        if (checkIsSkScene) Copy L0C → workspace (FP32, FINAL_ACCUMULATION);
+        else                Copy L0C → gmC       (FP16/BF16, FINAL_ACCUMULATION);
+    }
+
+    SetFlag<MTE1_MTE2>(l1BufId);
+    SetFlag<MTE1_MTE2>(l1BufId + L1_EVENT_ID_OFFSET);
+    abL1LoopCnt_++;
+}
+```
+
+### 4.3 AIV 归约路径
+
+```cpp
+if ASCEND_IS_AIV {
+    // 仅最后一轮的 tail tile 需要 AIV（kCnt 次累加）
+    if (curBlockIdxInAiv >= lastLoopTotalCnt * GetTaskRation()) {
+        WaitFlag<CrossCore>(AIC_SYNC_AIV_FLAG);
+        SyncAll();
+        return;
+    }
+    WaitFlag<CrossCore>(AIC_SYNC_AIV_FLAG);
+    SyncAll();
+    BlockEpilogueStreamK epilogue;
+    epilogue.Init(...);   // 计算本 AIV 负责的 mBurstBase、offsetWorkspace、offsetCGm
+    epilogue();           // for i in kCnt: Add(ub, ub[i*burstLen]); Cast FP32→FP16; DataCopyPad → C
+}
+```
+
+## 5. 从 pingpong / SWAT 升级到 StreamK 的关键修改点
+
+| 修改项 | pingpong / SWAT (优化前) | StreamK (优化后) |
+|--------|------------------------|-----------------|
+| 分核维度 | 仅 M、N 切分（DP） | M、N + **K 切分** |
+| 并行度 | `min(mCnt·nCnt, aicNum)` | `min(mCnt·nCnt·kCnt, aicNum)` |
+| Workspace | 不需要（或仅用于 L1 tiling） | **必需**：`aicNum × 256² × sizeof(FP32) + RPC` |
+| 输出路径 | AIC 直接 CopyL0C2GM → C（FP16/BF16） | SK tile：AIC → workspace(FP32)；AIV 归约 + cast → C |
+| AIV 启用 | 仅用于 ND2NZ / 量化类特殊处理 | **必需**：末轮 kCnt 段累加归约 |
+| 跨核同步 | AIC/AIV 可独立调度 | **必需** `CrossCoreSetFlag<AIC_SYNC_AIV_MODE_4>` 确保 workspace 就绪 |
+| `unitFlag` 控制 | 始终 `FINAL_ACCUMULATION` | 按 `iter0+iter1` 判断：非末次为 `NON_FINAL_ACCUMULATION` |
+| `cmatrixInitVal` | 仅首个 tile 初始化 | 每个 SK 段首次 MMA 都要初始化 L0C（因段间不累加） |
+| `baseK` | 64 或 128 | 固定 `128 / sizeof(FP16) = 64`（保 L0 双缓冲） |
+| `kL1` 上限 | 按 L1_BUFFER_NUM 推导 | **额外加 `STEPKA_THRESHOLD=4` 上限**，避免 SK 段过长挤掉 pingpong |
+| 调度器 | `SwatScheduler` / `PingpongScheduler` | **新增** `BlockSchedulerA16W16StreamK`，带 `skKTileNum`、`totalMNTileNumInDP`、`CheckIsSkScene` |
+| Epilogue | 无 / 简单 cast | **新增** `BlockEpilogueStreamK`：支持从 workspace 逐段 Add + Cast + DataCopyPad |
+
+## 6. 注意事项
+
+1. **只对特定 shape 有收益**：host tiling `IsCapable()` 会拒绝非目标 shape（SK 需 K≥4096 FP16 列 & mn≤核数/2；DP+SK 需 M/N 256 对齐 & K≥8192/FP16 & 余数≤核数/2）。不在目标区间的 shape 走 StreamK 反而会因 workspace 归约开销劣化，应退回 pingpong / SWAT。
+2. **Workspace 容量开销**：约 `aicNum × 128KB = 3MB+`（FP32），需确认 HBM 预算。
+3. **精度影响**：SK 路径的部分和在 workspace 用 FP32 保存，AIV 归约完成后再 cast 回 FP16/BF16，**精度等价或优于**纯 FP16 归约（减少了中间 round）。
+4. **cmatrixInitVal 陷阱**：每个 SK 分段（每次 `blockMmadOp` 调用）都是独立的 L0C 累加序列，必须 `cmatrixInitVal = (iter0==0 && iter1==0)`；若误写为「全局首次」，则第二个段开始 L0C 会错误累加上个段的结果。
+5. **SK Preload 仅适用 DP+SK**：纯 SK 模式下 `CheckIsSkScene(0) == true`，preload 分支跳过；否则会打乱稳态轮的 tile 分布，导致 workspace 偏移错位。
+6. **末轮 unitFlag 处理**：`iter0 + 1 == curKL1Iter && iter1 + 1 == kL0Iter` 必须 `FINAL_ACCUMULATION`，否则 CUBE 不发出「L0C 就绪」的 block 级同步，FIXP 无法开始搬出。
+7. **serpentine 行窗口继承**：scheduler 里仍用 `WINDOW_LEN=4` 做行窗口 + 奇数行反向（见 `UpdateMNTileIdx`），保证 B 流在片上的复用，不要因引入 K 切分而把这一层打掉。
+
+## 7. 实施常见问题与解决方案
+
+### 问题 1：Workspace 偏移计算错误，AIV 累加出来是错值
+
+**现象**：精度校验失败，输出的 C 矩阵某些 tile 全 0 或重复叠加。
+
+**原因**：offsetWorkspace 必须按「**末轮中 MN tile 的 index**」而非 `tileIdx` 直接算：
+
+```cpp
+// 错误写法（使用全局 tileIdx）
+offsetWorkspace = tileIdx * BLOCK_BASE_M * BLOCK_BASE_N;
+
+// 正确写法（先取末轮 MN 序号）
+offsetWorkspace = (((tileIdx % usedCoreNum) / skKTileNum) * skKTileNum
+                   + Get<MNK_K>(singleCoreCoord))
+                  * BLOCK_BASE_M * BLOCK_BASE_N;
+```
+
+### 问题 2：AIV 等待超时 / 跨核同步 flag 不匹配
+
+**现象**：运行 hang，或 AIV 在 SyncAll 处长时间停顿。
+
+**原因**：AIC 侧提前 return 的核（`curBlockIdx >= bs.GetBlockNum()`）没有发送 `AIC_SYNC_AIV_FLAG`，AIV 侧 Wait 永远不会满足。
+
+**解决方案**：空闲 AIC 核 **必须** 在 return 前补发 flag：
+
+```cpp
+if (curBlockIdx >= bs.GetBlockNum(usedCoreNum_)) {
+    AscendC::CrossCoreSetFlag<AIC_SYNC_AIV_MODE_4, PIPE_FIX>(AIC_SYNC_AIV_FLAG);
+    AscendC::CrossCoreSetFlag<AIC_SYNC_AIV_MODE_4, PIPE_FIX>(AIC_SYNC_AIV_FLAG + FLAG_ID_MAX);
+    return;
+}
+```
+
+### 问题 3：SK 场景下 L0C 累加异常（段之间互相污染）
+
+**现象**：多段 K 切分的 tile 算出来的 C 值是累加结果（而非该段的部分和）。
+
+**原因**：`cmatrixInitVal` 判定没有考虑 StreamK 每次 `operator()` 都是独立段：
+
+```cpp
+// 错误：以为是 DP，固定 false
+bool cmatrixInitVal = false;
+
+// 正确：每次 blockMmadOp 调用都是一个独立段
+bool cmatrixInitVal = (iter0 == 0 && iter1 == 0);
+```
+
+### 问题 4：MN 能被 aicNum 整除，误开 StreamK
+
+**现象**：打印 `[ERROR] StreamK requires: K >= 4096 and MN split count <= half of core number`；或即使 shape 满足，性能反而劣化。
+
+**原因**：
+- DP+SK 的必要条件是 `mCnt·nCnt % aicNum ≠ 0`，整除时退回纯 DP + pingpong 即可。
+- `mCnt·nCnt > aicNum/2` 但 `≤ aicNum` 时（未过 DP+SK 门槛），不要硬开 StreamK。
+
+**解决方案**：在 tiling 入口处加门禁（已由 `CheckStreamKSKTiling` / `CheckStreamKDPSKTiling` 实现），否则调度器会跑错的 tileIdx 模式。
+
+### 问题 5：baseK 取太大，stepK 被截到 1 失去 L1 pingpong
+
+**现象**：优化后 busy 占比没提升，MTE2 和 CUBE 仍然串行。
+
+**原因**：`baseK` 受 `l0aSize / DB_SIZE / FP16 / max(baseM,baseN)` 约束。如果误取 `baseK = 128`（FP16 路径），会让 `stepKa = depthA1/2 = 1`，L1 不再双缓冲。
+
+**解决方案**：遵循 `CalBaseK` 公式：
+
+```cpp
+baseK = min(singleCoreK, FloorAlign(l0aSize/2/sizeof(FP16)/max(baseM,baseN), alignValue));
+//                      ↑ 典型取 64 （128 bytes / 2 bytes），使 stepKa ≥ 2
+```
+
+### 问题总结
+
+| # | 问题 | 根因 | 解决方案 | 影响 |
+|---|------|------|---------|------|
+| 1 | workspace offset 错位 | 直接用 tileIdx 而非末轮 MN 序号 | 按 `(tileIdx % usedCoreNum) / skKTileNum` 计算 | 精度错误 |
+| 2 | AIV hang / 同步失败 | 空闲 AIC 未发 flag | 提前 return 前补发 CrossCoreSetFlag | 运行超时 |
+| 3 | L0C 跨段污染 | `cmatrixInitVal` 固定 false | 每段首次 `(iter0==0 && iter1==0)` 置 true | 精度错误 |
+| 4 | MN 整除仍开 StreamK | 未走 IsCapable 门禁 | 严格校验 SK/DPSK 判定条件 | 性能劣化 |
+| 5 | stepKa=1 失去 L1 pingpong | baseK 过大挤掉 depth | 按 CalBaseK 公式取 `baseK=64` | 性能未达预期 |
+
+## 8. 与 pingpong / SWAT 的取舍
+
+| 场景特征 | 推荐策略 |
+|---------|---------|
+| MN 块数 ≥ aicNum 且整除 | **pingpong** 足够，无需 SWAT/StreamK |
+| MN 块数 ≥ aicNum 非整除，末轮有明显尾块且 `baseM/baseN` 宽松 | **SWAT 机制 C**（末轮二维再切分）优先；`baseM·baseN` 已接近 CUBE 最小块时退化为 StreamK (DP+SK) |
+| MN 块数 < aicNum 且 `K` 大（≥ 4096 列） | **StreamK (SK)** 把空闲核用 K 切分拉起来 |
+| MN 块数 < aicNum 但 `K` 也小 | 无法通过 K 切分并行化，只能从 tiling / baseM/baseN 入手重做分块 |
+| 有 M/N 边缘薄片且 `mCnt·nCnt ≥ aicNum` | **SWAT 机制 B**（尾块合并） |
+| B 侧流式带宽严重 | 任何模式都应打开 **SWAT 机制 A**（serpentine 行窗口）；StreamK 已内置 |
+
+**StreamK 与 SWAT 不是互斥**：StreamK 的 scheduler 内部用了 SWAT 机制 A 的 serpentine 遍历；机制 B（尾块合并）仍可在 tiling 层叠加使用（但在 StreamK 的 FP16 当前版本中暂默认 `mBaseTailSplitCnt=1`）。机制 C（末轮二维再切分）与 StreamK 的 DP+SK 是**同一痛点的两种解法**——根据 `baseM/baseN` 相对 CUBE 单元粒度的松紧，择一使用。