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

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/reduction/ara-rowsplit.md

@@ -0,0 +1,219 @@
+# Reduce 类算子 - ARA Row-Split 分支
+
+> **适用场景**: A0>1（非尾轴）, R > R_max（分载模式）
+
+---
+
+## 目录
+
+- [一、分支特征](#一分支特征)
+- [二、Buffer 规划](#二buffer-规划)
+- [三、Tiling 参数计算](#三tiling-参数计算)
+- [四、Kernel 实现要点](#四kernel-实现要点)
+- [五、常见问题](#五常见问题)
+- [六、性能优化建议](#六性能优化建议)
+
+---
+
+## 一、分支特征
+
+| 特征 | 说明 |
+|------|------|
+| **模板类型** | ARA 模板（A 轴 + R 轴 + A 轴） |
+| **Shape 抽象** | (A1, R, A0) |
+| **载入模式** | 分载（R 行放不下，分 chunk 处理） |
+| **适用条件** | A0>1, R > R_max |
+| **切分方向** | 行方向（沿 R 分 chunk） |
+| **数据连续性** | 每列 R 个元素不连续（间隔 A0） |
+| **Reduce 结果** | 向量（A0 个值） |
+
+---
+
+## 二、Buffer 规划
+
+### 2.1 FP32 场景（Kernel侧）
+
+```cpp
+// Single Buffer 模式（分 chunk 处理）
+constexpr uint32_t a0TileBase = 64;  // FP32
+
+pipe->InitBuffer(inQueueX, 1, R_chunk_size * a0TileBase * sizeof(float));
+pipe->InitBuffer(outQueueY, 1, a0TileBase * sizeof(float));  // 最终结果
+pipe->InitBuffer(globalResultBuf, 1, a0TileBase * sizeof(float));  // 全局结果
+pipe->InitBuffer(chunkResultBuf, 1, a0TileBase * sizeof(float));  // chunk结果
+pipe->InitBuffer(tmpBuf, 1, tmpBufSize);
+
+// 总 UB = R_chunk×a0TileBase×4 + 3×a0TileBase×4 + tmpBufSize
+```
+
+### 2.2 tmpBufSize 计算（Host侧）
+
+```cpp
+// tmpBufSize 基于 R_chunk_size × alignedCols
+uint32_t alignedCols = ((tileA0Len * sizeof(float) + 31) / 32) * 32 / sizeof(float);
+
+constexpr uint32_t VECTOR_REG_WIDTH = 256;
+uint32_t perRepeat = VECTOR_REG_WIDTH / sizeof(float);  // 64
+uint32_t perBlock = 32 / sizeof(float);  // 8
+
+uint32_t repeats = (R_chunk_size * alignedCols + perRepeat - 1) / perRepeat;
+uint32_t tmpBufSize = ((repeats + perBlock - 1) / perBlock) * perBlock * sizeof(float);
+tmpBufSize = std::max(tmpBufSize, 4096u);
+```
+
+- tileA0Len是对A0进行切分分核之后，每个核需要处理的列数。
+---
+
+## 三、Tiling 参数计算
+
+### 3.1 分载判定（Host侧）
+
+```cpp
+// R_max 计算（注意：与全载模式公式不同，此处为单缓冲，overhead 和除数均不同）
+constexpr uint32_t a0TileBase = 64;  // FP32
+uint32_t tmpBufSize = 4096;
+uint32_t overhead = 3 * a0TileBase * sizeof(float) + tmpBufSize;
+uint32_t R_max = (UB_SIZE - overhead) / (a0TileBase * sizeof(float));
+R_max = std::min(R_max, 255u);
+R_max = std::max(R_max, 1u);
+
+if (R > R_max) {
+    // ARA-Row-Split 模式
+    loadMode = LOAD_SPLIT;
+    
+    // R 分 chunk
+    uint32_t R_chunks = (R + R_max - 1) / R_max;
+    uint32_t R_chunk_size = R_max;
+    uint32_t R_last_chunk_size = R - (R_chunks - 1) * R_chunk_size;
+}
+```
+
+### 3.2 A0Inner 计算（对A0进行多核切分，Host侧）
+
+```cpp
+// Row-Split buffer 使用: R_chunk×a0TileBase×4 + 3×a0TileBase×4 + tmpBufSize
+uint64_t ubPerTileBase = R_chunk_size * a0TileBase * sizeof(float) 
+                       + 3 * a0TileBase * sizeof(float) + tmpBufSize;
+uint64_t fixedOverhead = 3 * a0TileBase * sizeof(float) + tmpBufSize;
+
+int64_t factorMax = (UB_SIZE - fixedOverhead) / ubPerTileBase;
+if (factorMax < 1) factorMax = 1;
+
+int64_t a0FactorMax = (A0 + a0TileBase - 1) / a0TileBase;
+int64_t totalTilesMax = A1 * a0FactorMax;
+int64_t a0InnerMax = (totalTilesMax + blockDim - 1) / blockDim;
+
+int64_t a0Inner = std::min({a0InnerMax, factorMax, a0FactorMax});
+a0Inner = std::max(a0Inner, 1L);
+
+uint32_t tileA0Len = a0Inner * a0TileBase;
+```
+
+---
+
+## 四、Kernel 实现要点
+
+### 4.1 数据流
+
+```
+GM (A1, R, A0) → 分 R chunk 处理
+    ↓
+Chunk 0: GM[0:R_chunk, 0:tileA0Len] → UB
+    ↓
+[ReduceMax/ReduceSum Pattern::Reduce::RA] → chunkResult_0 (tileA0Len)
+    ↓
+[更新 globalResult] → globalResult = merge(globalResult, chunkResult_0)
+    ↓
+Chunk 1, 2, ... (重复)
+    ↓
+UB → GM (A1, A0)
+```
+
+**为什么选择 Pattern::Reduce::RA**:
+
+多核切分后，每个核处理部分 `(R_chunk, A0_inner)` 的数据，在 UB 中布局为：
+```
+[row0的全部A0_inner, row1的全部A0_inner, ..., row{R_chunk-1}的全部A0_inner]
+```
+即 `(R_chunk, alignedCols)` 的 2D 矩阵。
+
+Pattern::Reduce::RA 的含义：
+- **R** = Reduce 维度（沿第一维归约）
+- **A** = Align 维度（保留第二维）
+
+对于每个 `a0` 位置，取 R_chunk 个值归约，输出 A0_inner 个结果。
+
+**注意**：不能用 Level 2 API，因为它只能处理连续数据。
+
+### 4.2 核心 API 调用
+
+#### ReduceMax 分载实现
+
+```cpp
+// 对齐后的列数
+uint32_t alignedCols = ((tileA0Len * sizeof(float) + 31) / 32) * 32 / sizeof(float);
+
+// 初始化全局最大值为 -∞
+LocalTensor<float> globalResultLocal = globalResultBuf.Get<float>();
+Duplicate<float>(globalResultLocal, -INFINITY, alignedCols);
+
+for (uint32_t chunkIdx = 0; chunkIdx < R_chunks; chunkIdx++) {
+    uint32_t rStart = chunkIdx * R_chunk_size;
+    uint32_t rCount = (chunkIdx == R_chunks - 1) ? R_last_chunk_size : R_chunk_size;
+    
+    // Load R chunk
+    DataCopyExtParams copyParams{static_cast<uint16_t>(rCount), 
+                                  static_cast<uint32_t>(tileA0Len * sizeof(float)), 
+                                  static_cast<uint32_t>((A0 - tileA0Len) * sizeof(float)), 
+                                  0, 0};
+    DataCopyPadExtParams<float> padParams{false, 0, 0, 0};
+    // shape will be [rCount, alignedCols] with `[rCount, tileA0Len]` valid data.
+    DataCopyPad(xLocal, xGm[rStart * A0], copyParams, padParams);
+    
+    // ReduceMax for this chunk (Pattern::Reduce::RA)
+    uint32_t srcShape[] = {rCount, alignedCols};
+    LocalTensor<float> chunkResultLocal = chunkResultBuf.Get<float>();
+    ReduceMax<float, Pattern::Reduce::RA>(chunkResultLocal, xLocal, tmpLocal, srcShape, true);
+    
+    // Update globalResult (逐元素取最大值)
+    Max<float>(globalResultLocal, globalResultLocal, chunkResultLocal, alignedCols);
+}
+
+// 输出最终结果
+DataCopyPad(yGm[offset], globalResultLocal, {1, tileA0Len * sizeof(float), 0, 0, 0});
+```
+
+### 4.3 关键注意点
+
+1. **跨 chunk 合并**: 
+   - ReduceMax: 使用 `Max<float>` 逐元素取最大值
+   - ReduceSum: 使用 `Add<float>` 逐元素累加
+
+2. **边界处理**: 最后一个 R chunk 的大小可能小于 R_chunk_size
+
+3. **初始化**: 
+   - ReduceMax: 初始化为 `-INFINITY` 或数据类型的最小值
+   - ReduceSum: 初始化为 `0`
+
+4. **数据访问**: 需要正确计算 srcStride 跨越 A0
+
+---
+
+## 五、常见问题
+
+| 问题 | 原因 | 解决方案 |
+|-----|------|---------|
+| 精度下降 | chunk 合并逻辑错误 | 使用 Max/Add 逐元素合并 |
+| 输出错误 | 最后一个 R chunk 大小处理错误 | 使用 R_last_chunk_size |
+| 性能差 | 多次遍历数据 | 优化 chunk 策略 |
+| Buffer 不足 | Buffer 规划不合理 | 合理分配 GM/UB 空间 |
+| 精度过大 | srcShape 使用 A0 而非 alignedCols | 使用对齐后的列数 |
+
+---
+
+## 六、性能优化建议
+
+1. **减少数据访问**: 尽量减少 GM 访问次数
+2. **chunk 大小优化**: R_chunk_size = R_max，确保每个 chunk 充分利用 UB
+3. **流水线**: 不同 tile 的 chunk 可以并行处理
+4. **逐元素合并**: 使用 `Max<float>` 和 `Add<float>` 而非 Reduce 操作

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/reduction/multi-axis-transform.md

@@ -0,0 +1,83 @@
+# 多轴归约处理
+
+> 本文档描述合轴后仍为多段 A/R 交替序列（如 ARAR）时，如何展开执行。
+> 合轴规则见 [patterns.md](patterns.md#合轴)。
+
+---
+
+## 实际算子示例
+
+| 算子 | Shape | Axes | 合轴后 Pattern |
+|------|-------|------|---------------|
+| reduce_sum | [2,3,4,5] | [1,3] | **ARAR** [2,3,4,5] |
+| reduce_sum | [2048,2,48,2,2,2] | [1,3,5] | **ARARAR** [2048,2,48,2,2,2] → pad→ **ARARARAR** (8维) |
+| bn_training_reduce | [N,C,H,W] | [0,2,3] | **ARAR** [1,N,C,H×W] |
+
+## 典型场景：BatchNorm "保留 C、归约 N/H/W"
+
+```
+bn_training_reduce: 对 NCHW 张量沿 N,H,W 归约，保留 C 通道维
+  输入: [N, C, H, W]    axes=[0, 2, 3]
+         R  A  R  R
+
+  合轴: axes 2,3 相邻且同为 R → 合并 → R[N], A[C], R[H×W]
+  前置 A[1] → ARAR [1, N, C, H×W]
+
+  输出: sum[C] 和 squareSum[C]（双输出，每个通道一个值）
+  特点: 双输出归约 — 同一遍扫描同时算 Σx 和 Σx²，避免二次遍历
+```
+
+---
+
+## 高维 Pattern（≥5 维）的统一处理
+
+变换后维度 ≥ 5 时，通过 PadDimOne() 填充 size=1 维度统一到 **8 维（ARARARAR）或 9 维（ARARARARA）**：
+
+```
+5 维 ARARA → pad 到 9 维 ARARARARA
+6 维 ARARAR → pad 到 8 维 ARARARAR
+7 维 ARARARA → pad 到 9 维 ARARARARA
+8 维 → 直接 ARARARAR
+9 维 → 直接 ARARARARA
+```
+
+---
+
+## Kernel 侧执行方式
+
+多轴 Pattern 展开为嵌套循环，每层 R 轴独立走 AR 或 ARA 判定：
+
+```
+IterateInnerA<0, N>()   ← 遍历所有 A 轴（递归模板，编译期展开）
+  for a0 in A_axis_0:
+    for a1 in A_axis_1:
+      ...
+        LinearComputeR()  ← 处理对应 R 轴归约
+          for r in R_axis:
+            CopyIn → PreReduce → ReduceCompute → DoCaching → PostReduce → CopyOut
+```
+
+**每层 R 轴的 AR/ARA 判定**：看该 R 轴右侧是否还有 A 维度
+- R 轴是最内层（右侧无 A）→ **AR 模式**，用 Level 2 Reduce API，详见 [ar-fullload.md](ar-fullload.md) / [ar-colsplit.md](ar-colsplit.md)
+- R 轴右侧还有 A 维度 → **ARA 模式**，用 Pattern::Reduce::RA，详见 [ara-fullload.md](ara-fullload.md) / [ara-rowsplit.md](ara-rowsplit.md)
+
+**示例**：ARAR [2,3,4,5] 展开为：
+```
+for a0 in range(2):       ← A 轴 0
+  for r0 in range(3):     ← R 轴 0（右侧有 A[4] → ARA 模式）
+    for a1 in range(4):   ← A 轴 1
+      for r1 in range(5): ← R 轴 1（右侧无 A → AR 模式）
+        Reduce(tile)
+```
+
+---
+
+## 非连续多轴的数据搬运
+
+多轴归约时内存往往不连续（如 axes=[0,2] 使得 R 轴散布在内存中）：
+
+```
+DAV_3510:    CopyInWithNddma() — 多维 DMA 自动处理 stride 跳跃
+DAV_2201: DataCopyPad 的 blockCount/blockLen/srcStride 参数配置 stride copy
+       或外层循环逐 slice 搬运（每次搬连续片段，循环处理不连续间隔）
+```

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/reduction/multi-output-buffer.md

@@ -0,0 +1,115 @@
+# 多输出归约的 Buffer 规划
+
+> 许多归约算子需要同一遍扫描输出多个结果，比单输出多占 UB。本文给出通用 Buffer 方程。
+
+---
+
+## 常见多输出场景
+
+| 算子 | 输出数 | 输出内容 | 累加器 dtype |
+|------|--------|---------|-------------|
+| bn_training_reduce | 2 | sum[C] + squareSum[C] | FP32 |
+| reduce_var / reduce_std | 2 | mean[A] + var[A] | FP32 |
+| reduce_std_with_mean | 2 | std[A] + mean[A] | FP32 |
+| arg_max / arg_min | 2 | value[A] + index[A] | FP32 + INT32/FP32 |
+| arg_max_with_value | 2 | value[A] + index[A] | 同上 |
+
+## 通用 UB 方程
+
+```
+输入:
+  T_in  = 输入元素大小 (FP16=2, FP32=4)
+  T_acc = 累加器元素大小 (通常 FP32=4)
+  K     = 输出个数（双输出 K=2，三输出 K=3）
+  A_aligned = 保留轴对齐后大小
+
+Buffer 清单:
+  inBuf × 2              = tileSize × T_in × 2          ← 输入双缓冲
+  castBuf (仅低精度)      = tileSize × T_acc             ← FP16/BF16 → FP32
+  accumBuf × K           = A_aligned × T_acc × K         ← K 个累加器
+  tmpBuf                 = A_aligned × T_acc             ← 中间计算（如 x²）
+  outBuf × 2             = A_aligned × T_acc × 2         ← 输出双缓冲（可选）
+
+UB 方程:
+  tileSize × (T_in × 2 + T_acc)              ← 输入 + Cast
+  + A_aligned × T_acc × (K + 1 + 2)          ← K 累加器 + tmp + out双缓冲
+  ≤ UB_SIZE (DAV_2201: 192KB)
+
+求解 tileSize:
+  fixedBuf = A_aligned × T_acc × (K + 3)
+  perTileBuf = T_in × 2 + T_acc
+  tileSize = (UB_SIZE - fixedBuf) / perTileBuf
+```
+
+## 双输出示例：bn_training_reduce (K=2, FP16 输入)
+
+```
+A_aligned = CeilAlign(C, 8)        ← FP32 按 32B 对齐: 32/4=8
+T_in = 2 (FP16), T_acc = 4 (FP32)
+
+fixedBuf = A_aligned × 4 × (2 + 3) = A_aligned × 20
+  分解: sumBuf(A×4) + sqSumBuf(A×4) + tmpBuf(A×4) + outBuf×2(A×4×2)
+
+perTileBuf = 2 × 2 + 4 = 8   (FP16 双缓冲 + FP32 Cast)
+
+tileSize = (192KB - A_aligned × 20) / 8
+
+示例: C=64 → A_aligned=64
+  fixedBuf = 64 × 20 = 1280B
+  tileSize = (196608 - 1280) / 8 = 24416 元素
+  实际取 tileRows = tileSize / A_aligned = 381 行
+```
+
+## 双输出示例：ArgMax (K=2, value + index)
+
+```
+A_aligned = CeilAlign(A, 8)
+
+累加器:
+  maxValBuf: A_aligned × 4 (FP32)      ← 当前最大值
+  maxIdxBuf: A_aligned × 4 (FP32)      ← 当前最大值的下标（存为 float）
+
+额外:
+  cmpBuf: A_aligned / 8 (uint8_t)      ← Compare mask
+  注意: DAV_2201 上 Select 不支持 int32 dst → 下标存为 float，最后 Cast 为 int32
+
+fixedBuf = A_aligned × 4 × 2 + A_aligned × 4 + max(A_aligned/8, 32) + outBuf
+```
+
+## 跨核合并时 Workspace 方程
+
+多输出时 workspace 也要乘 K：
+
+```
+workspace = coreNum × CeilAlign(A_aligned × T_acc × K, cacheLineSize)
+
+示例: bn_training_reduce, C=256, 20核
+  workspace = 20 × CeilAlign(256 × 4 × 2, 256) = 20 × 2048 = 40KB
+```
+
+---
+
+## NCHW 布局的数据搬运注意事项
+
+"保留 C 归约 NHW" 场景（bn_training_reduce）中，NCHW 布局的内存不是按通道连续的：
+
+```
+NCHW 内存布局: x[n,c,h,w] 地址 = n×C×H×W + c×H×W + h×W + w
+  同一 (n,h,w) 的 C 个通道值步长 = H×W（不连续！）
+  同一 (n,c) 的 H×W 个空间位置连续
+
+两种处理方式:
+  方式A（推荐，DAV_2201/DAV_3510 通用）: 按通道遍历，外层 (n, c)，内层连续搬 H×W
+    → 每次搬运连续内存（高效），需 C 个独立累加器
+    → 适合大多数场景
+
+  方式B（仅 DAV_3510）: 用 NDDMA 多维搬运，一次配置自动处理 stride 跳跃
+    → DAV_2201 不支持 NDDMA
+
+  方式C（DAV_2201）: DataCopyPad 配置 stride 参数
+    → blockCount=R 行数, blockLen=连续片段字节数, srcStride=跳跃步长
+    → 适合有规律的 stride 模式
+
+实际 batch_norm_v3 采用方式A: 按通道遍历，每通道累加 N×H×W 个连续值
+  参见 /ascendc-api-best-practices 获取 DataCopyPad stride 配置详情
+```

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/reduction/patterns.md

@@ -0,0 +1,212 @@
+# Reduction 类算子场景路由
+
+> 本文档用于**场景判定**和**策略选择**。确定场景后，按链接进入对应详细文档。
+
+---
+
+## 合轴
+
+将 N 维 shape + axes 简化为更少维度。每个维度标记为 **A**（保留轴）或 **R**（归约轴），然后：
+1. **消除冗余维度**：size=1 且内存连续的维度消除
+2. **合并相邻同类型轴**：相邻维度都是 A（或都是 R）→ 合并（乘积）
+
+**示例**：
+- shape=[2,100,4], axes=[1,2] → 标记 A,R,R → 相邻 R 合并 → [2, 400] = (A, R) → 单轴 AR
+- shape=[2,3,4,5,6,7,8], axes=[1,2,4] → 标记 A,R,R,A,R,A,A → 相邻 R 合并 → [2,12,5,6,56] = (A,R,A,R,A) → 多轴归约
+
+---
+
+## 场景判定流程
+
+```
+给定: shape, axes (归约轴)
+
+Step 0: 合轴（见上节）
+  标记 A/R → 消除冗余维 → 合并相邻同类型轴
+
+Step 1: 合轴后是单轴还是多轴？
+  ├─ 单轴（AR 或 ARA）→ Step 2
+  └─ 多轴（ARAR 等交替序列）→ Shape 三步变换（详见 multi-axis-transform.md）
+       展开为嵌套循环，每个 R 维的归约按 Step 2 判定
+
+Step 2: A0 决定模式
+  ├─ A0 = 1 → AR 模式（每行 R 个元素连续，用 Level 2 Reduce API）
+  │   ├─ 可以在UB中至少处理1整行数据 → AR-FullLoad    → [ar-fullload.md]
+  │   └─ 否则 → AR-ColSplit    → [ar-colsplit.md]
+  │
+  └─ A0 > 1 → ARA 模式（[R,A0] 块连续，用 Pattern::Reduce::RA）
+      ├─ 可以在UB中处理所有R*tileA0Len数据（32字节对齐） → ARA-FullLoad  → [ara-fullload.md]
+      └─ 否则 → ARA-RowSplit  → [ara-rowsplit.md]
+
+常见特例（本质都是 AR 或 ARA，按上面走）：
+  - axis=0（最外维）→ A1=1, ARA 模式
+  - 全轴归约        → 所有维度合并为 R, A0=1, AR 模式
+  - Norm 类（归约+广播变换）→ 归约部分走 AR/ARA，变换部分是应用层逻辑
+```
+
+**正交维度**（确定分支后，根据算子特征和数据规模选择）：
+
+| 维度 | 选项 | 适用条件 | 详细文档 |
+|------|------|---------|---------|
+| 算法选择 | Welford Online | 分载 + 需要流式计算两个相关统计量 | [algorithms.md](algorithms.md#welford-online在线单遍) |
+| 多核策略 | Group Reduce | R 太大单核处理不完 + A 太小不足以并行 | [algorithms.md](algorithms.md#group-reduce跨核归约) |
+| 精度策略 | 二分累加 | 大向量 sum 精度敏感 | [algorithms.md](algorithms.md#二分累加--half-interval) |
+| 索引跟踪 | With-Index | 归约+返回极值位置 | [with-index.md](with-index.md) |
+
+---
+
+## 通用规则
+
+以下规则适用于所有场景。Tiling 设计原则和 tmpBufSize 公式见 [tiling-fields.md](tiling-fields.md)。
+
+**rLength vs rLengthAlign 参数使用对照表**:
+
+| 参数位置 | 用 rLength（有效数据） | 用 rLengthAlign（对齐后） |
+|---------|:---:|:---:|
+| DataCopyPad blockLen | ✅ | ❌ |
+| Reduce API count（Level 2） | ✅ | ❌ |
+| UB 内 rowOffset 计算 | ❌ | ✅ |
+| Buffer 大小分配 | ❌ | ✅ |
+
+---
+
+## S1: AR 模式（最内维归约）
+
+适用: 合轴后单轴归约，且归约轴式尾轴的场景
+
+每行 R 个元素连续，使用 Level 2 Reduce API 逐行归约。
+
+**AR 分支决策树**：
+
+```
+AR 模式 (A1, R)，A0 = 1
+    │
+    ├─ 可以在UB中至少处理1整行数据？
+    │   │
+    │   YES → AR-FullLoad（全载）
+    │   │     整行 R 个元素驻留 UB，CopyIn 一次完成归约
+    │   │     中间结果直接复用，不需要重复搬入
+    │   │
+    │   NO  → AR-ColSplit（分载）
+    │         对列方向分段加载归约，每次搬入 Ar < AR 个元素
+    │         需要跨 chunk 合并（Max/Add）
+    │
+    └─ 两种模式都使用 Level 2 Reduce API（数据连续，无需 Pattern）
+```
+
+| 分支 | 条件 | 说明 | 详细文档 |
+|------|------|------|---------|
+| **全载（FullLoad）** | 可以在UB中至少处理1整行数据 | 整行驻留 UB，中间结果直接复用 | [ar-fullload.md](ar-fullload.md) |
+| **分载（ColSplit）** | 其他 | 对列方向分段，每次搬入 Ar < AR 个元素，跨 chunk 合并 | [ar-colsplit.md](ar-colsplit.md) |
+
+> **索引变体**：需要返回极值位置时，AR-FullLoad 用 `ReduceMax(calIndex=true)`，详见 [with-index.md](with-index.md)。
+
+> **AR 归约后的标量广播操作**：Level 2 Reduce 归约 [R] 后得到 1 个标量。
+> 如果后续需要将该标量广播到 [R] 向量参与逐元素运算，使用 `Adds(dst, src, scalar, count)`
+> 或 `Muls(dst, src, scalar, count)`，一次 API 调用完成，替换 Duplicate 填充 + Add/Mul操作。
+> 详见 `/ascendc-api-best-practices` 的 `api-arithmetic.md`。
+
+---
+
+## S2: ARA模式
+
+适用: 合轴后单轴归约，且归约轴非尾轴场景
+
+> **核心认知**：ARA 模式 `(A1, R, A0)` 下，沿外层 A1 切分后，每次处理一个 `[R, A0_inner]` 块。
+> 该块在 GM 中连续，整块搬入 UB 后即为 `(R, alignedCols)` 的二维矩阵，
+
+**数据流**:
+```
+GM (A1, R, A0) → DataCopyPad(blockCount=R) → UB (R × alignedCols)
+    ↓
+[ReduceMax/ReduceSum Pattern::Reduce::RA, srcShape={R, alignedCols}] → result (alignedCols)
+    ↓
+UB (alignedCols) → GM (A1, A0)
+```
+
+**关键 API 调用**:
+```cpp
+uint32_t alignedCols = ((tileA0Len * sizeof(float) + 31) / 32) * 32 / sizeof(float);
+uint32_t srcShape[] = {R, alignedCols};
+ReduceMax<float, Pattern::Reduce::RA>(resultLocal, xLocal, tmpLocal, srcShape, true);
+```
+
+**ARA 分支决策树**：
+
+```
+ARA 模式 (A1, R, A0)，A0 > 1
+    │
+    ├─ 可以在UB中处理所有R*tileA0Len数据（32字节对齐）？
+    │   │
+    │   YES → ARA-FullLoad（全载）
+    │   │     [R, tileA0Len] 整块驻留 UB，CopyIn 一次完成全部 R 行的归约
+    │   │     中间结果直接复用，不需要重复搬入
+    │   │
+    │   NO  → ARA-RowSplit（分载）
+    │         每次搬入 r < R 行，分多次才能完成全部 R 行的归约
+    │         需要跨 chunk 合并（Max/Add）
+    │
+    └─ 两种模式都使用 Pattern::Reduce::RA（不需要 Transpose）
+```
+- tileA0Len 是沿着A0进行多核切分后每个核处理的a0(<=A0)
+
+| 分支 | 条件 | 说明 | 详细文档 |
+|------|------|------|---------|
+| **全载（FullLoad）** | 可以在UB中处理所有R*tileA0Len数据（32字节对齐） | R 行一次放入 UB，中间结果直接复用 | [ara-fullload.md](ara-fullload.md) |
+| **分载（RowSplit）** | 其他 | 每次搬入 r < R 行，分多次归约后跨 chunk 合并 | [ara-rowsplit.md](ara-rowsplit.md) |
+
+> **索引变体**：需要返回极值位置时，用 `Compare+Select` 逐行迭代替代 `Pattern::Reduce::RA`。
+> 详见 [with-index.md](with-index.md)。
+
+> **ARA 归约后的广播操作**：Pattern::Reduce::RA 归约 [R, alignedCols] 后得到 [1, alignedCols] 的结果向量。
+> 如果后续需要将该向量广播回 [R, alignedCols] 参与逐元素运算，使用 Sub/Div/Mul 等二元 API 的
+> BinaryRepeatParams 版本，设置 `src1RepStride=0`，一次 API 调用完成所有 R 行，
+> 无需手动循环或额外 broadcast buffer。详见 `/ascendc-api-best-practices` 的 `api-arithmetic.md`。
+
+### S3: 多轴归约
+
+适用: 合轴后多轴归约，比如：ARARA场景
+
+**Shape 变换**：任意 N 维 shape + axes 经三步变换压缩为 A/R 交替序列。
+详见 [multi-axis-transform.md](multi-axis-transform.md)。
+
+### S4: Welford Online（R 需 UB 切片）
+
+**适用**: ARA 模式下需要流式计算两个相关统计量（第二个依赖第一个的增量更新）。典型算子：reduce_var / reduce_std。参见 [algorithms.md](algorithms.md#welford-online在线单遍)。
+
+### S5: Group Reduce（R 跨核）
+
+**条件**: R 太大，单核无法完成全部 R 归约；同时 A 太小不足以充分利用多核
+
+```
+Phase1（各核独立）: 每核处理 A[段] × R[段]，输出 partial → workspace
+SyncAll()
+Phase2（合并）: 遍历各核 partial，合并为最终结果
+```
+
+Workspace: `coreNum × CeilAlign(outAAlign × 2 × sizeof(int32_t), 256)`
+
+---
+
+## S6: 全局归约
+
+适用: reduce_sum(axes=所有轴), reduce_max(axes=所有轴)
+
+所有元素按核均分，各核独立归约后两阶段合并（Atomic 或显式 Merge）。
+
+```
+Stage1: 各核 ReduceSum(mySlice) → partial → workspace[blockIdx * 64B]
+Stage2:
+  方式A: SetAtomicAdd → DataCopy → SetAtomicNone → SyncAll
+  方式B: SyncAll → core0 遍历 workspace 合并
+```
+
+---
+
+## 跨场景参考
+
+| 主题 | 文档 |
+|------|------|
+| 多输出 Buffer 方程 | [multi-output-buffer.md](multi-output-buffer.md) |
+| 通用 Tiling 字段定义 | [tiling-fields.md](tiling-fields.md) |
+| 索引跟踪变体 | [with-index.md](with-index.md) |