cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-ops-tune/ops-family/references/fa/fa_roofline_design.md

@@ -0,0 +1,141 @@
+# FA 族设计：三通道 Roofline（基本块 Bq/Bk 选取）
+
+> **来源（蒸馏）**：Ascend C Tiling 设计方法论·FlashAttention Roofline 分册。
+> 本文是 FA 基本块选取的**推导方法论**——禁止凭经验选取 Bq/Bk。
+
+## 1 为什么 FA 需要专门的 Roofline 模型
+
+FA 是 mix kernel（AIC 算 GEMM + AIV 算 softmax，跨核 stage 化），性能瓶颈
+**不能用单一 AI 概括**。三个独立吞吐通道各自可能成为瓶颈：
+
+1. **Cube 算力**（AIC 的 Mmad 吞吐）
+2. **HBM 带宽**（K/V/Q/O 的 GM 加载与写回）
+3. **跨核/片上吞吐**（AIV softmax 吞吐 + Cube↔Vector 片上握手 + O_acc streaming）
+
+> ⚠️ **常见建模错误**：把片上跨核握手（S/P/PV 的 L0C↔UB↔L1 movement）与 HBM
+> 加载混进同一个 AI 分母，再用「混合带宽」求单一 AI。这会把 AI 人为封顶在
+> `D/sizeof(T)`，让人误以为 FA 永远到不了 compute-bound，同时掩盖真正的第三
+> 瓶颈（AIV/片上吞吐——mix kernel 最常见瓶颈）。**三通道各自独立建模，
+> 性能 = min(三 ceiling)，瓶颈 = 限制项。**
+
+## 2 GQA 多头合并：mEff
+
+FA 类 Mmad 的有效 m 维不是 Bq 本身：
+
+```
+mEff = Bq × curG
+```
+
+curG = 同一 kvHead 下合并到一个 task 的 qHead 数（≤ G = Hq/Hkv）。
+
+- **Prefill**（Sq 大）：Bq 够大，mEff 主要受 L0A 容量约束，curG 可能 < G
+- **Decode**（Sq=1）：Bq=1，`mEff = curG`，应最大化 curG = G
+
+**mEff 是 FA Roofline 的核心自变量**——同时决定 AI 与三通道相对松紧。
+（GQA 合并本身是不变量 I2：同 kvHead 的 G 个 qHead 必须同 task，禁止拆 G 个
+task 各自重复搬 KV——KV 重复搬运 G 次，MTE2/L1 利用率塌陷。）
+
+## 3 三通道模型
+
+### 3.1 通道 2：HBM（主 Roofline）
+
+单 task 遍历全 Sk 的流量与算量：
+
+```
+FLOPs_total = 4 × mEff × Sk × D          # C1 与 C2 两个 GEMM
+Bytes_HBM ≈ 2 × Sk × D × sizeof(T)       # K/V 加载（主导，Sk ≫ mEff 时）
+             + 2 × mEff × D × sizeof(acc) × (Sk/Bk)   # O_acc streaming（仅 streaming 模式）
+
+AI_HBM ≈ 2·mEff / sizeof(T)              # 忽略 streaming 项的清晰上界
+ridge_HBM = Peak_CUBE_FLOPS / Peak_HBM_BW
+AI_HBM < ridge_HBM → HBM-bound 可能
+```
+
+（峰值参数从 soc-spec.yaml 取，不硬编码。）
+
+**关键结论**：
+- **AI_HBM ∝ mEff**（不封顶在 D/sizeof(T)）；
+- **Decode（mEff=G）的 AI ∝ G**——GQA group 合并是提升 decode AI 的唯一杠杆；
+- **Bk 经 O_acc streaming 项影响 AI**：streaming 模式增大 Bk 减少 O_acc 往返
+  （Sk/Bk 次）；非 streaming（O_acc 驻 UB）Bk 对 AI 无直接影响。
+
+**causal 的影响不在 AI**：完全 mask 的 tile 被跳过，FLOPs 与 K/V 加载**同比例
+减少**（平均有效 KV ≈ Sk/2），Sk 在 AI 推导中约掉 → AI ≈ 不变。causal 真正
+影响**绝对耗时与核间负载均衡**（见 mixed_kernel 文档 §多核切分）。
+
+### 3.2 通道 3：跨核/片上吞吐（AIV-bound 校核）
+
+若 AIV 端吞吐 < AIC 端，即使 HBM 与 Cube 都不饱和，算子仍被 AIV 拖住。
+
+```
+T_AIC(tile) ≈ FLOPs(tile) / (Peak_CUBE × cube_util)
+T_AIV(tile) ≈ softmax_ops(mEff·Bk) / AIV_vector_throughput
+              + onchip_bytes(mEff·Bk + mEff·D) / Peak_onchip_BW
+
+cross-core-bound ⟺ T_AIV > T_AIC
+```
+
+AIV 端每 tile 工作量：softmax over `[mEff, Bk]`（ReduceMax/Exp/ReduceSum ∝
+mEff·Bk）+ 片上握手 movement（S: L0C→UB `mEff×Bk`；P: UB→L1 `mEff×Bk`；
+PV: L0C→UB `mEff×D`——不占 HBM，占片上 SRAM 带宽）。
+
+**主杠杆**：提 AIC:AIV 比（`__mix__(1,2)` → 更多 AIV）；减握手粒度、
+per-stage 同步、双缓冲让 AIC/AIV 重叠；减 PipeBarrier 冗余（<30%）。
+
+### 3.3 通道 1：Cube 算力
+
+```
+Perf_compute = Peak_CUBE_FLOPS × cube_util
+```
+
+cube_util 主要由 Mmad m/n/k 对齐到 16 的倍数决定。
+
+### 3.4 三通道取 min
+
+| 区制 | 判据 | 主杠杆 |
+|------|------|--------|
+| Compute-bound | AI_HBM ≥ ridge 且 AIC 吞吐最低 | Mmad 对齐、Cube/Vector 重叠、减 PipeBarrier |
+| HBM-bound | AI_HBM < ridge 且 HBM 吞吐最低 | 增大 mEff（∝AI）、Q 驻 L1、增大 Bk 减 O_acc 往返 |
+| Cross-core-bound | T_AIV > T_AIC | 提 AIC:AIV 比、减握手粒度、双缓冲、减 PipeBarrier |
+
+常见 D 档位、mEff 较小时通常先撞 **HBM-bound 或 cross-core-bound**；增大 mEff
+提升 AI 后可能转入 compute-bound 或 cross-core-bound。
+
+## 4 基本块选取要点（推导，不照抄）
+
+- **K_BASE 尽量取到 D**（L0A/L0B 容量允许时）：`K_BASE = D` 单次 k-pass 完成
+  Mmad；K_BASE 越小 k-pass 次数越多，每次带 SetFlag/WaitFlag/PipeBarrier 同步
+  开销——**选 K_BASE 必须代入 k-pass 次数评估同步开销**；
+- **M_BASE / N 轴步进**：L1/L0 单槽容量约束下取尽量大（减分块循环次数），
+  上界由容量校验公式给出（运行时 `GetCoreMemSize` 查询，禁硬编码）；
+- 初始试验值：`K_BASE=D`、M/N 步进取容量允许的最大 16 倍数，按实测调整；
+- **Bk**：streaming UB 模式下优先增大（减 O_acc 往返）；受 softmax 状态 buffer
+  与握手 slot 容量约束。
+
+## 5 量化 FA 的 AI 修正（MX 类）
+
+MX 类（mxfp8/mxfp4）块量化格式 scale 必须沿被消费 matmul 的 **reduction
+（K-mmad）轴**量化（硬件硬约束："data must be consecutive over the reduction
+dimension"）：
+
+| 张量 | 被消费 matmul | K-mmad 轴 | scale 量化轴 |
+|------|-------------|----------|------------|
+| Q | Q·Kᵀ | D | D |
+| K | Q·Kᵀ | D | D |
+| P（kernel 内构造） | P·V | S_k | S_k |
+| V | P·V | S_k | **S_k（不是 BSND innermost 的 D！）** |
+
+**反直觉陷阱**：V 在 BSND `[B, Sk, Hkv, D]` 下 D 是 innermost 连续维度，按
+「沿连续维度量化」直觉会得 V scale 沿 D——与 PV Mmad 的 K-mmad=S_k 不兼容，
+业界标准沿 S_k。**违反后果：Mmad ScaleB 轴错位 → 输出 NaN/inf**（直接非数，
+不是漂移）。
+
+## 6 与本仓工具链的联动
+
+- 三通道的 Peak 参数：`ops-verdict/references/soc-spec.yaml`（逐字段溯源）；
+- 上板后区制验证：verdict 命中规则 ↔ 区制对照表见 [guide.md](guide.md)；
+  `mte2_active_bw_pct_of_peak`（facts_bridge 产出）直接服务 HBM 通道判定；
+  overlap_pct（trace_bubble 产出，需 A5 PipeTimeline/仿真）服务 cross-core
+  通道判定；
+- 候选参数探索：容量约束消费 soc-spec（与 tiling_candidates.py 同款容量
+  预算思路，FA 专用基本块推导按本文 §4）。

package/skills/asc-tools/tool-ops-tune/ops-family/references/fa/guide.md

@@ -0,0 +1,87 @@
+# FA 族指南（guide）——FlashAttention 类算子调优入口
+
+> **来源（蒸馏）**：内容整理自 Ascend C Tiling 设计方法论·FlashAttention 分册
+> 四层方法论（patterns / foundation / design / subfamilies，约 2000 行）+
+> 业界 Attention 设计实践（CATLASS 路径与标杆
+> 对齐）——台账残留项的先期知识就位（真实 FA 工程接入时方法论文档已可用，
+> 实战案例仍按无同型降级策略沉淀）。
+
+## 族特点
+
+FA（FlashAttention）类 = 分块化、不显式实例化 attention score 矩阵的 attention
+计算族：Q/K/V 三输入，计算图 **Q·Kᵀ → softmax → ·V** 两段 GEMM + 中间 online
+softmax（FA-2），沿 KV 维度分块流式累积，不在显存构建完整 `[Sq, Sk]` 矩阵。
+
+**与其它族的本质差异**（决定不能套用 reduction/elementwise/matmul 模式）：
+
+| 维度 | FA 类 | 其它族 |
+|------|------|--------|
+| Kernel 类型 | `__mix__(N, M)` AIC+AIV 协同（典型 `__mix__(1,2)`） | 多数纯 vector / 纯 cube |
+| 计算流 | 跨核 stage 化（Cube 算 GEMM，Vector 算 softmax） | 单核内完成 |
+| 跨 KV 分块状态 | 必须在线 softmax 累积（max/sum/O_acc） | 多数无在线状态 |
+| 任务维度 | s2（KV 分块）**禁入**任务分发维度 | 多数所有维度可分发 |
+
+**禁止**：`__vector__`（AIV_ONLY）做 FA 类——纯 Vector 实现 GEMM 性能比 Cube 低
+10-100×；仅 MVP 调试阶段可临时做精度基线。
+
+## 判定规则映射（verdict 命中 → 本族机制）
+
+FA 是 mix kernel，瓶颈形态跨 L1/L2/L3 三层，本仓 verdict 的消费方式：
+
+| verdict 命中 | FA 场景解读 | 深入文档 |
+|-------------|------------|---------|
+| L1_MTE2_BOUND（真饱和） | K/V 加载带宽主导（HBM-bound 区制） | [fa_roofline_design.md](fa_roofline_design.md)（增大 mEff 提升 AI） |
+| L1_LATENCY_SYNC_SUSPECT / 串行指纹 | AIC/AIV 握手未流水化（cross-core-bound 前兆） | [fa_mixed_kernel_design.md](fa_mixed_kernel_design.md)（流水编排） |
+| L1_VEC_BOUND | AIV softmax 吞吐主导（cross-core-bound） | 同上（提 AIC:AIV 比 / 减握手粒度） |
+| L1_CUBE_BOUND | Mmad 对齐/利用率问题（compute-bound） | fa_roofline（Mmad 对齐杠杆） |
+| L2_UNDERUTILIZATION / CORE_TAIL | causal 负载不均 / task 维度构造问题 | fa_mixed_kernel（多核切分与均衡） |
+
+> 注意：L3 MC² 规则不适用于单卡 FA；多卡 FA（sequence parallel）按 MC² 场景
+> 单独判定。**片上跨核握手不是 MTE2 带宽**——roofline 三通道模型见专文，
+> 禁止把握手流量混进 HBM AI 分母。
+
+## 调优路由（按性能区制）
+
+三通道 Roofline 判定（[fa_roofline_design.md](fa_roofline_design.md)）出区制后：
+
+| 区制 | 主杠杆 |
+|------|--------|
+| HBM-bound | 增大 mEff（∝AI）；Q 驻 L1；增大 Bk 减少 O_acc streaming 往返 |
+| Compute-bound | Mmad m/n/k 对齐 16；Cube/Vector 重叠；减 PipeBarrier |
+| Cross-core-bound | 提 AIC:AIV 比（如 `__mix__(1,2)`→更多 AIV）；per-stage 同步；双缓冲重叠；减 PipeBarrier |
+
+## 标杆对齐（对照业界 Attention 设计实践）
+
+| 标杆 | 位置 | 用途 |
+|------|------|------|
+| `aclnnFlashAttentionScore` | CANN op_api 文档 | 底层标杆：语义/dtype/layout/scale/mask 权威 |
+| `torch_npu.npu_fusion_attention` | torch_npu op-plugin | Python 标杆：可直接 NPU 实测对比 |
+
+关键映射陷阱（蒸馏）：
+- **seqlen 约定不同**：npu 标杆 `actual_seq_qlen/kvlen` 是**累加和**，内核常为
+  per-batch 原始长度——host 必须做差分转换；
+- **mask 语义**：`atten_mask 1=不参与`；causal（sparse_mode 2/3）须压缩下三角
+  `[2048,2048]` 否则 tiling 报 161001；
+- **scale**：默认 `1/√D`；标杆传自定义 scale 时 host 须覆盖 TilingData；
+- dropout/pse/sink/inner_precise 等字段不在前向调优范围，静默继承 = 语义错误。
+
+## 文档结构
+
+| 文档 | 内容 |
+|------|------|
+| 本 guide | 族定位 / 判定映射 / 调优路由 / 标杆对齐 |
+| [fa_roofline_design.md](fa_roofline_design.md) | 三通道 Roofline（mEff/AI 推导 / 区制判定 / causal 与量化修正） |
+| [fa_mixed_kernel_design.md](fa_mixed_kernel_design.md) | mix kernel 设计（数据流四阶段 / 不变量 I1-I5 / 流水编排 / 跨核同步 / softmax 实现陷阱） |
+
+## 模板状态（如实标注）
+
+本族**无可拷贝代码模板**（模板数 0）——Ascend C 路径无完整 FA 参考实现
+（asc-devkit 仅有 mix 融合示例 + SoftmaxFlashV2 building block 可作基线验证）；
+CATLASS 路径的整经验证核函数（`FAInferKernel`）在 参考实现 工程资产内，
+不在本仓。实施时按 [fa_mixed_kernel_design.md](fa_mixed_kernel_design.md) 的
+设计节点推进 + 无同型降级策略（验证强度↑）。
+
+## 知识缺口
+
+实战案例（E 级）待首个真实 FA 工程接入后沉淀：发现本 guide 未覆盖场景 →
+`ops-mechanism/scripts/log_gap.py --family fa --kind family_missing --note "<场景>"`。

package/skills/asc-tools/tool-ops-tune/ops-family/references/knowledge_gaps.json

@@ -0,0 +1,56 @@
+{
+  "schema": "opstune.knowledge-gaps/1.0",
+  "description": "ops-family 知识缺口计数落盘（SKILL.md 承诺的「未收录返回并计数上报」的载体）。Agent/人工在路由时发现族未收录/族内文档为骨架时追加 gap 条目；每季度由缺口感知回路（27-4）读取排产。",
+  "gaps": [
+    {
+      "family": "fa",
+      "kind": "family_missing",
+      "note": "FlashAttention 族无专项文档（SKILL.md 已标 ❌ 已知缺口）。部分解决（2026-10-15）：方法论三篇已蒸馏（guide/roofline/mix-kernel，源自 参考实现 四层方法论）——设计参考就位；货架代码与 E 级实战案例仍缺（无同型降级策略执行中）",
+      "first_seen": "2026-10-14",
+      "count": 0,
+      "resolved": "partial",
+      "resolved_at": "2026-10-15"
+    },
+    {
+      "family": "elementwise",
+      "kind": "guide_missing",
+      "note": "无 guide.md（仅 index + 2 篇设计文档），模板数为 0。已解决（2026-10-15）：guide.md 路由层已补，模板货架已补（templates/add_custom 可裁剪工程模板 ×5，源自 Kernel 直调工程模板）",
+      "first_seen": "2026-10-14",
+      "resolved": true,
+      "resolved_at": "2026-10-15",
+      "count": 0
+    },
+    {
+      "family": "sort",
+      "kind": "guide_skeleton",
+      "note": "guide 4 行；radix_sort.md 实质。已解决（2026-10-15）：guide 蒸馏为 M-way 归并三 Pattern 决策树 + Pattern C 四阶段架构（源自 Ascend C Tiling 设计方法论·sort 分册）",
+      "first_seen": "2026-10-14",
+      "count": 0,
+      "resolved": true,
+      "resolved_at": "2026-10-15"
+    },
+    {
+      "family": "simt",
+      "kind": "guide_skeleton",
+      "note": "guide 4 行；optimization-guide 实质。已解决（2026-10-15）：guide 蒸馏为 VF 三件套范式 + 共享内存/多核同步 + verdict 映射（源自 参考实现 13 篇）",
+      "first_seen": "2026-10-14",
+      "count": 0,
+      "resolved": true,
+      "resolved_at": "2026-10-15"
+    },
+    {
+      "family": "matmul",
+      "kind": "no_shelf_code",
+      "note": "六策略均为设计文档，无可拷贝模板（族表已改标「设计参考（无货架代码）」）",
+      "first_seen": "2026-10-14",
+      "count": 0
+    },
+    {
+      "family": "mc2",
+      "kind": "no_shelf_code",
+      "note": "3 策略均为设计文档，无可拷贝模板（族表已改标「设计参考（无货架代码）」）",
+      "first_seen": "2026-10-14",
+      "count": 0
+    }
+  ]
+}

package/skills/asc-tools/tool-ops-tune/ops-family/references/matmul/best-practices-guide.md

@@ -0,0 +1,14 @@
+# MatMul 类算子性能优化策略索引
+
+按策略类型查找对应的适用场景与详细设计文档。
+
+适用于 `matmul` 族所有变体：`matmul`、`matmul_mxfp4`、`matmul_a16w16`、`batch_matmul`、`matmul_all_reduce` 等。
+
+| 策略 | 适用场景 | 核心手段 | 详细文档 |
+|------|---------|---------|---------|
+| **pingpong** | 所有 matmul（基线，其它优化的默认前置） | L1/L0 双缓冲 + MTE2/MTE1/Fixpipe 事件同步流水化；`L1_BUFFER_NUM` 取满足 L1 预算的最大整数 | [pingpong_design.md](pingpong_design.md) |
+| **swat** | MN 够并行（`totalBlockCnt > aicNum` 数倍）但存在尾碎片负载不均 | 机制 A Serpentine 行窗口（B 侧复用 + 流式带宽）/ 机制 B 尾块合并 / 机制 C 末轮二维再切分 | [swat_design.md](swat_design.md) |
+| **streamk** | MN 欠并行（`totalBlockCnt < aicNum`）+ 长 K（≥ 2048），或 baseM/N 已到 CUBE 粒度下限的 MN 不整除情形 | SK / DP+SK 两子模式：切 K 到空闲核，AIV 从 workspace 归约 | [streamk_design.md](streamk_design.md) |
+| **fullload**（A-Full-Load / B-Full-Load） | 有"小侧矩阵"（一侧 ≤ L1/2）+ 对侧循环次数 `T ≥ 2` + 真 MTE2 bound | 小侧矩阵 + 随路 Scale 一次性驻留 L1，消除对侧循环中的重复 GM→L1 搬运 | [fullload_design.md](fullload_design.md) |
+| **scale_coalescing** | 假 MTE2 bound（MTE2 busy 高但带宽利用率 < 70%）+ 存在 < 20 KB 的 scale / bias / LUT 小块 | `scaleKL1 = SCALE_L1_BUFFER_NUM × kL1`，把 K 向 `baseK` 切碎的小块合并成一次大 MTE2 | [scale_coalescing_design.md](scale_coalescing_design.md) |
+| **mte2_preload** | pingpong 已开 + 各流水 busy ≤ 70%（准无 bound）+ 流水图可见 MTE2_PING/PONG 间 gap + `kL1TileNum ≥ 2` | Kernel 主循环改造为「段 1 首轮 PING / 段 2 预取 PONG / 段 3 消费」三段结构；零 TilingData 数值改动 | [mte2_preload_design.md](mte2_preload_design.md) |

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

@@ -0,0 +1,344 @@
+# matmul 减少重复载入（A-Full-Load / B-Full-Load）优化设计
+
+## 1. 优化目标
+
+针对 matmul 族（含量化变体 `matmul_mxfp4`、`matmul_mxfp8` 等）在 **"一侧矩阵小 + 对侧循环次数 ≥ 2"** 场景下的 **真 MTE2 bound**：把**小侧矩阵（A 或 B，含随路 Scale）从"每轮流式搬入"改为"一次性驻留 L1"**，消除小侧矩阵在对侧循环中的重复 GM→L1 搬运，等效把 MTE2 总字节数压缩 `(T-1)/T`（`T` 为对侧循环次数）。
+
+典型收益：`T = 5` 时 MTE2 总字节下降约 **16%–20%**，Task 总时间下降 **5%–15%**（对应 matmul MXFP4 `M=128, K=4096, N=81920` 实测 `183.87μs → 170.07μs`，约 **−7.5%**）。
+
+> **驻留层定位**：A-Full-Load / B-Full-Load 位于 **分支层（SWAT ↔ StreamK）之下、增强层（小数据块合并载入）之上** 的**驻留层**选型。与 StreamK 互斥；可与 SWAT 机制 A/B/C、pingpong 双缓冲、小数据块合并载入**叠加**。
+
+---
+
+## 2. 架构概览
+
+### 2.1 未优化路径（每 `kL1` 轮都重复搬 A / B）
+
+以 A-Full-Load 的反例为例（B-Full-Load 对称），单核在 N 方向有 `T = N_{pc} / baseN` 轮对侧循环：
+
+```
+for n_iter in range(T):                       # N 向外层（对侧循环）
+    for iter0 in range(kL1Iter):              # K 向内层
+        MTE2: GM → L1 A[baseM, kL1]   ~ 32 KB  ✔ 够大，但被重复搬 T 次
+        MTE2: GM → L1 B[kL1, baseN]   ~ 32 KB  ✔ 够大，每轮内容不同
+        MTE2: GM → L1 scaleA[kL1]     ~  2 KB  ✘ 小且重复 T 次
+        MTE2: GM → L1 scaleB[kL1]     ~  2 KB  ✘ 小，每轮内容不同
+        MTE1: L1 → L0 + CUBE
+```
+
+**冗余量**：A 与 scaleA 每轮都搬，`T − 1` 份是完全冗余的字节流。当 `baseM × K × dtype_A ≤ L1/2` 时物理上可以"一次性装入 L1 再复用 T 次"。
+
+### 2.2 优化路径（A-Full-Load：A + scaleA 一次性驻留 L1）
+
+```
+# 初始化阶段（n_iter=0, iter0=0）
+MTE2: GM → L1 A[baseM, K_full]           # 一次性搬全量 A（驻留）
+MTE2: GM → L1 scaleA[baseM, K_full/32]   # 一次性搬全量 scaleA（驻留）
+
+for n_iter in range(T):
+    for iter0 in range(kL1Iter):
+        # A 已驻留 L1，跳过搬运
+        MTE2: GM → L1 B[kL1, baseN]      # 每轮搬（不变）
+        MTE2: GM → L1 scaleB[kL1]        # 每轮搬（不变；若同时叠加合并载入则合并）
+        MTE1: L1 → L0                    # A 侧按 iter0 × kL1 偏移切片取
+        CUBE
+```
+
+B-Full-Load 为对称情形：B 与 scaleB 一次驻留，A 与 scaleA 每轮流式搬入。
+
+### 2.3 L1 布局（A-Full-Load，与 pingpong 布局解耦）
+
+```
+L1 地址空间 (L1_SIZE = 524 KB)  ← 以 A-Full-Load 为例
+┌───────────────────────────────────────────────────────────────────────────────┐
+│ B_ping │ B_pong │ scaleB_ping │ scaleB_pong │ A_full │ scaleA_full │ (reserved)│
+│ (kL1)  │ (kL1)  │ (scaleKL1)  │ (scaleKL1)  │ (fullK)│  (fullK/32) │           │
+└───────────────────────────────────────────────────────────────────────────────┘
+   ↑                                             ↑
+B 侧每 iter0 轮换                       A 侧全量驻留（只在 n_iter=0, iter0=0 搬一次）
+```
+
+关键点：
+- A 的 L1 区长度为 `baseM × Align(K, c0) × sizeof(dtype_A)`（A 全量占位）
+- scaleA 的 L1 区长度为 `baseM × CeilDiv(K, 32) × sizeof(dtype_scale)`
+- B 侧仍保留 pingpong（`bL1OneBuffer × l1BufNum`）与 B scale 双缓冲（`scaleBL1OneBuffer × SCALE_BUFFER_NUM`）
+- A 侧只需 1 份（驻留期间不覆盖，无需 pingpong）
+
+A-Full-Load 的 L1 偏移计算核心语句：
+
+```cpp
+// A-Full-Load：A 一份驻留；B 仍 pingpong
+aL1OneBuffer_ = (mAlign * kAlign) >> 1;                                              // 全量 A
+scaleAL1OneBuffer_ = baseM_ * CeilDiv(k_, MXFP_DIVISOR_SIZE_LOCAL) * MXFP_MULTI_BASE_SIZE_LOCAL;
+l1BufferAOffset_[0] = bL1OneBuffer_ * (l1BufNum_ >> 1) + scaleBL1OneBuffer_;          // A 在 B pingpong 之后
+l1BufferScaleAOffset_[0] = l1BufferAOffset_[0] + aL1OneBuffer_;                       // scaleA 紧跟 A
+```
+
+### 2.4 事件同步模型（A-Full-Load）
+
+在 pingpong 事件模型（`pingpong_design.md` §2.3）基础上：
+
+| 事件类型 | A-Full-Load 下的用途 |
+|---------|---------------------|
+| `MTE1_MTE2(l1BufId)`（B 的 L1 pingpong 事件） | B / scaleB 仍逐轮 pingpong 释放 |
+| `MTE1_MTE2(SCALE_BUFFER_FLAG_0/1)`（scaleB 独立 pingpong） | scaleB 的 pingpong 周期不变 |
+| **A 侧 pingpong 事件** | **取消**：A 全量驻留，整个 `operator()` 生命周期内不覆盖，不需要 MTE1→MTE2 释放事件；首次 MTE2 完成后仅需 `MTE2→MTE1` 就绪信号，后续每轮直接读 |
+
+关键约束：**A / scaleA 的 MTE2 只在 `abL1LoopCnt_ == 0`（即本次 `operator()` 的第一轮）发**，后续 `T × kL1Iter` 次内层循环都**跳过 A / scaleA 的 MTE2**，直接从驻留的 L1 区按 `iter0 × kL1` 偏移取数进 L0。
+
+---
+
+## 3. 关键参数配置
+
+```cpp
+constexpr uint32_t BASE_M         = 128;     // A-Full-Load：通常 baseM 较小
+constexpr uint32_t BASE_N         = 512;
+constexpr uint32_t BASE_K         = 128;
+constexpr uint32_t PINGPONG_NUM   = 2;       // B 的 L1 pingpong 仍为 2
+constexpr uint32_t L1_BUFFER_NUM  = 2;       // B 的 K 覆盖倍数（沿用 pingpong）
+constexpr uint32_t M_TAIL_TILE    = 1;       // *** 本优化强约束 *** A 全载下 M 尾禁止再切
+constexpr uint32_t N_TAIL_TILE    = 1;       // 与 M_TAIL_TILE 对称，若叠加 SWAT 机制 C 可放开
+
+// Host Tiling
+params.l1Params.kL1       = BASE_K * L1_BUFFER_NUM;
+params.l1Params.scaleKL1  = BASE_K * L1_BUFFER_NUM;    // 与 B 侧 scale 保持对齐；若叠加合并载入则改为 SCALE_L1_BUFFER_NUM × BASE_K
+params.l1Params.l1BufNum  = PINGPONG_NUM;
+params.schParams.mTailTile = M_TAIL_TILE;               // A-Full-Load 强制 1
+params.schParams.nTailTile = N_TAIL_TILE;
+```
+
+### 3.1 必选开关字段（Host→Device）
+
+| 字段 | A-Full-Load | B-Full-Load | SWAT 基线 | 作用 |
+|------|-------------|-------------|-----------|------|
+| `isAFullLoad` | **true** | false | false | Kernel 侧据此选择 `BlockMmadMxAFullLoad` 模板 |
+| `isBFullLoad` | false | **true** | false | Kernel 侧据此选择 `BlockMmadMxBFullLoad` 模板（对称扩展） |
+| `stepKa` | `CeilDiv(K, baseK)` | 由剩余 L1 反推 | 2 的幂 ≤ 4 | A 全载下 A 侧一次覆盖全 K |
+| `stepKb` | 由剩余 L1 反推 | `CeilDiv(K, baseK)` | 2 的幂 ≤ 4 | 对称 |
+| `scaleFactorA` | 1 | 由剩余 L1 反推 | 由 `_cal_scale_factors` 搜索 | scaleA 是否一次全载 |
+| `scaleFactorB` | 由剩余 L1 反推 | 1 | 同上 | scaleB 是否一次全载 |
+| `mTailTile` | **1** | SWAT 基线值 | 由 `_calc_tail_basic_block` 搜索 | A 全载禁止 M 尾再切，避免重新引入重复搬运 |
+| `nTailTile` | SWAT 基线值 | **1** | 同上 | 对称 |
+
+> **强校验**：`isAFullLoad` 与 `isBFullLoad` **互斥**，同时为 true 属 Tiling 错误；Kernel 侧应 static_assert 或运行期检查。
+
+### 3.2 L1 预算不等式（A-Full-Load，硬约束）
+
+$$
+\underbrace{\mathrm{baseM} \cdot \mathrm{Align}(K, c_0) \cdot |\mathrm{dtype}_A|}_{A\ \text{全载驻留}}
+\;+\;
+\underbrace{\mathrm{baseM} \cdot \mathrm{CeilDiv}(K, 32) \cdot |\mathrm{dtype}_{scale}|}_{scaleA\ \text{全载驻留}}
+\;+\;
+\underbrace{(\mathrm{baseN} \cdot \mathrm{kL1} \cdot |\mathrm{dtype}_B|) \cdot l1BufNum}_{B\ \text{流式} + pingpong}
+\;+\;
+\underbrace{\mathrm{baseN} \cdot \mathrm{CeilDiv}(\mathrm{scaleKL1}, 32) \cdot 2}_{scaleB\ pingpong}
+\;\le\; L_1\ (524288\ B)
+$$
+
+溢出时按 `stepKb` 从大到小收缩（`_get_depth_b1_a_full_load`）；收缩到 `stepKb=1` 仍溢出 → 本优化不可用，回退 SWAT。
+
+B-Full-Load 对称：把 A/B、baseM/baseN、dtype_A/dtype_B 同步镜像。
+
+---
+
+## 4. 关键代码实施点
+
+本节给出从 SWAT / 小数据块合并载入基线演进到 A-Full-Load 需要改的**六处**，涉及 Host launcher 与 `BlockMmad` 模板两个文件：
+
+### 4.1 Host launcher：选择 A-Full-Load 版本的 BlockMmad 模板
+
+```cpp
+using BlockScheduler = Block::QuantMatmulMxLastRoundTileBalanceScheduler;
+// 核心切换：用 A-Full-Load 版本的 BlockMmad
+using BlockMmadT = Block::BlockMmadMxAFullLoad<AType, BType, CType>;
+using QuantMatmulKernelImpl = Kernel::QuantMatmulMxKernelBaseImpl<ProblemShape, BlockMmadT, BlockScheduler>;
+
+// Tiling 参数：M_TAIL_TILE / N_TAIL_TILE 强制 1（见 §3.1）
+constexpr uint32_t M_TAIL_TILE = 1;
+constexpr uint32_t N_TAIL_TILE = 1;
+params.schParams.mTailTile = M_TAIL_TILE;
+params.schParams.nTailTile = N_TAIL_TILE;
+```
+
+B-Full-Load：把 `BlockMmadMxAFullLoad` 替换为 `BlockMmadMxBFullLoad`（当前 tutorial 未提供，按 §3.4 对称实现），`mTailTile / nTailTile` 互换。
+
+### 4.2 BlockMmad::Init：按全载大小重算 L1 偏移
+
+```cpp
+// 以 A-Full-Load 为例：BlockMmad::Init
+uint64_t mAlign = Align(baseM_, BLOCK_CUBE);
+uint64_t kAlign = Align(k_, MXFP_DIVISOR_SIZE_LOCAL);
+aL1OneBuffer_      = (mAlign * kAlign) >> 1;                                               // A 全量驻留
+scaleAL1OneBuffer_ = baseM_ * CeilDiv(k_, MXFP_DIVISOR_SIZE_LOCAL) * MXFP_MULTI_BASE_SIZE_LOCAL;
+bL1OneBuffer_      = (baseN_ * kL1_) >> 1;                                                 // B 仍按 kL1 流式
+scaleBL1OneBuffer_ = baseN_ * CeilDiv(kL1_, MXFP_DIVISOR_SIZE_LOCAL) * MXFP_MULTI_BASE_SIZE_LOCAL;
+
+// L1 布局：B pingpong → scaleB pingpong → A 驻留 → scaleA 驻留
+l1BufferAOffset_[0] = bL1OneBuffer_ * (l1BufNum_ >> 1) + scaleBL1OneBuffer_;
+l1BufferScaleAOffset_[0] = l1BufferAOffset_[0] + aL1OneBuffer_;
+for (int32_t bufferId = 0; bufferId < l1BufNum_; bufferId++) {
+    l1BufferBOffset_[bufferId] = bL1OneBuffer_ * (bufferId >> 1);
+}
+for (int32_t bufferId = 0; bufferId < SCALE_BUFFER_NUM; bufferId++) {
+    l1BufferScaleBOffset_[bufferId] = l1BufferBOffset_[bufferId] + bL1OneBuffer_ * (l1BufNum_ >> 1);
+}
+```
+
+### 4.3 BlockMmad::operator()：A / scaleA 仅在首轮搬运
+
+```cpp
+// A-Full-Load：BlockMmad::operator() 主循环
+for (uint64_t iter0 = 0; iter0 < kL1Iter_; ++iter0) {
+    // B 每轮搬（不变）
+    AscendC::Te::Copy(copyGM2L1, tensorBL1, gmBlockB);
+    AscendC::Te::Copy(CopyScaleGM2L1, tensorScaleBL1Buf, gmBlockScaleB);
+
+    // *** A / scaleA 只在第一轮搬 ***
+    if (abL1LoopCnt_ < kL1Iter_) {     // 等价于 abL1LoopCnt_ == iter0，首轮覆盖全 K
+        auto gmBlockA = gmA(AscendC::Te::MakeCoord(0, kL1Offset),
+                            AscendC::Te::MakeShape(curM, curGmAKL1));
+        AscendC::Te::Copy(copyGM2L1, tensorBlockAL1, gmBlockA);
+    }
+    if (abL1LoopCnt_ == 0) {           // scaleA 只在首轮搬一次全量
+        auto gmBlockScaleA = gmScaleA(
+            AscendC::Te::MakeCoord(0, 0),
+            AscendC::Te::MakeShape(curM, CeilDiv(k_, MXFP_DIVISOR_SIZE_LOCAL) * MXFP_MULTI_BASE_SIZE_LOCAL));
+        AscendC::Te::Copy(CopyScaleGM2L1, tensorScaleAL1, gmBlockScaleA);
+    }
+
+    // IterateL0：A 侧从驻留的 tensorBlockAL1 切 kL0Offset 片给 L0
+    IterateL0(tensorBlockAL1, tensorBlockScaleAL1, tensorBL1, tensorBlockScaleBL1,
+              curM, curN, curGmBKL1, curPadKL1, iter0, tensorL0C);
+
+    abL1LoopCnt_++;
+}
+```
+
+**关键点**：
+- `abL1LoopCnt_` 跨 `operator()` 调用不重置（类成员），所以只有整个 kernel 生命周期的首次调用才发 `scaleA` MTE2；A 每次 `operator()` 在首个 K 段仍会搬一次（但本次 `operator()` 内不再重复）
+- B-Full-Load 对称：`abL1LoopCnt_` 约束改为"B 在首个 K 段搬一次，scaleB 跨生命周期只搬一次"
+
+### 4.4 scaleA 从全量 L1 驻留区按 iter0 切片取 L0
+
+```cpp
+auto tensorBlockScaleAL1 = tensorScaleAL1(
+    AscendC::Te::MakeCoord(0, iter0 * CeilDiv(kL1_, MXFP_DIVISOR_SIZE_LOCAL) * MXFP_MULTI_BASE_SIZE_LOCAL),
+    AscendC::Te::MakeShape(curM, CeilDiv(kL1_, MXFP_DIVISOR_SIZE_LOCAL) * MXFP_MULTI_BASE_SIZE_LOCAL));
+```
+
+**漏加 `iter0 × CeilDiv(kL1_, 32) × 2` 偏移会导致精度错误**（所有 K 段使用同一段 scaleA 反量化）。与"小数据块合并载入"中 `scaleKL1IterOffset` 偏移机制同构。
+
+### 4.5 去掉 A 侧 pingpong 释放事件
+
+```cpp
+// 基线 SWAT：A 每轮都发
+AscendC::SetFlag<AscendC::HardEvent::MTE1_MTE2>(l1BufId);   // A 与 B 共用 l1BufId
+
+// A-Full-Load：只发 B 的释放事件；A 驻留期间不释放
+AscendC::SetFlag<AscendC::HardEvent::MTE1_MTE2>(l1BufId);           // B 侧（不变）
+AscendC::SetFlag<AscendC::HardEvent::MTE1_MTE2>(SCALE_BUFFER_FLAG_0 + scaleL1BufId);  // scaleB 侧（不变）
+// 不发 A/scaleA 的 MTE1→MTE2 释放（L1 驻留永不覆写）
+```
+
+**漏掉这一改动会导致 A 被错误覆写**（pingpong 事件仍在发，下一轮 MTE2 可能把 A 区写花）。
+
+### 4.6 CMakeLists.txt：新增 launcher 目标
+
+```cmake
+ascend_add_executable(matmul_tutorial_mxfp4_a_fullload
+    matmul_tutorial_mxfp4_a_fullload.cpp
+)
+```
+
+B-Full-Load 需新增 `BlockMmadMxBFullLoad` 模板 + `matmul_tutorial_mxfp4_b_fullload.cpp` launcher。
+
+---
+
+## 5. 适用场景与适用性校验
+
+### 5.1 典型 Shape 特征（由策略专家判定）
+
+| 维度 | 条件 | 说明 |
+|------|------|------|
+| 小侧容量 | `baseM × Align(K, c0) × dtype_A ≤ L1/2`（A 全载）；对称 B 全载 | L1 能装下，且预留 ≥ 1/2 L1 给对侧 pingpong |
+| 对侧循环次数 | `T = N_{pc} / baseN ≥ 2`（A 全载）；对称 B 全载 | T=1 时小侧本来就只搬 1 次，收益为 0 |
+| 多核排布 | A 全载：`mBlockCnt ≤ WINDOW_LEN(=4)` 且 `aicNum % mBlockCnt == 0` 且 `totalBlockCnt > aicNum` | 不然多核重复持有全载块、L1 浪费 |
+| MTE2 健康度 | 对侧流式 Bytes ≥ 20 KB（非"假 MTE2 bound"） | 小数据块密集场景需叠加合并载入，不可单用全载 |
+| 分支 | 未走 StreamK | StreamK 已把 K 切给多核，"全载"语义失效 |
+
+**典型场景举例**：
+
+| Shape (M, K, N) | 判定结果 | 理由 |
+|----|----|----|
+| `[128, 4096, 81920]` MXFP4, aicNum=32 | **A-Full-Load** | `baseM=128`，A 侧 256 KB 可驻 L1；`T_A = 81920/(32·512) = 5` |
+| `[81920, 4096, 128]` MXFP4, aicNum=32 | **B-Full-Load** | N=128 小，B 侧同上；`T_B = 5` |
+| `[1024, 4096, 1024]` MXFP4 | SWAT（不开全载） | 两侧都 2 MB > L1/2 |
+| `[128, 512, 81920]` MXFP4 | SWAT 或合并载入（不开全载） | A 侧仅 32 KB 确可驻，但 `kL1Iter = 512/(2·128) = 2` 偏少，叠加合并载入更稳妥 |
+
+### 5.2 不适用的情形（禁用条件）
+
+- 两侧矩阵都 `> L1/2` → 物理不可行
+- 对侧循环次数 `T = 1` → 小侧本来只搬 1 次，收益 = 0
+- 多核排布不满足 `mBlockCnt ≤ WINDOW_LEN + aicNum % mBlockCnt == 0` → 会造成多核重复驻留
+- CUBE bound 而非 MTE2 bound → 瓶颈不在搬运，全载反而可能拖慢（L1 分配不均）
+- **已启用 StreamK** → StreamK 切 K 分段，workspace 归约取代 L1 驻留
+
+### 5.3 与其他优化的关系
+
+| 叠加对象 | 兼容性 | 说明 |
+|---------|-------|------|
+| pingpong 双缓冲（`pingpong_design.md`） | ✅ **强兼容** | 全载只改小侧 L1 布局；对侧仍保留 pingpong |
+| SWAT 负载均衡（`swat_design.md`） | ✅ 兼容 | SWAT 改调度不动 K 方向 L1 分配；机制 C 下 `mTailTile/nTailTile` 会被全载强制为 1 |
+| 小数据块合并载入（`scale_coalescing_design.md`） | ✅ 兼容（**推荐叠加**） | 全载消除"小侧矩阵的重复搬运"，合并载入压缩"对侧 scale 的小数据块"；两者正交 |
+| StreamK（`streamk_design.md`） | ❌ **互斥** | StreamK 已把 K 切给多核独立累加，"驻留"语义失效 |
+
+**叠加顺序**：`分核（SWAT 或 StreamK）→ 全载（A/B-Full-Load）→ 合并载入（scale coalescing）`。
+
+---
+
+## 6. 常见问题与解决方案
+
+| 问题 | 现象 | 解决 |
+|------|------|------|
+| **精度错误（最常见）** | 输出 C 局部偏离 golden，尾部 K 段错得更严重 | 检查 §4.4 的 `tensorBlockScaleAL1` 切片偏移 `iter0 × CeilDiv(kL1_, 32) × 2` 是否正确；核对 A 侧 L0 拷贝的 `MakeCoord(0, kL0Offset)` 是否沿用 iter0 * kL1 + kL0Offset 相对驻留 buffer 的偏移 |
+| **L1 溢出** | 编译期或运行期 L1 overflow | 按 §3.2 L1 预算公式收缩 `stepKb`；收缩到 1 仍溢出 → 放弃全载，回 SWAT |
+| **A 数据被覆写** | 精度错误集中在 N 方向第 2 轮之后 | 检查 §4.5 A / scaleA 的 `SetFlag<MTE1_MTE2>` 是否正确去掉；检查 `abL1LoopCnt_` 是否跨 `operator()` 调用正确累加 |
+| **全载后性能反而劣化** | MTE2 时间下降有限甚至上升 | 检查 MTE2 子类型是否误判为"真 bound"（实际为"假 bound + 小数据块密集"，需叠加合并载入）；或 `T < 2` 导致全载无收益 |
+| **`mTailTile` 未强制 1** | A 全载 + `mTailTile=2`，M 尾重新被切为两段 | Host Tiling 层强制 `params.schParams.mTailTile = 1`（A 全载）/ `nTailTile = 1`（B 全载） |
+| **`isAFullLoad` 与 Kernel 模板不匹配** | Tiling 开 `isAFullLoad=true` 但 Kernel 仍实例化 `BlockMmadMxSwat` → A 仍每轮搬 | 按 §4.1 在 Host launcher 显式选择 `BlockMmadMxAFullLoad` 模板；或 Kernel 侧按 `isAFullLoad` 做 runtime 分派 |
+
+---
+
+## 7. 预期收益
+
+| 指标 | 优化前（SWAT 基线） | 优化后（A-Full-Load） | 变化 |
+|------|------|------|------|
+| A / scaleA MTE2 搬运次数（单核） | `T × kL1Iter` | `kL1Iter`（只首轮） | **÷ T** |
+| MTE2 总字节（单核） | `Bytes_total^{nl}` | `Bytes_total^{nl} − (T−1) × (Bytes_A + Bytes_scaleA)` | **下降 `(T−1)/T × Bytes_side / Bytes_total`** |
+| MTE2 段时间（`[128, 4096, 81920]` MXFP4） | — | — | **−7.5%** |
+| Task 总时间（同上） | 183.87 μs | 170.07 μs | **−7.5%** |
+| MTE2 带宽利用率 | `≥ 85%`（真 bound） | `≥ 85%`（仍高，但 MTE2 总 cycle 下降） | 基本持平 |
+
+典型收益区间：**5%–15% 端到端 Task 时间缩短**。`T` 越大（对侧 N / M 越长）、小侧 Bytes 占总 MTE2 字节比例越高时收益越大。
+
+---
+
+## 8. 泛化：不止 A 矩阵 —— 减少重复载入的一般化
+
+本优化的一般化原则是：**识别"跨循环内容不变"的数据流，将其从"每轮搬入"改为"一次驻留"**。除了 A/B 矩阵及随路 Scale，任何满足"容量 ≤ L1 可用空间 + 跨外层循环只读 + 跨外层循环内容一致"的数据都可套同一模板。
+
+| 场景 | 可驻留对象 | 驻留条件 | 收益来源 |
+|------|-------------|---------|---------|
+| 带 Scale 的量化 matmul（MXFP4/MXFP8） | A + scaleA（或 B + scaleB） | 见 §5.1 | 本文主体 |
+| matmul with bias（小 bias 向量） | bias N 或 M 向量 | `N × sizeof(bias_dtype) ≤ L1_REMAIN`，且 bias 在 K 向不变 | 1%–5%，次要 |
+| GroupMatmul / MoE 专家权重的 routing LUT | 每组的 expert-routing 表 | 单组 LUT < 1 KB 且跨组不变 | 2%–5%（LUT 访问频繁场景） |
+| Attention 的 mask / pos_embed | 共享 mask 小张量 | `mask_size < L1_REMAIN` 且跨 batch 不变 | 视 K 循环次数 |
+| DeepSeek-V3 / MLA 的持久化 KV 片段 | KV cache 的共享 head | 单 head 可驻 L1 且跨 query 头不变 | 5%–10% |
+
+**共用判定条件**：
+1. 容量：驻留数据 ≤ 可用 L1 空间（预留 ≥ 1/2 给流式对侧）
+2. 对侧循环：`T ≥ 2`
+3. 内容不变：跨外层循环只读或内容完全一致
+4. 分支：非 StreamK
+
+策略专家在输出方案时，**应按该算子实际的"可驻留侧"识别具体字段**，不要只按 A/B 矩阵模板照搬。