cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-ops-tune/ops-family/references/elementwise/templates/add_custom/scripts/test_torch.py

@@ -0,0 +1,99 @@
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+
+# ============================================================================
+# PyTorch 通路测试脚本
+# ============================================================================
+#
+# [MODIFY] 创建新算子时修改:
+# 1. SO_NAME: .so 文件名（需与 CMakeLists.txt 中的 target 名一致）
+# 2. OP_NAME: 算子名称（需与 register.cpp 中的注册名一致）
+# 3. compute_golden(): 替换为你的算子的正确计算逻辑
+# 4. 测试用例: 根据算子语义调整输入和预期输出
+# ============================================================================
+
+import sys
+import os
+
+import torch
+
+from golden import compute_golden
+
+# [MODIFY] 算子配置
+# .so 库名与算子名由环境变量提供（OP_SO_NAME / OP_NAME），未设置时 fail loud
+# ——避免硬编码文件名；OP_SO_NAME 需与 CMakeLists.txt target 一致，
+# OP_NAME 需与 register.cpp 注册名一致
+SO_NAME = os.environ.get("OP_SO_NAME")
+OP_NAME = os.environ.get("OP_NAME")
+if not SO_NAME or not OP_NAME:
+    print(
+        "ERROR: 请设置环境变量 OP_SO_NAME（.so 库名，与 CMakeLists.txt target 一致）"
+        "与 OP_NAME（算子注册名，与 register.cpp 一致）",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+DTYPE = torch.float32  # 数据类型
+ATOL = 1e-6  # 绝对容差
+RTOL = 1e-6  # 相对容差
+
+
+def run_test(name, x1, x2):
+    """运行单个测试用例，返回 (name, passed, max_diff)"""
+    op_fn = getattr(torch.ops.npu, OP_NAME)
+    y = op_fn(x1.npu(), x2.npu())
+    golden = compute_golden(x1, x2).npu()
+    max_diff = torch.max(torch.abs(y - golden)).item()
+    passed = torch.allclose(y.cpu(), golden.cpu(), atol=ATOL, rtol=RTOL)
+    return name, passed, max_diff
+
+
+def main():
+    # 加载算子库
+    so_path = os.path.join("build", SO_NAME)
+    if not os.path.exists(so_path):
+        print(f"ERROR: {so_path} not found. Run 'cmake .. && make' first.")
+        sys.exit(1)
+    torch.ops.load_library(so_path)
+
+    # [MODIFY] 测试用例（编号需与 PLAN.md §3.3 的 T*/P* 对齐）
+    results = []
+
+    # P1: 随机数据
+    x1 = torch.randn(8, 16, dtype=DTYPE)
+    x2 = torch.randn(8, 16, dtype=DTYPE)
+    results.append(run_test("P1 random", x1, x2))
+
+    # P2: 零值
+    x1 = torch.zeros(8, 16, dtype=DTYPE)
+    x2 = torch.zeros(8, 16, dtype=DTYPE)
+    results.append(run_test("P2 zeros", x1, x2))
+
+    # P3: 正负混合
+    x1 = torch.randn(8, 16, dtype=DTYPE)
+    x2 = -x1
+    results.append(run_test("P3 pos_neg", x1, x2))
+
+    # 汇总
+    total = len(results)
+    passed = sum(r[1] for r in results)
+    failed = total - passed
+    print(f"\n{'=' * 50}")
+    print(f"PyTorch test results ({OP_NAME})")
+    print(f"{'=' * 50}")
+    for name, ok, diff in results:
+        print(f"  {name}: {'PASSED' if ok else 'FAILED'} (Max diff={diff})")
+    print(f"{'=' * 50}")
+    print(f"Total: {total}, Passed: {passed}, Failed: {failed}")
+    print(f"Status: {'PASSED' if failed == 0 else 'FAILED'}")
+    sys.exit(0 if failed == 0 else 1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/asc-tools/tool-ops-tune/ops-family/references/elementwise/templates/add_custom/scripts/verify_result.py

@@ -0,0 +1,56 @@
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+
+# ============================================================================
+# 结果验证脚本
+# ============================================================================
+#
+# [MODIFY] 创建新算子时修改:
+# 1. dtype: 数据类型（需与 gen_data.py 和 add.asc 保持一致）
+# 2. rtol/atol: 容差参数（根据算子精度要求调整）
+# ============================================================================
+
+import numpy as np
+import sys
+
+# [MODIFY] 验证参数
+dtype = np.float32  # 数据类型，需与 gen_data.py 和 add.asc 保持一致
+rtol = 1e-5  # 相对容差
+atol = 1e-8  # 绝对容差
+
+
+def verify_result(output_path, golden_path):
+    output = np.fromfile(output_path, dtype=dtype)
+    golden = np.fromfile(golden_path, dtype=dtype)
+
+    if output.shape != golden.shape:
+        print(f"Shape mismatch: output {output.shape} vs golden {golden.shape}")
+        return False
+
+    if np.allclose(output, golden, rtol=rtol, atol=atol):
+        print(f"Verification PASSED! Shape: {output.shape}")
+        print(f"Max diff: {np.max(np.abs(output - golden))}")
+        return True
+    else:
+        diff = np.abs(output - golden)
+        print("Verification FAILED!")
+        print(f"Max diff: {np.max(diff)}, Mean diff: {np.mean(diff)}")
+        mismatches = np.where(diff > atol + rtol * np.abs(golden))[0]
+        print(f"Mismatch count: {len(mismatches)} / {len(golden)}")
+        return False
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        print("Usage: python verify_result.py <output.bin> <golden.bin>")
+        sys.exit(1)
+
+    success = verify_result(sys.argv[1], sys.argv[2])
+    sys.exit(0 if success else 1)

package/skills/asc-tools/tool-ops-tune/ops-family/references/elementwise/templates/usage_guide.md

@@ -0,0 +1,61 @@
+# Elementwise 模板使用指南（usage_guide）——add_custom 可裁剪工程模板
+
+> `templates/add_custom/` 的转换与适配说明。模板拷贝纪律（SKILL.md T1-T5）
+> 同样适用：**直接拷贝 + 只改 `[MODIFY]` 点**。
+
+## 模板来源与验证状态
+
+源自 Ascend C Kernel 直调工程模板（Vector 样例工程）
+（经真机验证的 Vector 样例工程：双缓冲 TQue + DataCopyPad 尾块处理 +
+多核均分 + 尾核特化 + torch 扩展双通路）。与本仓真机 E2E 走查同款工程形态
+（square_add@910B3）。
+
+## 目录结构
+
+```
+add_custom/
+├── op_kernel/
+│   ├── add_custom_tiling.h    Tiling 常量 + 结构体（kernel 和 host 共用）
+│   └── add_custom_kernel.asc  纯 kernel（KernelAdd 类 + 核函数入口，[MODIFY] 标记）
+├── op_host/
+│   ├── add_custom.asc         Host + main 入口（直调通路）
+│   └── data_utils.h           数据读写工具
+├── op_extension/
+│   ├── add_custom_torch.cpp   PyTorch host 实现（Tiling 计算 + launch）
+│   ├── register.cpp           TORCH_LIBRARY 注册
+│   └── ops.h                  函数声明
+├── CMakeLists.txt             双 target：可执行文件 + libadd_custom_ops.so
+└── scripts/                   gen_data / golden / verify / test_torch
+```
+
+## 转换步骤
+
+1. 整目录拷贝入工程，改名为 `<your_op>`；
+2. 只改 `[MODIFY]` 标记点（kernel 头注释列了 5 处：include 名 / 类名 / 核函数名 /
+   计算逻辑（`AscendC::Add` → 你的算子）/ 输入输出数量）；
+3. **计时结构不许改**：`InitBuffer(que, DOUBLE_BUFFER, TILE_LENGTH * sizeof(T))`
+   的双缓冲、`CopyIn/Compute/CopyOut` 三段循环、尾块 `DataCopyPad` 处理——
+   改了口径，前后对比失效（timing_harness 同款纪律）；
+4. TILE_LENGTH 按 tiling 候选调整：
+   `python3 ops-family/scripts/tiling_candidates.py --family elementwise
+   --shape SHAPE --dtype DTYPE --soc SOC`（容量预算校验内置，SHAPE/DTYPE/SOC
+   为实际值占位）。
+
+## 已内置的正确结构（不要自己重造）
+
+| 结构 | 位置 | 说明 |
+|------|------|------|
+| 多核均分 + 尾核特化 | Init 的 blockIdx 分支 | 非尾核 numPerCore / 尾核 tailNumLastCore |
+| 双缓冲流水 | InitBuffer DOUBLE_BUFFER | L1_SERIAL_NO_OVERLAP 的机制基线 |
+| 尾块对齐 | DataCopyPad + tailTileElementNum | 非 32 对齐 shape 不崩 |
+| 精度验证链 | scripts/{gen_data,golden,verify_result} | 工程现有容差（禁止自创） |
+| torch 双通路 | op_extension/ | torch.ops.npu 调用 + 与直调结果对拍 |
+
+## 性能调优挂钩（本仓链路）
+
+- 计时：无自带 benchmark 时拷
+  `ops-family/references/common/timing_harness/`（测量设施非优化变量）；
+- 判定：采集后 facts_bridge → verdict（MTE2/VEC/SCALAR 命中 → 见族 guide
+  [guide.md](../guide.md) 路由表）；
+- tiling 候选：tiling_candidates.py（elementwise 族四约束内置：
+  多核 512 元素对齐 / UB 256B 对齐 / 每核 ≥4KB / fp32 中间精度分支）。

package/skills/asc-tools/tool-ops-tune/ops-family/references/elementwise/vector_efficiency_design.md

@@ -0,0 +1,203 @@
+# Vector 计算效率优化设计
+
+## 1. 优化目标
+
+在纯 Vector 或 Vector 主导的算子中，性能瓶颈常来自三类 UB 内部效率损失：Scalar 侧为每个 Vector API 手动计算 repeat/mask，归约场景反复使用高延迟 reduce 指令，以及连续 Vector 计算链把中间结果写回 GM 后再读回 UB。本优化通过 Counter 模式减少控制指令、低延迟指令组合替代单一高延迟归约路径、UB 内数据直通消费，**减少 Scalar 开销、Vector 指令延迟和 GM 往返搬运**。
+
+| 指标 | naive | optimized | 收益 |
+|------|-------|-----------|------|
+| Scalar 控制指令 | 每条 Vector API 前手动计算 repeat/mask | Counter 模式一次设置，全程自动 | Scalar 开销降低 30-50% |
+| GM 搬运次数（n 步 Vector 链） | 2n 次（每步搬入+搬出） | 2 次（首次搬入 + 最终搬出） | 搬运次数减少 n 倍 |
+| 归约指令延迟 | WholeReduceSum 单条高延迟 | BlockReduceSum + WholeReduceSum 组合 | 延迟降低 20-40% |
+| 指令级并行 | 循环体串行执行 | 循环展开暴露并行性 | ILP 提升 |
+
+
+## 2. 架构概览
+
+### 2.1 三类优化在 Vector PIPE 中的位置
+
+三类优化均作用于单核 UB 内的 Vector 执行路径：
+
+- **Counter 模式（入口）**：`SetMaskCount(dataSize)` 后一次 Vector API 调用覆盖全部数据，避免手动计算 `repeatTimes` 和 `tailSize`。
+- **UB 融合链（中间）**：通过 `VECCALC` 队列将多步 Vector 计算的中间结果保留在 UB 内，不落地 GM，减少 `2n → 2` 次搬运。
+- **低延迟归约（出口）**：用 `BlockReduceSum + WholeReduceSum` 组合替代单一高延迟归约路径。
+
+### 2.2 数据流对比
+
+| 模式 | 数据流 | GM 搬运次数 |
+|------|--------|------------|
+| naive（反例） | 每步 Vector 后将中间结果搬出 GM，下一步再搬入 | `2n` 次 |
+| optimized（正例） | 首次搬入 UB(VECCALC)，中间结果链式消费，最终一次搬出 | `2` 次 |
+
+## 3. 关键参数配置
+
+```cpp
+// Counter 模式参数
+struct CounterModeConfig {
+    uint32_t totalElements;   // 总元素数，直接传给 SetMaskCount
+    uint32_t oneRepeatSize;   // 单次 repeat 处理元素数（如 128/256）
+};
+
+// UB 融合链参数
+struct FusedChainConfig {
+    uint32_t chainLength;     // Vector 计算链长度（如 3：Exp→Abs→Mul）
+    uint32_t veccalcBufferSize; // VECCALC buffer 大小（元素数）
+};
+
+// 低延迟归约参数
+struct LowLatencyReduceConfig {
+    uint32_t blockSize;       // BlockReduceSum 的块大小（如 64/128）
+    uint32_t numBlocks;       // 总块数 = totalElements / blockSize
+};
+```
+
+### 3.1 参数选取原则
+
+| 参数 | 典型值 | 说明 |
+|------|--------|------|
+| `oneRepeatSize` | 128 (FP16) / 64 (FP32) | 与 Vector Unit 宽度对齐 |
+| `chainLength` | 2-5 | 受限于 UB 容量，过长会挤占双缓冲空间 |
+| `blockSize` | 64 / 128 | BlockReduceSum 的有效块大小 |
+
+## 4. 核心计算循环
+
+### 4.1 naive 版本（优化前）
+
+**Counter 反例 — 手动 repeat/mask：**
+```cpp
+// 每条 Vector API 前手动计算 repeat 和 tail
+uint32_t repeatTimes = dataSize / ONE_REPEAT_SIZE;
+uint32_t tailSize = dataSize % ONE_REPEAT_SIZE;
+
+// 主块
+Add(dst, src1, src2, FULL_MASK, repeatTimes, {1, 1, 1, 8, 8, 8});
+
+// 尾块（需要额外一次 API 调用 + mask 设置）
+if (tailSize > 0) {
+    SetVectorMask(tailMask);
+    Add(dst + offset, src1 + offset, src2 + offset, tailMask, 1, {1, 1, 1, 8, 8, 8});
+}
+```
+
+**UB 融合反例 — 每步搬出 GM：**
+```cpp
+void Process() {
+    // Step 1: Exp
+    CopyIn();           // GM → UB
+    Compute_Exp();      // UB → UB
+    CopyOut();          // UB → GM
+
+    // Step 2: Abs
+    CopyIn1();          // GM → UB
+    Compute_Abs();      // UB → UB
+    CopyOut1();         // UB → GM
+}
+```
+
+**归约反例 — 单一 WholeReduceSum：**
+```cpp
+// 高延迟单条指令
+float sum = WholeReduceSum(src, dataSize);  // 延迟高，大数据量时明显
+```
+
+### 4.2 optimized 版本（优化后）
+
+**Counter 模式 — 一次调用覆盖全部：**
+```cpp
+// Counter 模式：SetMaskCount 后一次 API 调用
+SetMaskCount(dataSize);
+Add(dst, src1, src2, dataSize);  // 自动处理主块+尾块，无需手动 mask
+SetMaskMode(NORMAL);  // 完成后恢复 mask 模式
+```
+
+**UB 融合链 — 中间结果不落地 GM：**
+```cpp
+// 定义 VECCALC 队列用于中间结果
+TQue<QuePosition::VECCALC, 1> midQueue;
+pipe.InitBuffer(midQueue, 1, dataSize * sizeof(T));
+
+// 仅首次搬入、最终搬出
+CopyIn(inLocal, inGm, dataSize);  // GM → UB(VECCALC)
+
+// 链式计算，中间结果保留 UB
+LocalTensor<T> mid1 = midQueue.AllocTensor<T>();
+Exp(mid1, inLocal, dataSize);           // Exp
+
+LocalTensor<T> mid2 = midQueue.AllocTensor<T>();
+Abs(mid2, mid1, dataSize);              // Abs
+
+LocalTensor<T> outLocal = outQueue.AllocTensor<T>();
+Mul(outLocal, mid2, scale, dataSize);   // Mul
+
+CopyOut(outGm, outLocal, dataSize);      // UB → GM
+```
+
+**低延迟归约 — BlockReduceSum + WholeReduceSum 组合：**
+```cpp
+// 两阶段归约：先 BlockReduceSum 分块，再 WholeReduceSum 汇总
+// 阶段 1：BlockReduceSum，每 blockSize 个元素产生一个部分和
+for (uint32_t i = 0; i < numBlocks; i++) {
+    blockSums[i] = BlockReduceSum(src + i * blockSize, blockSize);
+}
+PipeBarrier<PIPE_V>();
+
+// 阶段 2：WholeReduceSum 汇总部分和
+float totalSum = WholeReduceSum(blockSums, numBlocks);
+```
+
+## 5. 从 naive 到 vector_efficiency 的关键修改点
+
+| 修改项 | naive（优化前） | vector_efficiency（优化后） |
+|--------|---------------|---------------------------|
+| Vector API 调用方式 | 手动计算 repeatTimes + tail mask | Counter 模式：SetMaskCount + 一次调用 |
+| 中间结果生命周期 | 每步搬出 GM，下步再搬入 | 保留 UB/VECCALC，链式直通消费 |
+| 归约指令 | WholeReduceSum 单条高延迟 | BlockReduceSum + WholeReduceSum 组合 |
+| GM 搬运次数（n 步链） | 2n 次 | 2 次 |
+| Scalar 开销 | 高（repeat/mask 计算） | 低（Counter 模式自动处理） |
+
+## 6. 注意事项 / 约束
+
+1. **Counter 模式依赖硬件支持**：仅部分 Vector API 支持 Counter 模式，使用前需确认 API 文档。
+
+2. **Counter 模式必须恢复 mask**：使用完 Counter 模式后，必须调用 `SetMaskMode(NORMAL)` 恢复，避免影响后续 Vector API。
+
+3. **UB 融合链长度受 UB 容量限制**：chainLength 过长或 dtype 较宽时，中间 buffer 可能挤占双缓冲空间。需精确计算 UB 预算。
+
+4. **BlockReduceSum 需要临时 buffer**：低延迟归约组合需要额外的 blockSums buffer，需确保 UB 有足够空间。
+
+5. **循环展开与 Hardware Loop 的交互**：展开后的循环仍需满足 Hardware Loop 条件（`uint16_t` 迭代变量、起始 0、步长 1），避免引入 if/else。
+
+6. **尾块处理**：Counter 模式自动处理尾块，但 Normal 模式下仍需保留尾块处理逻辑作为 fallback。
+
+## 7. 实施常见问题与解决方案
+
+| 问题 | 根因 | 解决方案 |
+|------|------|---------|
+| Counter 模式后后续 API 结果异常 | mask 未恢复为 NORMAL | 每次 Counter 模式后调用 `SetMaskMode(NORMAL)` |
+| UB 融合链 UB 溢出 | chainLength 过长或 dtype 宽 | 减少 chainLength 或 tile_size；精确计算 UB 预算 |
+| BlockReduceSum 结果不正确 | blockSize 未对齐 | blockSize 需对齐 Vector Unit 宽度（如 64/128） |
+| 循环展开后性能下降 | 展开因子过大导致 ICache miss | 展开因子 ≤ 4，默认推荐 2x |
+
+## 8. 选型决策与自检清单
+
+### 8.1 选型决策
+
+```
+if (profiling 显示 Scalar 时间占比高):
+    → 启用 Counter 模式
+elif (profiling 显示 MTE2/MTE3 中间搬运占比高，且有多步 Vector 链):
+    → 启用 UB 融合链（VECCALC 直通）
+elif (profiling 显示归约延迟高):
+    → 启用低延迟归约组合（BlockReduceSum + WholeReduceSum）
+else:
+    → 标准 Vector 实现即可
+```
+
+### 8.2 自检清单
+
+- [ ] Counter 模式使用后在适当位置恢复 `SetMaskMode(NORMAL)`
+- [ ] UB 融合链的 VECCALC buffer 大小已精确计算，不溢出
+- [ ] BlockReduceSum 的 blockSize 对齐 Vector Unit 宽度
+- [ ] 循环展开后尾块处理正确（`repTimes % unrollFactor`）
+- [ ] 寄存器预算 ≤ 32 RegTensor
+- [ ] 验证通过：与 naive 实现对比，结果一致

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

@@ -0,0 +1,174 @@
+# FA 族设计：Mix Kernel（数据流 / 不变量 / 流水 / 跨核同步 / softmax 陷阱）
+
+> **来源（蒸馏）**：Ascend C Tiling 设计方法论·FlashAttention 分册
+> foundation/fundamentals.md + design/{shape,resources,execution}.md。
+> 覆盖设计节点 N1（宏观形态）/ N2（并行策略）/ N4（softmax）/ N10（流水同步）。
+
+## 1 数学模型与数据流四阶段（FA-2 Online Softmax）
+
+对每个 KV 分块 j 顺序累积：
+
+```
+S_j   = (Q · K_jᵀ) × 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 仅 `[Bq, Bk]` 大小（与 Sk 无关，不实例化全矩阵由此实现）；
+跨块累积需 rescale 旧状态 `exp(m_{j-1} - m_j)`；归一化只在末块做一次。
+
+### 四阶段语义（AIC/AIV 协同）
+
+| 阶段 | 核 | 操作 | 同步语义 |
+|------|---|------|---------|
+| **C1** | AIC | Q·Kᵀ GEMM → `[Bq,Bk]` 中间矩阵到 GM | 完成后通知 AIV |
+| **V1** | AIV | scale + softmax + cast → 未归一化 P（`exp(S-m)`）到 GM | 等 C1 / 完成后通知 AIC |
+| **C2** | AIC | P·V GEMM → `[Bq,D]` 中间矩阵到 GM | 等 V1 / 完成后通知 AIV |
+| **V2** | AIV | 跨块在线累积（rescale + Add）；末块归一化写回 | 等 C2 |
+
+## 2 不变量 I1-I5（违反必崩）
+
+| # | 不变量 | 违反后果 |
+|---|--------|---------|
+| **I1** 数据流方向 | 同一 KV 分块内 stage 依赖严格 **C1→V1→C2→V2**（不同分块如何交错由设计定） | Fixpipe ADDR_MISALIGN / 数据未就绪 → 全零或乱值 |
+| **I2** GQA 同任务 | 同 kvHead 的 G 个 qHead 必须同 task 合并（mEff = curBq × curG 进 Mmad m 维） | KV 重复搬运 G 次，MTE2/L1 利用率塌陷 |
+| **I3** 跨 task 状态隔离 | 跨 task 状态（max/sum/O_acc/partial 段）必须按任务分槽隔离 | 被上一任务尾状态污染 → 乱值 |
+| **I4** s2 状态累积正确性 | 默认 task 级（s2 不进 taskIdx）或 Split-KV reduce（必补 combine）二选一，禁混用 | 乱值 / 多核死锁 / 精度崩塌 |
+| **I5** MX scale 轴对齐 | 量化 scale 沿被消费 matmul 的 K-mmad 轴（V 沿 S_k 不是 D） | Mmad ScaleB 轴错位 → NaN/inf |
+
+## 3 宏观形态（N1）
+
+### Kernel 类型
+- 推荐 `__mix__(1, 2)`（1 AIC + 2 AIV）；AIV 端瓶颈时提高 AIV 配比。
+- **禁止** `__vector__` 做 FA（性能低 10-100×）。
+
+### UB 模式（streaming 判定）
+判定：UB 上是否存在**常驻 ∝ m × D** 的 buffer（如 O_acc 常驻 UB）？
+- 有 → 必须改 **streaming UB 模式**：UB 用固定大小（与 D 无关）ping-pong
+  buffer；O_acc 移 GM workspace，跨 chunk 读回+rescale+累加+写出；单一代码
+  路径覆盖全 D 范围。
+- **禁止** `if D ≤ X: 朴素 else: streaming` 两套代码——streaming 在小 D 退化
+  为单 chunk loop（典型开销 ≤5%），维护两套成本远高。
+
+### Cube 分块层次
+- **L0 K 轴分块**（K_BASE 步长，`Mmad(.k=K_BASE, .cmatrixInitVal=(k==0))`
+  自累加）：D > L0 单 fragment 容量时（几乎总触发）；
+- **L1 M 轴分块**（M_BASE 行）：`mPad × D × sizeof(Q_T)` 超 L1 单槽时；
+- **L1 N 轴分块**（P·V 阶段 V LoadData）：大 D 触发，A5 尤其关键；
+  **统一走 N 轴分块代码路径**（小 D 循环 1 次），不按 D 分支。
+- V 转置加载用 `LoadDataWithTranspose`（**950PR 仅支持 L1→L0B 通路**）；
+  优先支持目标 dtype（bf16）直接转置的形态。
+- **Nz2Nz 陷阱**：非转置 load2dV2 不重排分形——上游 Nd2Nz 的 dst 必须让多
+  M-fractal 按分形步长**连续排布**才能 `mStep≥2` 批量装载，否则只能单分形
+  （牺牲 Cube 批量装载效率）。
+
+## 4 并行策略（N2）
+
+| 策略 | 任务维度 | 适用 |
+|------|---------|------|
+| **默认 task 级** | `taskIdx → (batch, kvHead, gS1Block, gBlock)`，s2 在 task 内顺序 | 默认；totalTasks ≥ usedCoreNum |
+| **Split-KV reduce**（FlashDecoding） | 同一 KV 序列沿 s2 拆多核，各算 partial 后 cross-core combine | totalTasks ≪ usedCoreNum 且 Sq==1（纯 decode）且 Sk > 2K |
+
+Split-KV reduce 启用契约：新增 partial reduce workspace 段（partial O +
+partial max/sum）+ 跨核 combine 阶段；softmax 变体走每切片独立计算。
+**禁止** totalTasks ≥ usedCoreNum 时启用。
+
+## 5 流水编排与跨核同步（N10）
+
+### 流水级数与 stage 顺序
+
+| 方案 | loop body | 说明 |
+|------|-----------|------|
+| 2 级（常见首选） | `C1+V1(本轮)` → `C2+V2(loop-PRELOAD_N 轮)` | V1 可先于 V2（ring buffer slot 物理隔离 state） |
+| 3 级 | `C1(本轮) → V2(上两轮) → V1+C2(上一轮)` | **V2 必须先于 V1**（V2 读上上轮 state，V1 会覆写） |
+
+### Ring buffer 深度（PRELOAD_N）
+默认 PRELOAD_N=2（3 slot）起步，跑通后按 PipeUtilization 在 1/2/3 间微调——
+但「是否启用 ring buffer 预取」是**结构决策必须设计期定死**（禁止退化逐块串行）。
+
+### Slot 语义分类（公式分离，禁止共用常量）
+
+| slot 语义 | 取模计数器 | 取模常量 | 索引 | 典型应用 |
+|----------|-----------|---------|------|---------|
+| 跨 stage 握手 | loop（全局迭代器） | DB（如 2） | `loop & (DB-1)` | 中间矩阵 DB |
+| 跨 task 状态 | **mloop（行计数器）** | PRELOAD_N+1（如 3） | `mloop % (PRELOAD_N+1)` | softmax max/sum |
+| 跨 loop 自读自写 | loop | PRELOAD_N+1 | `loop % (PRELOAD_N+1)` | V2 的 O_acc 落地段 |
+| task 环形缓冲 | loop | CACHE_SIZE（2 的幂） | `loop & (CACHE_SIZE-1)` | task 元信息 |
+
+> ⚠️ `mloop`（行级，softmax max/sum 是行状态）与 `loop`（迭代级，exp buffer）
+> **不可混用**——混用症状是 multi-s2 块精度漂移。`PRELOAD_N+1=3` 非 2 的幂
+> **必须用 %**；CACHE_SIZE 必须 2 的幂用 `&`（热路径省标量除法）。
+> **误用最小复现条件**：single task + multi s2 块（s2N ≥ 3）。
+
+### 跨核同步原语
+
+- 默认 `CrossCoreSetFlag<modeId,pipe>` / `CrossCoreWaitFlag<modeId,pipe>`
+  （公开 ISASI，精确通知 fire-and-forget）；
+- **两端 modeId 必须一致**：不一致 → flagId 空间独立 → **挂死**。950PR/950DT
+  （A5）核内 AIC↔单 AIV 握手用 modeId=4；A2/A3 仅支持 0/1/2。省略模板参数
+  退回默认 modeId=0（多核同步空间）→ WaitFlag 永远等不到 → 挂死；
+- `PipeBarrier<PIPE_ALL>` 仅契约位置兜底（跨 pipe 无对应 HardEvent 时）——
+  **禁止四处散布**（冗余率 <30%，50% 视为性能阻塞项）；
+- 同步粒度：per-stage（每 stage 完成即通知）是 FA 4-stage 常见选择；
+- 双 AIV（推荐）：双 AIV 全程参与；单 AIV 是简化替代（AIV1 early-return）。
+
+### Fixpipe 陷阱
+
+中间段落地位置（L0C→UB 片上 vs L0C→GM）默认**优选片上**。调用 L0C→UB 必须
+**显式构造 `isToUB=true` 的 FixpipeConfig**——默认 `CFG_ROW_MAJOR`（isToUB=false）
+指向 GM 物理地址，用它写 UB 目的地**静默出错**（编译过、结果错），极易被
+误诊为「硬件不支持 L0C→UB」而错误退到全程 GM。
+
+## 6 V1/V2 Softmax 实现陷阱（N4）
+
+- **实现路径**：默认 `SoftmaxFlashV2` 公开 API（`T` 仅 half/float，bf16 走
+  `<float>` + Cast）；`isBasicBlock` 模板参数**必须与 TilingFunc 传值一致**
+  ——不一致 → expMax UB 布局错位 → 逐行 rescale 读错偏移 → **编译过静默数值错**。
+- **首块初始化契约**（漏则整行 O 错并沿 s2 传播）：max=-∞、sum=0；
+  O_acc 的 GM workspace 段**必须显式清零**（GM 默认不清零）；首块无前序状态
+  → rescale 因子等价 1（V2 走「跳过 rescale」分支）。
+- **末块除零保护**：`O = O_acc / sum` 前对 sum 加 eps/clamp——padding 行或
+  极端输入下 sum 可能为 0 → inf/NaN 写出。
+- **mask 值用大有限负数（如 -1e30），禁用 -∞**：整行被屏蔽时 `rowmax=-∞` →
+  `exp(-∞-(-∞)) = NaN` 沿 s2 累积传播（FA 经典 NaN 陷阱）。
+- **完全屏蔽 tile：跳 C1 必须同步跳 V1**——只跳 C1 不跳 V1 → 全 mask 行仍进
+  softmax → NaN；跨核握手段需有效数据时 P 写全 0。
+- **online softmax 有状态**：跨 s2 块必须接入并回读 running max/sum/rescale
+  因子——不能当一次性 `src→dst` 无状态调用。
+
+## 7 编译期特化（N8）
+
+三维度分层判定：
+
+| 判定 | 处理 | FA 典型 |
+|------|------|--------|
+| 引入/删除 TBuf 成员或改 slot 数 | **编译宏分离 target** | dtype / causal on-off / sparse |
+| 热路径分支 | **constexpr 模板参数** | layout（BSND/BNSD）/ hasRope |
+| 仅数值参数 | **运行时 if** | 实际序列长度 |
+
+- mix kernel 推荐 **Dummy Block 模式**（Cube 核 VecBlockDummy / 反之）：
+  零死代码 + 类型安全；
+- causal mask buffer **默认不预分配完整 `[mEff,Bk]` 矩阵**——优先在 S 矩阵
+  原地生成（行号公式 + Compare/Select）或单行模板。
+
+## 8 内存划分要点（N7）
+
+- 所有 buffer 公式只允许：运行时查询的硬件常量 + Tiling 基本块 + dtype 字节宽
+  ——**禁止直接写数字**；
+- 每个 DataCopy 单次量 ≤ 对应 TQue 单槽容量（否则对称 chunk loop，V1/V2
+  **两侧都要切**）；
+- `Σ(单槽 × depth) ≤ GetCoreMemSize(UB)` 总量校验；
+- workspace 多段（握手段 / softmax 状态段 / O_acc 段 / partial 段）独立管理，
+  GM 自读自写段禁止裸 DataCopy 不经同步。
+
+## 9 与本仓调优链的衔接
+
+- **基线验证先行**（写自定义 kernel 前必做）：编译运行同类型 mix 示例
+  （asc-devkit `matmul_leakyrelu_advanced_api` / `matmul_gelu_high_performance`
+  / `softmaxflashv2` building block）确认 `__mix__(1,2)` + TPipe + SoftmaxFlashV2
+  在当前 CANN 可用；
+- verdict 命中 → 区制 → 杠杆的路由表见 [guide.md](guide.md)；
+- overlap_pct（trace_bubble）验证 AIC/AIV 流水化是否生效（pipeline 机制卡
+  阈值同款：>30% 生效）。