ops-tune-workbench-plugin 0.0.0-stage → 0.0.1-beta.2

package/skills/tool-ops-tune/ops-family/references/reduce/templates/softmax_v2_ar_recompute.md

@@ -0,0 +1,135 @@
+# SoftmaxV2 AR Recompute 模板
+
+## 1. 模板用途
+
+针对 2D `[A1, R]` 布局、R 超出 UB 容量的 Softmax 场景。将 R 切分为多个 chunk，通过三阶段重读 GM（求 max → 求 sum → 输出）完成 Softmax，使用 UB 间二分累加树（UpdateCache）高效合并跨 chunk 的局部 sum。
+
+## 2. 输入输出布局和 Softmax 轴
+
+- 输入 `x`：`[A1, R]`，行优先，Softmax 沿 R 轴计算。
+- 输出 `y`：`[A1, R]`，与输入同 shape、同 dtype。
+
+## 3. 适用 shape、dtype 和 UB 条件
+
+| 条件 | 要求 |
+|------|------|
+| 输入维数 | 2D，A0 = 1 |
+| R 大小 | R 超 UB 单次载入容量 |
+| dtype | FP32、FP16、BF16 |
+| UB 约束 | 预留 max(32B) + sum(32B) + cache(2048B) 后，三缓冲 xQueue + 双缓冲 yQueue + tmpBuffer |
+
+## 4. 类名、构造函数和 Init 接口
+
+```cpp
+namespace SoftmaxV2Ops;
+
+template <typename Tx, typename Ty>
+class SoftmaxV2ArRecompute : public SoftmaxV2OpsBase {
+public:
+    __aicore__ inline SoftmaxV2ArRecompute(TPipe* pipe);
+    __aicore__ inline void Init(GM_ADDR x, GM_ADDR y, const SoftmaxV2ArRecomputeTilingData* tilingData);
+    __aicore__ inline void Process();
+};
+```
+
+- **构造函数**：接收 `TPipe*`。
+- **Init**：计算每核行数 `currentRowBlock_`、`resultCacheID_`，初始化 xQueue（三缓冲）、yQueue（双缓冲）及 xTmp/xMax/xSum/cache buffer。
+- **Process**：逐行执行三阶段计算。
+
+## 5. 对应的 TilingData 和字段说明
+
+对应 `SoftmaxV2ArRecomputeTilingData`，定义在 [softmax_v2_tiling_data.h](softmax_v2_tiling_data.template)。
+
+| 字段 | 含义 | 单位 |
+|------|------|------|
+| a | A1 维总长度（行数） | 元素数 |
+| r | R 维实际长度 | 元素数 |
+| ubFactor | R 方向单 chunk 长度 | 元素数 |
+| ubFactorTail | R 方向尾块长度 | 元素数 |
+| aBlockFactor | 每核处理行数 | 行 |
+| aLoopCountCeil | R 方向 chunk 总数 | chunk |
+| basicBlockLoop | 二分树基础块数（≤ aLoopCountCeil 的最大 2^k） | 块 |
+| mainFoldCount | 需折叠块数 = FloorDiv(R,ubFactor) - basicBlockLoop | 块 |
+
+## 6. Host tiling 参数计算方法
+
+使用 [softmax_v2_tiling.h](softmax_v2_tiling.template) 中的 `TilingArRecompute`：
+
+```cpp
+softmax_tiling::CaseShape shape{a1, r, 1, dtypeCode};
+softmax_tiling::PlatformParam plat{ubSize, numBlocks};
+SoftmaxV2ArRecomputeTilingData td;
+int64_t blockDim = softmax_tiling::TilingArRecompute(shape, plat, td);
+```
+
+关键计算：
+- `ubFactor` = min(R, (ubFlexible / baseFactor) 按 lcm 对齐)，其中 baseFactor = dtypeSize×3 + dtypeSize×2 + 4
+- `aLoopCountCeil` = CeilDiv(R, ubFactor)
+- `basicBlockLoop` = FindNearestPower2(aLoopCountCeil)
+- `mainFoldCount` = FloorDiv(R, ubFactor) - basicBlockLoop
+
+## 7. CopyIn、归约、归一化和 CopyOut 流程
+
+三阶段处理，每行独立执行：
+
+```
+Process（逐行 rowIdx）:
+  Step 1 — 求 max:
+    for 每个 R chunk:
+      CopyIn chunk → CalculateMaxVF（VF 求 max，与 running max 合并）
+
+  Step 2 — 求 sum（二分累加树）:
+    for basicBlockIdx in [0, basicBlockLoop):
+      a. CopyIn 主块 → MainBlockCastSubExpVF（sub max, exp, 写入 xTmp）
+      b. 若需折叠: CopyIn 折叠块 → FoldBlockCastSubExpVF（sub max, exp, Add 到 xTmp）
+      c. ReduceSum(xTmp) → UpdateCache（按 cacheID 层级合并）
+    basicBlockLoop == 0 时: 单 chunk 直接 ReduceSum
+
+  Step 3 — 输出:
+    for 每个 R chunk:
+      CopyIn chunk → CalculateOutVF（sub max, exp, div sum, Cast 回原精度）→ CopyOut GM
+```
+
+## 8. 重计算与二分累加树优化
+
+- **三阶段重读**：输入读 3 次（max/sum/output），换取 UB 空间——R 可远超 UB 容量。
+- **MainBlock / FoldBlock 配对**：主块和折叠块的 exp 结果在 xTmp 上 `Add` 合并后一次 `ReduceSum`，归约次数减半。
+- **UpdateCache 二分树**：跨 chunk 的局部 sum 按 `GetCacheID(basicBlockIdx)` 层级二分合并，O(log N) 层而非 O(N) 串行。
+  - `GetCacheID(idx)` = `popcount(idx ^ (idx+1)) - 1`，确定当前块在二分树中的位置。
+  - `resultCacheID` = `GetCacheID(basicBlockLoop - 1)`，指向最终合并结果。
+- **三缓冲 xQueue**：支持 Main/Fold 双 chunk 并行载入。
+
+## 9. 主块、尾块、对齐和数值精度处理
+
+- **主块/尾块**：`ubFactor` 为主 chunk 长度，`ubFactorTail` 为尾 chunk（R 不能整除时）。尾块在 Step 1/3 中通过条件判断使用 `ubFactorTail`。
+- **折叠尾块**：当 `basicBlockIdx == mainFoldCount` 且 `ubFactorTail > 0` 时，折叠块使用 `ubFactorTail` 长度。
+- **对齐**：`ubFactor` 按 `Lcm(blockSize, Lcm(blockSize/dtypeSize, blockSize/dtypeSize))` 对齐。
+- **数值精度**：FP16/BF16 通过 `LoadTensorForDtypeTIn` 升至 FP32 计算；max/sum 用 FP32 维护；输出通过 `Cast` 降回。`xToFp32_` / `yToFp32_` 编译期常量控制转换路径。
+
+## 10. 独立 Kernel 入口示例
+
+```cpp
+#include "softmax_v2_tiling_data.h"
+#include "dav310/softmax_v2_base.h"
+#include "dav310/softmax_v2_ar_recompute.h"
+
+using namespace SoftmaxV2Ops;
+
+extern "C" __global__ __aicore__ __vector__ void
+softmax_ar_recompute_fp32(GM_ADDR x, GM_ADDR y, SoftmaxV2ArRecomputeTilingData tiling)
+{
+    TPipe pipe;
+    SoftmaxV2ArRecompute<float, float> op(&pipe);
+    op.Init(x, y, &tiling);
+    op.Process();
+}
+```
+
+## 11. 不适用场景和可选替代模板
+
+| 不适用场景 | 推荐替代 |
+|-----------|---------|
+| R 可载入 UB | [AR FullLoad](softmax_v2_ar_full_load.md)（无重读，带宽更优） |
+| R 极小（≤ 16/32） | [AR SmallR](softmax_v2_ar_small_r.md)（转置向量化） |
+| 3D [A1,R,A0] 布局（A0>1） | [ARA Recompute](softmax_v2_ara_recompute.md) |
+| 带宽极度受限、R 适中 | 评估 FullLoad 是否可用（3× 重读代价高） |

package/skills/tool-ops-tune/ops-family/references/reduce/templates/softmax_v2_ar_small_r.md

@@ -0,0 +1,122 @@
+# SoftmaxV2 AR SmallR 模板
+
+## 1. 模板用途
+
+针对 2D `[A1, R]` 布局、归约轴 R 极小（FP32 ≤ 16 / FP16/BF16 ≤ 32）的 Softmax 场景。通过将数据转置为 `(R, A1)` 布局，使短归约轴转到外层、长伴生轴转为向量化方向，将 VReg 利用率从 R/64 提升到接近 100%。
+
+## 2. 输入输出布局和 Softmax 轴
+
+- 输入 `x`：`[A1, R]`，行优先，Softmax 沿 R 轴（最后一轴）计算。
+- 输出 `y`：`[A1, R]`，与输入同 shape、同 dtype。
+- 内部转置为 `(R, A1)` 布局进行 VF 计算，输出前转置回 `(A1, R)`。
+
+## 3. 适用 shape、dtype 和 UB 条件
+
+| 条件 | 要求 |
+|------|------|
+| 输入维数 | 2D，A0 = 1 |
+| R 大小 | FP32 ≤ 16，FP16/BF16 ≤ 32（R ≤ 2×VL_FP32 = 128 时可转置向量化） |
+| dtype | FP32、FP16、BF16 |
+| UB 约束 | `tileA0Len * rAligned * (dtypeSize*2 + 4) * 2 + tileA0Len * 4` ≤ UB |
+
+## 4. 类名、构造函数和 Init 接口
+
+```cpp
+namespace SoftmaxV2Ops;
+
+template <typename Tx, typename Ty>
+class SoftmaxV2ArSmallR {
+public:
+    __aicore__ inline SoftmaxV2ArSmallR(TPipe* pipe);
+    __aicore__ inline void Init(GM_ADDR x, GM_ADDR y, const SoftmaxV2ArSmallRTilingData* tilingDataIn);
+    __aicore__ inline void Process();
+};
+```
+
+- **构造函数**：接收 `TPipe*`，保存 pipe 指针。
+- **Init**：接收输入 x、输出 y 的 GM 地址和 TilingData 指针，初始化 GlobalTensor 和 UB Buffer。
+- **Process**：执行完整 Softmax 计算。
+
+## 5. 对应的 TilingData 和字段说明
+
+对应 `SoftmaxV2ArSmallRTilingData`，定义在 [softmax_v2_tiling_data.h](softmax_v2_tiling_data.template)。
+
+| 字段 | 含义 | 单位 |
+|------|------|------|
+| totalA0Len | 转置后 A0 维长度（= 原 A1） | 元素数 |
+| totalRLen | 归约轴 R 实际长度 | 元素数 |
+| totalTiles | A0 方向总 tile 数 | tile |
+| tilesPerCore | 每核 tile 数 | tile |
+| tileA0Len | 主块 A0 tile 长度 | 元素数 |
+| tileA0Tail | 尾块 A0 长度 | 元素数 |
+| rTileBase | R 转置基础块（FP32=8/FP16=16） | 元素数 |
+| rAligned | R 对齐后长度 | 元素数 |
+
+## 6. Host tiling 参数计算方法
+
+使用 [softmax_v2_tiling.h](softmax_v2_tiling.template) 中的 `TilingArSmallR`：
+
+```cpp
+softmax_tiling::CaseShape shape{a1, r, 1, dtypeCode};
+softmax_tiling::PlatformParam plat{ubSize, numBlocks};
+SoftmaxV2ArSmallRTilingData td;
+int64_t blockDim = softmax_tiling::TilingArSmallR(shape, plat, td);
+```
+
+关键计算：
+- `rTileBase` = FP32 ? 8 : 16
+- `rAligned` = CeilDiv(R, rTileBase) × rTileBase
+- `tileA0Len` = a0TileNum × VL_FP32，受 UB 容量约束
+- `totalTiles` = CeilDiv(A1, tileA0Len)
+
+## 7. CopyIn、归约、归一化和 CopyOut 流程
+
+```
+Process:
+  1. preload 第一个 tile，CopyInAndTransPose（MultiCopy 转置 (A1,R)→(R,A1)）
+  2. for 每个 tile:
+     a. CalcMaxSubExp: 逐 A0 列求 max，sub max，exp，写入 tmpLocal 和 tmpLocal2
+     b. CopyInAndTransPose: 预载下一个 tile（双缓冲）
+     c. CalcReduceSum: 沿 R 轴 ReduceSum（Pattern::Reduce::RA）
+     d. CalcOutput: 逐列 div sum，FP16/BF16 做 Cast
+     e. CalcTranspose: TransDataTo5HD 转置回 (A1,R)
+     f. CopyOutY: DataCopyPad 写回 GM
+```
+
+## 8. 转置优化
+
+- **MultiCopy 转置**：使用 `MultiCopyParams<Tx, 2>` + `MultiCopyLoopInfo<2>` 在 CopyIn 阶段直接完成 `(A1,R)→(R,A1)` 转置，避免额外转置 pass。
+- **TransDataTo5HD**：输出前使用 `TransDataTo5HD` 将 `(R,A1)` 转回 `(A1,R)`，FP32 和 FP16/BF16 分别使用不同的 block 参数。
+- **VF 向量化**：转置后长轴 A1 沿 VReg 方向，每个 VReg 可处理 64 个 FP32 元素，利用率接近 100%。
+
+## 9. 主块、尾块、对齐和数值精度处理
+
+- **主块/尾块**：`tileA0Len` 为主块长度，`tileA0Tail` 为最后一个 tile 的实际长度。尾块通过 `UpdateMask` 精确掩码处理。
+- **对齐**：R 按 `rTileBase`（FP32=8/FP16=16）向上对齐，A0 按 `VL_FP32`（64）对齐。
+- **数值精度**：FP16/BF16 输入在计算前 `Cast` 升至 FP32，计算完成后 `Cast` 降回原精度。使用 `castTraitFp16ToFp32` / `castTraitFp32ToFp16` 控制饱和模式和舍入。
+
+## 10. 独立 Kernel 入口示例
+
+```cpp
+#include "softmax_v2_tiling_data.h"
+#include "dav310/softmax_v2_base.h"
+#include "dav310/softmax_v2_ar_small_r.h"
+
+using namespace SoftmaxV2Ops;
+
+extern "C" __global__ __aicore__ __vector__ void
+softmax_ar_small_r_fp32(GM_ADDR x, GM_ADDR y, SoftmaxV2ArSmallRTilingData tiling)
+{
+    TPipe pipe;
+    SoftmaxV2ArSmallR<float, float> op(&pipe);
+    op.Init(x, y, &tiling);
+    op.Process();
+}
+```
+
+## 11. 不适用场景和可选替代模板
+
+| 不适用场景 | 推荐替代 |
+|-----------|---------|
+| R > 2×VL_FP32（128） | [AR FullLoad](softmax_v2_ar_full_load.md)（R 可载入 UB）或 [AR Recompute](softmax_v2_ar_recompute.md)（R 超 UB） |
+| 3D [A1,R,A0] 布局（A0>1） | [ARA FullLoad](softmax_v2_ara_full_load.md) 或 [ARA Recompute](softmax_v2_ara_recompute.md) |

package/skills/tool-ops-tune/ops-family/references/reduce/templates/softmax_v2_ara_full_load.md

@@ -0,0 +1,144 @@
+# SoftmaxV2 ARA FullLoad 模板
+
+## 1. 模板用途
+
+针对 3D `[A1, R, A0]` 布局、R×A0_tile 可载入 UB 的 Softmax 场景。沿 A0 切 tile，跨 R 逐列 VF 计算，根据 R 大小分支选择不同的归约路径（R≤2、R≤4、R≤8 直接累加；R>8 使用 BinaryAddVF 二分折叠）。
+
+## 2. 输入输出布局和 Softmax 轴
+
+- 输入 `x`：`[A1, R, A0]`，行优先，Softmax 沿 R 轴计算。
+- 输出 `y`：`[A1, R, A0]`，与输入同 shape、同 dtype。
+- 数据在 UB 中布局为 `(R, tileA0Len)`，沿 R 逐行处理，A0 方向向量化。
+
+## 3. 适用 shape、dtype 和 UB 条件
+
+| 条件 | 要求 |
+|------|------|
+| 输入维数 | 3D，A0 > 1 |
+| R 大小 | R×tileA0Len 可载入 UB |
+| dtype | FP32、FP16、BF16 |
+| UB 约束 | `tileA0Len × (R+1) × (dtypeSize×2 + 4) + tileA0Len × 4` ≤ UB |
+
+## 4. 类名、构造函数和 Init 接口
+
+```cpp
+namespace SoftmaxV2Ops;
+
+template <typename T1, typename T2>
+class SoftmaxV2ARA {
+public:
+    __aicore__ inline SoftmaxV2ARA();
+    __aicore__ inline SoftmaxV2ARA(const SoftmaxV2ARATilingData* tilingDataIn);
+    __aicore__ inline void Init(GM_ADDR x, GM_ADDR y, TPipe* pipeIn);
+    __aicore__ inline void Process();
+};
+```
+
+- **构造函数**：无参默认构造，或接收 TilingData 指针。
+- **Init**：接收 x/y GM 地址和 `TPipe*`，初始化 GlobalTensor 和 UB Buffer（xQueue/yQueue 双缓冲 + xTmpBuf + xReduceBuf）。
+- **Process**：按 tile 遍历所有 (A1, A0) 组合，逐 tile 计算 Softmax。
+
+> **注意**：ARA 系模板的构造/Init 方式与 AR 系不同——ARA 在 Init 中接收 `TPipe*`，而 AR 在构造函数中接收。
+
+## 5. 对应的 TilingData 和字段说明
+
+对应 `SoftmaxV2ARATilingData`，定义在 [softmax_v2_tiling_data.h](softmax_v2_tiling_data.template)。
+
+主要字段：
+
+| 字段 | 含义 | 单位 |
+|------|------|------|
+| totalA1Len / totalRLen / totalA0Len | 各维总长度 | 元素数 |
+| totalTiles | 总 tile 数 = A1 × a0Outer | tile |
+| tilesPerCore | 每核 tile 数 | tile |
+| usedCoreNums | 实际使用核数 | 核 |
+| a0Outer | A0 方向 tile 总数 | tile |
+| tileA0Len / tileA0Tail | 主块/尾块 A0 tile 长度 | 元素数 |
+| binaryAddK | BinaryAdd 外层折叠层数 | 层 |
+| binaryAddLast | 最后是否需额外 2→1 折叠 | 标志 |
+| binaryAddInnerLoop | BinaryAdd 每层内循环次数 | 次 |
+| remainderLoopCount | R 对 8 取余后的折叠循环数 | 次 |
+| quotientLoopCount | R 整除 8 后的剩余折叠循环数 | 次 |
+| remainderTailOffset0~7 | 余数尾块各行偏移（越界指向 validNumInXUb 做零填充） | 元素数 |
+
+## 6. Host tiling 参数计算方法
+
+使用 [softmax_v2_tiling.h](softmax_v2_tiling.template) 中的 `TilingAraFullLoad`：
+
+```cpp
+softmax_tiling::CaseShape shape{a1, r, a0, dtypeCode};
+softmax_tiling::PlatformParam plat{ubSize, numBlocks};
+SoftmaxV2ARATilingData td;
+int64_t blockDim = softmax_tiling::TilingAraFullLoad(shape, plat, td);
+```
+
+关键计算：
+- `a0TileBase` = FP32 ? 64 : 128
+- `tileA0Len` = a0Inner × a0TileBase，受 UB 容量和核数约束
+- 当 R ≤ 8 时，binaryAdd* 字段不使用
+- 当 R > 8 时，`binaryAddQuotient` = 最大 2^k ≤ R-1，按 8 行分组做 BinaryAddVF
+
+## 7. CopyIn、归约、归一化和 CopyOut 流程
+
+```
+Process:
+  for 每个 tile (curA1Idx, curA0Idx):
+    1. CopyInX: DataCopyPad 批量载入 (curTileRLen × curTileA0Len) 块
+    2. Compute:
+       a. VFShiftVector: 逐 A0 列求 max → sub max → exp → 写入 xTmpLocal
+       b. VFReduceSum: 按 R 大小分支求 sum
+       c. VFCalculateOutput: 逐列 div sum → Cast 回原精度
+    3. CopyOutY: DataCopyPad 写回 GM
+```
+
+## 8. VF、BinaryAddVF 优化
+
+### R 大小分支归约
+
+| R 范围 | 归约路径 | 说明 |
+|--------|---------|------|
+| R ≤ 2 | `SumRLessThan2` | 逐行 VF `Add` 累加 |
+| R ≤ 4 | `SumRLessThan4` | 2 行配对 + 尾行处理（`TwoRowAddWithTail`） |
+| R ≤ 8 | `SumRLessThan8` | 4 行配对 + 尾行处理 |
+| R > 8 | `SumRMoreThan8` + `BinaryAddVF` | 8 行分组 + 二分折叠 |
+
+### BinaryAddVF 二分折叠（R > 8）
+
+1. **行分组**：将 R 行按 8 行一组分组，每组内用 `TwoRowAdd` 做 4→2→1 折叠。
+2. **余数处理**：不满 8 行的余数部分，用 `remainderTailOffset0~7` 精确控制每行偏移，越界行指向 `validNumInXUb`（零填充区域）。
+3. **二分树**：`BinaryAddVF` 按 `binaryAddK` 层 × `binaryAddInnerLoop` 次，每次 4→1 折叠，最后若 `binaryAddLast=1` 额外做 2→1。
+4. **TwoRowAddWithTail**：通用工具函数，处理 2 行配对 + 2 个尾行偏移。
+
+## 9. 主块、尾块、对齐和数值精度处理
+
+- **主块/尾块**：`tileA0Len` 为主块 A0 长度，`tileA0Tail` 为最后一个 A0 tile 的实际长度。尾块通过 `copyInParams.dstStride` 和 `copyInParams.srcStride` 处理非对齐。
+- **对齐**：A0 按 `a0TileBase`（FP32=64/FP16=128）对齐，`dstStride` 按 `BLOCK_SIZE`（32B）对齐。
+- **零填充**：R > 8 时，在 `xTmpLocal[validNumInXUb]` 位置写入零值，余数尾块越界行指向该区域，等效于零填充。
+- **数值精度**：FP16/BF16 通过 `LoadTensorForDtypeT1`（`DIST_UNPACK_B16` + `Cast`）升至 FP32；输出通过 `Cast` + `DIST_PACK_B32` 降回。
+
+## 10. 独立 Kernel 入口示例
+
+```cpp
+#include "softmax_v2_tiling_data.h"
+#include "dav310/softmax_v2_base.h"
+#include "dav310/softmax_v2_ara_full_load.h"
+
+using namespace SoftmaxV2Ops;
+
+extern "C" __global__ __aicore__ __vector__ void
+softmax_ara_full_load_fp32(GM_ADDR x, GM_ADDR y, SoftmaxV2ARATilingData tiling)
+{
+    TPipe pipe;
+    SoftmaxV2ARA<float, float> op(&tiling);
+    op.Init(x, y, &pipe);
+    op.Process();
+}
+```
+
+## 11. 不适用场景和可选替代模板
+
+| 不适用场景 | 推荐替代 |
+|-----------|---------|
+| R×tileA0 超 UB | [ARA Recompute](softmax_v2_ara_recompute.md)（R 切 bin 三阶段重读） |
+| A0 = 1（2D） | [AR FullLoad](softmax_v2_ar_full_load.md) 或 [AR SmallR](softmax_v2_ar_small_r.md) |
+| 需要在线更新（避免 3 次读入） | [ARA Online](softmax_v2_ara_online.md)（2 次读入） |

package/skills/tool-ops-tune/ops-family/references/reduce/templates/softmax_v2_ara_online.md

@@ -0,0 +1,185 @@
+# SoftmaxV2 ARA Online Softmax 模板
+
+## 1. 模板用途
+
+针对 3D `[A1, R, A0]` 布局的独立 Softmax 场景，使用在线（online）算法沿 R 分 chunk 逐块搬入，为每个 A0 列维护 running max 和 running sum。相比 ARA Recompute（输入读 3 次：max/sum/output），Online Softmax 将 max 与 sum 融合为单遍在线更新，输入只需读 2 次（1 遍在线 max+sum，1 遍输出），减少一次 R 全量搬入。
+
+> **重要**：本模板是**独立的 Online Softmax**，不包含 `QK^T`、`P×V`、`O_acc`、causal mask 或 FlashAttention 的 Cube/Vector 融合。它与 [融合 Attention Online Softmax 设计](fused_attention_online_softmax_design.md) 只共享在线 max/sum 数学基础，不是同一个实现。
+
+## 2. 输入输出布局和 Softmax 轴
+
+- 输入 `x`：`[A1, R, A0]`，行优先，Softmax 沿 R 轴计算。
+- 输出 `y`：`[A1, R, A0]`，与输入同 shape、同 dtype。
+- 输入为已经生成的 Softmax 数据，输出为完整 Softmax 概率。
+
+## 3. 适用 shape、dtype 和 UB 条件
+
+| 条件 | 要求 |
+|------|------|
+| 输入维数 | 3D，A0 > 1 |
+| R 大小 | 任意（R 分 chunk 处理，不受 UB 限制） |
+| dtype | FP32、FP16、BF16 |
+| UB 约束 | 双缓冲 xQueue/yQueue + xMaxBuf + xSumBuf，按 rChunkFactor 分 chunk |
+
+## 4. 类名、构造函数和 Init 接口
+
+```cpp
+namespace SoftmaxV2Ops;
+
+template <typename T1, typename T2>
+class SoftmaxV2ARAOnline : public SoftmaxV2OpsBase {
+public:
+    __aicore__ inline SoftmaxV2ARAOnline();
+    __aicore__ inline SoftmaxV2ARAOnline(const SoftmaxV2ARAOnlineTilingData* tilingDataIn);
+    __aicore__ inline void Init(GM_ADDR x, GM_ADDR y, TPipe* pipeIn);
+    __aicore__ inline void Process();
+};
+```
+
+- **构造函数**：无参默认，或接收 TilingData 指针。
+- **Init**：初始化 GM/UB buffer，xQueue/yQueue（双缓冲，大小 = `tileA0Len × rChunkFactor`）+ xMaxBuf/xSumBuf。
+- **Process**：按 tile 遍历，每 tile 执行在线 max+sum 和输出两遍。
+
+## 5. 对应的 TilingData 和字段说明
+
+对应 `SoftmaxV2ARAOnlineTilingData`，定义在 [softmax_v2_tiling_data.h](softmax_v2_tiling_data.template)。
+
+| 字段 | 含义 | 单位 |
+|------|------|------|
+| totalRLen / totalA0Len | R/A0 维总长度 | 元素数 |
+| totalTiles | 总 tile 数 = A1 × tileA0Outer | tile |
+| tilesPerCore | 每核 tile 数 | tile |
+| usedCoreNums | 实际使用核数 | 核 |
+| tileA0Outer | A0 方向 tile 总数 | tile |
+| tileA0Len / tileA0Tail | 主块/尾块 A0 长度 | 元素数 |
+| rChunkFactor | R 方向单 chunk 长度（默认 128） | 元素数 |
+| rChunkTotalLoop | R 方向 chunk 总数 | chunk |
+| rChunkTail | R 方向尾 chunk 长度 | 元素数 |
+
+## 6. Host tiling 参数计算方法
+
+使用 [softmax_v2_tiling.h](softmax_v2_tiling.template) 中的 `TilingAraOnline`：
+
+```cpp
+softmax_tiling::CaseShape shape{a1, r, a0, dtypeCode};
+softmax_tiling::PlatformParam plat{ubSize, numBlocks};
+SoftmaxV2ARAOnlineTilingData td;
+int64_t blockDim = softmax_tiling::TilingAraOnline(shape, plat, td);
+```
+
+关键计算：
+- `rChunkFactor` = min(128, R)
+- `rChunkTotalLoop` = CeilDiv(R, rChunkFactor)
+- `rChunkTail` = R - (rChunkTotalLoop - 1) × rChunkFactor
+- UB 占用（每个 A0 列）：`2 × rChunkFactor × dtypeSize + 2 × rChunkFactor × 4 + 4 + 4` 字节
+
+## 7. 在线更新公式
+
+沿 R 分 chunk，按 A0 列独立维护 running max (`m`) 和 running sum (`l`)：
+
+```text
+m_new = max(m_old, chunk_max)
+corr  = exp(m_old - m_new)
+l_new = l_old * corr + sum(exp(x - m_new))
+```
+
+最终 Softmax 输出：`softmax(x) = exp(x - m_final) / l_final`
+
+### 与 ARA Recompute 三次读取输入的区别
+
+| 特性 | ARA Recompute | ARA Online |
+|------|--------------|------------|
+| 输入读取次数 | 3 次（max/sum/output） | 2 次（在线 max+sum / output） |
+| max 与 sum 计算 | 分离（先 max 全量，再 sum 全量） | 融合（单遍在线更新） |
+| cache buffer | 需要（二分累加树） | 不需要 |
+| 数值稳定性 | Safe Softmax（先减 max） | Safe Softmax（在线减 running max） |
+| 带宽 | 3× R 全量读 | 2× R 全量读 |
+
+## 8. CopyIn、归约、归一化和 CopyOut 流程
+
+```
+Process（逐 tile）:
+  第一遍 — CalcOnlineMaxSum:
+    初始化 running max = -inf, running sum = 0
+    for 每个 R chunk:
+      CopyInX → 逐 A0 列:
+        1. 求 chunk 内局部 max (mLocal)
+        2. m_new = max(m_old, mLocal)
+        3. corr = exp(m_old - m_new)
+        4. chunk_sum = Σ exp(x - m_new)
+        5. l_new = l_old * corr + chunk_sum
+        6. 更新 xMaxLocal = m_new, xSumLocal = l_new
+
+  第二遍 — 输出:
+    for 每个 R chunk:
+      CopyInX → CalcOutput:
+        sub max → exp → div sum → Cast 回原精度
+      CopyOutY → GM
+```
+
+## 9. 主块、尾块、FP32 running 状态和数值稳定性
+
+- **主块/尾块**：`tileA0Len` 为主块 A0 长度，`tileA0Tail` 为尾块。`rChunkTail` 为 R 方向尾 chunk 长度。
+- **对齐**：A0 按 `a0TileBase`（FP32=8/FP16=16）对齐。
+- **FP32 running 状态**：running max 和 running sum 始终用 FP32 维护（`xMaxBuf`/`xSumBuf` 为 `float` 类型），即使输入/输出为 FP16/BF16，确保数值稳定性。
+- **数值稳定性**：
+  - 每步减去 running max `m_new`，避免 exp 溢出。
+  - `corr = exp(m_old - m_new)` ≤ 1（因 m_new ≥ m_old），修正历史 sum。
+  - 第一遍在线计算最终 max 和 sum，第二遍用最终值做归一化。
+
+## 10. 独立 Kernel 入口示例
+
+```cpp
+#include "softmax_v2_tiling_data.h"
+#include "dav310/softmax_v2_base.h"
+#include "dav310/softmax_v2_ara_online.h"
+
+using namespace SoftmaxV2Ops;
+
+extern "C" __global__ __aicore__ __vector__ void
+softmax_ara_online_fp32(GM_ADDR x, GM_ADDR y, SoftmaxV2ARAOnlineTilingData tiling)
+{
+    TPipe pipe;
+    SoftmaxV2ARAOnline<float, float> op(&tiling);
+    op.Init(x, y, &pipe);
+    op.Process();
+}
+```
+
+### Host tiling 示例
+
+```cpp
+#include "softmax_v2_tiling.h"
+
+softmax_tiling::PlatformParam plat;
+plat.ubSize = ubSize;       // 运行时查询
+plat.numBlocks = numBlocks; // 运行时查询
+
+softmax_tiling::CaseShape shape;
+shape.a1 = 4; shape.r = 2049; shape.a0 = 256; shape.dtypeCode = 0; // FP32
+
+SoftmaxV2ARAOnlineTilingData td;
+int64_t blockDim = softmax_tiling::TilingAraOnline(shape, plat, td);
+// blockDim 为 <<<>>> 启动核数
+```
+
+## 11. 本模板不包含的内容
+
+本模板是**独立的 Online Softmax**，不包含：
+
+- `QK^T`（score 计算）
+- `P×V`（概率与 Value 的乘积）
+- `O_acc`（输出累加器）
+- causal mask（因果掩码）
+- Attention workspace
+- FlashAttention 的 Cube/Vector 融合
+
+如需了解融合 Attention 中的 Online Softmax 设计，参见 [融合 Attention Online Softmax 设计](fused_attention_online_softmax_design.md)。两者只共享在线 max/sum 数学基础，不是同一个实现。
+
+## 12. 不适用场景和可选替代模板
+
+| 不适用场景 | 推荐替代 |
+|-----------|---------|
+| A0 = 1（2D） | [AR Recompute](softmax_v2_ar_recompute.md) |
+| R×tileA0 可载入 UB 且带宽充裕 | [ARA FullLoad](softmax_v2_ara_full_load.md)（单次载入） |
+| R 超 UB 且不需要在线更新 | [ARA Recompute](softmax_v2_ara_recompute.md)（三阶段重读） |