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

package/assets/ops-direct-invoke/skills/ascendc-performance-best-practices/references/reduce/templates/softmax_v2_tiling_data.template

@@ -0,0 +1,278 @@
+/**
+ * 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.
+ */
+
+/*!
+ * \file softmax_v2_tiling_data.h
+ * \brief SoftmaxV2 六个模板的 TilingData 结构定义（host 与 device 共用，packed 布局保持一致）。
+ *
+ * 本文件集中定义六个独立的 TilingData 结构体，每个结构体对应一个 Kernel 模板。
+ * 模板之间互不依赖，使用者只需 include 本文件和对应模板头文件即可独立实例化。
+ *
+ * 结构体与模板对应关系：
+ *   - SoftmaxV2ArSmallRTilingData    → dav310/softmax_v2_ar_small_r.h   (SoftmaxV2ArSmallR)
+ *   - SoftmaxV2ARTilingData          → dav310/softmax_v2_ar_full_load.h  (SoftmaxV2AR)
+ *   - SoftmaxV2ArRecomputeTilingData → dav310/softmax_v2_ar_recompute.h  (SoftmaxV2ArRecompute)
+ *   - SoftmaxV2ARATilingData         → dav310/softmax_v2_ara_full_load.h (SoftmaxV2ARA)
+ *   - SoftmaxV2ARARecomputeTilingData→ dav310/softmax_v2_ara_recompute.h (SoftmaxV2ARARecompute)
+ *   - SoftmaxV2ARAOnlineTilingData   → dav310/softmax_v2_ara_online.h    (SoftmaxV2ARAOnline)
+ *
+ * 所有结构体使用 #pragma pack(1)，确保 Host 与 Device 内存布局一致。
+ */
+
+#ifndef SOFTMAX_V2_TILING_DATA_H
+#define SOFTMAX_V2_TILING_DATA_H
+
+#include <cstdint>
+
+#pragma pack(1)
+
+// ============================================================================
+// AR Small R — 对应模板 SoftmaxV2ArSmallR (dav310/softmax_v2_ar_small_r.h)
+//
+// 适用场景：2D [A1, R] 布局，R 极小（FP32≤16 / FP16≤32），转置为 (R, A1) 向量化。
+// 字段说明：
+//   totalA0Len    — 转置后的 A0 维长度（= 原 A1），单位：元素数
+//   totalRLen     — 归约轴 R 的实际长度，单位：元素数
+//   totalTiles    — A0 方向总 tile 数，单位：tile
+//   tilesPerCore  — 每核处理的 tile 数，单位：tile
+//   tileA0Len     — 主块 A0 tile 长度（VL_FP32 对齐），单位：元素数
+//   tileA0Tail    — 尾块 A0 实际长度，单位：元素数；主块时等于 tileA0Len
+//   rTileBase     — R 方向转置基础块大小，FP32=8 / FP16=16，单位：元素数
+//   rAligned      — R 对齐后长度（按 rTileBase 向上取整），单位：元素数
+//
+// Host 侧生成约束：
+//   - tileA0Len 须为 VL_FP32 (64) 的倍数
+//   - rAligned = CeilDiv(R, rTileBase) * rTileBase
+//   - tilesPerCore = CeilDiv(totalTiles, numBlocks)，totalTiles = CeilDiv(A1, tileA0Len)
+// ============================================================================
+struct SoftmaxV2ArSmallRTilingData {
+    int64_t totalA0Len;
+    int64_t totalRLen;
+    int64_t totalTiles;
+    int64_t tilesPerCore;
+    int64_t tileA0Len;
+    int64_t tileA0Tail;
+    int64_t rTileBase;
+    int64_t rAligned;
+};
+
+// ============================================================================
+// AR Full Load — 对应模板 SoftmaxV2AR (dav310/softmax_v2_ar_full_load.h)
+//
+// 适用场景：2D [A1, R] 布局，R 可整段载入 UB，单 pass VF 计算。
+// 字段说明：
+//   a             — A1 维总长度（行数），单位：元素数
+//   r             — R 维实际长度，单位：元素数
+//   rAligned      — R 对齐后长度（按 32B/dtypeSize 向上取整），单位：元素数
+//   ubFactor      — 单次 UB 载入的行数（A 方向分块），单位：行
+//   aBlockFactor  — 每核处理的行数，单位：行
+//   rLoopCount    — R 方向 VL_FP32 分段数 = CeilDiv(rAligned, VL_FP32)，单位：段
+//
+// Host 侧生成约束：
+//   - rAligned 按 blockSize/dtypeSize 对齐
+//   - ubFactor 受 UB 容量约束，须满足 ubFactor * rAligned * (dtypeSize*2 + 4) <= ubSize
+//   - aBlockFactor = CeilDiv(A1, numBlocks)
+// ============================================================================
+struct SoftmaxV2ARTilingData {
+    int64_t a;
+    int64_t r;
+    int64_t rAligned;
+    int64_t ubFactor;
+    int64_t aBlockFactor;
+    int64_t rLoopCount;
+};
+
+// ============================================================================
+// AR Recompute — 对应模板 SoftmaxV2ArRecompute (dav310/softmax_v2_ar_recompute.h)
+//
+// 适用场景：2D [A1, R] 布局，R 超出 UB，R 切 chunk 三阶段重读 GM + 二分累加树。
+// 字段说明：
+//   a               — A1 维总长度（行数），单位：元素数
+//   r               — R 维实际长度，单位：元素数
+//   ubFactor        — R 方向单 chunk 长度（UB 内一次载入的 R 元素数），单位：元素数
+//   ubFactorTail    — R 方向尾块长度（最后一个 chunk 的实际长度），单位：元素数
+//   aBlockFactor    — 每核处理的行数，单位：行
+//   aLoopCountCeil  — R 方向 chunk 总数 = CeilDiv(R, ubFactor)，单位：chunk
+//   basicBlockLoop  — 二分树展开的基础块数（<= aLoopCountCeil 的最大 2^k），单位：块
+//   mainFoldCount   — 需要折叠的块数 = aLoopCountCeil - basicBlockLoop，单位：块
+//
+// Host 侧生成约束：
+//   - ubFactor 受 UB 容量约束，须满足多 buffer 约束
+//   - ubFactorTail = R - ubFactor * FloorDiv(R, ubFactor)；R 整除时为 0
+//   - basicBlockLoop = FindNearestPower2(aLoopCountCeil)
+//   - mainFoldCount = FloorDiv(R, ubFactor) - basicBlockLoop
+// ============================================================================
+struct SoftmaxV2ArRecomputeTilingData {
+    int64_t a;
+    int64_t r;
+    int64_t ubFactor;
+    int64_t ubFactorTail;
+    int64_t aBlockFactor;
+    int64_t aLoopCountCeil;
+    int64_t basicBlockLoop;
+    int64_t mainFoldCount;
+};
+
+// ============================================================================
+// ARA Full Load — 对应模板 SoftmaxV2ARA (dav310/softmax_v2_ara_full_load.h)
+//
+// 适用场景：3D [A1, R, A0] 布局，R×A0_tile 可载入 UB，沿 A0 切 tile 跨 R 逐列 VF。
+// 字段说明：
+//   totalA1Len          — A1 维总长度，单位：元素数
+//   totalRLen           — R 维总长度，单位：元素数
+//   totalA0Len          — A0 维总长度，单位：元素数
+//   totalTiles          — 总 tile 数 = A1 * a0Outer，单位：tile
+//   tilesPerCore        — 每核处理的 tile 数，单位：tile
+//   usedCoreNums        — 实际使用的核数，单位：核
+//   a1Outer             — A1 外层循环数（= totalA1Len），单位：次
+//   tileA1Len           — A1 方向 tile 长度（当前为 1），单位：元素数
+//   tileA1Tail          — A1 方向尾块长度（= totalA1Len），单位：元素数
+//   a0Outer             — A0 方向 tile 总数 = CeilDiv(A0, tileA0Len)，单位：tile
+//   tileA0Len           — 主块 A0 tile 长度，单位：元素数
+//   tileA0Tail          — 尾块 A0 实际长度，单位：元素数
+//   binaryAddK          — BinaryAdd 外层折叠层数，单位：层
+//   binaryAddLast       — BinaryAdd 最后是否需额外 2→1 折叠（0 或 1），单位：标志
+//   binaryAddInnerLoop  — BinaryAdd 每层内循环次数，单位：次
+//   remainderLoopCount  — R 对 8 取余后的折叠循环数，单位：次
+//   quotientLoopCount   — R 整除 8 后的剩余折叠循环数，单位：次
+//   remainderTailCount  — 余数部分的尾块计数，单位：个
+//   remainderOffset     — 余数部分在 UB 中的偏移，单位：元素数
+//   baseLineOffset      — 8 行 baseline 偏移，单位：元素数
+//   validNumInXUb       — UB 中有效元素数 = R * tileA0Len，单位：元素数
+//   quotientTailOffset  — 商部分尾块偏移，单位：元素数
+//   remainderTailOffset — 余数部分尾块偏移，单位：元素数
+//   remainderTailOffset0~7 — 余数尾块各行的具体偏移（越界则指向 validNumInXUb 做零填充），单位：元素数
+//
+// Host 侧生成约束：
+//   - tileA0Len 须为 a0TileBase 的倍数（FP32=8 / FP16=16）
+//   - 当 R <= 8 时，binaryAdd* 字段不使用（可全为 0）
+//   - 当 R > 8 时，binaryAddQuotient = 最大 2^k <= R-1，按 8 行分组做 BinaryAddVF
+// ============================================================================
+struct SoftmaxV2ARATilingData {
+    int64_t totalA1Len;
+    int64_t totalRLen;
+    int64_t totalA0Len;
+    int64_t totalTiles;
+    int64_t tilesPerCore;
+    int64_t usedCoreNums;
+    int64_t a1Outer;
+    int64_t tileA1Len;
+    int64_t tileA1Tail;
+    int64_t a0Outer;
+    int64_t tileA0Len;
+    int64_t tileA0Tail;
+    uint16_t binaryAddK;
+    uint16_t binaryAddLast;
+    uint16_t binaryAddInnerLoop;
+    uint16_t remainderLoopCount;
+    uint16_t quotientLoopCount;
+    uint16_t remainderTailCount;
+    uint32_t remainderOffset;
+    uint32_t baseLineOffset;
+    uint32_t validNumInXUb;
+    uint32_t quotientTailOffset;
+    uint32_t remainderTailOffset;
+    uint32_t remainderTailOffset0;
+    uint32_t remainderTailOffset1;
+    uint32_t remainderTailOffset2;
+    uint32_t remainderTailOffset3;
+    uint32_t remainderTailOffset4;
+    uint32_t remainderTailOffset5;
+    uint32_t remainderTailOffset6;
+    uint32_t remainderTailOffset7;
+};
+
+// ============================================================================
+// ARA Recompute — 对应模板 SoftmaxV2ARARecompute (dav310/softmax_v2_ara_recompute.h)
+//
+// 适用场景：3D [A1, R, A0] 布局，R 超出 UB，R 切 bin 三阶段跨 bin 二分折叠。
+// 字段说明：
+//   totalRLen              — R 维总长度，单位：元素数
+//   totalA0Len             — A0 维总长度，单位：元素数
+//   totalTiles             — 总 tile 数 = A1 * tileA0Outer，单位：tile
+//   tilesPerCore           — 每核处理的 tile 数，单位：tile
+//   usedCoreNums           — 实际使用的核数，单位：核
+//   tileA0Outer            — A0 方向 tile 总数，单位：tile
+//   tileA0Len              — 主块 A0 tile 长度，单位：元素数
+//   tileA0Tail             — 尾块 A0 实际长度，单位：元素数
+//   binAddRFactor          — R 方向单 bin 长度（默认 128），单位：元素数
+//   binAddRLoop            — R 方向完整 bin 数 = FloorDiv(R, binAddRFactor)，单位：bin
+//   binAddRTotalLoop       — R 方向 bin 总数 = CeilDiv(R, binAddRFactor)，单位：bin
+//   binAddRTail            — R 方向尾 bin 长度，单位：元素数
+//   binAddBasicBlockLoop   — 二分树展开的基础块数，单位：块
+//   binAddMainFoldCount    — 需要折叠的块数，单位：块
+//   binAddCacheBufferCount — 二分累加 cache buffer 数量，单位：个
+//   binAddResultCacheID    — 最终结果所在的 cache buffer 索引，单位：索引
+//
+// Host 侧生成约束：
+//   - binAddRFactor 默认 128，可根据 UB 容量调整
+//   - binAddRTail = R - (binAddRTotalLoop - 1) * binAddRFactor
+//   - binAddBasicBlockLoop = FindNearestPower2(binAddRTotalLoop)
+//   - binAddCacheBufferCount / binAddResultCacheID 由 GetCacheID 计算
+// ============================================================================
+struct SoftmaxV2ARARecomputeTilingData {
+    int64_t totalRLen;
+    int64_t totalA0Len;
+    int64_t totalTiles;
+    int64_t tilesPerCore;
+    int64_t usedCoreNums;
+    int64_t tileA0Outer;
+    int64_t tileA0Len;
+    int64_t tileA0Tail;
+    int64_t binAddRFactor;
+    int64_t binAddRLoop;
+    int64_t binAddRTotalLoop;
+    int64_t binAddRTail;
+    int64_t binAddBasicBlockLoop;
+    int64_t binAddMainFoldCount;
+    int64_t binAddCacheBufferCount;
+    int64_t binAddResultCacheID;
+};
+
+// ============================================================================
+// ARA Online Softmax — 对应模板 SoftmaxV2ARAOnline (dav310/softmax_v2_ara_online.h)
+//
+// 适用场景：3D [A1, R, A0] 布局，沿 R 分 chunk 在线更新 running max / running sum。
+// 输入读 2 次（1 遍在线 max+sum，1 遍输出），无需二分 cache。
+// 字段说明：
+//   totalRLen       — R 维总长度，单位：元素数
+//   totalA0Len      — A0 维总长度，单位：元素数
+//   totalTiles      — 总 tile 数 = A1 * tileA0Outer，单位：tile
+//   tilesPerCore    — 每核处理的 tile 数，单位：tile
+//   usedCoreNums    — 实际使用的核数，单位：核
+//   tileA0Outer     — A0 方向 tile 总数，单位：tile
+//   tileA0Len       — 主块 A0 tile 长度，单位：元素数
+//   tileA0Tail      — 尾块 A0 实际长度，单位：元素数
+//   rChunkFactor    — R 方向单 chunk 长度（默认 128），单位：元素数
+//   rChunkTotalLoop — R 方向 chunk 总数 = CeilDiv(R, rChunkFactor)，单位：chunk
+//   rChunkTail      — R 方向尾 chunk 长度，单位：元素数
+//
+// Host 侧生成约束：
+//   - rChunkFactor 默认 128，若大于 R 则取 R
+//   - rChunkTail = R - (rChunkTotalLoop - 1) * rChunkFactor
+//   - tileA0Len 须为 a0TileBase 的倍数（FP32=8 / FP16=16）
+// ============================================================================
+struct SoftmaxV2ARAOnlineTilingData {
+    int64_t totalRLen;
+    int64_t totalA0Len;
+    int64_t totalTiles;
+    int64_t tilesPerCore;
+    int64_t usedCoreNums;
+    int64_t tileA0Outer;
+    int64_t tileA0Len;
+    int64_t tileA0Tail;
+    int64_t rChunkFactor;
+    int64_t rChunkTotalLoop;
+    int64_t rChunkTail;
+};
+
+#pragma pack()
+
+#endif  // SOFTMAX_V2_TILING_DATA_H

package/assets/ops-direct-invoke/skills/ascendc-performance-best-practices/references/reduce/templates/state_resident_design.md

@@ -0,0 +1,337 @@
+# 融合算子 UB 状态 Buffer 跨循环常驻优化设计
+
+> **定位说明**：本文档是融合算子（如 FlashAttention）中 UB 状态管理和流水设计的**建议性参考**。`SoftmaxFlashV2`、`preLoadNum` 等接口和概念**不是**当前 `templates/` 目录下七个 Kernel 已实现的统一接口。各模板有各自的局部 max/sum cache 机制（如 AR-Recompute 的 `UpdateCache` 二分树、ARA-Recompute 的 `cacheBuffer`），但并非完整的状态驻留方案。
+
+## 1. 优化目标
+
+在 Flash Attention / Sparse Flash Attention 等融合算子场景中，online softmax 需要在 S2 方向多次循环中累积 `softmaxMax`、`softmaxSum`、`softmaxExp` 三个状态。naive 实现每次 S2 循环都重新分配/释放这些 UB buffer，引入不必要的 `PipeBarrier` 和 `InitBuffer` 开销。
+
+本设计将三个状态 buffer **一次性分配后常驻 UB**，通过 `loop % preLoadNum` 索引实现双缓冲复用，避免每轮 S2 循环的重复分配开销，同时支持读写并行流水。
+
+> **注意**：`SoftmaxFlashV2` 和 `preLoadNum` 是融合 Attention 算子中的概念，当前 dav310 目录下的七个 Softmax Kernel 未实现此完整方案。各模板的局部 max/sum cache（如 [AR Recompute](softmax_v2_ar_recompute.md) 的 `cachebuffer` 和 [ARA Recompute](softmax_v2_ara_recompute.md) 的 `cacheBuffer_`）是 UB 内部的临时状态管理，与本文档的跨循环常驻设计不同。
+
+| 指标 | naive | optimized | 收益 |
+|------|-------|-----------|------|
+| S2 循环内 InitBuffer 调用 | 每轮 3 次 | 0 次 | 消除重复分配开销 |
+| PipeBarrier 数量 | 每轮若干 | 显著减少 | 减少事件同步等待 |
+| UB 空间利用率 | 低（频繁分配释放产生碎片） | 高（预分配连续布局） | 更可控的内存预算 |
+| 流水重叠度 | 低（单份 buffer，必须等 MTE3 写完才能开始下一轮） | 高（双缓冲支持读写并行） | 支持 pingpong 流水 |
+
+> 适用场景：FlashAttention / Sparse FlashAttention 等融合 Attention 算子中内嵌的 online softmax 状态管理。
+
+## 2. 架构概览
+
+### 2.1 存储层级与数据流
+
+```
+GM (Global Memory)
+  │
+  │ MTE3 (workspace ←→ GM)
+  ▼
+UB Buffer [softmaxMax_ping | softmaxMax_pong | softmaxSum_ping | softmaxSum_pong | softmaxExp_ping | softmaxExp_pong]
+  │
+  │ Vector PIPE (SoftmaxFlashV2 / online softmax)
+  ▼
+UB Output → MTE3 → GM
+```
+
+### 2.2 常驻 Buffer 布局
+
+```
+UB 地址空间:
+[softmaxMaxBuff: SOFTMAX_TMP_BUFFER_SIZE * preLoadNum]
+[softmaxSumBuff: SOFTMAX_TMP_BUFFER_SIZE * preLoadNum]
+[softmaxExpBuff: SOFTMAX_TMP_BUFFER_SIZE * preLoadNum]
+
+索引计算:
+outIdx = loop % preLoadNum
+softmaxOutOffset = outIdx * SOFTMAX_TMP_BUFFER_SIZE / sizeof(COMPUTE_T)
+```
+
+### 2.3 双缓冲原理
+
+- **常驻**：`InitBuffer` 仅在算子初始化阶段调用一次，三个状态 buffer 常驻 UB 不释放。
+- **双缓冲索引**：通过 `loop % preLoadNum` 轮询使用 ping/pong 两组 buffer。当 `preLoadNum = 2` 时，Vector PIPE 处理第 N 轮数据的同时，MTE3 可向第 N+1 轮 buffer 写入上一轮结果，实现读写并行。
+
+### 2.4 事件同步模型
+
+| 事件类型 | 含义 | 用途 |
+|---------|------|------|
+| `V_MTE3` | Vector 完成 → 允许 MTE3 覆写 | 状态 buffer 释放控制 |
+| `MTE3_V` | MTE3 完成 → 允许 Vector 读取 | 状态 buffer 数据就绪 |
+
+> 注：具体事件类型需根据实际 PIPE 配置调整，核心原则是「Vector 计算」与「MTE3 搬运」通过双缓冲解耦。
+
+## 3. 关键参数配置
+
+```cpp
+// Host 侧 TilingData（或 constInfo）
+struct SoftmaxConstInfo {
+    uint32_t preLoadNum;           // 双缓冲深度，通常取 2
+    uint32_t softmaxTmpBufferSize; // 单个状态 buffer 大小，通常 = 2K（2048 bytes）
+};
+
+// Kernel 侧 UB buffer 定义
+TBuf<QuePosition::VECCALC> softmaxMaxBuff;
+TBuf<QuePosition::VECCALC> softmaxSumBuff;
+TBuf<QuePosition::VECCALC> softmaxExpBuff;
+
+// InitBuffer 一次性分配（构造函数或 Init 阶段）
+pipe->InitBuffer(softmaxMaxBuff, SOFTMAX_TMP_BUFFER_SIZE * constInfo.preLoadNum);
+pipe->InitBuffer(softmaxSumBuff, SOFTMAX_TMP_BUFFER_SIZE * constInfo.preLoadNum);
+pipe->InitBuffer(softmaxExpBuff, SOFTMAX_TMP_BUFFER_SIZE * constInfo.preLoadNum);
+```
+
+### 3.1 preLoadNum 选取原则
+
+| preLoadNum | UB 占用 | 流水重叠度 | 适用场景 |
+|-----------|---------|-----------|---------|
+| 1 | 3 × 2K = 6KB | 无（串行） | UB 极端紧张，仅做状态常驻不求重叠 |
+| **2** | 3 × 2K × 2 = **12KB** | pingpong 双缓冲 | **默认推荐**，读写并行 |
+| 3 | 18KB | 三段流水 | S2 循环极长、MTE3 延迟高 |
+| 4 | 24KB | 四段流水 | UB 充裕且 MTE3 为瓶颈时考虑 |
+
+### 3.2 SOFTMAX_TMP_BUFFER_SIZE 计算
+
+```
+SOFTMAX_TMP_BUFFER_SIZE = row_length * sizeof(COMPUTE_T)
+
+典型值（row_length = 512, COMPUTE_T = float）:
+SOFTMAX_TMP_BUFFER_SIZE = 512 * 4 = 2048 bytes
+```
+
+## 4. 核心计算循环
+
+### 4.1 naive 版本（优化前）
+
+```cpp
+for (uint32_t s2Loop = 0; s2Loop < s2LoopNum; s2Loop++) {
+    // 每轮都重新分配 —— 开销大
+    TBuf<QuePosition::VECCALC> softmaxMaxBuff;
+    TBuf<QuePosition::VECCALC> softmaxSumBuff;
+    TBuf<QuePosition::VECCALC> softmaxExpBuff;
+    pipe->InitBuffer(softmaxMaxBuff, SOFTMAX_TMP_BUFFER_SIZE);
+    pipe->InitBuffer(softmaxSumBuff, SOFTMAX_TMP_BUFFER_SIZE);
+    pipe->InitBuffer(softmaxExpBuff, SOFTMAX_TMP_BUFFER_SIZE);
+
+    LocalTensor<COMPUTE_T> softmaxMaxUb = softmaxMaxBuff.Get<COMPUTE_T>();
+    LocalTensor<COMPUTE_T> softmaxSumUb = softmaxSumBuff.Get<COMPUTE_T>();
+    LocalTensor<COMPUTE_T> softmaxExpUb = softmaxExpBuff.Get<COMPUTE_T>();
+
+    // 计算 score = Q_i * K_j^T
+    // ... matmul 结果在 mmResUb ...
+
+    // Softmax 计算
+    SoftmaxFlashV2<...>(mmResUb, softmaxSumUb, softmaxMaxUb, mmResUb,
+                        softmaxExpUb, inSumTensor, inMaxTensor, ...);
+
+    // 每轮结束 buffer 自动释放，但下一轮重新分配
+}
+```
+
+### 4.2 optimized 版本（优化后）
+
+```cpp
+// 阶段 1：Init 阶段一次性分配（仅执行一次）
+pipe->InitBuffer(softmaxMaxBuff, SOFTMAX_TMP_BUFFER_SIZE * constInfo.preLoadNum);
+pipe->InitBuffer(softmaxExpBuff, SOFTMAX_TMP_BUFFER_SIZE * constInfo.preLoadNum);
+pipe->InitBuffer(softmaxSumBuff, SOFTMAX_TMP_BUFFER_SIZE * constInfo.preLoadNum);
+
+// 获取完整的常驻 UB tensor
+LocalTensor<COMPUTE_T> softmaxMaxUb = softmaxMaxBuff.Get<COMPUTE_T>();
+LocalTensor<COMPUTE_T> softmaxExpUb = softmaxExpBuff.Get<COMPUTE_T>();
+LocalTensor<COMPUTE_T> softmaxSumUb = softmaxSumBuff.Get<COMPUTE_T>();
+
+for (uint32_t s2Loop = 0; s2Loop < s2LoopNum; s2Loop++) {
+    // 双缓冲索引
+    uint32_t outIdx = s2Loop % (constInfo.preLoadNum);
+    uint32_t softmaxOutOffset = outIdx * SOFTMAX_TMP_BUFFER_SIZE / sizeof(COMPUTE_T);
+
+    // 计算 score = Q_i * K_j^T
+    // ... matmul 结果在 mmResUb ...
+
+    // Softmax 计算，使用常驻 buffer + 偏移索引
+    SoftmaxFlashV2<...>(mmResUb, softmaxSumUb[softmaxOutOffset],
+        softmaxMaxUb[softmaxOutOffset], mmResUb,
+        softmaxExpUb[softmaxOutOffset], inSumTensor, inMaxTensor, ...);
+
+    // 可选：MTE3 将本轮结果写回 GM/workspace，与下一轮 Vector 计算重叠
+    // WaitFlag<V_MTE3>(outIdx);   // 等待上一轮 MTE3 完成
+    // MTE3 搬运...
+    // SetFlag<MTE3_V>(outIdx);    // 通知下一轮数据就绪
+}
+```
+
+### 4.3 双缓冲流水示意（preLoadNum = 2）
+
+```
+时间线 →
+─────────────────────────────────────────────────────
+S2 Loop 0:  [Vector: softmax on ping]  [MTE3: write ping result]
+S2 Loop 1:                                [Vector: softmax on pong]  [MTE3: write pong result]
+S2 Loop 2:                                                          [Vector: softmax on ping]  ...
+```
+
+> 当 Vector 处理 Loop N（pong buffer）时，MTE3 可同时写 Loop N-1（ping buffer）的结果到 GM/workspace，消除 MTE3 等待。
+
+## 5. 从 naive 到 state_resident 的关键修改点
+
+| 修改项 | naive（优化前） | state_resident（优化后） |
+|--------|---------------|------------------------|
+| buffer 分配位置 | S2 循环内，每轮 `InitBuffer` | 算子 Init 阶段，**一次性分配** |
+| buffer 生命周期 | 每轮结束释放，下轮重新分配 | **常驻 UB**，循环结束不释放 |
+| buffer 数量 | 单份（3 个） | `3 × preLoadNum` 份，支持双缓冲 |
+| buffer 索引 | 固定偏移 0 | `loop % preLoadNum` 轮询索引 |
+| 地址计算 | `buff.Get<T>()` | `buff.Get<T>()[outIdx * size / sizeof(T)]` |
+| PipeBarrier 数量 | 每轮分配/释放触发多次 | 仅 Init 阶段一次，循环内无 |
+| MTE3 与 Vector 重叠 | 无（串行） | 有（双缓冲解耦，可选事件同步） |
+| UB 预算确定性 | 低（动态分配碎片化） | 高（预分配总量 = 3×2K×preLoadNum） |
+
+## 6. 注意事项 / 约束
+
+1. **UB 空间约束**：常驻占用 `3 × SOFTMAX_TMP_BUFFER_SIZE × preLoadNum`。以 `preLoadNum = 2`、`SOFTMAX_TMP_BUFFER_SIZE = 2048` 为例，总占用 12KB。需确保 UB 总预算（通常为 256KB）扣除该部分后仍有足够空间给其他 buffer（如输入 tile、输出 tile、中间计算 buffer）。
+
+2. **preLoadNum 上限**：受 UB 总量限制。若 `preLoadNum` 过大导致 UB 溢出，编译/仿真阶段会报错。建议按以下公式校验：
+   ```
+   totalResident = 3 × SOFTMAX_TMP_BUFFER_SIZE × preLoadNum
+   totalResident + otherBuffers ≤ UB_SIZE
+   ```
+
+3. **状态 buffer 与 Softmax API 的兼容性**：`SoftmaxFlashV2` 等高级 API 要求传入的 `softmaxMaxUb`、`softmaxSumUb`、`softmaxExpUb` 为 `LocalTensor` 类型。使用偏移索引后的子 tensor 需确保类型和形状匹配 API 要求。
+
+4. **初始化清零**：首次使用常驻 buffer 前，建议通过 `Duplicate` 或 `DataCopy` 将初始值（如 max = -inf, sum = 0）写入，避免残留数据干扰 online softmax 的累积逻辑。
+
+5. **与 workspace 的关系**：Flash Attention 场景下，online softmax 的 intermediate m、l、O 通常需要 GM workspace 跨 S2 tile 传递。常驻优化解决的是 **UB 内部 buffer 分配**，不改变 GM workspace 的使用逻辑。
+
+## 7. 实施常见问题与解决方案
+
+### 问题 1：UB 内存溢出
+
+**现象**：编译或仿真报错，提示 UB 分配失败或溢出。
+
+**原因**：`preLoadNum` 设置过大，或 `SOFTMAX_TMP_BUFFER_SIZE` 计算错误（如未按 `sizeof(COMPUTE_T)` 对齐），导致常驻 buffer 总占用超出 UB 容量。
+
+**解决方案**：
+- 降低 `preLoadNum`（如 3→2 或 2→1）
+- 校验 `SOFTMAX_TMP_BUFFER_SIZE` 是否按 32B 或 64B 对齐（Ascend 硬件对齐要求）
+- 使用 `printf` 或调试工具打印 UB 总占用：
+  ```cpp
+  // 调试打印
+  printf("UB resident size: %u bytes\n",
+         3 * SOFTMAX_TMP_BUFFER_SIZE * preLoadNum);
+  ```
+
+### 问题 2：softmax 结果错误（数值漂移）
+
+**现象**：精度校验失败，softmax 输出与参考实现不一致。
+
+**原因**：双缓冲索引错误，如 `softmaxOutOffset` 计算时未除以 `sizeof(COMPUTE_T)`，导致指针偏移到错误位置；或 `preLoadNum` 为 1 时仍使用 `% preLoadNum` 索引（结果始终为 0，逻辑正确但无优化效果）。
+
+**解决方案**：
+- 校验偏移计算：
+  ```cpp
+  // 正确：按元素个数偏移
+  uint32_t softmaxOutOffset = outIdx * SOFTMAX_TMP_BUFFER_SIZE / sizeof(COMPUTE_T);
+  // 错误：按字节偏移直接传给 LocalTensor
+  // uint32_t softmaxOutOffset = outIdx * SOFTMAX_TMP_BUFFER_SIZE; // ❌
+  ```
+- 在首循环前显式初始化状态 buffer：
+  ```cpp
+  Duplicate(softmaxMaxBuff.Get<COMPUTE_T>(), FLOAT_NEG_INF, 3 * SOFTMAX_TMP_BUFFER_SIZE / sizeof(COMPUTE_T) * preLoadNum);
+  ```
+
+### 问题 3：preLoadNum = 2 但无性能提升
+
+**现象**：cycle 数与 naive 版本接近，双缓冲未生效。
+
+**原因**：仅做了 buffer 常驻，但未在 Vector 和 MTE3 之间插入事件同步实现真正的流水重叠。`SoftmaxFlashV2` 调用后紧跟 MTE3 写回，仍是串行执行。
+
+**解决方案**：插入 `SetFlag` / `WaitFlag` 事件对，将 MTE3 写回与下一轮 Vector 计算解耦：
+```cpp
+// 正确的流水同步模式
+for (uint32_t s2Loop = 0; s2Loop < s2LoopNum; s2Loop++) {
+    uint32_t curIdx = s2Loop % preLoadNum;
+    uint32_t prevIdx = (s2Loop + preLoadNum - 1) % preLoadNum;
+
+    // 等待上一轮 MTE3 写回完成（释放当前 buffer）
+    WaitFlag<MTE3_V>(curIdx);
+
+    // Vector 计算
+    SoftmaxFlashV2<...>(...);
+
+    // 通知 MTE3 可以写回当前 buffer
+    SetFlag<V_MTE3>(curIdx);
+
+    // MTE3 异步写回上一轮结果（与下一轮 Vector 计算重叠）
+    // 注意：实际代码中 MTE3 写回应在 SetFlag 之后、下一轮 WaitFlag 之前完成
+}
+```
+
+### 问题 4：与 online softmax 的 m/sum 累积逻辑冲突
+
+**现象**：多 tile（S2 循环）场景下，softmax 结果跨 tile 不一致。
+
+**原因**：online softmax 要求跨 tile 维护 running max 和 running sum。若每个 S2 循环使用独立的 buffer（双缓冲），但未正确将上一轮状态传递到下一轮（如通过 GM workspace），会导致状态断裂。
+
+**解决方案**：
+- 明确区分「UB 内部状态 buffer」（本优化，用于单轮 softmax 计算）和「跨 tile 累积状态」（通过 GM workspace 传递，属于 online softmax 算法本身）。
+- 本优化不改变 online softmax 的跨 tile 状态传递逻辑，仅优化单 tile 内的 UB buffer 分配策略。
+
+### 问题总结
+
+| # | 问题 | 根因 | 解决方案 | 影响 |
+|---|------|------|---------|------|
+| 1 | UB 溢出 | preLoadNum 过大或 size 未对齐 | 降低 preLoadNum、校验对齐 | 编译/仿真失败 |
+| 2 | 精度失败 | 偏移计算错误或 buffer 未初始化 | 校验 offset 公式、首循环清零 | 结果错误 |
+| 3 | 性能未提升 | 缺少事件同步，仍是串行 | 插入 SetFlag/WaitFlag | 性能无改善 |
+| 4 | 跨 tile 不一致 | 混淆 UB 优化与 online softmax 状态传递 | 保持 GM workspace 累积逻辑不变 | 精度失败 |
+
+## 8. 实测性能、叠加关系与自检清单
+
+### 8.1 与其他优化的叠加关系
+
+| 优化 | 叠加可行性 | 说明 |
+|------|-----------|------|
+| **pingpong 双缓冲** | ✅ 高度兼容 | 本优化是 pingpong 在 softmax 状态 buffer 上的具体应用，`preLoadNum` 对应 pingpong 深度 |
+| **online softmax 算法** | ✅ 必要前置 | 状态常驻优化的前提是使用 online softmax（跨 S2 循环维护状态），两者缺一不可 |
+| **FP32 中间计算** | ✅ 兼容 | 状态 buffer 的 `COMPUTE_T` 可设为 float，与 FP32 数值稳定性优化共存 |
+| **mte2_preload** | ⚠️ 部分兼容 | 若 softmax 前有 MTE2 预取，需确保预取 buffer 与常驻 buffer 不冲突 |
+| **swat / streamk** | ❌ 不适用 | 这两种优化针对 MatMul CUBE 核心，与 softmax Vector 核心无直接交集 |
+
+### 8.2 选型决策
+
+```
+if (融合算子包含 online softmax && S2 循环次数 > 1):
+    → 启用 state_resident 优化
+    → preLoadNum = 2（默认，UB 充裕时可试 3）
+else:
+    → 无需本优化（单轮 softmax 无循环复用收益）
+```
+
+### 8.3 自检清单
+
+- [ ] `InitBuffer` 仅在算子初始化阶段调用一次，不在 S2 循环内
+- [ ] `preLoadNum` 取值为 1/2/3/4，且满足 UB 预算约束
+- [ ] `softmaxOutOffset` 计算正确：`outIdx * SOFTMAX_TMP_BUFFER_SIZE / sizeof(COMPUTE_T)`
+- [ ] 首循环前状态 buffer 已初始化（max = -inf, sum = 0）
+- [ ] 双缓冲索引与事件同步（SetFlag/WaitFlag）配套使用，实现真正流水
+- [ ] 精度校验通过（与 naive 版本对比，误差在 1e-5 以内）
+- [ ] cycle 数对比：optimized / naive < 0.9（至少 10% 提升，通常 15-25%）
+
+## 9. 与当前 dav310 模板的联系与区别
+
+当前 `templates/dav310/` 下的七个 Kernel 各有局部 max/sum cache 机制，但它们与本文档的跨循环常驻方案有本质区别：
+
+| 特性 | 本文 state_resident 方案 | dav310 模板的局部 cache |
+|------|------------------------|----------------------|
+| 适用场景 | 融合 Attention 跨 S2 循环 | 独立 Softmax 单 pass 内的跨 chunk |
+| 状态生命周期 | 跨 S2 循环常驻 UB | 单 tile 内临时使用 |
+| 双缓冲索引 | `loop % preLoadNum` | 无（直接使用 `cacheID` 索引） |
+| 事件同步 | SetFlag/WaitFlag 流水 | 无（同步计算） |
+| 涉及模板 | 融合 Attention（本目录未提供） | [AR Recompute](softmax_v2_ar_recompute.md)、[ARA Recompute](softmax_v2_ara_recompute.md) |
+
+- **AR Recompute** 的 `cachebuffer`（2048B）用于 UB 间二分累加树的 `UpdateCache`，是单行 R 方向的局部 sum 合并，非跨 S2 循环状态。
+- **ARA Recompute** 的 `cacheBuffer_` 用于跨 bin 的 `UpdateCache` 二分树，同样是单 tile 内的局部 sum 合并。
+- **ARA Online** 的 `xMaxBuf_`/`xSumBuf_` 维护 running max/sum，是单 tile 内跨 R chunk 的在线状态，非跨 S2 循环。
+
+> 本文档不宣称当前 dav310 Softmax 已实现完整的融合状态驻留方案。