@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.5

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/cube-matmul-then-vector-softmax-reduce/cube-matmul-then-vector-softmax-reduce-design.md

@@ -0,0 +1,205 @@
+# Cube MatMul → Vector Softmax/Reduce 场景设计指导
+
+本文仅在 Step 3 的 Blaze 官方库方案已记录明确 `native_gaps`、场景索引唯一命中 `cube-matmul-then-vector-softmax-reduce` 后读取。不用于 Step 2、Step 4 或独立设计。
+
+## 0. 输入与源码前提
+
+### 0.1 必需输入
+
+| 输入                            | 来源                      | 状态要求                                                                                                            |
+| ------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `requirements_contract`       | Step 3 需求合同           | frozen                                                                                                              |
+| `operator_interface_contract` | Step 3 接口合同           | frozen                                                                                                              |
+| `matmul_base_analysis`        | Step 2 Investigation      | ready，含`abi_bindings[]`、`kernel_policy_block_scheduler_chain`、`tilingdata_params_and_scheduler_semantics` |
+| `native_gaps`                 | Step 3 官方方案覆盖性分析 | 存在明确 gap：Blaze 库无 softmax epilogue                                                                           |
+| `investigation_report_facts`  | Step 2                    | 具备 L0C2UB 输出能力的 BlockMmad 的 splitM CV sync 模式已记录                                                       |
+
+### 0.2 Blaze 源码前提
+
+| 前提                          | Investigation 须记录的事实                                                                                                                                                    |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| L0C2UB 输出路径               | BlockMmad 的 L0C2UB 输出路径使用`CopyL0C2UB` + splitM trait（如 `CopyL0C2UBTraitSplitM`）；`block_mmad_matmul_fixpipe_opti.h`、`block_mmad_qbmm_mx.h` 等均具备此能力 |
+| splitM CV sync                | BlockMmad 构造 AIV`SetFlag(AIV_SYNC_AIC_FLAG, +1)`，析构 AIC `WaitFlag(flags with FLAG_ID_MAX)`，tile 循环内 Wait/Set per N-tile                                        |
+| GemmUniversal 调用路径        | 对应 kernel（如`kernel_matmul_fixpipe_opti.h`）的 `operator()` → `epilogueOp.Init(params, problemShape)` → `blockMmad.Init()` → `MatmulProcess` tile loop        |
+| BlockEpilogueFixpipe 接口模式 | `operator()(blockShape, dstOffset, splitM, baseM, baseN, ubDB)` 内部 N-tile 循环 + CV sync                                                                                  |
+| 适用 kernel 结构特征          | 当前资产假设 5 个结构维度（见 [cv-sync §0](cv-sync-and-two-phase-entry.md)）：栈 epilogue + idle return 在 Init 之前 + MODE_4 CV sync + 6-arg 签名 + splitM。不匹配的维度需按 §0 适配方向调整 |
+
+前提缺失时只允许一次无场景名的补充调查问题；仍缺则不生成可执行 DESIGN。
+
+## 1. 精确匹配条件
+
+### 1.1 设计主线
+
+本场景支持两种行级归约变体，共享相同的两阶段执行结构和 CV sync 模式：
+
+**变体 A — Online Softmax**（默认变体，资产 `online_softmax_per_tile_epilogue.h` + `online_softmax_cross_core_epilogue.h`）
+
+MatMul（MM/BMM/GMM）产生最终 FP 输出 `[R,N]` 后，执行行级 online softmax：
+
+```
+logits = A @ B                    # MatMul，L0C2UB → UB
+# Phase 1 (per-tile, V1):
+for each N-tile:
+    tileMax = reduce_max(logits[row, tile])           # 跨 N-tile 局部 max
+    onlineMax = max(onlineMax, tileMax)               # 合并全局 max
+    expVals = exp(logits[row, tile] - onlineMax)      # 减 + exp
+    onlineSum = onlineSum * exp(oldMax - onlineMax)   # rescale 旧 sum
+             + reduce_sum(expVals)                    # 累加新 sum
+    write expVals → GM expWorkspace
+    write onlineMax → GM onlineMax, write onlineSum → GM onlineSum
+# Phase 2 (cross-core, V2):
+    maxFinal = max over all cores of onlineMax         # 跨核归约
+    sumFinal = Σ_c onlineSum_c * exp(onlineMax_c - maxFinal)
+    output = expVals * exp(mHistory - maxFinal) / sumFinal  # 最终 rescale
+```
+
+**变体 B — Pure Reduce**（基于变体 A 资产改写，详见 [Reduce 适配指导](reduce-adaptation-guide.md)）
+
+MatMul 产生最终 FP 输出 `[R,N]` 后，执行行级 reduce（如 reduce_max、reduce_sum、reduce_min 等），输出 `[R,1]`。相比 softmax 更简单：
+
+```
+logits = A @ B                    # MatMul，L0C2UB → UB
+# Phase 1 (per-tile, V1):
+for each N-tile:
+    tileResult = reduce(logits[row, tile])             # 单 pass 归约（无 exp/rescale）
+    onlineResult = merge(onlineResult, tileResult)     # max/min 取极值，sum 直接累加
+    write onlineResult → GM partialResult
+# Phase 2 (cross-core, V2):
+    finalResult = merge over all cores of partialResult  # 跨核合并，直接输出
+```
+
+与 softmax 的关键差异：无 exp/rescale 逻辑、无 expWorkspace/mHistory、workspace 缩减为 1 个 buffer、V2 无 ping-pong rescale pass。详见 [Reduce 适配指导](reduce-adaptation-guide.md)。
+
+### 1.2 有效性门禁
+
+- 归约域为完整逻辑行 `[0, N)`，逐 N-tile 增量更新
+- 两阶段执行：V1 逐 tile（AIC+AIV CV sync），V2 跨核归约（仅 AIV）
+- MatMul 使用具备 L0C2UB 输出能力的 BlockMmad，splitM=1
+- softmax 变体公式为标准 `softmax(x) = exp(x - max(x)) / sum(exp(x - max(x)))`
+- reduce 变体公式为 `output[row] = reduce(logits[row, 0:N])`，reduce 为可按行合并的归约操作（如 max、sum、min 等）
+
+### 1.3 常见误用
+
+| 误用                               | 原因                                   | 正确场景                                   |
+| ---------------------------------- | -------------------------------------- | ------------------------------------------ |
+| matmul + elementwise（无 reduce）  | softmax/reduce 含跨元素归约            | `elementwise-broadcast-epilogue-fusion`  |
+| matmul + GLU                       | GLU 是两路投影，不是行级归约           | `cube-matmul-then-vector-glu`            |
+| matmul + per-token quant           | quant 输出 int8+scale，不是 FP 归约输出 | `cube-matmul-then-vector-pertoken-quant` |
+| matmul + softmax/reduce + per-token quant | 两个独立 Vector 后处理阶段             | `unsupported`（多命中）                  |
+
+## 2. 接口与数据流
+
+### 2.1 Cube 输出
+
+具备 L0C2UB 能力的 BlockMmad 通过 `CopyL0C2UB`（+ splitM trait）将 L0C 结果写入 UB。splitM=1 时每个 AIV sub-block 收到 `CeilDiv(baseM, TaskRation)` 行。
+
+### 2.2 V1 PerTile 数据流
+
+```
+UB(matmulData) ──→ V: ReduceMax + Sub + Exp + ReduceSum ──→ UB(maxT, sumT, mmData)
+GM(onlineMax, onlineSum) ──→ UB(preMax, preSum) ──→ V: merge + rescale
+UB(maxT, sumT, mmData) ──→ MTE3 ──→ GM(onlineMax, onlineSum, expWorkspace, mHistory)
+```
+
+### 2.3 V2 CrossCore 数据流
+
+```
+GM(onlineMax, onlineSum) ──→ UB(allMaxCore, allSumCore) ──→ V: ComputeMaxSum ──→ UB(maxFinal, sumFinal)
+GM(mHistory) ──→ UB(mHist)
+GM(expWorkspace) ──→ UB(expTile[ping/pong]) ──→ V: rescale ──→ MTE3 ──→ GM(softmaxOut)
+```
+
+## 3. 三层增量合同
+
+### 3.1 Block 层
+
+- 复用 Blaze 库具备 L0C2UB 能力的 BlockMmad（如 `BlockMmad<MatmulMultiBlockFixpipeOpti>`、`BlockMmad<MatmulWithScaleMx>` 等），不修改
+- splitM=1（PerTileEpilogue 按 sub-block 分配行）
+- `ubDB=1`（首版不启用 UB ping-pong）
+
+### 3.2 Kernel 层
+
+- 从 `group_matmul_kernel_cv1_v2.h` 资产适配生成项目内 `matmul_softmax_kernel.h`，遵循 [cv1_v2 适配指导](cv1-v2-adaptation-for-softmax-reduce.md)
+- 适配核心：保留 `tuple<V1, V2>` + `Cv1Kernel` 委托模式，重写 `RunV2` 为 `V2.Init(params) + V2.ReduceAll()`，删除现有实现特有的类型别名/Params 字段/Tensor 构造/行分配逻辑
+- Phase 1 委托给 `GemmUniversal<BlockMmad, V1>`（Cv1Kernel），在作用域内闭合 CV sync 生命周期
+- Phase 2 在特化内部：`SyncAll` → `V2.Init(params)` → `V2.ReduceAll()`（仅 AIV）
+- kernel entry 只需 `GemmUniversal<PS, BM, tuple<V1, V2>, BS> kernel; kernel(params);`
+
+### 3.3 Epilogue 层
+
+**V1 PerTileEpilogue**（资产 `online_softmax_per_tile_epilogue.h`）：
+
+- 适配标准 BlockEpilogue 接口
+- `Init(params, problemShape)` 内含 `InitSyncFlag`（`if ASCEND_IS_AIV` 保护，`initialized_` guard）。workspace 初始化 + `SyncAll` 移到两阶段 kernel 的 `InitWorkspaceGlobal`（直接实现，不依赖 epilogue 实例）
+- `operator()(blockShape, dstOffset, splitM, baseM, baseN, ubDB)` 内含 N-tile 循环 + CV sync
+- 析构调用 `CleanUpSyncFlag`
+- CV sync 常量硬编码，与 Blaze 库 `BlockEpilogueFixpipe` 一致（以 Blaze 库源码为准）
+
+**V2 CrossCoreEpilogue**（资产 `online_softmax_cross_core_epilogue.h`）：
+
+- 独立接口：`Init(params)` + `ReduceAll()`
+- softmax 变体：内部 Phase 1 跨核归约 + Phase 2 N-tile ping-pong rescale
+- reduce 变体：仅 Phase 1 跨核合并，无 Phase 2 rescale（详见 [Reduce 适配指导](reduce-adaptation-guide.md)）
+
+## 4. Workspace 布局合同
+
+### 4.1 Softmax 变体
+
+```
+GM workspace 布局:
+  [0, cubeCoreNum*M*4)              : onlineMax  (float, [cubeCoreNum, M])
+  [..., +cubeCoreNum*M*4)           : onlineSum  (float, [cubeCoreNum, M])
+  [..., +M*ceil(N/baseN)*4)         : mHistory   (float, [M, numNTiles])
+  [..., +M*nAlignExp*4)             : expWorkspace (float, [M, nAlignExp])
+
+常量:
+  FLOAT32_BYTES = sizeof(float) = 4
+  DATA_BLOCK = 32
+  ELM_PER_32B = DATA_BLOCK / FLOAT32_BYTES = 8
+  nAlignExp = ceil(N / ELM_PER_32B) * ELM_PER_32B
+```
+
+### 4.2 Reduce 变体
+
+```
+GM workspace 布局:
+  [0, cubeCoreNum*M*4)              : partialResult  (float, [cubeCoreNum, M])
+
+常量:
+  FLOAT32_BYTES = sizeof(float) = 4
+```
+
+reduce 变体仅需 1 个 buffer（每核每行的 partial 归约结果），无 mHistory / expWorkspace / onlineSum。详见 [Reduce 适配指导](reduce-adaptation-guide.md)。
+
+## 5. 条件 SplitM
+
+splitM=1 是本场景的必需条件：
+
+- PerTileEpilogue 按 `CeilDiv(baseM, TaskRation)` 分配行，每个 AIV sub-block 独立处理
+- BlockMmad 使用 `CopyL0C2UBTraitSplitM`（`DUAL_DST_SPLIT_M`）将 L0C 结果分别写入两个 sub-block 的 UB 区域
+- 不启用 splitM 会导致 UB 布局不匹配（BlockMmad 写全 M 行，PerTileEpilogue 只读半行）
+
+## 6. 验证增量
+
+| 维度        | 覆盖                                         |
+| ----------- | -------------------------------------------- |
+| N-tile      | 单 N-tile（N=baseN）、多 N-tile（N>baseN）   |
+| 多核        | 单核（cubeCoreNum=1）、多核（cubeCoreNum>1） |
+| M 奇偶      | M 为偶数、M 为奇数（splitM 行分配 tail）     |
+| 非对齐      | K/N 非 16 对齐、M 非 baseM 对齐              |
+| tail        | N-tail、M-tail                               |
+| 重复 launch | 相同输入连续运行多次                         |
+
+精度门禁：`max_abs_error < 2e-3` 或 `max_rel_error < 0.01`。
+
+## 7. 输出与门禁
+
+DESIGN 必须冻结：
+
+- `implementation_route: blaze_custom`
+- `selected_scenario: cube-matmul-then-vector-softmax-reduce`
+- `abi_crosswalk_delta`：softmax 变体追加 onlineMax/onlineSum/mHistory/expWorkspace/softmaxOut；reduce 变体追加 partialResult/outputReduce 的 operand、Params、offset 和 consumer
+- `consumed_contracts`：matmul_base_analysis（BlockMmad + Scheduler + Tiling）
+- `added_contracts`：V1/V2 epilogue 接口、workspace 布局、CV sync 生命周期
+- `customization_scope`：仅 V1/V2 epilogue 资产和 kernel entry 编排
+- `forbidden_change_scope`：Blaze 库 BlockMmad、Scheduler、GemmUniversal、Tiling 引擎

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/cube-matmul-then-vector-softmax-reduce/cube-matmul-then-vector-softmax-reduce-development.md

@@ -0,0 +1,99 @@
+# Cube MatMul → Vector Softmax/Reduce 开发指导
+
+本文在同目录 [设计指导](cube-matmul-then-vector-softmax-reduce-design.md) 已冻结、`implementation_route=blaze_custom` 且 `selected_scenario=cube-matmul-then-vector-softmax-reduce` 后用于编译项目 PLAN。Step 4 不重新决定归约公式、归约域、workspace 布局或同步协议。
+
+## 1. PLAN 输入和阅读
+
+PLAN 必须绑定 workspace 布局、producer/consumer 集、归约公式（softmax 或 reduce）、splitM 合同和基础 MatMul ABI。必读：
+
+- [Online Softmax/Reduce Epilogue 设计专题](online-softmax-reduce-epilogue-design.md)
+- [CV Sync 与两阶段 Entry 编排专题](cv-sync-and-two-phase-entry.md)
+- [Reduce 适配指导](reduce-adaptation-guide.md)（reduce 变体必读）
+- [SplitM 专题](../elementwise-broadcast-epilogue-fusion/splitm-contract-and-debugging.md)（DESIGN 激活 splitM 时）
+- Investigation 指定的具备 L0C2UB 能力的 BlockMmad、GemmUniversal、同步、Tiling 来源
+- [Tiling 方法](../../kernel-design/tiling-selection.md)、[Launcher 方法](../../launcher/launcher-development.md)
+- [同步方法](../../fundamentals/blaze-sync-patterns.md) 和当前 CANN 实际头文件
+
+## 2. 有序动作
+
+### 2.1 核对 Base MatMul
+
+核对 DESIGN/Investigation 与当前 Blaze 源码版本的抽象一致性：
+
+- BlockMmad 的 L0C2UB 输出路径使用 `CopyL0C2UB` + splitM trait（如 `block_mmad_matmul_fixpipe_opti.h`、`block_mmad_qbmm_mx.h` 等）
+- 对应 kernel 的 `operator()` 调用路径（如 `kernel_matmul_fixpipe_opti.h`）：`epilogueOp.Init` → `blockMmad.Init` → `MatmulProcess`
+- `block_scheduler_matmul_basic.h` 的 `GetBlockShape`/`GetBlockCoord` 接口
+- 确认 kernel 结构特征与 [cv-sync §0](cv-sync-and-two-phase-entry.md) 匹配（5 个维度逐一核对，不匹配时按适配方向调整）
+
+### 2.2 选择执行拓扑
+
+- `__mix__(1, 2)`：1 AIC + 2 AIV per block
+- `splitM=1`：PerTileEpilogue 按 sub-block 分配行
+- `ubDB=1`：首版不启用 UB ping-pong（slot 恒为 0）
+- 先闭合 CV sync 生命周期（构造/析构 + tile loop），再做性能选择
+
+### 2.3 复制并适配资产
+
+1. 复制 `online_softmax_per_tile_epilogue.h` 到项目 `blaze_custom/epilogue/`（reduce 变体复制后按 [Reduce 适配指导](reduce-adaptation-guide.md) 改写）
+2. 复制 `online_softmax_cross_core_epilogue.h` 到项目 `blaze_custom/epilogue/`（reduce 变体同理）
+3. 按 [cv1_v2 适配指导](cv1-v2-adaptation-for-softmax-reduce.md) 从 `group_matmul_kernel_cv1_v2.h` 适配生成项目 `blaze_custom/kernel/matmul_softmax_kernel.h`（在 `operator()` 开头添加 `InitWorkspaceGlobal` + `SyncAll`）。适配后不得在项目内保留原始 `group_matmul_kernel_cv1_v2.h`：两个特化模板参数列表相同，同处一个编译单元会触发歧义错误（见适配指导 §7）
+4. 复制 `blaze_custom/utils/common_utils.h` 和 `integral_constant.h`（如项目无已有副本）
+5. 确认 CV sync 常量与 Blaze 库 BlockMmad 一致（以 Blaze 库源码为准）
+6. 根据 DESIGN 冻结的 dtype 实例化模板参数（如 `bf16` 输入 + `float` 输出）
+
+### 2.4 编写 Kernel Entry
+
+1. 在 `op_kernel/matmul_softmax_kernel.h` 中定义类型别名：
+   - `DispatchPolicy = MatmulMultiBlockFixpipeOpti<ND_ALIG_1V2_FIXPIPE, 0>`  // 示例为普通 matmul；MX 量化等变种使用对应 DispatchPolicy（如 MatmulWithScaleMx）
+   - `BlockScheduler = BlockSchedulerMatmulBasic<ProblemShape>`
+   - `BlockMmad = BlockMmad<DispatchPolicy, AType, LayoutA, BType, LayoutB, CType, LayoutC, BiasType, LayoutBias>`
+   - `PerTileEpilogue = OnlineSoftmaxPerTileEpilogue<OutT, OutT, false>`
+   - `CrossCoreEpilogue = OnlineSoftmaxCrossCoreEpilogue<OutT>`
+   - `EpiloguePipeline = AscendC::Std::tuple<PerTileEpilogue, CrossCoreEpilogue>`
+   - `KernelImpl = GemmUniversal<ProblemShape, BlockMmad, EpiloguePipeline, BlockScheduler>`
+2. 计算 workspace 布局（softmax 变体：onlineMax/onlineSum/mHistory/expWorkspace 的 offset；reduce 变体：partialResult 的 offset，详见设计指导 Section 4.2）
+3. 构造 `KernelImpl::Params`（嵌套 `cv1Params` + `epilogueV2Params`）
+4. 调用 `KernelImpl kernel; kernel(kParams);`（两阶段编排由适配后的特化内部完成）
+5. V1 epilogue 析构需 `initialized_` guard（idle 核未调 `Init` → 跳过 `CleanUpSyncFlag`）
+
+### 2.5 编写 Tiling 和 Launcher
+
+1. 复用 `blaze_matmul_tiling.h` 的 `MatmulTilingSwat` 引擎
+2. 扩展 tiling data POD：追加 `cubeCoreNum`、`vecCoreNum`、`ubDB` 字段
+3. Host 侧 workspace 大小计算使用设计指导 Section 4 的布局公式
+4. Launcher 按 `usedCoreNum` 启动 `__mix__` grid
+
+### 2.6 生成 Golden
+
+Golden 分两步：先按所选 MatMul 变种计算 logits，再对 logits 的最后一维执行归约。MatMul 部分的输入构造和计算由具体变种决定（普通 matmul / MX 量化 / grouped matmul 等），归约部分按变体选择：
+
+- softmax 变体：`golden = torch.softmax(logits.to(float), dim=-1)` → fp32
+- reduce 变体：`golden = torch.reduce(logits.to(float), dim=-1)` → fp32（reduce 为可按行合并的归约操作，如 max、sum、min 等）
+- logits 为 MatMul 的 FP 输出，归约沿 N 维（完整逻辑行）
+- 数据存为二进制文件，host 侧读取
+
+## 3. 验证和交付
+
+### 3.1 精度验证
+
+| 维度        | 覆盖                                                 |
+| ----------- | ---------------------------------------------------- |
+| N-tile      | 单 N-tile（N=baseN）、多 N-tile（N=baseN*2, *4, *8） |
+| 多核        | 单核（totalTiles=1）、多核（totalTiles=cubeCoreNum） |
+| M 奇偶      | M 为偶数、M 为奇数                                   |
+| 非对齐      | K/N 非 16 对齐、M 非 baseM 对齐                      |
+| tail        | N-tail（N%baseN≠0）、M-tail（M%baseM≠0）           |
+| 重复 launch | 相同输入连续运行 3 次                                |
+| 大 case     | M≥1024, K≥4096, N≥6144                            |
+
+精度门禁：`max_abs_error < 2e-3` 或 `max_rel_error < 0.01`。
+
+每个 case 记录实际 tiling（baseM/baseN/baseK/cubeCoreNum）和实际误差。
+
+### 3.2 交付
+
+- 编译通过（`cmake --build`）
+- 精度全部 PASS
+- 清理诊断后 clean build 并重跑 Full
+- 交付分别声明正确性和性能状态
+- 项目内不含原始 `group_matmul_kernel_cv1_v2.h`（已适配重命名为 `matmul_softmax_kernel.h`，见 §2.3 第 3 条）

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/cube-matmul-then-vector-softmax-reduce/cv-sync-and-two-phase-entry.md

@@ -0,0 +1,156 @@
+# CV Sync 与两阶段 Kernel 编排专题
+
+本专题详细描述适配后的 `matmul_softmax_kernel.h`（从 `group_matmul_kernel_cv1_v2.h` 适配）的两阶段编排和 CV sync 生命周期。
+是 [场景设计指导](cube-matmul-then-vector-softmax-reduce-design.md) Section 3.2 的展开，适配步骤见 [cv1_v2 适配指导](cv1-v2-adaptation-for-softmax-reduce.md)。
+
+## 0. 适用范围
+
+本专题的资产和编排方案基于以下 5 个 kernel 结构特征。适配时须逐一核对，不匹配的维度需按"适配方向"调整：
+
+| 结构维度 | 当前资产假设 | 不匹配时的适配方向 |
+|----------|-------------|-------------------|
+| **epilogue 存储模型** | 栈对象（ctor/dtor 在所有核触发，含 idle） | 若为类成员：析构无死锁风险，`initialized_` guard 非必需 |
+| **idle 核返回时机** | return 在 `Init` 之前 | 若 return 在 `Init` 之后或无 return：workspace 初始化 + `SyncAll` 可保留在 `Init` 中，无需 `InitWorkspaceGlobal` |
+| **CV sync 机制** | ctor/dtor 中 CrossCore set/wait（MODE_4） | 若为 per-tile NotifyVector/WaitForCube：epilogue 需在 tile loop 内匹配 helper 调用，不依赖 ctor/dtor |
+| **epilogue 调用签名** | `(blockShape, dstOffset, splitM, baseM, baseN, ubDB)` | 若不同：epilogue `operator()` 签名需匹配实际 kernel 传入的参数 |
+| **splitM 支持** | 支持（splitM=1） | 若不支持：行分配逻辑需改为全 M 行，不用 `CeilDiv(baseM, TaskRation)` |
+
+适配者只需检查自己的 kernel 在这 5 个维度上的实际行为，对照即可确定哪些部分可直接复用、哪些需要调整。
+
+## 1. 两阶段 Kernel 编排
+
+适配后的 kernel 是 `GemmUniversal` 的 `tuple<V1, V2>` 特化。kernel entry 只需：
+
+```cpp
+using EpiloguePipeline = AscendC::Std::tuple<PerTileEpilogue, CrossCoreEpilogue>;
+using KernelImpl = GemmUniversal<ProblemShape, BlockMmad, EpiloguePipeline, BlockScheduler>;
+
+typename KernelImpl::Params kParams{
+    {problemShape, mmadParams, perTileParams, schParams},  // cv1Params
+    crossCoreParams};                                        // epilogueV2Params
+
+KernelImpl kernel;
+kernel(kParams);
+```
+
+特化内部的 `operator()` 编排两阶段：
+
+```cpp
+// Phase 1: MatMul + PerTile online softmax (AIC BlockMmad + AIV PerTileEpilogue)
+{
+    Cv1Kernel cv1Kernel;
+    cv1Kernel(params.cv1Params);
+}
+
+// Phase 2: Cross-core reduction + final rescale (AIV only)
+AscendC::SyncAll();
+if ASCEND_IS_AIV {
+    RunV2(params);
+}
+```
+
+`RunV2` 适配后只需 3 行：
+
+```cpp
+__aicore__ inline static void RunV2(Params const& params)
+{
+    BlockEpilogueV2 epilogueV2;
+    epilogueV2.Init(params.epilogueV2Params);
+    epilogueV2.ReduceAll();
+}
+```
+
+### Phase 1 内部流程（Cv1Kernel = GemmUniversal<BlockMmad, V1>）
+
+```
+构造: AIV SetFlag(AIV_SYNC_AIC_FLAG, +1)              — 预置 ping+pong UB 空闲
+epilogueOp.Init(params, problemShape):
+    AIV: workspace 初始化 → SyncAll → InitSyncFlag()
+    AIC: SyncAll()
+blockMmad.Init(params.mmadParams)                       — AIC only, L1/L0 布局
+MatmulProcess:                                          — tile loop
+    for each block:
+        AIC: blockMmad(gmBlockA, gmBlockB, gmBlockBias, ubLocal, validBlockShape)
+            内部: WaitFlag(AIV_SYNC_AIC_FLAG) → CopyL0C2UB → SetFlag(AIC_SYNC_AIV_FLAG)
+        AIV: epilogueOp(validBlockShape, offsetC, splitM, baseM, baseN, ubDB)
+            内部: WaitFlag(AIC_SYNC_AIV_FLAG) → PerTileEpi → SetFlag(AIV_SYNC_AIC_FLAG)
+析构: AIC WaitFlag(4 flags with FLAG_ID_MAX)            — drain
+      AIV CleanUpSyncFlag()                             — 消耗 HardEvent
+```
+
+### Phase 2 内部流程
+
+```
+SyncAll()                                               — 所有核到达
+AIV: CrossCoreEpi.Init(params)
+     CrossCoreEpi.ReduceAll()
+         Phase 1: ComputeMaxSum (跨核归约 maxFinal/sumFinal)
+         Phase 2: N-tile ping-pong rescale → GM softmaxOut
+```
+
+## 2. CV Sync 常量
+
+CV sync 常量硬编码在 PerTileEpilogue 中，必须与 Blaze 库 `BlockMmad` 和 `BlockEpilogueFixpipe` 的当前实现保持一致。Blaze 库演进时这些值可能变化，适配时以 Blaze 库源码为准：
+
+| 常量                    | 方向     | 含义         |
+| ----------------------- | -------- | ------------ |
+| `AIC_SYNC_AIV_MODE_4` | —       | CV sync mode |
+| `AIV_SYNC_AIC_FLAG`   | AIV→AIC | UB 槽位空闲  |
+| `AIC_SYNC_AIV_FLAG`   | AIC→AIV | UB 数据就绪  |
+
+不依赖 `cv_sync_constants.h` 资产文件，遵循 Blaze 库 `BlockEpilogueFixpipe` 的相同模式（在类内 `static constexpr` 硬编码）。
+
+## 3. FLAG_ID_MAX 语义
+
+`__mix__(1, 2)` 模式下，硬件自动将 AIV sub-block 1 的 flag N 映射到 AIC 的 flag N+FLAG_ID_MAX。FLAG_ID_MAX 的值由 `__mix__` 模式决定，取值以 Blaze 库当前实现为准。
+
+- **AIC 侧**：在 splitM=1 时，每个 N-tile 的 `WaitFlag`/`SetFlag` 操作 4 个 flag（`AIV_SYNC_AIC_FLAG+slot`、`+slot+FLAG_ID_MAX`、`+slot+1`、`+slot+1+FLAG_ID_MAX`），对应 ping/pong × sub-block 0/1。
+- **AIV 侧**：只操作 2 个 flag（`AIC_SYNC_AIV_FLAG+slot`、`+slot+1`），不显式操作 `+FLAG_ID_MAX`（硬件自动映射）。
+
+## 4. InitWorkspaceGlobal
+
+workspace 初始化 + `SyncAll` 已从 PerTileEpilogue 的 `Init` 中移除，移到两阶段 kernel 的 `InitWorkspaceGlobal`（在 `Cv1Kernel` 之前执行，直接实现初始化逻辑，不依赖 epilogue 实例）：
+
+- 所有核（含 idle）在 `InitWorkspaceGlobal` 执行路径上（两阶段 kernel 的 `operator()` 无 idle return）
+- AIV 执行 workspace 初始化（VF `Duplicate` 填充 UB → `V_MTE3` 同步 → MTE3 `CopyUB2GM` 分核并行写 GM），AIC 直接到达 `SyncAll` 等待
+- 分核策略：`totalElems = cubeCoreNum * M`，按 `GetBlockNum() * GetTaskRation()` 均分到全部 AIV
+- softmax 变体：onlineMax = -inf, onlineSum = 0；reduce 变体：partialResult 按归约类型初始化
+- `SyncAll` 保证 workspace 初始化完成后才进入 Phase 1
+- 完整实现见 [cv1_v2 适配指导](cv1-v2-adaptation-for-softmax-reduce.md) §5 代码骨架中的 `InitWorkspaceGlobal`
+
+**原因**：`kernel_matmul_fixpipe_opti.h` 在 idle 核 return 之后才调用 `epilogueOp.Init()`，idle 核不到达 `Init` 中的 `SyncAll` → 死锁。移到两阶段 kernel 后，所有核都经过 `InitWorkspaceGlobal`。
+
+PerTileEpilogue 的 `Init` 只保留参数设置 + `InitSyncFlag`（`if ASCEND_IS_AIV` 保护）。
+
+## 5. Idle 核处理
+
+`kernel_matmul_fixpipe_opti.h` 的 idle 核处理：
+
+```
+curBlockIdx >= realCoreNums → return (跳过 Init + tile loop)
+```
+
+- **Phase 0 `InitWorkspaceGlobal`**（两阶段 kernel）：所有核到达，包括 idle 核
+- **Phase 1 CV sync 构造/析构**：idle 核也构造/析构 epilogue 栈对象。CrossCore sync（构造 set flag，析构 wait flag）自身配平。HardEvent sync 只在 active 核执行（idle 核未调 `Init` → `initialized_=false` → 析构跳过 `CleanUpSyncFlag`）
+- **Phase 1 `SyncAll`**（两阶段 kernel Phase 2 之前）：所有核到达
+- **Phase 2 `ReduceAll`**：`myRows_==0` 时内部直接 return
+
+## 6. PerTileEpilogue 的 HardEvent 生命周期
+
+PerTileEpilogue 内部使用 3 个 HardEvent flag（`ZERO_FLAG=0`）做 MTE2/V/MTE3 管线同步：
+
+| 事件          | set 时机          | wait 时机            | 用途                        |
+| ------------- | ----------------- | -------------------- | --------------------------- |
+| `V_MTE2`    | V 计算完成        | 下一 tile MTE2 读 GM | 保证 V 写完 UB 后 MTE2 才读 |
+| `MTE3_V`    | MTE3 写回完成     | V 读取前             | 保证 MTE3 写完 UB 后 V 才读 |
+| `MTE3_MTE2` | MTE3 写回 GM 完成 | 下一 tile MTE2 读 GM | 保证 GM 数据可见            |
+
+`InitSyncFlag` 在 tile loop 前预置这 3 个 flag（set 一次）。
+`CleanUpSyncFlag` 在 tile loop 后消耗这 3 个 flag（wait 一次）。
+配平关系：每个 flag 在整个生命周期中 set 次数 = wait 次数 + 1（InitSyncFlag 预置 1 个，CleanUpSyncFlag 消耗 1 个）。
+
+## 7. 模板匹配优先级
+
+适配后的特化与 `cv1_v2` 的 `Enable_` 都是 `void`（默认），模板参数列表相同。如果两个特化同时存在于编译单元中，编译器会报歧义错误。
+
+**解决方法**：项目只需包含适配后的 `matmul_softmax_kernel.h`，不同时包含原始 `group_matmul_kernel_cv1_v2.h`。如果项目同时需要两个场景（per-token-quant + softmax），则需要在适配后的特化中增加 ScheduleType 约束以区分。