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

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/paradigms/reduction/references/reduction-template-overview.md

@@ -0,0 +1,238 @@
+# reduction 模板总览
+
+> 描述本范式 kernel 模板划分、 TilingKey 划分、TilingData 划分及三者之间的联系
+
+| 概念 | 说明 |
+|------|------|
+| **模板** | Kernel 的编译期特化实例。同一份 kernel 代码根据 TilingKey 字段值的不同组合，编译出不同的执行路径 |
+| **TilingKey** | Host 端 tiling 阶段算出的编译期开关（一组 bool/int 等字段），决定运行时框架加载哪个编译实例。一个模板可对应多个 TilingKey（一对多），一个 TilingKey 只对应一个模板 |
+| **TilingData** | Host 端 tiling 阶段算出的运行时参数（struct）。一个模板只对应一个 TilingData，一个 TilingData 可被多个模板共用 |
+
+**三者协作流程**：TilingKey 决定"走哪条路"，TilingData 提供"路上的参数"。
+
+## 1 范式术语
+
+### 1.1 术语表
+
+| 术语 | 含义 |
+|------|------|
+| **A 轴** | 非 reduce 轴（preserve） |
+| **R 轴** | reduce 轴（沿此轴规约） |
+| **pattern** | 合轴预处理后轴的类型序列，形如 `A R A R …` |
+| **TailA** | 合轴预处理后尾轴是A，如 `ARA` |
+| **TailR** | 合轴预处理后尾轴是R，如 `ARAR` |
+| **Base 模板** | 仅A轴参与分核，核间无依赖，核内可处理完对应的R轴 |
+| **Group 模板** | A轴和R轴都参与分核，核间有依赖，需要二次reduce |
+| **空 tensor** | Empty Tensor, shape中含有0的tensor, 如 (3, 0)，分 EMPTY_A（A 轴含 0）和 EMPTY_R（R 轴含 0） |
+| **二分缓存树** | 所有 reduce 算子统一使用二分缓存树累加，提升累加精度（对 sum/mean 有精度收益，对 max/min/any/all 结果不变；prod 因 fp 舍入不满足结合律，结果可能有差异） |
+| **All Reduce** | 所有轴都 reduce 的算子，合轴后 pattern 恒为 `AR` |
+| **post_reduce_input** | PostReduce 阶段的额外 GM 输入（如 mean/variance 等统计量）。shape 与输出 y 相同（A 轴，size = aTotal） |
+| **D_T** | 算子 tensor 数据的 dtype（模板参数，如 fp16/bf16/fp32） |
+
+## 2 kernel 模板分类
+
+### 2.1 kernel 模板分类
+
+所有 reduce 算子（sum/mean/max/min/prod/any/all）统一使用二分缓存树累加。对 sum/mean 有精度收益，对 max/min/any/all 结果不变（满足结合律），prod 因 fp 舍入不满足结合律、结果可能有差异，但统一路径简化了模板设计。
+
+**按多核切分轴分为三类**:
+- 空 Tensor 模板：不需要做 reduce 计算，是一个简化模板
+- Base 模板：仅A轴参与分核，核间无依赖，核内可处理完对应的R轴
+- Group 模板：A轴和R轴都参与分核，核间有依赖，需要二次reduce。A较小时借R开多核可以提升性能。
+
+**模板分类汇总**:
+| # | 模板 | 使用场景 | 准入条件 |
+| ---- | ---- | ------- | ------ |
+| 1 | Base | 所有 reduce 算子（sum/mean/max/min/prod/any/all）的 Base 模板 | 非空tensor, A轴较大，足够开多核 |
+| 2 | Group | 所有 reduce 算子的 Group 模板 | 非空tensor, A轴较小，需要借R开多核 |
+| 3 | Empty | 所有 reduce 算子的空 Tensor 模板 | 空tensor（EMPTY_A / EMPTY_R 共用） |
+
+每个算子选择 1/2/3 中的 1~3 个模板。
+
+## 3 TilingKey
+
+### 3.1 TilingKey 定义
+
+reduction 范式 TilingKey 采用 **2 个 bool** 字段：`isGroup` / `isEmptyTensor`。
+
+```cpp
+ASCENDC_TPL_ARGS_DECL(
+    ReduceGeneric,
+    ASCENDC_TPL_BOOL_DECL(isGroup, 0, 1),   // 0=base/empty, 1=group
+    ASCENDC_TPL_BOOL_DECL(isEmptyTensor, 0, 1),  // 空 tensor 模板
+);
+```
+
+**字段含义**：
+- `isGroup`：0=base/empty，1=group（A×R 2D 分核）
+- `isEmptyTensor`：0=非空，1=空 tensor（EMPTY_A/EMPTY_R 共用）
+
+
+**TPL_SEL 结构（3 个 tilingkey 组合）**：
+
+```cpp
+ASCENDC_TPL_SEL(
+    // base 模板
+    ASCENDC_TPL_ARGS_SEL(
+        ASCENDC_TPL_BOOL_SEL(isGroup, 0),
+        ASCENDC_TPL_BOOL_SEL(isEmptyTensor, 0),
+    ),
+    // 空 tensor 模板
+    ASCENDC_TPL_ARGS_SEL(
+        ASCENDC_TPL_BOOL_SEL(isGroup, 0),
+        ASCENDC_TPL_BOOL_SEL(isEmptyTensor, 1),
+    ),
+    // group 模板（isEmptyTensor 固定 0，与 empty 互斥）
+    ASCENDC_TPL_ARGS_SEL(
+        ASCENDC_TPL_BOOL_SEL(isGroup, 1),
+        ASCENDC_TPL_BOOL_SEL(isEmptyTensor, 0),
+    ),
+);
+```
+
+**设计决策**：
+- **dtype 不进 tilingkey**：框架按 REG_OP 中注册的输入名，为每种 dtype 自动生成独立编译实例（通过 `DTYPE_<INPUT_NAME>` 宏，如输入名为 `x` 则框架定义 `DTYPE_X`）。因此 dtype 分支在编译期已由框架展开，不需要进 tilingkey
+
+
+### 3.2 TilingKey与kernel模板对应关系
+
+| 模板 | isGroup | isEmptyTensor |
+|---|---|---|
+| Base | 0 | 0 |
+| Group | 1 | 0 |
+| EMPTY | 0 | 1 |
+
+**约束**：
+- `isGroup=1` 与 `isEmptyTensor=1` 互斥（group 不与 empty 组合）
+
+**实例数**：
+
+| | isEmptyTensor=0 (base) | isEmptyTensor=1 (empty) | isGroup=1 (group) | 单 dtype 总计 |
+|---|---|---|---|---|
+| 组合数 | 1 | 1 | 1 | **3** |
+
+## 4 TilingData
+
+### 4.1 TilingData 定义
+
+reduction 范式有 **2 份** TilingData struct：
+- Base / Group 模板共用 `ReduceGenericTilingData`
+- Empty 模板使用独立的 `ReduceEmptyTilingData`
+
+> 命名约定：`ReduceGenericTilingData` / `ReduceEmptyTilingData` 为范式占位名，开发时替换为实际算子名（如 `EuclideanNormTilingData` / `EuclideanNormEmptyTilingData`）。
+
+#### 4.1.1 Base / Group TilingData
+
+```cpp
+constexpr int32_t MAX_PATTERN_RANK = {RANK}; // 本算子最大rank值,替换为实际值
+struct ReduceGenericTilingData {
+    // ─── pattern 描述 ───
+    int32_t axisNum;                  // 2~MAX_PATTERN_RANK
+    int64_t axisShape[MAX_PATTERN_RANK];  // 合轴后每根轴的 size
+    int64_t axisStride[MAX_PATTERN_RANK]; // 每根轴的 GM stride（按 element 计）
+    // axisType[i] 不需要：i 偶→A，i 奇→R（A 起头+严格交替）
+
+    // ─── 多核切分（外层 A loop 扁平为线性计数，按 coreNum 均匀分核）───
+    int64_t aLoopCntTotal;            // ∏(outer A 整根) × aSplitChunkCnt
+    int64_t aSplitChunkCnt;           // CeilDiv(axisShape[aSplitIdx], aUbFactor)
+    int64_t aBigCoreLoopCnt;          // 大核处理的块数（= aSmallCoreLoopCnt + (aBigCoreCnt > 0 ? 1 : 0)）
+    int64_t aSmallCoreLoopCnt;        // 小核处理的块数（= aLoopCntTotal / coreNum，floor；
+                                      //   == 0 等价 aLoopCntTotal < coreNum，只有前 aBigCoreCnt 核工作）
+    int32_t aBigCoreCnt;              // 大核个数（= aLoopCntTotal % coreNum）
+    int32_t usedCoreNum;              // 实际使用核数
+
+    // ─── UB 切分 ───
+    int32_t aSplitIdx;            // UB 内被切分的 A 轴下标
+    int32_t rSplitIdx;            // UB 内被切分的 R 轴下标
+    int64_t aUbFactor;                // valid：A 维实际元素数（可能非 block 对齐，UB 行 stride 由 postBufSize 兜底）
+    int64_t rUbFactor;                // valid：R 维实际元素数
+    int64_t rUbFactorAlign;           // padded：UB 行 stride（tail-R 且 UB 切尾轴 且 尾轴全载 且 尾轴非对齐时 > rUbFactor，其余相等）
+    int64_t innerAProdAlign;          // padded：含最内 burst-tail A 的 CeilAlign
+    int64_t innerRProdAlign;          // padded：含最内 burst-tail R 的 CeilAlign
+
+    // ─── 外层 R loop 扁平化 ───
+    int64_t rLoopCntTotal;            // ∏(外层 R 轴 size) × CeilDiv(axisShape[rSplitIdx], rUbFactor)
+
+    // ─── UB buffer 字节数 ───
+    int64_t preBufSize;               // pre 阶段单份 buffer 大小（含 R 维，按 maxDtypeSize），blocksize 对齐
+    int64_t postBufSize;              // post 阶段单份 buffer 大小（不含 R 维，按 maxDtypeSize），blocksize 对齐
+    int64_t cacheBufUbSize;           // 固定 16 × 1024 (= 16 KB)
+
+    // ─── group 模板 ───
+    int64_t rGroupCnt;                // Phase 1 分组数 = Phase 2 workspace R 维大小（base 不读）
+
+    // ─── 算子自定义字段 ───
+    // 由具体算子按需追加，如 mean 算子追加 `float invRTotal`（= 1/R_total）
+};
+
+```
+
+**为什么只有 `rUbFactorAlign` 而没有 `aUbFactorAlign`**：
+
+- **tail-R 需要 `rUbFactorAlign`**：pattern 最简为 `AR`，前面无其他 R 轴可切。R 全载非对齐时不能 FloorAlign（R 小于 1 个 block 时 FloorAlign 会变 0），改用 CeilAlign，故需独立存 padded 版
+- **`aUbFactorAlign` 不需要**：三种情形（aSplitIdx==LastA / aSplitIdx!=LastA / tail-R）均直接使用 `aUbFactor`，理由见 [reduction-binary-base-tiling.md](reduction-template-binary-base/reduction-binary-base-tiling.md) §1.2 Step 1 约束
+
+**`rUbFactor` / `rUbFactorAlign`**：
+- valid（`rUbFactor`）：GM stride、valid 元素数、partial chunk 判定
+- padded（`rUbFactorAlign`）：UB 行 stride、ReduceXxx srcShape、UB 占用预算
+- Align > valid 条件：tail-R 且 UB 切尾轴 且 尾轴全载 且 尾轴非对齐，其余相等
+
+#### 4.1.2 Empty TilingData
+
+```cpp
+struct ReduceEmptyTilingData {
+    // ─── 多核切分 ───
+    int32_t usedCoreNum;            // EMPTY_A: 0（所有核早退）；EMPTY_R: 切分算出的核数
+    int64_t aTotal;                 // ∏(所有 A 轴 axisShape)，EMPTY_A 不读
+    int64_t aUbFactor;              // 单 chunk a 元素数（4 约束取 min）
+    int32_t aBigCoreCnt;            // 大核个数
+    int64_t aBigCoreLoopCnt;        // 每大核 chunk 数
+    int64_t aSmallCoreLoopCnt;      // 每小核 chunk 数
+
+    // ─── UB buffer ───
+    int64_t postBufSize;            // post 阶段单份 buffer 字节数
+};
+```
+
+### 4.2 TilingData与kernel模板对应关系
+
+| TilingData | 使用的 kernel 模板 |
+|------------|------------------|
+| `ReduceGenericTilingData` | Base / Group |
+| `ReduceEmptyTilingData` | Empty |
+
+**约束**：
+- Group 模板 Phase 2 的大小核字段（`aSmallCoreLoopCnt_p2` / `aBigCoreCnt_p2` / `aBigCoreLoopCnt_p2` / `usedCoreNum_p2`）由 kernel 侧用 `usedCoreNum` 现算，不单独存入 TilingData
+
+## 5 总结
+
+| 模板名 | 准入条件 | TilingKey 字段值 | TilingData 名 |
+|--- |---|---|---|
+| Base | 非空, A轴够分核 | isGroup=0, isEmptyTensor=0 | ReduceGenericTilingData |
+| Group | 非空, A轴不够分核且R有并行度 | isGroup=1, isEmptyTensor=0 | ReduceGenericTilingData |
+| Empty | 空 tensor（EMPTY_A / EMPTY_R） | isGroup=0, isEmptyTensor=1 | `ReduceEmptyTilingData`（独立 7 字段） |
+
+
+## 6 产出
+
+> 通过前面知识，使不同算子产出对应的模板、TilingKey、TilingData
+
+### 6.1 产出结果
+
+结合算子公式，参考前面章节，逐步产出算子实际使用的模板、TilingKey、TilingData：
+
+**1. 输出模板**：参考 [§2.1 kernel 模板分类](#21-kernel-模板分类)，按 `isEmptyTensor`（空 tensor 短路）、`isGroup`（Group 触发判定）取值，输出算子实际使用的模板（Base / Group / Empty 中的 1~3 个）。
+
+**2. 输出 TilingKey**：参考 [§3.1 TilingKey 定义](#31-tilingkey-定义) 和 [§3.2 TilingKey与kernel模板对应关系](#32-tilingkey与kernel模板对应关系)，按所选模板输出 `isGroup` / `isEmptyTensor` 各字段取值。
+
+**3. 输出 TilingData**：参考 [§4.1.1 Base / Group TilingData](#411-base--group-tilingdata) 和 [§4.1.2 Empty TilingData](#412-empty-tilingdata)，按所选模板确定对应的 TilingData struct：Base/Group 用 `ReduceGenericTilingData`，Empty 用 `ReduceEmptyTilingData`。按算子需要确定 `MAX_PATTERN_RANK`（影响 `axisShape`/`axisStride` 数组长度）。算子自定义字段（如 mean 的 `invRTotal`）追加在 `ReduceGenericTilingData` 末尾。
+
+### 6.2 产出校验
+
+每个算子完成三要素确定后，按以下清单校验：
+
+| # | 校验项 | 规则 |
+|---|--------|------|
+| 1 | `isGroup=1` 与 `isEmptyTensor=1` 互斥 | group 不与 empty 组合 |
+| 2 | dtype 不进 TilingKey | 走 `DTYPE_<INPUT_NAME>` 编译期实例化 |
+| 3 | Empty 使用独立 `ReduceEmptyTilingData` | 不复用 Base/Group struct |

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/paradigms/reduction/references/reduction-tiling-preprocess.md

@@ -0,0 +1,218 @@
+# reduction 范式 Tiling 预处理
+
+> ub 切分前的预处理阶段。所有模板（Base/Group/Empty）共用同一套预处理逻辑。
+
+依赖输入：[reduction-template-overview.md](reduction-template-overview.md)、[common/value-depend-process.md](../../common/value-depend-process.md)
+
+## 1 算子信息获取
+
+### 1.1 平台信息获取
+
+```cpp
+coreNum      = ascendcPlatform.GetCoreNumAiv();
+ubSize       = ascendcPlatform.GetCoreMemSize(UB, ubSize);
+blockSize    = Ops::Base::GetUbBlockSize(context);      // 不要写 32
+cacheLineSize = Ops::Base::GetCacheLineSize(context);   // 不要写 256/512
+vectorSize   = Ops::Base::GetVRegSize(context);
+```
+
+**约束**：
+- 每个返回值必须校验非 0，报错用 `OP_LOGE_FOR_INVALID_ARGUMENT_WITH_REASON`（param 取 `platform.<参数名>`，reason 注明查询接口名）
+- 严禁将平台参数写死，必须通过接口获取
+
+### 1.2 算子输入输出获取及校验
+
+**约束**：
+- 标量输入按算子语义处理（示例 euclidean_norm：rank-0 视作 [1] 单元素张量；标量判断用 `gert::Shape::IsScalar()` 官方 API，勿手写 `GetDimNum() == 0`；不支持的算子显式报错）
+- 获取可选输入要使用 `GetOptionalInputShape` 和 `GetOptionalInputDesc`
+- 可选输入为空时要特殊处理，不能直接返回失败
+- 可选 attr 为空时要使用默认值，不能直接返回失败
+- shape/dtype 要严格校验，不支持的 shape/dtype 必须报错。**错误日志分层**：参数值错误用 `OP_LOGE_FOR_INVALID_VALUE_WITH_REASON`、shape 维度错误用 `OP_LOGE_FOR_INVALID_SHAPEDIM_WITH_REASON`、dtype 错误用 `OP_LOGE_FOR_INVALID_DTYPE_WITH_REASON`；
+- 必须使用 INFO 级别日志打印算子每个输入参数/属性，包括但不限于 shape、dtype、attr；
+
+### 1.3 值依赖分析
+
+> `axes` 只是个标识，含义是 reduce 的轴信息，算子中有可能叫 axes/axis/dim/dims 等。
+
+reduce 算子的 host 端要做 pattern 预处理（合轴/切分），依赖 `axes` 的**实际数值**。如果 `axes` 是个 `tensor`，就需要获取 tensor 的值。framework 默认只传 shape/dtype，此时必须显式声明"值依赖"。三处契约详见 [common/value-depend-process.md](../../common/value-depend-process.md)。
+
+reduce 系列通常 `x` 在 0、`axes` 在 1 → 填 `{1}`：
+
+| # | 位置 | 声明 |
+|---|------|------|
+| 1 | `op_def.cpp` 输入定义 | `this->Input("axes").ParamType(REQUIRED).ValueDepend(OPTIONAL)...` |
+| 2 | `IMPL_OP_INFERSHAPE` 注册块 | `.InputsDataDependency({1})` |
+| 3 | `IMPL_OP_OPTILING` 注册块 | `.TilingInputsDataDependency({1})` |
+
+> 空 tensor 短路同样依赖 axes 数值（判断 A/R 类型），需要值依赖。
+
+## 2 合轴
+
+**流程**：axes 归一化 + 空 tensor 短路 → 去轴 → 合轴 → 补轴
+
+### 前置：axes 归一化 + 空 tensor 短路
+
+在进入合轴四步之前，先完成两项前置：
+
+**axes 归一化**：将用户传入的 reduce 轴参数（`axes`/`axis`/`dim`/`dims` 等，名称因算子而异）解析为合法、规范化的 reduce 轴下标集合。包含以下步骤（顺序不可换）：
+
+1. **空 axes 语义判定**：`axes=[]`（axesNum==0）的语义按算子公式判定——多数算子（对标 TF/PyTorch）按 "all reduce" 展开为 `[0..xRank-1]`；少数算子（`noopWithEmptyAxes=true`）按 "不 reduce" 处理。
+2. **dtype 解析**：axes 输入可能是 int32 或 int64（`IndexNumberType`），按实际 dtype 读取数值。
+3. **越界校验**：对原始值校验 `v < -xRank || v >= xRank` → 报错（须在转正之前——如 `-xRank-1` 转正后变成 `-1`，会漏检）。
+4. **负数转正**：`v < 0` → `v + xRank`（对标 torch.sum，负数表示从末尾倒数）。归一化后所有轴下标落在 `[0, xRank)`。
+5. **去重校验**：重复轴下标 → 报错。
+6. **排序**：去重后升序排序，便于后续合轴按轴顺序处理。
+
+归一化完成后，遍历 xShape，按下标是否在 reduce 集合中标记 A/R 类型，构建初始 A/R 类型表（`axisShape` + `isReduceAxis`），作为合轴四步的输入。
+
+> infershape 与 tiling 两端的归一化逻辑必须完全一致。
+
+**空 tensor 短路**（`HandleEmptyTensor()`）：检查 axisShape（必须在合轴四步之前）：
+- 任一 A 轴 size == 0 → **EMPTY_A**（output 空 tensor），不进入合轴，跳转 Empty 模板
+- 任一 R 轴 size == 0 且所有 A 轴 size > 0 → **EMPTY_R**（output = `empty_r_output_value`），不进入合轴，跳转 Empty 模板
+- 否则（所有 axisShape ≥ 1）→ 进入合轴四步
+
+**优先级**：**EMPTY_A > EMPTY_R**（A=0 时 output 必空，无论 R 是否 0）。
+
+> 空 tensor 短路后不进入合轴四步，直接跳转 Empty 模板 tiling 处理。
+
+**两子模板共用 `isEmptyTensor=1` tilingkey + 同一份 `<op>_empty.h`**，靠 `usedCoreNum` 在 kernel 内区分：
+- EMPTY_A：`usedCoreNum = 0`，所有核早退
+- EMPTY_R：`usedCoreNum` = 切分算出的核数
+
+### 步骤 1：去 1 轴
+
+**对应函数**: `DropSizeOneAxes()`
+
+无论 A 轴或 R 轴，`size == 1` 的整根轴直接删除。
+
+**不变量（非空保留）**：若整张图所有轴 size 都为 1（∏shape == 1），删除会清空轴列表，此时**保留 1 根占位 `A=1`** 作为结果，不允许列表为空。
+
+### 步骤 2：合轴
+
+**对应函数**: `FuseAxis()`
+
+连续 A 轴合并为 1 根 A 轴，连续 R 轴合并为 1 根 R 轴。
+
+### 步骤 3：补 leading A 轴
+
+**对应函数**: `PadLeadingOneA()`
+
+若第 0 轴是 R 轴，前置一根大小为 1 的 A 轴。保证最高轴必为 A。
+
+**stride 计算**：合成 A=1 的 stride = `∏所有轴 size`（整段总元素数），不是 1。
+
+### 步骤 4：补 R 增广（纯 A 退化路径）
+
+**对应函数**: `PadRIfPureA()`
+
+若上一步完成后仍无 R 轴（纯 A 场景），按 A 轴 size 分两种：
+
+- **A=1**（全 1 退化，∏shape==1）：**末尾补** `[R=1]`，pattern 由 `A` 变 `AR`（tail-R）。
+  此时 A=R=1，单元素 reduce，无 burst 性能问题。
+  好处：全 1 退化统一走 tail-R 路径，某些算子可因此省去 TailA 模板。
+- **A>1**（纯 A 但非全 1，如无 reduce 轴的 passthrough）：**前置** `[A=1, R=1]`，pattern 由 `A` 变 `ARA`（tail-A）。
+  **约束**：此场景必须前置 ARA，**绝不能末尾补 R=1 的 AR**。`AR` 路径下 tail R=1 而 A>1 会导致 UB burst 长度塌到底，性能崩。
+
+### 合轴后的 pattern 形态
+
+四步执行完后，pattern 必然形如 `A R A R … A R …`，A 起头，A/R 严格交替，每根轴 size ≥ 2（首部补 1 的 A、紧随其后补 1 的 R 除外）。
+
+**支持的 pattern 范围**：
+
+| pattern | 轴数 | tail 类型 |
+|---------|------|-----------|
+| AR | 2 | R |
+| ARA | 3 | A |
+| ARAR | 4 | R |
+| ARARA | 5 | A |
+| ARARAR | 6 | R |
+| ARARARA | 7 | A |
+| ARARARAR | 8 | R |
+| ARARARARA | 9 | A |
+
+**tail 类型判定**：`axisNum` 偶数 → tail R；`axisNum` 奇数 → tail A。kernel 侧由 axisNum 奇偶现算。
+
+**轴类型判定**：合轴后 A 起头 + 严格交替，`axisType[i]` 完全由位置 `i` 的奇偶决定：`i` 偶 → A，`i` 奇 → R。
+
+### 算子级 pattern 上界分析（MAX_PATTERN_RANK）
+
+MAX_PATTERN_RANK = 该算子合轴后 pattern 的**最大可能轴数**，用于 TilingData `axisShape` 数组分配和合法性校验。
+
+**推导方法**：
+
+1. 按算子自身语义确定 reduce 轴信息——来源因算子而异：可能是 axes/axis/dim 等显式输入，可能是 attr，也可能由 format 隐式决定（如 NCHW 格式下固定 C 为 A 轴、其余为 R 轴），还可能是算子公式固化的（如固定尾轴 reduce 的算子恒有 1 根 R 轴）。无论来源如何，最终都要得到输入张量各轴的 A/R 标记
+2. 在最坏情况下，将连续的 R 轴视为 1 段，统计 R 的连续段数，记为 `rseg`
+3. 合轴后 A 与 R 严格交替、A 起头，A 段数最多 = `rseg + 1`，因此合轴后最大轴数 = `2 × rseg + 1`（A/R 类型标记以 A 结尾时达上限；以 R 结尾（含全 R）时为 `2 × rseg`）；纯 A（`rseg=0`，即不 reduce）补 R 增广后为 ARA = 3（A=1 全 1 退化时为 AR = 2）。标记由算子的 reduce 轴语义确定：固定 reduce 轴按固定标记取精确 MAX（如 NCHW reduce N/HW，标记 `R A R` → MAX = ARAR = 4，即使 HW=1 去 1 后成 ARA 也只是变小）；axes 由输入决定时按最坏情形（以 A 结尾）取 `2 × rseg + 1`，rseg 不定则兜底 9
+4. 框架上界为 9，取 `min(推导值, 9)`
+
+**典型例子**：
+
+| reduce 轴语义 | 合轴后 pattern | MAX_PATTERN_RANK |
+|------|------|------|
+| 固定标记，以 R 结尾（全 R 为其 rseg=1 特例；如 NCHW reduce N/HW：`R A R`） | `(AR) × rseg` | `2 × rseg` |
+| 固定标记，以 A 结尾（如 `R A R A`） | `(AR) × rseg + A` | `2 × rseg + 1` |
+| axes 任意（rseg 不定） | 兜底 | 9 |
+
+> 例：`RARA` → R0 是 1 段、R2 是 1 段 → `rseg=2` → MAX=5。合轴四步：R A R A → 补 leading A → `A R A R A`（5 轴，A 结尾达上限）。
+
+推导出的 MAX_PATTERN_RANK 定义在各算子 `tiling_data.h` 中（无前缀，直接 `constexpr int32_t MAX_PATTERN_RANK = N;`），host 和 kernel 共享。
+
+### Tiling 端合轴代码规范
+
+1. **封装为独立函数**：去 1、合轴、补 leading A、补 R 增广 各自独立函数，可独立单元测试
+2. **每函数有效代码行数 ≤ 50**（不含空行、注释）
+3. **shape/dtype 校验必不可少**
+4. **空 tensor 短路在合轴之前**
+
+## 3 合轴产出校验
+
+> 为了校验 agent 是否真正理解了合轴逻辑，需要给出一个复杂输入的样例来校验。固定输入，合轴输出必定相同。
+
+**样例 1：通用 reduce，axes=[1,3]**
+
+输入 shape `(2, 3, 4, 5, 6)`，axes=[1, 3]，reduce 轴 = {1, 3}。
+
+- 初始 A/R 类型表：A0=2, R0=3, A1=4, R1=5, A2=6
+- 步骤 1 去 1 轴：无 size==1 的轴，不变
+- 步骤 2 合轴：无连续同类型轴，不变
+- 步骤 3 补 leading A：第 0 轴是 A，不变
+- 步骤 4 补 R 增广：已有 R 轴，不变
+- 结果：pattern = `A0 R0 A1 R1 A2`（ARARA，axisNum=5，tail-A）
+
+**Golden**：`axisShape = [2, 3, 4, 5, 6]`，`axisNum = 5`，`isTailR = false`（奇数轴）。
+
+**样例 2：全 1 退化**
+
+输入 shape `(1, 1, 1)`，axes=[0, 1, 2]，reduce 轴 = {0, 1, 2}。
+
+- 初始 A/R 类型表：R0=1, R1=1, R2=1（全 R）
+- 步骤 1 去 1 轴：全删，列表空 → 保留 1 根占位 `A=1`
+- 步骤 2 合轴：仅 1 根 A，不变
+- 步骤 3 补 leading A：第 0 轴是 A，不变
+- 步骤 4 补 R 增广：无 R 轴，A=1 → 末尾补 [R=1]，pattern 变 `AR`
+- 结果：pattern = `A R`（AR，axisNum=2，tail-R）
+
+**Golden**：`axisShape = [1, 1]`，`axisNum = 2`，`isTailR = true`（偶数轴）。
+
+**样例 3：EMPTY_R 短路**
+
+输入 shape `(3, 0, 4)`，axes=[1]：
+- A 轴 = {0, 2}，R 轴 = {1}
+- axisShape[1] = 0（R 轴为 0），但 axisShape[0] = 3 > 0、axisShape[2] = 4 > 0 → **EMPTY_R**（不是 EMPTY_A）
+
+**Golden**：`isEmptyTensor=1, usedCoreNum=按 aTotal=12 切分`，output = `empty_r_output_value`。
+
+**样例 4：EMPTY_A 短路**
+
+输入 shape `(0, 3, 4)`，axes=[1]：
+- A 轴 = {0, 2}，R 轴 = {1}
+- axisShape[0] = 0（A 轴为 0）→ **EMPTY_A**
+
+**Golden**：`isEmptyTensor=1, usedCoreNum=0, SetBlockDim(1)`，output = 空 tensor。
+
+**校验要点**：
+1. 空 tensor 短路在合轴四步之前
+2. EMPTY_A 优先级 > EMPTY_R（A=0 时 output 必空）
+3. EMPTY_A: `usedCoreNum=0, SetBlockDim(1)`（框架要求 ≥ 1）
+4. EMPTY_R: `usedCoreNum` = 按 aTotal 切分算出的核数

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/paradigms/reduction/references/reduction-tuple-reduce.md

@@ -0,0 +1,72 @@
+# reduction 范式 Tuple Reduce 变体
+
+**定义**（本范式术语）：Tuple Reduce = 对同一输入（或同一组输入）沿相同归约轴做 N 次独立归约的算子形态。
+
+> 实现：kernel 内通过 for 循环调用 N 次标准 Process 流程，N 次归约共享 TilingData 与 UB 切分（见核心约束）。
+
+**核心约束**：
+1. **共享归约轴**：所有归约过程的归约轴完全相同（共享 TilingData 的前提）
+2. **跨过程同步**：按全局（跨 processIdx）判定是否存在 WAR——跨过程 WAR 由 Mutex Lock/Unlock 段链按序天然覆盖（全局各轮的段依次串接，无首末轮跳过技巧）；base/empty 入口 for 循环不插入同步语句，跨过程 WAR 的段序在 Process 内部流水同步中保证。Group 分支循环末尾的 SyncAll 同时兜住 workspace WAR 与 UB 侧跨过程 WAR
+
+> `N_REDUCES` = 独立归约过程数。一次归约过程内部可产出多个分叉输出，分叉输出不增加 `N_REDUCES`——过程数与输出张量数解耦。`N_REDUCES` 为算子级常量（归约过程数由算子本身固定），不进 TilingKey/TilingData。
+
+**总体策略**：（与标准范式的差异）
+- 模板参数不变，不新增模板参数
+- 差异仅在 Process 内部：Process 按 `processIdx` 分发，CopyOut 写到不同输出指针
+- 合轴、TilingKey、TilingData、多核切分、UB 切分、二分缓存树算法等全部不变
+
+**Kernel 入口结构**：
+
+```cpp
+template <bool isGroup, bool isEmptyTensor>
+__global__ __aicore__ void reduce_generic(
+    GM_ADDR input..., GM_ADDR output...,
+    GM_ADDR workspace, GM_ADDR tiling)
+{
+    REGISTER_NONE_TILING;
+    AscendC::TPipe pipe;
+
+    if constexpr (isEmptyTensor) {
+        GET_TILING_DATA_WITH_STRUCT(ReduceEmptyTilingData, tilingData, tiling);
+        ReduceOp<DTYPE_X> op;
+        op.Init(/*...*/, &tilingData, &pipe);
+        for (int processIdx = 0; processIdx < N_REDUCES; processIdx++) {
+            op.Process(/*...*/, processIdx); // ⛔ 跨过程 WAR：各轮 Lock/Unlock 段链全局依次串接（核心约束 2）
+        }
+    } else if constexpr (isGroup) {
+        GET_TILING_DATA_WITH_STRUCT(ReduceTilingData, tilingData, tiling);
+        ReduceOp<DTYPE_X> op;
+        op.InitGroup(/*...*/, &tilingData, &pipe);
+        for (int processIdx = 0; processIdx < N_REDUCES; processIdx++) {
+            op.ProcessGroup(/*...*/, processIdx);
+            SyncAll();  // ⛔ 兜住跨过程 WAR：下一轮 Phase 1 写 workspace/UB 前，本轮 Phase 2 必须读完
+        }
+    } else {
+        GET_TILING_DATA_WITH_STRUCT(ReduceTilingData, tilingData, tiling);
+        ReduceOp<DTYPE_X> op;
+        op.Init(/*...*/, &tilingData, &pipe);
+        for (int processIdx = 0; processIdx < N_REDUCES; processIdx++) {
+            op.Process(/*...*/, processIdx); // ⛔ 跨过程 WAR：各轮 Lock/Unlock 段链全局依次串接（核心约束 2）
+        }
+    }
+}
+```
+
+**ElementWise 分发**（`processIdx` 是运行时变量，用运行时 if/else）：
+
+```cpp
+void Process(int processIdx, /* srcBuf, dstBuf */)
+{
+    if (processIdx == 0) {
+        // 归约过程 0 的 Elewise（如：Cast only）
+    } else if (processIdx == 1) {
+        // 归约过程 1 的 Elewise（如：Cast + Mul）
+    }
+}
+```
+
+**UB 预算**：与标准范式一致。N 次循环复用同一份 workspace 和 UB，**禁止在 workspace 公式或 UB 预算中乘以 N**。
+
+**性能特征**：
+- CopyIn 执行 N 次（每次循环各做一次），带宽开销为标准 Reduction 的 N 倍
+- UB buffer / Workspace：与标准范式一致（每次循环复用同一份）

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/paradigms/reduction/references/reduction-vf-fusion-rules.md

@@ -0,0 +1,95 @@
+# VF 融合分析
+
+> **适用范围**: reduction 范式通用方法论。§1.1 存活节点分析（L + P）和 §1.2 VF 融合分析时使用。
+
+## 1. 穷举所有相邻操作对
+
+**列出计算图中所有连续 Vector 操作对，逐对判据。禁止只检查"看起来像"的那一对。**
+
+方法：从计算图第一条 Vector 操作开始，相邻两两配对。每一对都走三条硬规则判据。全部检查完才进 §1.3 决策。
+
+### 1.1 连续可融对 → 合并为单条 VF 链
+
+逐对判据回答"哪些相邻操作可以融"，但**不会告诉你它们应该合成一个 VF 还是多个**。判据结束后，要再看一步：
+
+**判据只有三条硬规则：**
+1. **链长 ≤ 7**——超过 7 条 Vector 操作必须拆为多次 VF 调用
+2. **Cast 可参与 VF**——reduction 范式中 Cast 使用 `Reg::Cast` 寄存器指令（见 [common/cast-rules.md](../../common/cast-rules.md) §4.3），可串入 VF 寄存器链路，不作为断点
+3. **RegBase 指令必须存在**——对应操作在 [regbase_api_whitelist.md](../../../api/regbase_api_whitelist.md) 白名单中能找到
+
+**多消费者不打断链。** 即使某个中间结果被 VF 外的其他步骤引用，VF 链仍可继续——VF 内部把这个值 `StoreAlign` 到 UB 即可，寄存器链路不受影响。代价是多写一次 UB 会多占一个 P slot，需要纳入物理 trace 做峰值验证。
+
+```
+VF 内:  ...→vdiv→raw_x(reg)→StoreAlign→UB (供VF外读)
+                                │
+                                └→Round→round_x(reg)→...  链继续！
+```
+
+所以判断方法为：从第一条 Vector op 开始，只要 RegBase 指令在白名单中存在、非超长链（≤7），链就延续。**不因分叉而断链。**
+
+### 1.2 能不能融取决于 RegBase API 能力
+
+判断一个 RegBase API 是否可用、是否 VF 安全，唯一入口是白名单：[regbase_api_whitelist.md](../../../api/regbase_api_whitelist.md)
+
+对照计算图中相邻操作——它们的操作用 RegBase 指令能否串成寄存器链路？能 → 融。不能（指令不在白名单中）→ 不融。
+
+寄存器链组合（两条或多条 RegBase 指令串在 VF 循环内完成）：`Compare + Select`, `Mul + Add`, `Ln + Mul`, `Exp + Sub`, `Cast(fp16→fp32) + Square`, `Cast(fp32→fp16) + 任意计算` 等。
+
+### 1.3 存活节点压力——融合 vs 拆分取舍
+
+多消费者融合虽然合法，但会增加 P 压力：VF 需要同时持有所有输入 buffer + 所有输出 buffer（包括为外部消费者多写的）。如果合并后峰值超过目标 P，则需要**主动拆分** VF 来降压。
+
+**判据流程**：
+1. 先推满最长链（≤7）
+2. 做物理 trace，检查峰值是否 ≤ 目标 P
+3. 若超 P → 在分叉输出最多的位置拆分 VF，释放部分 buffer 后再续链
+4. 重复直到峰值 ≤ P
+
+**总结**：多消费者融合="可以但不是必须"。选择融还是拆，由 P 约束决定。
+
+## 2. 融合改变存活节点大小
+
+融合前每个中间结果各占 1 个 UB buffer。融合后中间结果在寄存器内不进 UB——存活节点 = 所有输入操作数 + 最终输出 + 其他还活着的 buffer。
+
+```
+A+B+C+D = E
+
+全融 A+B+C+D： 5 个节点（A, B, C, D, E 同时活着）
+融 A+B+C：     4 个节点（A, B, C, TMP1 活着）→ 再 TMP1+D = E
+只融 A+B：     3 个节点（A, B, TMP1）→ 再 TMP1+C = TMP2 → TMP2+D = E
+```
+
+## 3. Cast 参与 VF 融合
+
+reduction 范式中 Cast 使用 `Reg::Cast` 寄存器指令（详见 [common/cast-rules.md](../../common/cast-rules.md) §4.3），在寄存器内完成类型转换，**可与前后 Vector 操作融合**。
+
+Cast 在 VF 链中的位置：
+- **扩位 Cast（b16→fp32）**：通常在 VF 链头部，`LoadAlign<D_T, DIST_UNPACK_B16>` → `Reg::Cast<float, D_T>` → 后续计算
+- **缩位 Cast（fp32→b16）**：通常在 VF 链尾部，`Reg::Cast<D_T, float>` → `StoreAlign<D_T, DIST_PACK_B32>`
+
+```
+// 扩位 Cast + Square 融合为 1 条 VF 链
+LoadAlign<half, DIST_UNPACK_B16>(b16Reg, srcUb);
+Cast<float, half, kCastTraitB16ToF32>(f32Reg, b16Reg, mask);
+Mul<float>(f32Reg, f32Reg, f32Reg, mask);       // Square
+// ... 继续后续计算
+StoreAlign<float>(dstUb, f32Reg, mask);           // 输出 fp32
+```
+
+**CastTrait 配置**：扩位用 `kCastTraitB16ToF32`（`CAST_NONE`），缩位用 `kCastTraitF32ToB16`（`CAST_RINT`），详见 [common/cast-rules.md](../../common/cast-rules.md) §4.1。
+
+## 4. 存活节点扩大限制
+
+融合使更多输入 buffer 同时活着——融合后的物理存活节点数不得超过融合前的 P + 3。超过 → 只部分融合，或回 §1 调整调度先释放不再需要的 buffer。
+
+### 案例
+
+**reduction preReducePhase: Cast→Square→Add→Mul 全链融合**
+
+计算图 `Cast(fp16→fp32) → Square → Add → Mul`，Add/Mul 的第二操作数为寄存器标量（不占 UB）。所有中间值均为单消费者，无分叉。`Reg::Cast`、`Reg::Mul` 指令均存在，链长=4 ≤ 7。
+
+全链合并为 **1 个 VF**。融合后 fp32 中间值在寄存器，全链只入 UB 一次（fp16 输入）、出 UB 一次（fp32 输出到 tmpBuf）。P = 2（输入 buffer + 输出 buffer）。
+
+### 反例：A+B+C+D 在 P=3 下不能全融
+
+全融需要 5 个节点（A,B,C,D,E 同时存活）≤ 3+3=6。看起来可行？但若当前调度下 A,B 已经和其他步骤共享 buffer，实际节点更紧张。**关键不是公式，是结合实际持有 trace 看**——在融合发生的那一步，加上所有输入 operands 之后的持有数是否超 P。超了就不能全融。