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

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/flashattention/foundation/roofline.md

@@ -0,0 +1,227 @@
+# FlashAttention 类算子 — 基本块与 Roofline 分析
+
+> 本文档定义 FA 类算子**基本块(Bq, Bk)选取**的 Roofline 方法论,承接 [`design/shape.md` §3](../design/shape.md)(N3)。
+> **前置**:已完成 [`fundamentals.md`](./fundamentals.md) 分析产出(选型结论 + shape 边界 + 性能精度目标)。
+> **产出去向**:本文推导出的 `mEff` / `Bk` / 性能区制,是 [`design/shape.md` §5 多核](../design/shape.md)、[`design/resources.md` §1 内存](../design/resources.md)、[`design/execution.md` §3 流水/同步](../design/execution.md) 的输入,不可在完成本文推导前凭经验选取。
+> **命名说明**:`mEff` / `curG` 等为方法论抽象名,对应的公开 API 见 [`fundamentals.md` §0](./fundamentals.md)。
+
+---
+
+## §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)`(建模 artifact),让人误以为 FA 永远到不了 compute-bound;
+> - 掩盖真正的第三瓶颈(AIV/片上吞吐),而它恰恰是 mix kernel 最常见的瓶颈。
+>
+> **正确做法**:三个通道各自独立建模,性能 = 三个 ceiling 取 **min**;瓶颈 = 限制项。
+
+---
+
+## §2 三通道 Roofline 模型
+
+### §2.0 GQA 多头合并:mEff 的定义
+
+FA 类 Mmad 的有效 m 维不是 Bq 本身,而是:
+```
+mEff = Bq × curG
+```
+curG = 同一 kvHead 下合并到一个 task 的 qHead 数(≤ G = Hq/Hkv,见 [`fundamentals.md` §3.2 I2](./fundamentals.md))。
+
+> 记号约定:`Bq` 指名义 Q 块大小,`curBq` 指某 task 的实际处理量(尾块 `curBq < Bq`);同理 `curG ≤ G`。容量校验用实际量 `mEff = curBq × curG`,块尺寸规划用名义 `Bq × G`。下文在不涉及尾块时统一写 `mEff = Bq × curG`。
+
+- **Prefill**(Sq 较大):Bq 本身足够大,mEff 主要受 L0A 容量约束,curG 可能 < G
+- **Decode**(Sq=1):Bq=1,`mEff = curG`,应最大化 curG = G
+
+**mEff 是 FA Roofline 的核心自变量**——它同时决定 AI 和三通道的相对松紧。
+
+### §2.1 单 task 的 FLOPs(遍历全 Sk)
+
+两个 GEMM,各遍历全 Sk:
+```
+C1 (Q·K^T):  2 × mEff × Sk × D
+C2 (P·V):    2 × mEff × Sk × D
+FLOPs_total = 4 × mEff × Sk × D
+```
+
+> **causal 的影响不在 AI**:causal / 下三角 mask 下,被完全 mask 的 tile 被跳过——**FLOPs 与对应的 K/V HBM 加载同比例减少**(平均有效 KV 长度约 Sk/2)。由于 §2.2 的 AI 推导中 Sk 会约掉,**AI ≈ 不变**;causal 真正影响的是**绝对耗时**与**核间负载均衡**(见 [`design/shape.md` §5.5](../design/shape.md)),不是算术强度。跳过完全屏蔽 tile 时的**正确性要求**(C1、V1 都要跳过,mask 值用大有限负数防 NaN)见 [`design/execution.md` §1](../design/execution.md)(N4 softmax)。
+
+### §2.2 通道 2:HBM 带宽与 AI_HBM(主 Roofline)
+
+**单 task 的 HBM 流量**(用户张量,遍历全 Sk):
+
+| 张量 | 流量 | 说明 |
+|------|------|------|
+| K 加载 | `Sk × D × sizeof(T)` | 全序列加载一次 |
+| V 加载 | `Sk × D × sizeof(T)` | 全序列加载一次 |
+| Q 加载 | `mEff × D × sizeof(T)` | 驻留(L1),摊薄 |
+| O 写回 | `mEff × D × sizeof(T)` | 末块写出 |
+| **O_acc streaming**(仅 streaming UB 模式)| `2 × mEff × D × sizeof(acc) × (Sk/Bk)` | 每个 s2 chunk 读回+写出 O_acc,共 Sk/Bk 次 |
+
+`Sk ≫ mEff` 时(典型),K/V 主导:
+```
+Bytes_HBM ≈ 2 × Sk × D × sizeof(T)  +  2 × mEff × D × sizeof(acc) × (Sk/Bk)
+```
+
+**算术强度(对 HBM)**:
+```
+AI_HBM = FLOPs_total / Bytes_HBM
+```
+
+忽略 O_acc streaming 项(Bk 足够大时该项小)时的**清晰上界**:
+```
+AI_HBM ≈ 4·mEff·Sk·D / (2·Sk·D·sizeof(T)) = 2·mEff / sizeof(T)
+```
+
+**关键结论**(与 [`base_design.md` §2.2-§2.3](../subfamilies/base_design.md) 一致):
+- **AI_HBM ∝ mEff**(不封顶在 D/sizeof(T))
+- Decode(mEff = G):`AI_HBM = 2G / sizeof(T)`,故 **decode 的 AI ∝ G**,GQA group 合并是提升 AI 的唯一杠杆
+- **Bk 通过 O_acc streaming 项影响 AI**:streaming 模式下增大 Bk 减少 O_acc 往返次数(Sk/Bk),从而降低 HBM 流量、提升 AI。非 streaming(O_acc 驻 UB)下 Bk 对 AI 无直接影响,仅减少 s2 loop 切换开销
+
+**HBM ceiling**:
+```
+Perf_HBM = Peak_HBM_BW × AI_HBM
+ridge_HBM = Peak_CUBE_FLOPS / Peak_HBM_BW   (FLOPs/Byte)
+AI_HBM < ridge_HBM  → 该通道可能是瓶颈(HBM-bound)
+```
+
+### §2.3 通道 3:跨核/片上吞吐(AIV-bound 校核)
+
+FA 是 mix kernel:AIC 算 GEMM 的同时 AIV 算 softmax + 做片上握手。若 **AIV 端吞吐 < AIC 端吞吐**,即使 HBM 与 Cube 都不饱和,算子仍被 AIV 拖住(cross-core-bound)。
+
+**AIV 端每 tile 的工作量**:
+- softmax over `[mEff, Bk]`:ReduceMax / Exp / ReduceSum,∝ mEff·Bk
+- 片上握手 movement(不占 HBM,占片上 SRAM 带宽):
+  - S:L0C→UB(Fixpipe),`mEff × Bk` 元素
+  - P:UB→L1,`mEff × Bk` 元素
+  - PV:L0C→UB,`mEff × D` 元素
+
+**校核判据(吞吐平衡)**:
+```
+T_AIC(tile) ≈ FLOPs(tile) / (Peak_CUBE_FLOPS × cube_util)
+T_AIV(tile) ≈ softmax_ops(mEff·Bk) / AIV_vector_throughput
+              + onchip_bytes(mEff·Bk) / Peak_onchip_BW
+
+cross-core-bound  ⟺  T_AIV > T_AIC
+```
+
+**主杠杆**(见 [`design/execution.md` §3.2](../design/execution.md) 跨核同步):
+- 提高 AIC:AIV 比例(如 `__mix__(1,2)` → 更多 AIV)
+- 减小握手粒度、per-stage 同步、双缓冲让 AIC/AIV 重叠
+- 减少 PipeBarrier 冗余(< 30%,见 [`design/execution.md` §3.4](../design/execution.md))
+
+> **与旧模型的关系**:旧模型的"L2 流量项"实际是本通道的片上握手 movement,不应记为 HBM/L2 带宽下的 AI 分母项,而应作为**独立的 AIV/片上吞吐校核**。
+
+### §2.4 通道 1:Cube 算力(compute ceiling)
+
+```
+Perf_compute = Peak_CUBE_FLOPS × cube_util
+```
+cube_util 主要由 Mmad m/n/k 对齐到 16 的倍数决定(见 §4 杠杆表)。
+
+### §2.5 三通道取 min
+
+```
+Perf ≈ min( Perf_compute,  Perf_HBM,  Perf_crosscore )
+瓶颈 = 三者中最小的那个通道
+```
+
+| 区制 | 判据 | ceiling | 主杠杆 |
+|---|---|---|---|
+| **Compute-bound** | AI_HBM ≥ ridge_HBM 且 AIC 吞吐最低 | `Peak_CUBE × util` | Mmad 对齐、Cube/Vector 重叠、减 PipeBarrier |
+| **HBM-bound** | AI_HBM < ridge_HBM 且 HBM 吞吐最低 | `Peak_HBM × AI_HBM` | 增大 mEff(∝AI)、Q 驻 L1、增大 Bk 减 O_acc 往返 |
+| **Cross-core-bound** | T_AIV > T_AIC | AIV/片上吞吐 | 提 AIC:AIV 比、减握手粒度、双缓冲、减 PipeBarrier |
+
+FA 类在常见 D 档位、mEff 较小时通常先撞 **HBM-bound 或 cross-core-bound**;通过增大 mEff 提升 AI 后,可能转入 compute-bound 或 cross-core-bound。
+
+---
+
+## §3 基本块可行域:下界(性能)与上界(硬件)
+
+### §3.1 下界 — Roofline 反推最小 mEff
+
+HBM-bound 下 `Perf ∝ AI_HBM ∝ mEff`,需要 mEff 足够大才能达到可接受性能。从 `AI_HBM = 2·mEff/sizeof(T)` 反推:
+```
+目标 AI = α × ridge_HBM   (α 为可接受的 ridge 占比,如 0.3~0.5)
+→ mEff_min = ceil(α × ridge_HBM × sizeof(T) / 2)
+```
+
+Decode 场景 mEff = curG ≤ G:若 `mEff_min > G`,说明该 shape 下 HBM-bound 无法靠增 mEff 突破 → 依赖流水隐藏延迟(见 §4)或 split-KV reduce(见 [`design/shape.md` §2](../design/shape.md) N2 启用判据)。
+
+### §3.2 上界 — 硬件容量约束最大 mEff / Bk
+
+基本块受三层硬件约束,取三者交集:
+
+1. **UB 约束**(主约束,见 [`design/resources.md` §1.1](../design/resources.md)):所有 UB buffer 总和 ≤ UB 容量。V1-chunk 模式下 softmax 状态 buffer(max/sum/expMax)是全 mEff 常驻项,随 mEff 线性增长(每行一个 datablock,见 §4.1 说明)
+2. **L1 约束**(见 [`design/resources.md` §1.3](../design/resources.md)):A1 端口 `mPad × D × sizeof(T) × rotation_slots ≤ L1_A1_port`;B1 端口 `Bk × D × sizeof(T) × rotation_slots ≤ L1_B1_port`
+3. **L0 约束**(见 [`design/resources.md` §1.4](../design/resources.md)):C1 输出 `S = [mEff, Bk]` 与 C2 输出 `[mEff, D]` 都落 L0C,但两个 GEMM **时间复用**同一 L0C(C1 的 S 经 Fixpipe 撤出后 C2 才写 PV),故 L0C 需满足二者中较大者:`max(mEff × Bk_pad, mEff × D_pad) × sizeof(float) ≤ L0C`。Bk 常大于 D,故 C1 项常为 L0C 的绑定约束
+
+**V1 两模式与上界的关系**:
+
+| 模式 | 触发条件 | v1In 占用 | v1Out 占用 |
+|------|---------|----------|----------|
+| V1-fit | `mEff × Bk_pad × sizeof(float) ≤ UB 单槽容量` | `mEff × Bk_pad × 4` | `mEff × Bk_pad × 2` |
+| V1-chunk | 上述不满足 | `chunkRows_v1 × Bk_pad × 4` | `chunkRows_v1 × Bk_pad × 2` |
+
+### §3.3 硬件常量来源
+
+所有 Peak 值与容量必须**运行时查询**,禁止硬编码:
+- `Peak_CUBE_FLOPS` / `Peak_HBM_BW`:平台规格(见 `/npu-arch`)
+- UB / L1 / L0 容量:`PlatformAscendC::GetCoreMemSize(...)` 系列
+
+---
+
+## §4 场景特化:Prefill / Decode / Causal
+
+| 场景 | mEff 来源 | 典型瓶颈 | 首要杠杆 |
+|------|----------|---------|---------|
+| **Prefill**(Sq 大)| Bq 大,mEff 受 L0A 约束,curG 可 < G | compute 或 cross-core | 增大 Bq 提 AI;Mmad 对齐;流水重叠 |
+| **Decode**(Sq=1)| mEff = curG ≤ G | HBM 或 cross-core(AI 天花板低)| 最大化 curG=G;核数富余时 split-KV reduce |
+| **Causal**(叠加)| 同上 | 同上 + 负载不均 | AI 近似不变(FLOPs 与 K/V 字节同比例减);zigzag/剪枝均衡(见 optimization §4.2)|
+
+---
+
+## §5 量化路径的 AI 修正
+
+量化 dtype 下 K/V 的 HBM 流量按量化字节宽计:
+```
+Bytes_HBM ≈ 2 × Sk × D × sizeof(quant_T)
+AI_HBM = 2·mEff / sizeof(quant_T)
+```
+
+**fp16(2B)→ fp8(1B)**:`sizeof` 减半 → **AI_HBM 翻倍(≈ +100%)**,不是旧混合模型给出的 +48%。+48% 是把片上握手混进 AI 分母的 artifact。
+
+量化路径的完整契约(scale 轴、c1v1Loop)见 [`quantization_design.md`](../subfamilies/quantization_design.md)。
+
+---
+
+## §6 产出清单
+
+进入 §3 多核切分前,DESIGN.md 必须展示以下推导(**每项展示算式,禁止只给结论**):
+
+- [ ] **AI_HBM 公式** + 代入 mEff/D/sizeof 的数值 + **ridge_HBM**
+- [ ] **三通道 ceiling** 各自估算 + **min 取哪个 → 瓶颈区制**
+- [ ] **cross-core 校核**:T_AIV vs T_AIC 的定性/定量判断
+- [ ] **mEff_min**(Roofline 下界)+ **mEff_max / Bk_max**(硬件上界)
+- [ ] **V1 模式判定**(V1-fit / V1-chunk)
+- [ ] **最终选定** mEff, Bk 值 + 在可行域中的相对位置
+- [ ] **场景**:prefill / decode /(是否 causal)
+- [ ] **性能上限估算** = min(三通道 ceiling)
+
+---
+
+## §7 参考资源
+
+| 主题 | 入口 |
+|---|---|
+| 设计流程(WHAT)| [`design/shape.md`](../design/shape.md) §3(N3)|
+| 数学模型与不变量 | [`fundamentals.md`](./fundamentals.md) |
+| 内存容量约束公式 | [`design/resources.md`](../design/resources.md) §1 |
+| 优化杠杆(流水 / 同步 / 负载)| [`design/execution.md` §3](../design/execution.md)、[`design/shape.md` §5.5](../design/shape.md) |
+| 变体 mEff/AI 特化 | [`base_design.md` §2](../subfamilies/base_design.md)、[`quantization_design.md` §2](../subfamilies/quantization_design.md) |
+| 平台规格(Peak 值)| `/npu-arch` |

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/flashattention/implementation_ref.md

@@ -0,0 +1,201 @@
+# FlashAttention 类算子 — 实现层参考(跨核同步 / Fixpipe / 平台参数)
+
+> 本文档承接 [`design/`](./design/_governance.md) 的**设计决策**(WHAT,节点 G→N12),提供进入实现时的**具体实现参考**(HOW-to-implement):跨核同步原语的模板参数、PIPE 映射、平台 modeId 取值、Fixpipe 参数结构体。
+> **定位**:`design/` 各节点只回答"该决策什么";本文件提供"选定后如何落地"。设计阶段无需加载本文件,进入实现阶段再查。
+> **来源纪律**:本文所有 API 签名、modeId 语义、flagId 规则、Fixpipe 参数均取自 **asc-devkit 公开文档**(路径见各节末尾)。实现时应以目标 CANN 版本的实际头文件与文档为准。
+
+---
+
+## §1 平台 modeId 取值(先确定目标平台)
+
+跨核同步用 `CrossCoreSetFlag<modeId, pipe>` / `CrossCoreWaitFlag<modeId, pipe>`(ISASI 公开 API)。`modeId` 决定同步范围:
+
+| modeId | 语义 | 适用 |
+|--------|------|------|
+| 0 | AI Core 核间同步(所有 AIC 之间 / 所有 AIV 之间)| 纯 Cube / 纯 Vector 全核同步 |
+| 1 | AI Core 内部,两个 AIV 之间 | AIV↔AIV |
+| 2 | AI Core 内部,AIC 与**所有** AIV 之间(广播式:AIC set 后两个 AIV 都放行;两个 AIV 都 set 后 AIC 才放行)| 混合场景全 AIV 参与 |
+| 4 | AI Core 内部,AIC 与**单个** AIV 之间(AIC set 后 AIV0 或 AIV1 放行;AIV0 或 AIV1 set 后 AIC 放行)| 混合场景单 AIV 独立握手 |
+
+> ⚠️ **平台支持差异**(asc-devkit 公开文档明确):
+> - **Ascend 950PR / 950DT**:支持 modeId 0 / 1 / 2 / 4
+> - **上一代产品(如 A2/A3)**:仅支持 modeId 0 / 1 / 2(**不支持 4**)
+>
+> FA 类是 AIC+AIV 混合 kernel,核内 AIC↔AIV 握手在 950PR 上用 **modeId=2 或 4**;若目标是 950PR 且希望 AIC 与单个 AIV 独立握手,用 **modeId=4**。**进入实现前必须先确认目标平台支持的 modeId 集合**,照抄不支持的 modeId 会编译/运行失败。
+
+**modeId=4 下的双 AIV flagId 映射**(asc-devkit 公开文档 `flagId取值范围说明`,950PR/950DT):
+
+```
+AIV0 set flagId 0-10  ↔  AIC wait flagId 0-10
+AIV1 set flagId 0-10  ↔  AIC wait flagId 16-26   (AIV1 相对 AIV0 偏移 16)
+AIC  set flagId 0-10  ↔  AIV0 wait flagId 0-10
+AIC  set flagId 16-26 ↔  AIV1 wait flagId 0-10
+```
+
+即 modeId=4 下 AIC 与两个 AIV 分别握手,AIC 侧针对 AIV1 的 flagId 需加 **16 偏移**。这与 modeId=2 的"广播式"(AIC 一次 set 通知所有 AIV)语义不同。
+
+> **来源**:`asc-devkit/docs/zh/api/SIMD-API/basic_api/sync_control/inter_core_sync/CrossCoreSetFlag_ISASI.md`(modeId 语义、modeId 支持取值、flagId 取值范围)。
+
+---
+
+## §2 flagId 冲突与 pipe 约束(asc-devkit 公开文档)
+
+> ⚠️ **flagId 冲突风险**(公开文档 `CrossCoreSetFlag_ISASI.md` 明确):
+> - **Matmul 高阶 API 内部使用 CrossCoreSetFlag**——不建议同时使用 CrossCoreSetFlag 与 Matmul 高阶 API,否则 flagId 冲突。Matmul 内部占用 flagId 范围 `[0, 2N-1]`(N=Matmul 对象数,最多 4 个 → 占用 `[0,7]`)。**此占用仅在实例化 Matmul 高阶对象(`matmul::Matmul<...>` / `REGIST_MATMUL_OBJ`)时成立;直接调用裸 `Mmad(...)` Cube 指令不占用任何 flagId**(裸指令无内部握手)。故 `[0,7]` 是否需规避,取决于本 kernel 用的是高阶 Matmul 对象还是裸 Mmad 指令。
+> - **SyncAll 硬件同步接口内部也使用 CrossCoreSetFlag**——占用 flagId `[11,14]`,**同样仅在实际调用 `SyncAll` 时成立**;未调用则该区间可用。
+>
+> 规避原则:先确认本 kernel 实际使用了哪些内部占用 flagId 的 API(高阶 Matmul 对象 / SyncAll),仅规避**实际被占用**的区间——不要因"FA 用 Mmad"就无条件规避 `[0,7]`(裸 Mmad 不占)。若拿不准,规避两区间是安全的保守做法,但应知其可能过度保守。
+
+**flagId 取值范围**:
+- modeId 0/1/2:`0-15`
+- modeId 4(950PR/950DT):见 §1 的 AIV0/AIV1 映射(0-10 与 16-26)
+
+> ⚠️ **不同生命周期事件必须用不同 flagId**。每个 flagId 对应一个**计数器**(set 加一 / wait 减一,见 §3 与 `CrossCoreSetFlag_ISASI.md`),不是电平。若把「跨 task 边界」事件与「loop 内 stage(如 V1 P-ready)」事件复用同一 flagId,边界 wait 会被**残留的 loop-stage token 提前满足** → task 间 workspace 提前复用 → **非确定性覆写**(高竞争 multi-task-per-core 场景才暴露,单 task 测不出)。规则:跨 task 边界 flag 与 loop 内 stage flag 分配**互不相同**的 flagId,且各自都避开 §2 上文**实际被占用**的区间(高阶 Matmul 对象 → [0,7];调用 SyncAll → [11,14];裸 Mmad 指令两区间均不占,可自由使用)。
+
+**pipe 模板参数约束**(公开文档 `pipe支持的流水类型说明`):
+- **modeId 0/1/2**:支持 `PIPE_V / PIPE_M / PIPE_MTE1 / PIPE_MTE2 / PIPE_MTE3 / PIPE_FIX`;**不支持 `PIPE_ALL` / `PIPE_S`**。
+- **modeId 4(950PR/950DT)**:在上述基础上**额外支持 `PIPE_S`**;仅不支持 `PIPE_ALL`。
+- 950PR/950DT 上 modeId 与 pipe 模板参数**生效**,`CrossCoreWaitFlag` 阻塞**指定流水**的后续指令;上一代产品上二者不生效,阻塞**全部流水**。
+
+> **来源**:`asc-devkit/docs/zh/api/SIMD-API/basic_api/sync_control/inter_core_sync/CrossCoreSetFlag_ISASI.md`、`CrossCoreWaitFlag_ISASI.md`。
+
+---
+
+## §3 跨核同步实现骨架(承接 design/execution.md §3.2 的架构模式选择)
+
+> [`design/execution.md §3.2`](./design/execution.md) 已完成两个正交决策:**架构模式**(单/双 AIV)+ **平台 modeId**(见 §1)。本节用 asc-devkit 公开原始 API `CrossCoreSetFlag/WaitFlag` 给出两种架构模式的实现骨架。
+
+**公开 API 签名**:
+```cpp
+template <uint8_t modeId, pipe_t pipe>
+__aicore__ inline void CrossCoreSetFlag(uint16_t flagId);
+
+template <uint8_t modeId = 0, pipe_t pipe = PIPE_S>
+__aicore__ inline void CrossCoreWaitFlag(uint16_t flagId);
+```
+
+> ⚠️ **必须显式指定模板参数**。`CrossCoreWaitFlag` 的默认 `modeId=0` 会等待 modeId-0 的 flagId 空间;若配对的 `CrossCoreSetFlag` 用了 `modeId=4`,两套 flagId 计数器**互相独立**,WaitFlag 永远等不到 → **死锁**。Set 与 Wait 两侧的 `modeId` 必须一致。
+
+### §3.1 模式 B:双 AIV 全参与(充分利用 Vector 算力)
+
+数据流:AIC 通过 Fixpipe(见 §4)将 Cube 输出分发到两个 AIV 的 UB,双 AIV 全程参与计算。modeId=4 下 AIC 需分别与 AIV0、AIV1 握手。
+
+```cpp
+// 平台: 950PR → CC_MODE = 4; A2/A3 → CC_MODE = 2
+constexpr uint8_t CC_MODE = 4;
+constexpr uint16_t AIV1_FLAG_OFFSET = 16;   // modeId=4 下 AIC↔AIV1 的 flagId 偏移
+
+// --- AIC 侧(生产方):算完 Cube → 通知两个 AIV ---
+// ... Fixpipe: L0C → UB ...
+AscendC::CrossCoreSetFlag<CC_MODE, PIPE_FIX>(flagId);                    // 通知 AIV0
+AscendC::CrossCoreSetFlag<CC_MODE, PIPE_FIX>(flagId + AIV1_FLAG_OFFSET); // 通知 AIV1
+
+// --- AIV 侧(消费方):等 AIC → 读 → 回通知 ---
+AscendC::CrossCoreWaitFlag<CC_MODE, PIPE_V>(flagId);   // 各 AIV 用自己的 0-10 flagId
+// ... softmax / accumulate ...
+AscendC::CrossCoreSetFlag<CC_MODE, PIPE_MTE3>(flagId); // 回通知 AIC
+
+// --- AIC 等两个 AIV 完成 ---
+AscendC::CrossCoreWaitFlag<CC_MODE, PIPE_MTE2>(flagId);                    // 等 AIV0
+AscendC::CrossCoreWaitFlag<CC_MODE, PIPE_MTE2>(flagId + AIV1_FLAG_OFFSET); // 等 AIV1
+```
+
+> 注:上例常量 `CC_MODE` / `AIV1_FLAG_OFFSET` 为算子自定义命名,值(4 / 16)来自 §1 公开文档规则。是否封装成 Buffer 管理类由实现自行决定;asc-devkit 公开 API 层面即上述 `CrossCoreSetFlag/WaitFlag`。
+
+### §3.2 模式 A(简化替代):单 AIV + AIV1 early-return
+
+数据流:AIC 只与 AIV0 握手,AIV1 在 Process() 入口 early-return。无需 AIV1 偏移。
+
+```cpp
+constexpr uint8_t CC_MODE = 4;  // 950PR
+
+// AIC → AIV0
+AscendC::CrossCoreSetFlag<CC_MODE, PIPE_FIX>(flagId);
+// AIV0 等待
+AscendC::CrossCoreWaitFlag<CC_MODE, PIPE_MTE2>(flagId);
+// AIV0 → AIC
+AscendC::CrossCoreSetFlag<CC_MODE, PIPE_MTE3>(flagId);
+// AIC 等待(仅一次)
+AscendC::CrossCoreWaitFlag<CC_MODE, PIPE_MTE2>(flagId);
+```
+
+- **AIV1 行为**:必须在 Process() 入口 `if (GetSubBlockIdx() != 0) return;` early-return,否则其 WaitFlag 等不到信号 → 挂死。
+- **代价**:浪费一半 Vector 算力。
+
+### §3.3 PIPE 映射约定(FA 4-stage)
+
+| 方向 | 场景 | SetFlag PIPE | WaitFlag PIPE |
+|------|------|-------------|---------------|
+| AIC → AIV | Cube 完成(L0C→UB Fixpipe)通知 Vector | `PIPE_FIX` | `PIPE_V` 或 `PIPE_MTE2` |
+| AIV → AIC | Vector 完成(P 写 GM/L1)通知 Cube | `PIPE_MTE3` | `PIPE_MTE2` |
+
+pipe 必须落在 §2 允许集合内(不含 `PIPE_ALL` / `PIPE_S`)。
+
+### §3.4 架构模式决策建议
+
+| 场景 | 推荐架构 | 平台 modeId | 理由 |
+|------|---------|-----------|------|
+| FA/GQA(A5/950PR),追求吞吐 | 模式 B | 4 | 双 AIV 充分利用 Vector 算力 |
+| FA/GQA(A2/A3)| 模式 B | 2 | 上一代仅支持 modeId 0/1/2 |
+| 快速原型验证 | 模式 A | 按平台 | 代码更简单,但浪费一半 Vector 算力 |
+
+---
+
+## §4 Fixpipe 输出参数(承接 design/execution.md §3.5)
+
+Fixpipe(L0C→UB/GM)的参数结构体**因平台而异**(asc-devkit 公开文档 `Fixpipe_L0CToUB.md`):
+
+| 平台 | 参数结构体 |
+|------|-----------|
+| Ascend 950PR / 950DT | `FixpipeParamsArch3510<config.format>` |
+| Atlas 200I/500 A2 推理产品 | `FixpipeParamsM300` |
+
+**Fixpipe 随路能力**(950PR/950DT,公开文档):搬运过程中支持随路格式转换(F32→F16 / F32→BF16 为纯 Cast,非量化)、随路量化(scalar/tensor)、随路 ReLU、随路通道合并。
+
+**FA 用法要点**:
+- C1 的 S 矩阵、C2 的 PV 矩阵均需保持 **fp32** 输出到 UB(V1/V2 在 UB 上做 fp32 计算),**不使用随路 Cast**。
+- 若需把 Cube 输出分发到双 AIV,依平台参数结构体的相应字段配置(具体字段名以目标 CANN 版本 `FixpipeParamsArch3510` 文档为准)。
+
+> **来源**:`asc-devkit/docs/zh/api/SIMD-API/basic_api/cube_compute_ISASI/cube_compute_store/Fixpipe_L0CToUB.md`;参数结构体字段见 `Fixpipe搬运参数（FixpipeParamsArch3510、FixpipeParamsM300）结构体说明`。
+
+---
+
+## §5 清单 3(cross-core sync 时序)—— 跨核同步实现自检清单
+
+> 本清单即通用自检 **清单 3(cross-core sync 时序)**,由 [`design/execution.md §3.2`](./design/execution.md) 的跨核同步决策引出。各变体 Self-Check 中"继承 清单 3"即指本节。
+
+**通用**:
+- [ ] AIV → AIC 的通知在数据写完之后
+- [ ] AIC → AIV 的等待在数据读取之前
+- [ ] 同核内 pipe 同步用 `SetFlag/WaitFlag`,跨核用 `CrossCoreSetFlag/WaitFlag`,不混用
+- [ ] GM 自读自写段有明确的同步机制
+- [ ] 跨阶段依赖用对应 `HardEvent`,不用 `PipeBarrier` 替代
+- [ ] PipeBarrier 冗余率 < 30%(见 design/execution.md §3.4)
+
+**模板参数(最易踩坑,GQA 死锁根因)**:
+- [ ] `CrossCoreSetFlag<modeId, pipe>` 与配对的 `CrossCoreWaitFlag<modeId, pipe>` **modeId 一致**(不能一侧显式 4、另一侧用默认 0)
+- [ ] `CrossCoreWaitFlag` 显式指定了 `modeId` 与 `pipe` 模板参数(默认 modeId=0 会等错 flagId 空间)
+- [ ] pipe 未使用 `PIPE_ALL` / `PIPE_S`
+- [ ] 目标平台确实支持所选 modeId(950PR 支持 0/1/2/4;A2/A3 仅 0/1/2)
+
+**flagId 管理**:
+- [ ] 用户自定义 flagId 避开 Matmul 高阶 API 占用区间(`[0, 2N-1]`,最多 `[0,7]`)与 SyncAll(`[11,14]`)
+- [ ] 同一 flagId 计数器设置次数在允许范围内
+- [ ] modeId=4(950PR)下 AIC↔AIV1 的 flagId 已加 16 偏移
+
+**架构模式**:
+- [ ] 模式 B:AIC 对 AIV0/AIV1 分别 Set/Wait(modeId=4 下两次,AIV1 加 16 偏移);AIV1 **不** early-return
+- [ ] 模式 A:AIV1 在 Process() 入口 early-return;AIC 只 Set/Wait 一次
+
+---
+
+## §6 参考资源
+
+| 主题 | 入口 |
+|---|---|
+| 设计决策(WHAT)| [`design/execution.md`](./design/execution.md) §3 |
+| CrossCoreSetFlag/WaitFlag 公开文档 | `asc-devkit/docs/zh/api/SIMD-API/basic_api/sync_control/inter_core_sync/` |
+| Fixpipe(L0C→UB)公开文档 | `asc-devkit/docs/zh/api/SIMD-API/basic_api/cube_compute_ISASI/cube_compute_store/` |
+| 平台差异 / 架构基础 | `/npu-arch` |
+| Ascend C API 用法(Mmad / LoadData / Fixpipe / CrossCore)| `/ascendc-api-best-practices` |
+| 通用编码规范 / 入口属性 | `ops-direct-invoke` plugin `workflows/development-guide.md` |