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

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

@@ -0,0 +1,138 @@
+# FlashAttention 类算子 — 正交维度组合规则
+
+> 本文档定义在**基础 FA** 核心算子(含 GQA / MHA / MLA 三形态)上正交叠加的两类 trait(量化 / 稀疏)与 feature flags 之间的交互规则。
+> 多个 `subfamilies/` / `specialization/` 文件同时加载时(例如"MXFP8 GQA + Causal"),必须按本文档校核冲突。
+
+---
+
+## §1 正交维度交互总表
+
+```
+核心算子:基础 FA(含 GQA / MHA / MLA 三形态,沿 head / hidden-dim 变化)
+  │
+  ├── 正交叠加 trait(各自独立 on/off,叠在基础 FA 上):
+  │     量化轴:非量化 / MXFP8 / INT8 / AntiQuant
+  │     稀疏轴:非稀疏 / BlockSparse / SlidingWindow / ...
+  │
+  └── feature flags(可叠加在任意组合上):
+        PSE / RoPE / Sink / PostQuant / Prefix / ChunkedPrefill / ...
+```
+
+**量化 × 稀疏 组合成熟度**(每格 = 基础 FA + 该量化 + 该稀疏):
+
+```
+                 ┌──── 稀疏轴 ────┐
+                 │ 非稀疏 │  稀疏 │
+       ┌─────────┼────────┼───────┤
+量化轴 │ 非量化  │   ✓    │  📋   │
+       │ MXFP8   │   ✓    │   ?   │
+       │ INT8    │   ✓    │   ?   │
+       │ AntiQ   │   ✓    │   ?   │
+       └─────────┴────────┴───────┘
+```
+
+✓ = 已验证或已有扩展契约  📋 = 占位骨架(未落地)  ? = 未探索
+基础 FA 的 GQA / MHA / MLA 三形态是核心算子内部沿 head / hidden-dim 的变化,不是叠加 trait,故不进本正交矩阵。
+
+---
+
+## §2 交互规则
+
+### §2.1 基础子族 × 量化
+
+| 交互点 | 规则 | 加载来源 |
+|---|---|---|
+| **Mmad 模板** | 基础子族决定 fm/filter 的角色(Q/K/P/V),量化路径决定 dtype 链(fm_dtype / filter_dtype / acc_dtype)| `base_design §8` + `quantization_design §1` |
+| **P-scale 回传(MXFP8 特有)** | AIV 做完 SoftmaxFlashV2 后对 P 做量化 → P 数据(fp8)+ P-scale(e8m0) 写回 L1P 段 → AIC BMM2 读取时同时加载 P 数据 + P-scale | `quantization_design §6` |
+| **I5 不变量校核** | V scale 必须沿 PV Mmad 的 K-mmad = S_k 量化,**不能**沿 D | `fundamentals §3.5` + `quantization_design §10 Q1` |
+| **c1v1Loop 子循环** | MXFP8 量化路径在 BMM1 阶段引入 c1v1Loop(K 维按 256 切片),基础子族决定 task 维度不变 | `quantization_design §6` |
+| **V2 末块量化链** | V2 末块的 O 在写回前需要做 fp32 → 量化 dtype cast + scale 生成,该两步链的 dtype 选择取决于输出 dtype | `quantization_design §8.3` |
+
+**冲突解决优先级**:
+1. **I5 不变量优先**:任何与 I5 冲突的设计必须拒绝(例如 V scale 沿 D)
+2. **量化路径的 MX Mmad(MmadMx/MxMatmul)优先**:基础子族无法改变量化 Mmad 的 API 选择
+3. **c1v1Loop 仅在量化路径激活**:非量化 GQA/MLA 不需要 c1v1Loop
+
+### §2.2 基础子族 × 稀疏
+
+| 交互点 | 规则 | 加载来源 |
+|---|---|---|
+| **Causal mask** | 与 GQA 的 Bq-major mEff 行排布交互:mask 模板只需一份 + 整体平移 curG 次 | `base_design §10.2 清单 5` |
+| **SlidingWindow** | 影响 task 维度构造(sparse 模式可能跳过部分 KV chunk),但 task 维度基础结构仍按基础子族 | `sparse_design §3` |
+| **BlockSparse** | sparse pattern 粒度决定是否能走 Cube(block-sparse 可走,token-level 需 gather) | `sparse_design §1` |
+
+**冲突解决优先级**:
+1. **基础子族优先**:sparse pattern 不能破坏 GQA 同 kvHead 同任务不变量(I2)
+2. **Causal 与 SlidingWindow 互斥**:同一算子不能同时启用两种 mask
+
+### §2.3 量化 × 稀疏
+
+| 交互点 | 规则 | 加载来源 |
+|---|---|---|
+| **Sparse mask 与 scale 轴** | sparse pattern 跳过的 KV chunk 对应的 scale 段也必须跳过,否则 scale 与数据不对齐 | `quantization_design §4` + `sparse_design §4` |
+| **Workspace 段叠加** | 量化 scale staging 段 + sparse 索引段同时存在,需要分别计算容量 | `quantization_design §4` + `sparse_design §4` |
+
+**冲突解决优先级**:
+1. **I5 不变量优先**:sparse 不能破坏 scale 轴对齐
+2. **量化路径的 c1v1Loop 不受 sparse 影响**:c1v1Loop 是按 K 维切片,与 sparse pattern 正交
+
+### §2.4 Feature flags × 其他维度
+
+| feature flag | 与基础子族 | 与量化 | 与稀疏 | 加载来源 |
+|---|---|---|---|---|
+| **PSE**(partial sum extension)| 无特化 | 无特化 | 无特化 | `feature_flags §1` |
+| **RoPE** | 需要在 Q/K 加载后做 RoPE 旋转,影响 L1→L0 加载路径 | 与量化 dtype 无冲突 | 与 sparse 无冲突 | `feature_flags §2` |
+| **Sink** | 无特化 | 无特化 | 与 Causal/SlidingWindow 组合(保留首尾 token) | `feature_flags §3` |
+| **PostQuant VF** | 输出 dtype 走量化路径,与基础子族的 V2 末块量化链耦合 | **强耦合**:PostQuant 本质是输出端的量化,必须先加载 `quantization_design §1` | 无特化 | `feature_flags §4` |
+| **Prefix** | 无特化 | 无特化 | 无特化 | `feature_flags §5` |
+| **ChunkedPrefill** | 影响 task 维度构造(Sq 维也切),但基础结构仍按基础子族 | 无特化 | 与 Causal 组合时需要处理 chunk 边界 mask | `feature_flags §6` |
+
+**冲突解决优先级**:
+1. **PostQuant 与量化路径强耦合**:PostQuant 的输出 dtype 复用量化路径的 V2 末块量化链
+2. **Sink 与稀疏 mask 交互**:Sink 保留首尾 token,与 SlidingWindow/Causal 组合时需要显式处理 mask 边界
+3. **RoPE 在量化路径下**:RoPE 旋转在 fp32 累加器上执行,不受输入量化 dtype 影响
+
+---
+
+## §3 冲突解决优先级总表
+
+当多个 `subfamilies/` 文件同时加载时,按以下优先级解决冲突:
+
+| 优先级 | 规则 |
+|---|---|
+| **P1** | I1-I5 不变量(`fundamentals §3`):任何变体组合都不能违反 |
+| **P2** | 量化路径的 I5(scale 轴对齐):不可妥协 |
+| **P3** | 基础子族的 task 维度构造:不能破坏 GQA I2 |
+| **P4** | feature flags 正交性:不能破坏其他维度的不变量 |
+| **P5** | 编译宏笛卡尔积:按 `design/execution.md §2`(N8 编译期特化)识别需要分离的 target |
+
+---
+
+## §4 加载协议
+
+**Architect 加载流程**:
+
+1. 读 `patterns.md` §2 确定基础子族 → 加载对应 `subfamilies/` 文件
+2. 若用户需求包含量化 dtype → 额外加载 `quantization_design.md` + 按 §2.1 校核
+3. 若用户需求包含 sparse pattern → 额外加载 `sparse_design.md` + 按 §2.2/§2.3 校核
+4. 若用户需求包含 feature flags → 额外加载 `feature_flags.md` 对应章节 + 按 §2.4 校核
+5. 若存在多维度叠加 → 按 §3 优先级解决冲突
+
+**Developer 实现流程**:
+
+1. 按 DESIGN.md 中 Architect 选定的变体组合,读取对应 `subfamilies/` 文件的 Self-Check 清单(§10)
+2. 按本文档 §2 的交互表,逐项校核实现是否满足交互规则
+3. 按本文档 §3 优先级表,在精度回归中优先验证 P1-P3 不变量
+
+---
+
+## §5 组合示例
+
+| 场景 | 加载文件 | 关键交互点 |
+|---|---|---|
+| GQA + fp16 + Causal | `base_design` | Causal mask 与 GQA Bq-major 行排布 |
+| GQA + MXFP8 + Causal | `base_design` + `quantization_design` + §2.1 | P-scale 回传 + Causal mask + I5 校核 |
+| GQA + MXFP8 + SlidingWindow | `base_design` + `quantization_design` + `sparse_design` + §2.1 + §2.3 | P-scale + sparse 索引 + I5 |
+| MLA + fp16 | `base_design §11` | latent absorption 链 |
+| GQA + PostQuant | `base_design` + `feature_flags §4` + §2.4 | V2 末块量化链 |
+| GQA + RoPE + Causal | `base_design` + `feature_flags §2` | RoPE 在 L1→L0 路径,mask 在 V1 |

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

@@ -0,0 +1,173 @@
+# FlashAttention 类算子 — 5 扩展点框架
+
+> 本文档定义 FA 各变体在通用骨架之外的 **5 个扩展点**。确定变体后,本文告诉你**只需要在哪些点上特化**,其余部分按通用骨架。
+> **通用设计流程** → [`design/`](../design/_governance.md)(节点 G→N12);**变体特定契约** → 对应 `subfamilies/` 文件;**选型入口** → [`patterns.md`](../patterns.md)。
+> **加载时机**:选型确认变体后(节点 N0 之后,见 [`design/_governance.md` §1](../design/_governance.md))加载本文件,确定该变体在 5 个扩展点上的特化范围。
+
+---
+
+## §1 5 扩展点 capability-map
+
+为了让上层在不同变体间复用同一份 Tiling 决策框架,本节定义 5 个扩展点。每个变体在这 5 个点上特化,通用骨架(`design/` 各节点 N1-N12)对所有变体一致。
+
+### §1.1 ConstInfo / RunInfo 字段
+
+| 字段类别 | 说明 |
+|---|---|
+| **ConstInfo 通用字段**(所有变体读)| `batchSize` / `qHeadNum` / `kvHeadNum` / `qSeqSize` / `kvSeqSize` / `headDim` / dtype / scale 等 |
+| **ConstInfo 变体特定字段** | 仅对应变体读;不读的变体字段保持默认值。例如 GQA 形态需要 group 合并相关字段、MLA 形态需要 latent 维度相关字段(具体字段名见各 `subfamilies/` 文件)|
+| **RunInfo 通用字段(per-task)**| 包含以下职责类别的字段:<br>· **任务标识**:batch / kvHead / Sq 块 / G 块等维度索引<br>· **块内偏移与实际尺寸**:`actS1Size` 类 / `actS2Size` 类 / m 维有效维 / m 维对齐维<br>· **边界标志**:跨 batch 重置、跨 s2 块首尾标志 等 |
+| **变体特定 task 结构** | FA / GQA / MHA 复用 RunInfo 通用结构;MLA 复用 + 加 latent 维元数据字段 |
+
+**设计原则**:
+- ConstInfo **单一来源**——所有变体字段并集存于同一结构体,变体不消费的字段保默认即可,避免多结构维护
+- 新增变体时优先扩 ConstInfo + 复用 RunInfo;仅当 task 维度本身不同时才另起 TaskInfo(典型见 `design/shape.md §2`(N2)描述的 split-KV reduce 并行模式)
+
+### §1.2 Cube 端扩展点
+
+| 扩展点 | 通用骨架 | 变体特化 |
+|---|---|---|
+| **是否走 Cube** | FA / GQA / MHA / MLA 走 Cube | 启用 split-KV reduce 并行模式时 partial 计算与 combine 可能由 Vector 直接做 |
+| **L1 rotation 深度** | task 级双缓冲 | 因变体而异(见下表)|
+| **L0 K-axis 分块** | 全变体通用 K-axis 分块 | 变体不变 |
+| **L1 M / N 轴分块** | 通用骨架,触发条件按容量校验 | 变体不变 |
+
+**L1 rotation 深度变体对照**:
+
+| 变体 | L1 QP 槽数 | L1 KV 槽数 | 依据 |
+|---|---|---|---|
+| FA / GQA 推理(默认)| 标准 task 级双缓冲 | 标准 task 级双缓冲 | GQA 中 K/V 在同 kvHead 内复用,标准深度即够 |
+| GQA prefill(高吞吐)| 同推理 | 推理深度 + 1 段预取(可选)| 长 KV 场景预取 1 个 chunk |
+| MLA | 较深(QP 多槽)| 较深(KV 多槽)| Latent absorption 需保留更长 K_compressed 历史 |
+
+**禁止**:把跨核握手槽(Cube↔Vector 跨核固定深度,见 `design/execution.md §3.3` slot 权威表)和 L1 rotation 槽(变体特定)写在同一常量。
+
+### §1.3 Vector 端扩展点
+
+| 扩展点 | 通用骨架 | 变体特化 |
+|---|---|---|
+| **Softmax 实现** | V1/V2 online softmax 算法模式(见 `design/execution.md §1` N4) | 可选 SoftmaxFlashV2 API 或手动指令级实现。启用 split-KV reduce 并行模式时,每核处理自己的 s2 切片,不走 stateful 累积 |
+| **计算链插入点** | C1 → V1(softmax)→ C2 → V2(streaming 归一化)| MLA 在 V1 之后插入 latent absorption 两步计算链 |
+
+**V2 rescale 模式**(通用,不依赖特定 API):
+
+| s2 位置 | 操作 | 说明 |
+|---------|------|------|
+| 非末轮 | V_accum = V_accum × expMax + P × V_new | rescale + 累加 |
+| 末轮 | V_out = (同上) / sum | rescale + 累加 + 归一化 |
+
+expMax = exp(old_max - new_max),由 V1 阶段输出。**禁止**:将 V1 的输出当作已归一化的 softmax 概率直接使用。
+
+> ⚠️ **行广播陷阱**:`expMax` 与 `sum` 是**行级量**——每行 1 个有效值(形如 `[m, 1]`,常按 32B 广播存储为 `[m, broadcast]`),而 `O_acc` / `V_out` 是 `[m, D]`。Ascend C 的矢量运算是**严格 element-wise、不自动做行广播**。因此 rescale(× expMax)与末块归一化(÷ sum)**不能**用两个 shape 不同的张量直接相乘,须**逐行**用"矢量 × 标量"的方式处理(取该行的标量值作用于整行 D 个元素),或先显式把行向量广播到 `[m, D]` 再 element-wise。具体 API 与签名以目标版本文档为准。
+
+### §1.4 Workspace 扩展点
+
+| 扩展点 | 通用骨架 | 变体特化 |
+|---|---|---|
+| **标准段** | 跨核握手段 + 自读自写段 + 任务级状态段 | FA / GQA / MHA 默认 task 级并行下走以上标准段组合 |
+| **变体新增段** | — | MLA 增 int32 中间段。启用 split-KV reduce 并行模式时另增 partial reduce 段 |
+
+### §1.5 Service 类划分约定
+
+**Service 类组织约定**:
+
+- 按 Cube 计算 / Vector 计算两条线**独立成 service 头**
+- 每个 service 头封装该端的 stage 实现
+- **base FA 变体共享 service 骨架**:MLA 属基础 FA 的 head / hidden-dim 变体(kvHeadNum=1 + latent absorption),其 latent absorption 计算链**在 base service 内以变体分支承接**,不单开独立 service 头。仅当出现真正正交、显著改变 task 维度的扩展(如 split-KV reduce 并行模式的纯 Vector 路径)时才另起 service 头
+
+| 变体 | service 类入口 | 关键计算链 |
+|---|---|---|
+| FA / GQA / MHA | Cube 服务 + Vector 服务(默认命名)| 标准 4 段 Q·K^T → Softmax → P·V → rescale |
+| MLA(base 内变体分支)| 复用 base Cube / Vector 服务,latent absorption 以变体分支承接 | 标准 4 段 + latent absorption 两步链 |
+| FlashDecoding 并行模式 | 仅 Vector 服务(无 Cube)| partial reduce + cross-block combine |
+
+---
+
+## §2 dtype 路径通用框架
+
+dtype 是 FA 类的一个独立维度,各变体都要面对。具体 dtype 路径见对应 `subfamilies/` 文件。
+
+### §2.1 fp16
+
+标准路径,所有变体默认支持。
+
+- Mmad 模板:`Mmad<float, half, half>`(fp16 × fp16 → fp32 accumulator)
+- V1 / V2 输出到 GM 的中间段与 KV_T 同型 = half
+- 所有 Cast 仅在 UB 上执行
+
+详见 [`base_design.md` §8](../subfamilies/base_design.md)。
+
+### §2.2 bf16
+
+**关键契约**:bf16 路径**与 fp16 路径同型**——V 全程 bf16,**无任何 Cast / pre-cast / Reinterpret 中转**。
+
+详见 [`base_design.md` §8](../subfamilies/base_design.md)。
+
+### §2.3 量化 dtype
+
+输入 / 输出 / 累加器走量化 dtype(int8 / FP8 / MX 类格式)。
+
+详见 [`quantization_design.md`](../subfamilies/quantization_design.md)。
+
+---
+
+## §3 变体扩展契约索引
+
+每个变体的扩展契约在独立的 `subfamilies/` 文件中展开:
+
+| 变体 | `subfamilies/` 文件 | 5 扩展点特化概要 |
+|------|-------------|-----------------|
+| FA / GQA(默认)| [`base_design.md`](../subfamilies/base_design.md)| mEff / curG / Bq-major / BSND 写回 |
+| MHA(G=1)| [`base_design.md`](../subfamilies/base_design.md)(§10.3 MHA 退化)| GQA 的退化特例 |
+| MLA(base 内变体分支)| [`base_design.md` §11](../subfamilies/base_design.md)| latent absorption / kvHeadNum=1 / int32 段(base FA 的 head/hidden-dim 变体,非独立子族)|
+| 稀疏 FA | [`sparse_design.md`](../specialization/sparse_design.md)| sparse pattern / KV chunk 跳过 |
+| 量化 FA | [`quantization_design.md`](../subfamilies/quantization_design.md)| I5 scale 轴对齐 / c1v1Loop / P-scale 回传 |
+
+---
+
+## §4 变体间禁止事项
+
+### §4.1 变体混用禁止
+
+同一算子内**禁止混用基础 FA 形态**:不能"主要是 GQA 但在某些路径上走 MLA latent absorption"。
+
+设计阶段 DESIGN.md §架构选型必须显式声明基础 FA 形态,后续 Tiling 决策 / Workspace 公式 / Service 类划分按所选形态对应表实施。并行策略(默认 / split-KV reduce)是独立维度,与形态正交。
+
+### §4.2 常量语义分离禁止
+
+以下三类槽数**必须用不同常量定义**,**禁止**共用一个常量:
+
+| 槽数 | 语义 | 决策位置 |
+|---|---|---|
+| 跨核握手槽 | Cube↔Vector 跨核握手 buffer 的轮转(典型固定值)| `design/execution.md §3.3` |
+| L1 rotation 槽 | 任务级 KV / Q 预取深度(变体特定)| 本文件 §1.2 |
+| V2 自读自写槽 | V2 阶段同时活跃的 task 数 | `design/execution.md §3.3` + `design/resources.md §1.5 Q2` |
+
+混用同一常量会导致 silent 数据污染或 race(O_acc 被覆写 / KV 预取阻断 / Cube↔Vector 握手错位)。
+
+---
+
+## §5 跨变体扩展点汇总
+
+下表列出每个变体在 5 个扩展点上的特化内容,供快速横向对照:
+
+| 扩展点 | FA / GQA | MLA | 稀疏 | 量化 |
+|---|---|---|---|---|
+| ConstInfo | gMaxPerTask 等 group 合并字段 | latent 维度字段 | sparse pattern 描述字段 | scale 轴 / dtype / Tiling 派生字段 |
+| Cube | 标准 task 级双缓冲 | L1 加深(latent history)| 同 base + 可能 gather | MmadMx/MxMatmul / c1v1Loop / Load2DMX |
+| Vector | 标准 V1/V2 online softmax | + latent absorption 两步链 | 同 base + mask 跳过 | + P-scale 回传 + V2 末块量化链 |
+| Workspace | 标准 3 段组合 | + int32 中间段 | + sparse 索引段(可能)| + scale staging 段 |
+| Service | 默认 Cube + Vector 命名 | base 内变体分支(复用 base service)| 同 base | 默认复用(除非量化占比大)|
+
+---
+
+## §6 参考资源
+
+| 阶段 / 主题 | 入口 |
+|---|---|
+| 选型入口 | [`patterns.md`](../patterns.md) |
+| 基础理论 | [`fundamentals.md`](./fundamentals.md) |
+| 设计流程(WHAT)| [`design/`](../design/_governance.md)(节点 G→N12)|
+| 组合规则 | [`composition.md`](./composition.md) |
+| 结构性方案决策 | [`design/execution.md` §3](../design/execution.md)、[`design/shape.md` §5.5](../design/shape.md) |
+| 实现层参考(跨核同步 / Fixpipe)| [`implementation_ref.md`](../implementation_ref.md) |

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

@@ -0,0 +1,245 @@
+# FlashAttention 类算子 — 基础理论层
+
+> 本文档定义 FA 类的**通用数学模型、不变量与分析阶段产出**。所有 FA 变体(GQA / MLA / 量化 / 稀疏)共享本节内容。
+> **选型入口** → [`patterns.md`](../patterns.md);**设计流程** → [`design/`](../design/_governance.md)(节点 G→N12)。
+
+---
+
+## §0 抽象名与公开 API 对照
+
+> 本目录方法论用**抽象名**表达设计概念(如 `mEff`、`K_BASE`),便于跨平台复用。下表把这些抽象名映射到 **asc-devkit 公开 API**(有文档/头文件),供实现时定位。
+> **纪律**:本 skill 只引用公开资料(asc-devkit 开源社区、CANN 官方文档)。抽象名承载"该决策什么 / 该满足什么不变量";**其具体变量命名由实现自行决定**,方法论不绑定任何一份实现的私有符号名。
+
+**抽象概念 → 公开 API**:
+
+| 方法论抽象名 | 含义 | 对应的公开 Ascend C API / 概念 |
+|---|---|---|
+| `mEff` = Bq × curG | Mmad 有效 m 维 | Mmad 的 `m` 维参数(`MmadParams.m`);数值由 Tiling 决定,变量名自定 |
+| `curG` / `gMaxPerTask` | 合并到一个 task 的 qHead 数 / 其上限 | Tiling 派生量,无固定 API 名;由 Host Tiling 决定 |
+| `K_BASE` / `M_BASE` / `S2_BASE` | L0/L1 分块基础块 | Mmad `k`/`m`/`n` 维分块步长(`MmadParams`)+ LoadData 分块参数;数值 Tiling 决定,变量名自定 |
+| `CACHE_SIZE` / `PRELOAD_N` | 流水 ring buffer 深度 / task 环形缓冲区大小 | 算子自定义常量(非 API);由流水编排设计决定,见 `design/execution.md §3`(N10 流水/同步)|
+| V1 softmax | online softmax V1 阶段 | **`SoftmaxFlashV2<float>`**(asc-devkit `include/adv_api/activation/softmaxflashv2.h`,有文档与示例);`T` 仅支持 half/float,bf16 走 `<float>`+Cast |
+| bf16 Mmad | fm/filter=bf16, acc=fp32 | `Mmad<float, bfloat16_t, bfloat16_t>`(公开 Mmad 模板;见 `Mmad.md`)|
+| V 转置加载 | L1→L0B 转置 | `LoadDataWithTranspose`(公开 `LoadDataWithTranspose.md`;950PR 仅支持 L1→L0B 通路)|
+| V2 归一化 1/sum | 求倒数 | `Reciprocal<float, config>`(950PR 仅提供带 config 的重载;config 有默认值 `DEFAULT_RECIPROCAL_CONFIG`,无需显式传参;`Reciprocal.md`),或 `Div` 替代 |
+| 跨核同步 | AIC↔AIV 握手 | `CrossCoreSetFlag<modeId,pipe>` / `CrossCoreWaitFlag<modeId,pipe>`(公开 ISASI;modeId 语义见 implementation_ref.md §1)|
+| L0C→UB 搬运 | Fixpipe | `Fixpipe` + `FixpipeParamsArch3510`(950PR)/ `FixpipeParamsM300`;见 implementation_ref.md §4 |
+
+**跨核同步 modeId(公开文档)**:950PR/950DT 支持 modeId 0/1/2/4;A2/A3 等上一代仅支持 0/1/2。FA 混合 kernel 的 AIC↔AIV 握手在 950PR 用 modeId 2 或 4,详见 [`implementation_ref.md` §1](../implementation_ref.md)。
+
+> **重要**:某些 FA 参考实现内部有私有融合函数(如把 V1 softmax 融合成单函数)或私有的跨核同步封装类。这些**不是** Ascend C 公开 API,走 asc-devkit 公开 API 的开发路径**无法直接调用**。本 skill 不推荐、不依赖任何私有符号——默认路径一律用上表的公开 API。
+
+---
+
+## §1 FA 类算子定位
+
+### §1.1 算子定义
+
+FA(FlashAttention)类算子是分块化、不显式实例化 attention score 矩阵的 attention 计算族。三个输入 Q / K / V,一个输出 O,沿 KV 维度分块流式累积 softmax 与加权和,**不在显存中构建完整的 [Sq, Sk] score 矩阵**。
+
+输入语义(以维度名表示,具体 layout 由设计阶段声明):
+- **Q**:query,含 batch / Sq / qHead / D 维(典型 BSND layout `[B, Sq, Hq, D]`)
+- **K, V**:key / value,含 batch / Sk / kvHead / D 维(典型 BSND layout `[B, Sk, Hkv, D]`)
+- **O**:输出 attention,维度与 Q 同
+
+D 为 head dim,Hq / Hkv 为 query / kv head 数。FA 类内不同变体在 Hq 与 Hkv 的关系、KV 是否经压缩、Sq 是否退化为 1 等维度上特化。其他 layout(BNSD / SBHD 等)需要在设计阶段额外声明 stride 计算。
+
+### §1.2 与其他算子族的边界
+
+FA 类与其他算子族的关键区分:
+
+| 区分维度 | FA 类 | 其他族 |
+|---|---|---|
+| Kernel 类型 | `__mix__(N, M)` AIC+AIV 协同 | 多数为纯 vector / 纯 cube |
+| 计算流 | 跨核 stage 化(Cube 算 GEMM / Vector 算 softmax)| 单核内完成 |
+| 跨 KV 分块状态 | 必须在线 softmax 累积(max/sum/O_acc)| 多数无在线状态 |
+| 任务维度 | s2(KV 分块)**禁入**任务分发维度 | 多数所有维度均可任务分发 |
+| Workspace | 多段跨核握手 + 自读自写 GM 段 | 多数无 / 单段 |
+
+因此 FA 类不能套用 reduction / elewise / matmul 的设计模式,必须按本目录的方法论。
+
+---
+
+## §2 数学模型(FA-2 Online Softmax)
+
+### §2.1 计算公式
+
+对每个 KV 分块 `j = 0, 1, ..., (Sk/Bk)-1` 顺序累积:
+
+```
+S_j   = (Q · K_j^T) * scale                                  # [Bq, Bk]
+m_j   = max(m_{j-1}, rowmax(S_j))                            # [Bq]   (m_{-1} = -∞)
+sum_j = exp(m_{j-1} - m_j) * sum_{j-1} + rowsum(exp(S_j - m_j))  # [Bq]
+O_j   = exp(m_{j-1} - m_j) * O_{j-1} + exp(S_j - m_j) · V_j  # [Bq, D]
+
+最终: O = O_last / sum_last
+```
+
+**关键性质**:
+- `S_j`(Q·K^T 结果)仅 `[Bq, Bk]` 大小,与 Sk 无关 —— FA 的"不实例化全矩阵"由此实现
+- 跨 KV 分块累积时需要 **rescale 旧状态**(`exp(m_{j-1} - m_j)`),这是 online softmax 的本质
+- 末块归一化(除以 `sum_last`)只做一次;**中间步骤的 P 不做归一化**——V1 阶段输出的是 `exp(S_j - m_j)`(未归一化指数),归一化推迟到 V2 末块(见 §2.2 与 `design/execution.md §1` N4 softmax)
+
+### §2.2 数据流四阶段语义
+
+FA 类把每个 KV 分块的计算切成 4 个 stage,跨 AIC / AIV 协同执行:
+
+| 阶段 | 核 | 操作 | 输入 → 输出中间矩阵 | 跨核同步语义 |
+|---|---|---|---|---|
+| **C1** | AIC | Q·K^T GEMM(Nd2Nz Q/K → L1 → L0 → Mmad → Fixpipe)| → `[Bq, Bk]` 中间矩阵到 GM | 完成后通知 AIV |
+| **V1** | AIV | scale + softmax + cast | `[Bq, Bk]` → 未归一化的 P(`exp(S-m)`)到 GM | 等 C1 完成 / 完成后通知 AIC |
+| **C2** | AIC | P·V GEMM(Nd2Nz P/V → L1 → L0 → Mmad → Fixpipe)| P + V → `[Bq, D]` 中间矩阵到 GM | 等 V1 完成 / 完成后通知 AIV |
+| **V2** | AIV | 跨 KV 分块累积(默认 task 级模式下做 online rescale + Add;末块归一化)| `[Bq, D]` → 写回 attentionOut(末块)/ GM 自读自写段(非末块,在线累积)| 等 C2 完成 |
+
+C1 → V1 → C2 → V2 是同一 KV 分块内的严格数据流方向(见 §3.1 不变量 I1)。不同 KV 分块之间如何交错(流水排布、loop body 内 stage 顺序、几级流水)由设计阶段决定,不在本不变量约束内。
+
+> **注**:V2 阶段的"跨 KV 分块累积"语义因并行策略而异:
+> - **默认 task 级**(s2 在 task 内顺序):V2 跨 s2 块在线累积 max / sum / O_acc(stateful)
+> - **Split-KV reduce**(s2 跨核切分):V2 只算自己切片的 partial 值,最终的 max / sum / O 在跨核 combine 阶段产生
+> 详见 [`design/shape.md §2`(N2 并行策略选择)](../design/shape.md)。
+
+### §2.3 跨 KV 分块状态
+
+数学上跨 KV 分块需要持有三类量:
+
+- **max**:`[Bq]` 维,每行当前最大 score
+- **sum**:`[Bq]` 维,每行归一化后的 sum
+- **O_acc**:`[Bq, D]` 维,累积的(未归一化)输出
+
+**两种并行策略下,这三类量的物理实现与生命周期不同**:
+
+| 并行策略 | max / sum 持有方式 | O_acc 持有方式 |
+|---|---|---|
+| **默认 task 级**(详见 `design/shape.md §2` N2)| task 内跨 s2 在线更新(stateful);通常 UB 常驻(尺寸 `[Bq]` 小)| 设计核心决策点(见 `design/shape.md §1.2` N1 UB 模式决策):大 D 场景 ∝ m × D 常驻 UB 无法承受,必须改存 GM workspace 每 chunk 流式 rescale/accumulate |
+| **Split-KV reduce** | 每核计算 partial(无 stateful 累积);最终 max / sum 在 cross-core combine 阶段产出 | 每核计算 partial O,落 partial reduce workspace 段;最终 O 在 combine 阶段加权归并 |
+
+---
+
+## §3 不变量 I1-I5
+
+任何 FA 类实现都必须满足以下五个不变量。**违反必崩**(silent zero / 精度漂移 / 多核死锁)。
+
+### §3.1 I1 — 数据流方向不变量
+
+同一 KV 分块内,stage 依赖方向严格为 **C1 → V1 → C2 → V2**。
+
+禁止:
+- 把 stage 重排成 C1 → C2 → V1 → V2(让 AIC / AIV 角色分段)
+- 在 stage 之间用错跨核同步方向(如 V1 完成只设置 AIC 等待但不设置 V1→C2 通知)
+
+流水的 loop body 执行顺序(无论是 2 级还是 3 级)与本不变量不冲突 —— 它讲的是不同 KV 分块如何交错,同一分块内的依赖方向仍是 C1→V1→C2→V2。
+
+**违反后果**:Mm2 Fixpipe ADDR_MISALIGN / 跨核数据未就绪 → 输出全零或乱值。
+
+### §3.2 I2 — GQA 同 kvHead 同任务不变量
+
+GQA 形态中,同一 kvHead 下的 G 个 qHead **必须在同一个任务内合并处理**(`mEff = curBq × curG`,合并到 Mmad m 维度)。
+
+禁止:
+- 把 G 个 qHead 拆到 G 个独立任务,每个任务各自搬运同一份 KV
+
+**违反后果**:KV 重复搬运 G 次,Mte2 / L1 利用率塌陷。
+
+### §3.3 I3 — 跨 task 状态隔离不变量
+
+跨 task 持有的状态(默认 task 级模式下的 online softmax max / sum / O_acc / exp;split-KV reduce 模式下的 partial 段)**必须按任务分槽隔离**,不同任务的状态不能共享同一物理位置。
+
+禁止:
+- 用单一 buffer 跨任务共用 stateful 状态(默认 task 级模式)
+- 用单一段跨核共用 partial 输出(split-KV reduce 模式)
+- 在任务级 PRELOAD 下,用同一 task slot 公式覆盖跨 stage handshake buffer(混淆 task-level 与 loop-level slot 语义,见 [`design/execution.md §3.3`](../design/execution.md))
+
+**违反后果**:被上一任务的尾状态污染 → 输出乱值。
+
+### §3.4 I4 — s2 状态累积正确性不变量
+
+跨 KV 分块的 online softmax 状态(`max` / `sum` / `O_acc`)必须被**完整、正确地累积**,这是 FA 数学正确性的硬要求。
+
+满足此不变量的两种合法切分方案:
+
+1. **默认 task 级切分(主流场景)**:s2 loop 在 task 内部顺序执行,`s2` 索引**不进入** taskIdx 任务分发维度。
+2. **Split-KV reduce(适用 Sq=1 + 大 Sk + 核数富余场景,详见 [`design/shape.md §2`](../design/shape.md) N2)**:s2 沿 KV 维拆给多核并行,每核计算自己切片的局部状态,完成后通过专门的 cross-core combine 阶段归并出最终结果。
+
+**禁止**:
+- 在默认 task 级模式下把 `s2` 放入 taskIdx
+- 启用 split-KV reduce 但**不补**partial reduce + cross-core combine
+- 在同一算子内混用两种切分方案
+
+**违反后果**:输出乱值 / 多核死锁 / 精度崩塌
+
+### §3.5 I5 — MX 类格式 scale 轴对齐不变量
+
+MX 类(mxfp8 / mxfp4 / mxfp6 等)块量化格式的 scale **必须沿被消费 matmul 的 reduction (K-mmad) 轴量化**。
+
+**根源**:硬件 Tensor Core 对 MX 类格式的硬约束—— "data must be consecutive over the reduction dimension"。
+
+**attention 中的推论**:
+
+| 张量 | 被消费 matmul | K-mmad 轴 | scale 量化轴 |
+|------|------------|---------|-----------|
+| Q | Q·K^T | D | D |
+| K | Q·K^T | 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 不兼容。**业界标准把 V scale 沿 S_k 量化**。
+
+**违反后果**:Mmad ScaleB 轴错位 → 输出 NaN / inf(Mmad 直接产出非数,不是数值漂移)。
+
+> 量化 trait 的完整契约见 [`quantization_design.md`](../subfamilies/quantization_design.md)。
+
+---
+
+## §4 分析阶段必须产出清单
+
+设计阶段开始之前,必须先回答以下问题。产出落到 DESIGN 文档(或同等阶段产物)。
+
+### §4.1 选型结论
+
+回答:**这个 attention 算子的选型结论是什么(基础 FA 形态 + 正交 trait)?**
+
+判定依据:
+- Sq、Hq、Hkv、是否有 KV 压缩、是否纯 decode、是否稀疏
+- 选型决策表见 [`patterns.md` §2](../patterns.md)
+
+**产出**:选型结论(基础 FA 形态: GQA / MHA / MLA;正交 trait: 量化 / 稀疏)+ 选定理由。
+
+### §4.2 输入 shape 边界与合法性约束
+
+回答:**用户输入 shape `(B, Sq, Sk, Hq, Hkv, D)` 的合法范围与边界如何处理?**
+
+必须区分:
+- **合法性约束**(必须校验并拒绝):如 `Hkv ≠ 0`、`Hq % Hkv == 0`、`D` 落在支持档位
+- **数值上限**(**不应硬性拒绝**):如 B、Sq、Sk、Hq 的实际上限应由内部基本块设计承担
+
+通用约束(适用于所有 Ascend C 算子)见 `development-guide §1`。本节只标注 **FA 类特有**的合法性条件:
+- `Hq % Hkv == 0`(GQA group 整除)
+- `D` 必须落在 Tiling 支持的对齐档位
+- causal / sliding window 等可选模式的合法组合
+
+**产出**:合法性校验清单 + 内部基本块如何承担数值上限的设计思路。
+
+### §4.3 dtype / causal / 可选特性枚举
+
+回答:**需要支持哪些可选特性的组合?**
+
+常见特性维度:
+- **dtype**:fp16 / bf16 / fp32 / 量化(int8/FP8)
+- **causal mask**:on / off / 子模式(下三角 / sliding window / sink)
+- **sparse pattern**:on / off
+- **alibi / RoPE 等位置编码**:是否在算子内集成
+- **feature flags**:PSE / PostQuant / Prefix / ChunkedPrefill 等(详见 [`feature_flags.md`](../specialization/feature_flags.md))
+
+**产出**:特性维度笛卡尔积清单 + 必须支持的组合 / 可延后的组合。
+
+此清单决定 `design/execution.md §2`(N8 编译期特化)编译宏分类(哪些必须编译宏分离独立 target)与精度门禁规划(每个组合需要的 atol)。
+
+### §4.4 性能与精度目标声明
+
+回答:**达成什么样的精度门禁?达成什么样的性能预算?**
+
+- **精度门禁**:各 dtype × 各模式组合的 atol / rtol;来源指向 `/ops-precision-standard`,FA 类暂无独立条目,按 attention / softmax 通用区间取
+- **性能预算**:典型场景的 Task Duration 目标(若已知);若有对标实现,声明对标方与差距 acceptance(如不超过 X%)
+- **基本块 Roofline 目标**:声明目标性能区制(compute-bound / HBM-bound / cross-core-bound);若对标实现已知,声明基本块尺寸与算术强度的对标值。[`roofline.md`](./roofline.md)(经 `design/shape.md §3` N3 进入)将据此通过三通道 Roofline 分析确定最优 Bq/Bk
+
+**产出**:精度目标表 + 性能目标声明(可为开放型,无具体数字)。