cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-ops-tune/ops-mechanism/references/optimize/ascendc-regbase-vf.md

@@ -0,0 +1,45 @@
+# 机制卡：RegBase / SIMD VF（A5 向量范式）
+
+> 对应判定规则：L1_VEC_BOUND（深度档：>80% 接近极限后的存量空间）、多步融合 Vector、
+> MemBase 已尽场景。仅 A5（dav-3510）；A2/A3 保留兼容分支，禁止下沉此路径。
+> 内容沉淀自 A5 RegBase/VF 与 SIMT 范式调优一线实践。
+> **DSL 适用域**：本卡实施细节以 **Ascend C** 为准；Triton / CATLASS / TileLang 的等价原语与实施差异见 [index.md 跨 DSL 原语对照表](index.md#跨-dsl-原语对照六原语--dsl)——跨 DSL 实施时以该表为路由、对应 DSL 专项文档为深度参考，不按本卡字面照搬。
+
+## 原理
+
+A5 的 RegBase 编程范式把数据驻留寄存器（RegTensor），以 SIMD VF（Vector Function）指令
+直接计算，绕开 UB 往返与队列同步。适用：多步短生命周期计算（量化/激活/归一化组合）、
+UB 带宽已成约束的 Vector 算子。
+
+## 适用前提
+
+- 目标 SoC = A5（编译目标 ascend950 / dav-3510）；A2/A3 必须保留原实现分支；
+- 多步计算间数据生命周期短（适合寄存器驻留）；
+- UB 预算紧张（寄存器驻留缓解 UB 压力）或 Vector 指令链长。
+
+## 关键结构（模板必须原样保留的部分）
+
+RegTensor / MaskReg / LoadAsFp32 / StoreFromFp32 等 MicroAPI VF 计算结构——
+**模板内这些结构禁止降级为高层 API**（模板拷贝纪律，见 ops-family）。
+
+## 编译修复顺序（MicroAPI 报错时，禁止直接降级）
+
+1. 命名空间别名（`namespace MicroAPI = Reg;`）
+2. API 签名适配（对照 `$ASCEND_HOME_PATH/.../reg_compute/` 实际头文件）
+3. include 路径修正
+4. 全部无效才降级**对应分支**，并在结果中列出尝试过的修复与失败原因
+
+## 验证与精度风险
+
+- 数值稳定性：VF 计算的舍入行为与高层 API 可能不同（如求逆 VF 化案例：须覆盖数值
+  稳定性验证）→ 精度用例含边界值/异常位型；
+- 判定证据复采：vec_ratio / vec_fp32_ratio 变化 + wall 收益（event 口径）。
+
+## 回滚
+
+编译修复三连无效且降级后无收益 / 精度位型失败 → revert 整个 VF 分支（保留兼容分支）。
+
+## 模板资产
+
+`ops-family:references/simt/optimization-guide.md`（SIMT 不规则读写）、
+`ops-family:references/elementwise/vector_efficiency_design.md`。

package/skills/asc-tools/tool-ops-tune/ops-mechanism/references/optimize/ascendc-tiling.md

@@ -0,0 +1,51 @@
+# 机制卡：Ascend C Tiling 优化（切分与多核负载）
+
+> 对应判定规则：L2_CORE_TAIL、L2_IMBALANCE_*、L2_UNDERUTILIZATION、L1_MTE2_BOUND
+>（tile 尺寸侧）。内容沉淀自 tiling 调优一线实践与各族理论建模沉淀。
+> **DSL 适用域**：本卡实施细节以 **Ascend C** 为准；Triton / CATLASS / TileLang 的等价原语与实施差异见 [index.md 跨 DSL 原语对照表](index.md#跨-dsl-原语对照六原语--dsl)——跨 DSL 实施时以该表为路由、对应 DSL 专项文档为深度参考，不按本卡字面照搬。
+
+## 机制清单
+
+| 场景 | 机制 | 说明 |
+|------|------|------|
+| 切核不足 | Block Dim 提升 | 「最低垂果实」：4 核→20 核案例利用率 10%→50%；但 Task <25us 时增核放大头开销，须权衡。**候选参数不再经验拍**：`ops-family/scripts/tiling_candidates.py` 按 soc-spec 容量约束产出候选表 + 逐候选容量占用 |
+| 核间长尾 | 尾块均衡 | 数据总量不整除核数时尾块分散到更多核（swat：蛇形行窗口 + 尾块合并 + 末轮二维再切分） |
+| 长尾持续 | block swat / 尾轮均衡 | 两簇检测（前后半段核均值差 ≥2%）提示 NUMA/L2 slice 偏斜时优先 |
+| 搬运次数多 | 增大 tile | mte2_instructions 过大时（与 UB 预算联动；候选表已附 UB 占用计算） |
+| MN 欠并行 | streamk（SK/DP+SK） | totalBlockCnt < aicNum + K 长：切 K 到空闲核，AIV 归约（matmul 族） |
+| 尾碎片不均 | swat | MN 够并行（>aicNum 数倍）但尾碎片负载不均 |
+
+> MC² 配平候选（四剪枝 + Top-N）的执行载体为 `mc2_search.py`。
+
+## Tiling 理论建模（多机制联动时的前置）
+
+卡间切分 ↔ 核间切分 ↔ 单核 Buffer 规划三层联动（跨层耦合）：改一个 baseM 同时影响
+通信粒度、核利用率、L1/L0 容量。多机制候选冲突时先做 tiling 建模再选单变量——
+
+```
+Step1 输出：卡间切分 / 多核切分 / 单核切分（Cube: L1+L0 split；Vec: UB split）
+        / Buffer 规划（L1/L0/UB 分层）/ 分支场景覆盖（dtype/shape/对齐）
+```
+
+各族理论模型与 fallback：`ops-family`（matmul/mc2/reduce/elementwise/broadcast/
+conversion/convolution/fa/sort 路由表）。**fa 族当前仅 fallback 兜底（已知缺口）**，
+FA 类调优按无同型案例降级策略执行并沉淀案例。
+
+## 验证
+
+L2 规则复跑（__tail_ratio / __imbalance_pct / row_count 变化）+ 同口径性能；
+tiling 改动后 device fault 处置：①回滚确认基线可复跑 ②-g 重编 + msSanitizer 定位
+③缩小改动粒度 ④核对深度/容量联动字段。
+
+## 回滚
+
+长尾加剧 / 利用率未升 / 精度失败 → revert。切分类改动可能改变 tiling_key——
+delta_compare 默认 WARN 不阻断（MECHANISM_KEYS 语义）。
+
+## 精度风险
+
+切分与分核默认语义保持；改变归约分块顺序 → 语义变更类（附验证用例）。
+
+## 模板资产
+
+`ops-family:references/matmul/guide.md`（六策略互斥判定树）、各族 guide。

package/skills/asc-tools/tool-ops-tune/ops-mechanism/references/optimize/data-copy.md

@@ -0,0 +1,67 @@
+# 机制卡：数据搬运优化（MTE2/MTE3 —— 真假 bound 二分）
+
+> 对应判定规则：L1_MTE2_BOUND、L1_MTE3_BOUND、L1_FIXP_BOUND。
+> 核心方法：**先分真假 bound，再选机制**——真带宽饱和优化数据量/复用；假 bound（busy 高
+> 但带宽低）优化搬运组织。判定引擎的反证条目已给出方向，机制卡只做实施。
+> **DSL 适用域**：本卡实施细节以 **Ascend C** 为准；Triton / CATLASS / TileLang 的等价原语与实施差异见 [index.md 跨 DSL 原语对照表](index.md#跨-dsl-原语对照六原语--dsl)——跨 DSL 实施时以该表为路由、对应 DSL 专项文档为深度参考，不按本卡字面照搬。
+
+## 原理与二分
+
+```
+理论 MTE2 耗时 = GM_to_UB_datas(KB) × 1024 / GM 峰值带宽
+实际 MTE2 耗时 = ai*_mte2_time(us)
+
+实际 ≈ 理论（差 <20%，或 active_bw ≥ 峰值 80%）→ 真带宽饱和：
+  机制方向 = 削减数据量（复用/驻留/更小 dtype）与减少搬运次数（增大 tile）
+实际 >> 理论（active_bw < 40% 峰值）→ 假 bound（搬运组织问题）：
+  机制方向 = 合并小搬运 / 对齐 / 缓解同步
+```
+
+## 机制清单
+
+| # | 机制 | 适用条件 | 检查方式 |
+|---|------|---------|---------|
+| 1 | 增大单次搬运量 | 单次 <16KB | GM_to_UB_datas / mte2_instructions |
+| 2 | 512B 地址对齐 | fixpipe_ratio >5~15% | PipeUtilization fixpipe_ratio |
+| 3 | 合并小搬运 | 多次 <20KB 小块 → 合并成一次大 MTE2（scaleKL1 = SCALE_L1_BUFFER_NUM × kL1） | matmul scale_coalescing 实践 |
+| 4 | L2 CacheMode | L2 hit <50% | L2Cache.csv；只读一次的数据 CACHE_MODE_DISABLE 防污染 |
+| 5 | UB/TBuf 常驻复用 | 多 tile 重复从 GM 搬同一数据 | Bank 冲突规避与常驻联动设计 |
+| 6 | Double Buffer | MTE 与计算串行 | 转 pipeline.md |
+| 7 | 增大 tile | 搬运次数过多 | mte2_instructions 过大 |
+| 8 | 避免同地址多核访问 | 各核 mte2_time 差异大 | 跨核共享读改广播/分片 |
+| 9 | L2 复用（带宽未打满时） | tile 调大使数据驻留 L2；**相邻核处理相邻数据**共享缓存行 | 实际带宽/峰值 <80% 且有复用 |
+| 10 | 基本块选型（stride 消除） | stride 搬移效率低于连续搬移——重构数据布局/选连续大粒度搬移指令 | 搬移指令序列含高 stride |
+| 11 | 原地消费 | UB 内数据可直接消费的不搬出再搬入 | 搬入搬出成对出现且无中间消费方 |
+
+## 适用前提
+
+- verdict 命中 L1_MTE2_BOUND（severity 分档决定投入深度）；
+- **反证条目必须先读**：true-bandwidth-saturation 命中 → 只走 1/4/5/7（数据量侧）；
+  fake-mte2-small-packet 命中 → 优先 2/3/8（组织侧）；
+- MC² 算子先过 L3_MTE2_POLLUTED：污染为 true 时本卡全部机制无效，转 mc2.md 通信掩盖。
+
+## 验证
+
+```bash
+# 同口径性能 + 搬运指标复采
+# 期望：mte2_active_bw 上升（组织侧修复）或 mte2_instructions 下降（数据量侧修复）
+python3 ../ops-verdict/scripts/verdict.py --rules ../ops-verdict/rules/L1-single-core.yaml \
+    --csv <new.csv> --scalar mte2_active_bw_pct_of_peak=<复测值> --soc <soc> -o round-N.verdict.json
+```
+
+## 回滚条件
+
+噪声带内 / 精度失败 / L2 命中率反而下降（CacheMode 误用污染）→ revert。
+
+## 精度风险
+
+数据搬运类机制默认语义保持；改 dtype（如 fp16 计算）属语义变更，须精度代价标注。
+
+## 模板资产
+
+- `ops-family:references/common/datacopy_optimization_design.md`（非对齐/小批量多搬；设计参考，无货架代码）
+- `ops-family:references/common/ub_resident_design.md`（常驻复用 + Bank 规避；设计参考，无货架代码）
+- matmul 族 fullload / scale_coalescing / mte2_preload：`ops-family:references/matmul/guide.md`
+  （均为设计参考——matmul 族当前无货架模板代码）
+- 可拷贝货架模板见 conversion（11 个 transpose .template）与 broadcast（code/ 5 个
+  .h/.cpp）两族；reduce 族 Softmax 模板 ×8（`references/reduce/templates/dav310/`）

package/skills/asc-tools/tool-ops-tune/ops-mechanism/references/optimize/index.md

@@ -0,0 +1,45 @@
+# 机制索引（optimize-index）
+
+> 消费时机：verdict 判定完成后按 findings[].mechanism_refs 路由，只加载命中的单张卡。
+> **证据先行：没有 verdict 不加载机制卡**（禁止先看机制猜瓶颈）。
+
+## 索引表（rule_id → 机制卡）
+
+| rule_id | 机制卡 | 一句话机制 |
+|---------|--------|-----------|
+| L1_MTE2_BOUND | [data-copy.md](data-copy.md) | 真饱和→数据量/复用；假 bound→对齐/合并小搬运 |
+| L1_MTE3_BOUND | [data-copy.md](data-copy.md) | 搬出侧同二分 |
+| L1_FIXP_BOUND | [data-copy.md](data-copy.md) | 512B 地址对齐 |
+| L1_VEC_BOUND | [api-usage.md](api-usage.md) + [ascendc-regbase-vf.md](ascendc-regbase-vf.md)（A5 深度档） | UB 融合/减 Cast/融合指令；VF 范式 |
+| L1_CUBE_BOUND | [ascendc-tiling.md](ascendc-tiling.md) + ops-family matmul | tiling / L1 复用 / L0C 累加 |
+| L1_SCALAR_BOUND | [api-usage.md](api-usage.md) | 标量削减六法 |
+| L1_LATENCY_SYNC_SUSPECT | [pipeline.md](pipeline.md) | Double Buffer / 同步删减 |
+| L1_SERIAL_NO_OVERLAP | [pipeline.md](pipeline.md) | 双缓冲全形态 + workspace 份数 + AIC:AIV 配比 |
+| L2_CORE_TAIL / L2_IMBALANCE_* | [ascendc-tiling.md](ascendc-tiling.md) | 尾块均衡 / swat / NUMA 偏斜处置 |
+| L2_UNDERUTILIZATION | [ascendc-tiling.md](ascendc-tiling.md) | Block Dim 提升（头开销权衡） |
+| L2_HEAD_OVERHEAD | [api-usage.md](api-usage.md) | 减核 / 缩 TilingData / TPipe 外置 |
+| L3_MC2_*（全档） | [mc2.md](mc2.md) | Local Matmul 首选 + 通信掩盖 + 膨胀控制 |
+| L3 配平环节 | [mc2-balancing.md](mc2-balancing.md) | TilingData 驱动系统搜索（四剪枝 + Top-N） |
+| L3_MTE2_POLLUTED | [mc2.md](mc2.md) | 单核访存机制无效，改道通信掩盖 |
+| L3_RANK_IMBALANCE | [mc2.md](mc2.md) | 跨 rank 长尾排查 |
+| L0_ICACHE_MISS | [api-usage.md](api-usage.md) | 代码布局/分支整理 |
+| L0_L2_LOW_HIT | [memory-hierarchy.md](memory-hierarchy.md) | CacheMode 二分 + 工作集切分 |
+| L0_STALL_DOMINANT | [pipeline.md](pipeline.md) | stall 枚举 → 对应流水机制（M2 细化） |
+
+## 跨 DSL 原语对照（六原语 × DSL）
+
+| 原语 | Ascend C | CATLASS | Triton | TileLang | SHMEM/MC² |
+|------|---------|---------|--------|----------|-----------|
+| 双缓冲 | InitBuffer(q,2,sz) / ping-pong+event | STAGES 参数 | num_stages + UB 余量 | DB-ANALYSIS | 通算 ping-pong（CrossCore） |
+| 流水掩盖 | 事件同步 MTE/计算 | pipeline policy | 软件流水 | schedule 原语 | 通信-计算交错 |
+| 同步降本 | 删冗余 SetFlag/WaitFlag | — | barrier 合并 | — | flag 粒度放宽 |
+| 分核均衡 | blockDim/尾块/swat | BlockScheduler-Swizzle | 网格切分 | tile 划分 | rank 分片 |
+| 存储层级 | UB/L1/L0 驻留 | L1/L0TileShape | — | — | 远端 window 驻留 |
+| 标量削减 | Muls/常量折叠/外提 | — | constexpr 化 | — | — |
+
+## 已知覆盖缺口（降级策略见 SKILL.md）
+
+- FA 类混合绑核（AIC+AIV CrossCore mode2）：跨 j 迭代 GM buffer ping-pong、flag 粒度
+  放宽、GM→L1 滚动预取只有通用原理，实施细节自行论证 + 提高验证强度；
+- MoE routing / key-value sort / gather-scatter / histogram（SIMT 不规则读写）；
+- Double Buffer 非 TQue 形态（ping-pong event id + prologue/drain 自行论证）。

package/skills/asc-tools/tool-ops-tune/ops-mechanism/references/optimize/mc2-balancing.md

@@ -0,0 +1,77 @@
+# 机制卡：MC² 流水配平（TilingData 驱动的系统搜索）
+
+> 对应判定规则：L3 各 MC² 档位的配平环节。内容：长短块排布 + AIC/AIV 分离架构 + 统一搜索算法（多卡实测沉淀）。
+
+## AIC/AIV 分离架构与 Pattern
+
+MC² 算子 = AIC（matmul 计算）+ AIV（UDMA/shmem 跨卡通信）分离架构，同步方向由执行
+顺序决定：
+
+| Pattern | 执行顺序 | 同步方向 |
+|---------|---------|---------|
+| A（如 alltoall + matmul） | AIV 先通信 → AIC 等数据 → 计算 | AIV `CrossCoreSetFlag` → AIC `CrossCoreWaitFlag` |
+| B（如 matmul + alltoall） | AIC 先计算 → AIV 等完成 → BarrierAll → 通信 | AIC `NotifyComputeComplete` → AIV `WaitComputeComplete` |
+
+配平改变的是**长短块排布**（长块 = 大 M 的计算块，短块 = 小 M 的计算块），使计算块的
+耗时分布与通信块节奏互补。
+
+## 统一搜索算法（禁止经验值交付）
+
+输入：TilingData（baseM/baseN/baseK/usedCoreNum，长短块各自）+ 隔离测试 R 值 +
+配平比 ρ = max(R, 1/R)（长块与短块的 M 大小之比）。
+
+```
+搜索空间：长块 M ∈ {候选集}，短块 M = 长块 M / ρ（对齐修正），块数切分方案
+四条剪枝（可行性）：
+  ① 核利用率：usedCoreNum × 块数覆盖不下降
+  ② L1/L0 容量：baseM/baseN/baseK 组合不超片上预算
+  ③ 膨胀下界：计算膨胀 + 通信膨胀的估算不超过收益
+  ④ 对齐约束：M/N/K 对齐要求（512B / 分形对齐）
+输出：Top-N 候选 → 逐个实测（tileCnt 扫描）→ 按跨 rank max 口径择优
+```
+
+**执行载体**：`ops-mechanism/scripts/mc2_search.py`——上述算法的脚本化：
+
+```bash
+python3 skills/ops-mechanism/scripts/mc2_search.py \
+    --m 4096 --base-n 128 --base-k 64 --used-core-num 16 \
+    --r-value 2.4 --soc a5 -o candidates.json
+```
+
+- 容量剪枝②读 `ops-verdict/references/soc-spec.yaml`（不硬编码）；
+  对齐剪枝④分级：分形对齐 16（Cube 硬约束）剪枝，512B 对齐（搬运推荐态，
+  DataCopyPad 场景可接受）降级为候选上的 warn 记录；
+- 输出 Top-N 候选（每候选带块布局 / 容量占用计算 / warn）+ 全部剪枝记录
+  （可审计证据：剪枝记录本身是证据）；
+- 排序 = 实测顺序不是最终结论：每候选仍须逐个实测（同口径 task-based、
+  跨 rank max、delta_compare 三段结论）后择优；
+- **配平方案卡必须附本搜索器输出**（候选清单 + 剪枝记录）——经验值交付
+  的禁令自此有执行载体。
+
+## TilingData 依赖（硬约束 MC-1）
+
+host 代码须打印 baseM/baseN/baseK/usedCoreNum（含长块/短块各自的 tiling data）。
+未打印 → 在源码副本启用 PrintTilingData → 重新运行采集。缺这些数据核利用率计算
+失真、剪枝失效。
+
+## 长短块排布
+
+- R < 1（通信侧慢）：短块多、长块少——让计算碎片塞进通信间隙；
+- R > 1（计算侧慢）：长块多——让通信（快）在长计算块间流水；
+- ρ 是理想比，实际排布按 Top-N 实测修正（估算 ≠ 实测，膨胀会吃掉理论收益）。
+
+## 验证
+
+每候选实测必须同口径（同一 msprof task-based 采集、同 warmup/loops、跨 rank max），
+用 delta_compare 出三段结论；配平收益核算用隔离测试的 T_comm/T_compute 代入
+掩盖率公式。
+
+## 回滚
+
+- 候选劣化（跨 rank max 口径）→ 弃用并记录（搜索的负结果也是证据）；
+- tiling 改动后 device fault → 回滚确认基线可复跑 → -g 重编 + msSanitizer 定位 →
+  缩小改动粒度（baseK 128→192 而非 256）→ 核对深度/容量联动字段。
+
+## 精度风险
+
+块切分改变累加分块顺序 → 语义变更类：边界值 + 大 shape + 异常位型验证用例必附。

package/skills/asc-tools/tool-ops-tune/ops-mechanism/references/optimize/mc2.md

@@ -0,0 +1,103 @@
+# 机制卡：MC² 通算融合优化（Local Matmul 首选 + 通信掩盖 + 膨胀控制）
+
+> 对应判定规则：L3_MC2_BALANCED / COMPUTE_BOUND / STRONG_COMPUTE / COMM_BOUND /
+> STRONG_COMM / L3_MTE2_POLLUTED / L3_RANK_IMBALANCE。
+> 内容沉淀自 MC² 通算融合调优实践（指标定义 / Bound 判定 / Local Matmul /
+> 流水配平 / 膨胀分析），本卡将其机制决策浓缩为可执行顺序。
+> **DSL 适用域**：本卡实施细节以 **Ascend C** 为准；Triton / CATLASS / TileLang 的等价原语与实施差异见 [index.md 跨 DSL 原语对照表](index.md#跨-dsl-原语对照六原语--dsl)——跨 DSL 实施时以该表为路由、对应 DSL 专项文档为深度参考，不按本卡字面照搬。
+
+## 策略优先级（与 R 值无关的固定顺序）
+
+```
+① Local Matmul（首选，不依赖 Bound 判定）
+   本 rank 数据无需通信 → 独立计算与通信重叠。任何 R 档位都先做这一步。
+② 流水配平（在 ① 基础上叠加）
+   由 R 值与 TilingData 驱动的系统搜索（见 mc2-balancing.md），禁止 1-2 个经验值交付。
+③ matmul 计算效率（仅计算 Bound，优先级最低，正交可叠加）
+   转 ops-family:references/matmul/guide.md（pingpong/streamk/fullload…）。
+```
+
+### ① 的模式选型（沉淀自 MC² 通算融合实践）
+
+| 执行顺序 | 推荐模式 | 机制 |
+|---------|---------|------|
+| 通信后计算（Pattern A，如 alltoall+matmul） | **前置独立** | LocalMatmul 先执行，与首次通信重叠隐藏通信延迟 |
+| 通信后计算且通信量小 / Local 占比小 | 融合 | self rank 在通信块循环内一起算（独立计算收益不大） |
+| 计算后通信（Pattern B，如 matmul+alltoall） | **后置独立** | 通信块只算远程 rank，Local 后置不冲突 |
+| 计算后通信且通信量小 | 融合 | 同上 |
+
+**Local matmul 连续性约束**：前置/后置模式下 Local 数据段的 M 维切分必须连续
+（否则 WaitFlag 顺序与数据顺序错位）。
+
+## 各 R 档位的机制方向
+
+| 档位 | R | 机制方向 |
+|------|---|---------|
+| 强通信 | <0.5 | 从短块出发搜索，最大化 tileCnt（计算块尽量小、轮次尽量多） |
+| 通信 | <1 | 用计算掩盖通信，增大 tileCnt |
+| 平衡 | 0.9~1.1 | 等分切分即最优，配平空间小 |
+| 计算 | 1.1~2 | 用通信掩盖计算，增大 tileCnt |
+| 强计算 | >2 | 增大 tileCnt 收益极小，倾向**少切分**（tileCnt 小、tile 大）+ 叠加 ③ |
+
+## MTE2 污染（L3_MTE2_POLLUTED 命中）的路由
+
+CrossCoreWaitFlag 挂在 AIC MTE2 流水线等待 AIV 通信 → aic_mte2_ratio 含通信等待空转：
+
+- **单核访存机制全部无效**（判定引擎已禁用 L1_MTE2_BOUND，机制路由改道本卡）；
+- 有效方向 = 消除/减少通信等待本身：Local Matmul、配平（减少互等）、Pattern A/B 的
+  同步粒度（CrossCore flag 粒度放宽 —— 实施细节需自行论证并提高验证强度）。
+
+## 膨胀分析（切分参数变更时必做）
+
+切分变化同时引入两类膨胀，**最小化瓶颈方膨胀**（被掩盖方膨胀影响小）：
+
+| 膨胀类型 | 表现 | 判读 |
+|---------|------|------|
+| 计算膨胀 | 流水断流 / 用核不满 / mac_ratio 下降 | 每块 matmul 效率损失（尾块/小 tile） |
+| 通信膨胀 | 头开销分摊变差 / 带宽下降 | 分片数增加 → 单片通信效率下降 |
+
+配平搜索的剪枝规则（四条，见 mc2-balancing.md）已内置膨胀可行性判断；Top-N 候选
+必须**实测**（隔离测试已产出 T_comm/T_compute，核算成本极低）。
+
+## 性能指标核算（每方案必选输出）
+
+```
+加速比 = 融合前耗时（tileCnt=1）/ 融合后耗时
+掩盖率 = (融合前耗时 − 融合后耗时) / min(T_compute, T_comm)     # 上限 1.0
+跨 rank：T_task = max(rank 稳态均值)                              # 木桶效应
+```
+
+## 前置数据硬约束
+
+| # | 约束 |
+|---|------|
+| MC-1 | 缺 TilingData（baseM/baseN/baseK/usedCoreNum，含长短块）不得做配平分析；host 未打印则在源码副本启用 PrintTilingData 补采 |
+| MC-2 | 配平方案必须系统搜索（四剪枝 + Top-N 实测），禁止经验值直接交付 |
+| MC-3 | 隔离测试在源码副本进行，产物保留、代码副本丢弃 |
+| MC-4 | 一切性能数据出自 msprof Task Duration（task-based），禁 host 计时 |
+
+## 验证与回滚
+
+- 精度：全量 case 工程容差（通信+计算双路径都要过）；
+- 性能：跨 rank max 口径对比（delta_compare 会拒绝跨 rank 口径不一致的对比）；
+- 回滚：配平搜索候选逐个实测，劣化候选直接弃用（搜索本身就是多候选实测，负结果
+  记入报告「保留与回滚清单」——它是瓶颈证据的组成部分）。
+
+## 精度风险
+
+Local Matmul 是数学等价改造（语义保持）；配平改变归约/累加分块顺序时属语义变更
+（浮点结合律），须边界值/大 shape 验证。
+
+## 性能抖动诊断（L3_RANK_IMBALANCE 命中的下钻，蒸馏）
+
+op_summary 的 Device_id 列识别多卡参与：同卡多行 = 多轮执行，不同卡同序号行 =
+同轮次。**时间维度**（同卡跨轮次）与**空间维度**（同轮次跨卡）分别分析
+aiaiv/mte 指标的离散度：
+- 时间抖动大（同卡 p95≫p50）→ 系统噪声（DVFS/同卡负载），加轮次取稳态而非
+  追机制；
+- 空间抖动大（同轮跨卡差异）→ 真 rank 不均衡，走配平/Local Matmul 机制。
+（snapshot 的 p50/p95 分布字段 + delta_compare 抖动诊断段已承载该数据。）
+
+## 模板资产
+
+`ops-family:references/mc2/guide.md`（3 策略 + 模板代码）。

package/skills/asc-tools/tool-ops-tune/ops-mechanism/references/optimize/memory-hierarchy.md

@@ -0,0 +1,40 @@
+# 机制卡：存储层次优化（L2/UB/L1/L0 复用）
+
+> 对应判定规则：L1_MTE2_BOUND（真饱和档）、L0_L2_LOW_HIT、L1_VEC_BOUND（UB 往返类）。
+> 内容沉淀自存储层次调优一线实践（L2 命中率判读、UB 常驻复用设计）。
+> **DSL 适用域**：本卡实施细节以 **Ascend C** 为准；Triton / CATLASS / TileLang 的等价原语与实施差异见 [index.md 跨 DSL 原语对照表](index.md#跨-dsl-原语对照六原语--dsl)——跨 DSL 实施时以该表为路由、对应 DSL 专项文档为深度参考，不按本卡字面照搬。
+
+## 机制清单（按层次）
+
+| 层次 | 机制 | 适用证据 | 关键约束 |
+|------|------|---------|---------|
+| L2 | `SetL2CacheHint(CacheMode::CACHE_MODE_NORMAL)` | L2 hit <50% 且数据有复用 | — |
+| L2 | 只读一次数据 `CACHE_MODE_DISABLE` | 流式数据污染 L2 | 与上一条二分：有复用开 NORMAL，无复用 DISABLE |
+| L2 | 工作集切分（访问序改造） | 大工作集整体 miss | L2 参数随 SoC 变化，须重算容量 |
+| L1 | B 矩阵/小侧矩阵驻留（fullload） | 小侧 ≤L1/2 + 对侧 T≥2 + 真 MTE2 bound | L1 预算 = 分形 + ping-pong 缓冲 |
+| L0 | L0C 累加（多 matmul 累加不回写） | CUBE bound + Fixpipe 高 | 累加链精度（语义变更类） |
+| UB | tile/loop 间常驻复用（TBuf 替代重复 MTE2） | 多 tile 重复搬同一数据 | UB 容量 + Bank 冲突规避（padding 32B 整数倍） |
+| 寄存器 | 中间值留寄存器/areg | 短生命周期中间量 UB 往返 | 寄存器压力与 spill 反证 |
+
+## Bank 冲突规避（常驻复用的伴生问题）
+
+| 冲突类型 | 判定字段 | 修法 |
+|---------|---------|------|
+| bankgroup | vec_bankgroup_cflt_ratio >3% | 修改 repeatStride/blockStride |
+| bank | vec_bank_cflt_ratio >3% | UB tensor 起始地址 + 32B 整数倍 padding |
+| 资源 | vec_resc_cflt_ratio >5% | 错开 Vector/Cube 调度 |
+| MTE | vec_mte_cflt_ratio >3% | 搬运与计算时序调整 |
+
+## 验证
+
+L2Cache.csv 复采（hit rate 变化）+ verdict 复跑；驻留类改造须核对 L1/L0/UB 三级预算
+表（改一处动全身——跨层耦合）。
+
+## 回滚
+
+hit rate 未升反降 / UB 容量挤压导致 tile 变小引起 MTE 次数上升 / 精度失败 → revert。
+
+## 模板资产
+
+`ops-family:references/common/ub_resident_design.md`；
+matmul fullload：`ops-family:references/matmul/guide.md`。

package/skills/asc-tools/tool-ops-tune/ops-mechanism/references/optimize/pipeline.md

@@ -0,0 +1,95 @@
+# 机制卡：流水优化（Double Buffer / 流水掩盖 / 同步降本）
+
+> 对应判定规则：L1_SERIAL_NO_OVERLAP、L1_LATENCY_SYNC_SUSPECT、L1_FIXP_BOUND（气泡相关）、
+> L0_STALL_DOMINANT。跨 DSL 原语对照见文末。
+>
+> 内容沉淀自 Ascend C 双缓冲与流水判读的一线实践，跨 DSL 原语对照见文末。
+
+## 原理
+
+单缓冲下 MTE 搬运与计算串行：pipe busy 求和 ≈100% 但各 pipe 均不满 → 「串行无重叠指纹」
+（判定规则 L1_SERIAL_NO_OVERLAP 命中即此形态）。双缓冲把 tile 搬运与上一 tile 计算
+重叠：理想收益上界 ≈ max(t_copy, t_compute) / (t_copy + t_compute)。
+
+## 适用前提
+
+- verdict 命中 L1_SERIAL_NO_OVERLAP 或 LATENCY/SYNC 可疑 + 反证「串行指纹」；
+- UB/L1 容量预算：双缓冲 = 2×tile 缓存，须核对 TilingData 的 buffer 规划；
+- 循环内无跨 tile 数据依赖（有依赖需先做依赖分析或改滚动窗口）。
+
+## 实施形态（分场景）
+
+| 场景 | 形态 | 关键点 |
+|------|------|--------|
+| TQue 标准流水 | `InitBuffer(queue, 2, size)` | bufNum=2；EnQue/DeQue 配对；循环内无多余 Sync |
+| 非 TQue（裸 MTE + 事件） | ping-pong 两组 UB + event id | 须自行论证 prologue/drain 段（已知知识缺口，验证强度↑） |
+| Cube-Vector 混合 | workspace 份数 2→4 | 减少 Cube/Vector 互等（GroupedMatmul 案例 154.2→131.8us） |
+| AIC:AIV 配比 | 1:1 → 1:2 | Cube/Vector 耗时严重不匹配时（同案例 218.1→154.2us，收益最大） |
+| 同步删减 | 删除经依赖证明冗余的 SetFlag/WaitFlag/barrier | 每删一处必须给出依赖论证（精度/正确性风险点） |
+
+## 验证（每轮门禁）
+
+```bash
+# ① 精度全量（工程现有测试，禁止自创容差）
+bash run.sh --verify-all
+# ② 同口径性能（与基线同 timing_method/warmup/repeat）
+bash run.sh --perf  # event 口径
+# ③ 机制生效证据：DoubleBuffer 生效 = MTE 与计算重叠比例 >30%（部分 10-30%，未生效 <5%）
+python3 ../ops-verdict/scripts/verdict.py --rules ../ops-verdict/rules/L1-single-core.yaml \
+    --csv <new PipeUtilization.csv> --soc <soc> -o round-N.verdict.json
+# 期望：__pipe_sum_mean 明显下降或 L1_SERIAL_NO_OVERLAP 转为 NOT_HIT
+```
+
+**重叠比例的直接度量**：上板有 A5 PipeTimeline 或
+仿真路径（cannsim）时，用 trace 工具替代间接指纹：
+
+```bash
+# 仿真路径：collect_sim.sh 采 trace → 重叠度标量
+bash ../ops-collect/scripts/collect_sim.sh --exe <exe> --soc-version Ascend950 --output ./prof/sim
+python3 ../ops-verdict/scripts/trace_bubble.py --trace-dir ./prof/sim/cannsim_*/report/ \
+    --scalar-out overlap_scalars.json
+# overlap_pct 即「MTE×计算 busy 交集/并集」的实测值（本卡阈值的直接对照）：
+#   >30% 生效 ｜ 10-30% 部分生效 ｜ <5% 未生效
+# KEEP 结论附 overlap_pct 前后对照（机制生效判读，而非仅 speedup）
+```
+
+上板无 trace 设施时，`__pipe_sum_mean` 间接指纹照旧（medium 置信度如实保留），
+报告标注「重叠度为间接推断」。
+
+## 无 Bound 形态（NO_BOUND_FOUND / 全 pipe 低占用，沉淀自一线调优实践）
+
+各单元利用率均不高、无明显单一瓶颈时，流水化优先于单点优化：
+
+| # | 机制 | 说明 |
+|---|------|------|
+| 1 | PingPong 粒度调优 | 控制每次搬入量，确保**计算时间 ≥ 搬运时间**（否则 DB 反而暴露搬运瓶颈） |
+| 2 | MMAD→Fixpipe UnitFlag 同步 | 用 UnitFlag 信号替代显式 Barrier（MMAD 输出→Fixp 输入硬依赖场景） |
+| 3 | 减少单次搬运量（渐进式） | 边算边搬不积压——避免「全量搬完才开始算」 |
+| 4 | Preload 窗口 | 当前计算未完成时启动下一批搬入；窗口大小匹配计算耗时（搬完算没完 = 白搬） |
+| 5 | 指令提早发射 | 搬移指令不等当前计算完全结束；计算流水线填充 |
+| 6 | Vec 融合减重复搬运 | 同一数据多次搬入场景：寄存器内连续处理 + 驻留期间全量消费 |
+
+trace 判读（trace_bubble）：MTE2 全在前 VECTOR 全在后 = DB 未生效；交替出现
+= 流水健康。tiling 修正：tile 粒度匹配 PingPong 分段；DB 使能时实际可用 UB ÷2。
+
+## 回滚条件
+
+- speedup < 1.05（噪声带内）→ 加采样轮次复测，仍带内 → revert；
+- 精度任一 case fail → revert（该轮性能数字不进报告）；
+- 容量联动被破坏（tile 改动后 device fault）→ revert + 缩小改动粒度（如 baseK 128→192
+  而非直接 256）+ msSanitizer 定位。
+
+## 精度风险分级
+
+- 语义保持类：双缓冲、搬运合并、调度顺序、同步删减（须依赖论证）→ 常规门禁。
+- 语义变更类：归约顺序改变（浮点结合律）→ 额外边界值/大 shape 验证用例。
+
+## 跨 DSL 原语对照（双缓冲）
+
+| DSL | 双缓冲实现 |
+|-----|-----------|
+| Ascend C | `InitBuffer(queue, 2, size)`（TQue）/ ping-pong 两组 UB + event id（非 TQue） |
+| CATLASS | `MmadAtlasA2Pingpong` STAGES 参数 |
+| Triton-Ascend | UB 留 50% 余量 + num_stages |
+| TileLang | DB-ANALYSIS 分析后实施 |
+| SHMEM/MC² | 通信-计算 ping-pong（CrossCore flag 同步，见 mc2.md） |