@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-binary-sum.md

@@ -0,0 +1,260 @@
+# 二分缓存树
+
+> 本范式所有 reduce 算子（sum/mean/max/min/prod/any/all）统一使用二分缓存树。对 sum/mean 有精度收益（浮点累加误差从 O(M) 降到 O(log M)），对 max/min/any/all 结果不变（满足结合律），prod 因 fp 舍入不满足结合律、结果可能有差异，但统一路径简化了模板设计。
+
+## 一、背景与问题
+
+假设要对 N=10000 个 fp32 数求和，结果为 1 个数。NPU 的 UB（Unified Buffer）单次只能载入 B=512 个数，无法一次性装入全部数据。
+
+因此必须分块处理：将 10000 个数分成 M=⌈N/B⌉=20 块（前 19 块各 512 个，最后 1 块 272 个），逐块载入 UB、用向量指令 reduce 成 1 个部分和，最后把 M=20 个部分和合并成最终结果。
+
+**核心问题：如何合并这 20 个部分和，使浮点累加误差尽可能小？**
+
+---
+
+## 二、为什么用二分树
+
+### 2.1 顺序累加的精度问题
+
+最直观的做法是维护一个累加器，每算完一块就加上去：
+
+```
+s = 0
+for i in 0..M-1:
+    s = s + chunk_sum[i]    // 顺序累加
+```
+
+随着 `s` 逐渐增大，后续 `chunk_sum[i]` 相对于 `s` 越来越小。浮点加法中，两个量级差异大的数相加会丢失有效位，**误差随累加次数线性增长，为 O(M)**。
+
+### 2.2 树形归约的优势
+
+二分树把 M 个部分和两两配对、逐层合并，树高仅 log₂(M)：
+
+```
+第0层:  s0   s1   s2   s3   s4   s5   s6   s7   ...  (16个部分和)
+         \  /     \  /     \  /     \  /
+第1层:    a0       a1       a2       a3         ...  (8个)
+           \      /           \      /
+第2层:      b0                 b1               ...  (4个)
+             \               /
+第3层:          c0            c1                     (2个)
+                 \          /
+第4层:              d0                              (1个 = 最终结果)
+```
+
+每一层相加的两个数量级相近，有效位损失小。**误差增长为 O(log M)**。
+
+当 M=20 时，顺序累加误差 ~O(20)，二分树 ~O(log₂16)=O(4)，精度显著提升。
+
+---
+
+## 三、非 2 幂的处理：主尾配对
+
+二分树要求叶子数为 2 的幂，但 M=20 不是 2 的幂。
+
+取 P = 严格小于 M 的最大 2 幂 = 16，尾段 T = M − P = 4。
+
+将尾段 4 块与主段前 4 块**两两配对合并**，每对产生 1 个部分和：
+
+```
+Phase A (配对, i=0..3):
+    chunk[i] 与 chunk[i+P] 配对
+    → 载入两块 → 逐元素相加成 1 块 → reduce → 1 个部分和
+
+Phase B (独立, i=4..15):
+    chunk[i] 单独处理
+    → 载入 → reduce → 1 个部分和
+```
+
+配对后，树的输入数恰好为 P=16（2 幂），形成完美二叉树。
+
+> **为什么取"严格小于"而非"≤"**：当 M 本身为 2 幂时（如 M=16），取 P=M/2=8 而非 M=16，树深少 1 层，缓存空间省一个 fp32 槽；代价是需多做 M/2 次配对（Phase A）。M 非 2 幂时（如 M=20），两种取法结果相同。用一点计算换空间更划算。
+
+> 配对时两块逐元素相加成一个块再 reduce，而非各自 reduce 后再加两个标量——这样元素级配对精度更好，且只调一次 reduce。尾块可能不足 B 个数（如最后一个 272），与主块配对时将尾块的有效元素逐元素加到主块对应位置即可（等价于尾块补零到 B 再逐元素相加），不影响求和结果。
+
+---
+
+## 四、顺序循环中的树形归约
+
+### 4.1 核心挑战
+
+NPU 单核顺序执行，无法真正并行做树形归约。传统树形归约需保存全部叶子（第0层 s0..s_{P-1}），当 P 较大时 UB 空间不够。需要一个机制：**在顺序循环中，把每个部分和写到正确的树层级，用 L=log₂(P)+1 个 cache 槽轮转复用，替代保存全部叶子的空间开销**。
+
+### 4.2 多级缓存
+
+在 UB 中开辟 L 个缓存槽，L = log₂(P) + 1 = 5（level 0..4）：
+
+| 层级 | 含义 | 覆盖范围 | 写入频率 |
+|------|------|---------|---------|
+| cache[0] | 1 个部分和 | 1 块 | 每 1 次迭代 |
+| cache[1] | 2 个部分和的合并 | 2 块 | 每 2 次迭代 |
+| cache[2] | 4 个部分和的合并 | 4 块 | 每 4 次迭代 |
+| cache[3] | 8 个部分和的合并 | 8 块 | 每 8 次迭代 |
+| cache[4] | 全部 16 个部分和的合并 | 16 块 | 最后 1 次（树根）|
+
+### 4.3 写入层级规则
+
+迭代序号 i 的二进制表示中，**末尾连续 1 的个数**决定写入层级：
+
+```
+level(i) = i 的二进制末尾连续 1 的个数
+```
+
+直觉：这与二进制计数器的进位传播一致——当低位全为 1 时，加 1 会触发连续进位，进位传播到第几位，就对应写入第几层。
+
+前 16 次迭代（P=16）的层级分配：
+
+| i | 二进制 | 末尾 1 个数 | 写入层级 | 动作 |
+|---|--------|-----------|---------|------|
+| 0 | 0000 | 0 | cache[0] | 直接写入 |
+| 1 | 0001 | 1 | cache[1] | 吸收 cache[0]，写入 |
+| 2 | 0010 | 0 | cache[0] | 直接写入 |
+| 3 | 0011 | 2 | cache[2] | 吸收 cache[0,1]，写入 |
+| 4 | 0100 | 0 | cache[0] | 直接写入 |
+| 5 | 0101 | 1 | cache[1] | 吸收 cache[0]，写入 |
+| 6 | 0110 | 0 | cache[0] | 直接写入 |
+| 7 | 0111 | 3 | cache[3] | 吸收 cache[0,1,2]，写入 |
+| ... | ... | ... | ... | ... |
+| 15 | 1111 | 4 | cache[4] | 吸收 cache[0,1,2,3]，写入（树根）|
+
+### 4.4 写入时的吸收规则
+
+写入 cache[k] 前，先把 cache[0], cache[1], ..., cache[k-1] 全部吸收（相加），再覆盖写 cache[k]：
+
+```
+写入 cache[k]:
+    result = 当前部分和
+    for j = 0 to k-1:
+        result = result + cache[j]    // 吸收所有低层
+    cache[k] = result                  // 覆盖写本层
+```
+
+**为什么必须正序（j=0→k-1）吸收？** cache[j] 覆盖 2^j 块的数据量，正序吸收保证每步相加的两个数量级匹配：result(1块) + cache[0](1块) → result 变 2 块量级 → result(2块) + cache[1](2块) → result 变 4 块量级 → ……每步 result 与 cache[j] 覆盖范围相同，精度最优。若倒序（j=k-1→0），result(1块) 直接加 cache[k-1](2^(k-1) 块)，量级悬殊，小数被吃有效位，破坏二分树的精度优势。顺序不能变。
+
+**为什么 cache[k] = result 是覆盖而不是 cache[k] = cache[k] + result 累加？** cache[k] 此前保存的是上一轮同层写入的旧值（已被更高层吸收过）。若累加，会把过期旧值叠进当前结果，导致重复计算。
+
+### 4.5 树填充过程（P=16）
+
+以 S 表示每次迭代产生的部分和：
+
+```
+i=0:  cache[0]=S                                   树: [S, _, _, _, _]
+i=1:  cache[1]=S+cache[0]                          树: [_, S, _, _, _]
+i=2:  cache[0]=S                                   树: [S, _, _, _, _]
+i=3:  cache[2]=S+cache[0]+cache[1]                 树: [_, _, S, _, _]
+i=4:  cache[0]=S                                   树: [S, _, S, _, _]
+i=5:  cache[1]=S+cache[0]                          树: [_, S, S, _, _]
+i=6:  cache[0]=S                                   树: [S, _, S, _, _]
+i=7:  cache[3]=S+cache[0]+cache[1]+cache[2]        树: [_, _, _, S, _]
+...
+i=15: cache[4]=S+cache[0]+cache[1]+cache[2]+cache[3]  树: [_, _, _, _, S] ← 根
+```
+
+迭代结束后，cache[4]（最高层）包含全部 16 个输入的累加和，也就是所有 20 块的最终结果。
+
+---
+
+## 五、数据流图
+
+```
+GM: 10000 个 fp32
+     │
+     │  分块载入 (每块 B=512)
+     ▼
+ ┌──────────────────────────────────────────────────────┐
+ │  chunk[0]  chunk[1]  ...  chunk[15]  │  chunk[16..19] │
+ │  ─────── 主段 P=16 块 ──────────  │  ─尾段 T=4 块─ │
+ └────┬────────┬─────────────┬────────┴──────┬─────────┘
+      │        │             │               │
+      │   Phase A (i<T): chunk[i] 与 chunk[i+P] 配对     │
+      │       → 载入两块 → 逐元素相加成 1 块 → reduce     │
+      │   Phase B (i≥T): chunk[i] 独立处理               │
+      │       → 载入 → reduce                            │
+      │        │             │               │
+      ▼        ▼             ▼               │
+   每块/每对载入 UB → 向量 reduce → 1 个 fp32  │
+      │        │             │               │
+      ▼        ▼             ▼               │
+ ┌────────────────────────────────────────┐  │
+ │       二分缓存树 (UB, 仅 5 个 fp32)      │  │
+ │                                        │  │
+ │  cache[0]  cache[1]  cache[2]  ...  cache[4] │
+ │                                        │  │
+ │  按"末尾 1 个数"规则确定写入层级,         │  │
+ │  写入前吸收所有低层, 覆盖写本层           │  │
+ └────────────────────────────────────────┘  │
+                   │                        │
+                   ▼                        │
+           cache[4] = 最终总和 ◄──────────────┘
+```
+
+---
+
+## 六、伪码
+
+### 6.1 辅助函数
+
+```
+// FindNearestPower2: 严格小于 value 的最大 2 的幂。 value 为 0 或 1 时特例
+// 例: value=0→0, 2→1, 3→2, 4→2, 8→4, 16→8, 20→16
+FindNearestPower2(value):
+    if value == 0: return 0
+    if value <= 2: return 1
+    return 1 << floor(log2(value - 1))
+
+// GetCacheID: 二进制末尾连续 1 的个数 = 写入层级
+// 例: 0→0, 1→1, 2→0, 3→2, 4→0, 5→1, 6→0, 7→3, 8→0
+GetCacheID(idx):
+    return count_ones(idx ^ (idx + 1)) - 1
+
+// DoCaching: 吸收所有低层后覆盖写本层
+DoCaching(k, result):
+    for j = 0 to k-1:
+        result = result + cache[j]           // 正序吸收所有低层
+    cache[k] = result                         // 覆盖写本层
+
+// GetCacheRoot: 取缓存树根节点（最高层）
+GetCacheRoot(P):
+    L = log2(P) + 1
+    return cache[L-1]
+```
+
+### 6.2 主流程
+
+```
+输入: N=10000 个数, UB 容量 B=512
+M = ceil(N / B)              // 20, 总块数
+P = FindNearestPower2(M)     // 16, 主段长度(2幂)
+T = M - P                    // 4,  尾段长度
+L = log2(P) + 1              // 5,  缓存树层数
+
+for i = 0 to P-1:
+    // ── 1. 载入并求和 ──
+    if i < T:                                // Phase A: 主尾配对
+        load chunk[i]    → tmpBuf[0]
+        load chunk[i+P]  → tmpBuf[1]
+        tmpBuf[0] = tmpBuf[0] + tmpBuf[1]    // 逐元素相加成 1 块
+        result = reduce(tmpBuf[0])           // 1 个 fp32
+    else:                                    // Phase B: 独立
+        load chunk[i]    → reduce → result
+
+    // ── 2. 写入缓存树 ──
+    k = GetCacheID(i)                        // 末尾连续1的个数 = 写入层级
+    DoCaching(k, result)                     // 吸收所有低层，覆盖写 cache[k]
+
+answer = GetCacheRoot(P)                     // 树根 = 最终结果
+```
+
+---
+
+## 七、设计要点总结
+
+1. **主尾配对解决非 2 幂**：把 M 拆成 P（严格小于 M 的最大 2 幂）+ T，尾段 T 块与主段前 T 块配对合并，使树输入数为 P（2 幂），形成完美二叉树。M 为 2 幂时取 P=M/2，树深少 1，空间更省。
+
+2. **末尾 1 规则编码树结构**：顺序循环中，迭代序号 i 的二进制末尾连续 1 的个数决定写入层级，使顺序执行天然形成树形归约的依赖关系，无需显式建树。
+
+3. **吸收低层再覆盖写**：写入 cache[k] 前吸收所有低层 cache[0..k-1]，然后覆盖。低层旧值已被吸收，覆盖不影响正确性，且不需要额外缓冲。
+
+4. **精度提升**：树形归约每层相加的两个数量级相近，误差为 O(log P) 而非顺序累加的 O(M)。
+
+5. **空间极小**：缓存树仅需 L=log₂(P)+1 个 fp32，远小于保存全部中间结果的开销。

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

@@ -0,0 +1,146 @@
+# Reduce 高层 API（ReduceXxx 系列）
+
+> ReduceSum / ReduceMax / ReduceMin / ReduceProd / ReduceAny / ReduceAll 的 API 原型、硬约束、Pattern 选择、srcShape 计算、isReuseSource 与 buffer 份数。
+
+## 1 API 原型
+
+```cpp
+// 重载 1：不传 sharedTmpBuffer（API 内部 PopStackBuffer）
+template <class T, class pattern, bool isReuseSource = false>
+void ReduceSum(const LocalTensor<T>& dst, const LocalTensor<T>& src,
+               const uint32_t srcShape[], bool srcInnerPad);
+
+// 重载 2：显式传 sharedTmpBuffer
+template <class T, class pattern, bool isReuseSource = false>
+void ReduceSum(const LocalTensor<T>& dst, const LocalTensor<T>& src,
+               const LocalTensor<uint8_t>& sharedTmpBuffer,
+               const uint32_t srcShape[], bool srcInnerPad);
+
+// ReduceMax / ReduceMin / ReduceProd / ReduceAny / ReduceAll 同族同签名
+```
+
+## 2 硬约束
+
+| 约束 | 规则 | 违反后果 |
+|------|------|---------|
+| **src/dst 地址不可重叠** | `src` 和 `dst` 必须指向 UB 不同段 | 结果不可预测 |
+| **src 起始地址 32B 对齐** | ReduceSum src 起始地址需 32B 对齐 | UB 非对齐访问运行时错 |
+| **sharedTmpBuffer 与 src/dst 不可重叠** | sharedTmpBuffer 必须与 src/dst 指向 UB 不同段 | 内部 scratch 污染 src/dst |
+| **不处理累加溢出** | b16 输入必须先 Cast 到 fp32 再做 reduce | 大数值/长 R 累加溢出 |
+| **srcInnerPad** | 必须传 `true`（已按 32B 对齐填充） | tail-R 下读错 padding lane |
+| **isReuseSource** | `true`：API 把 src 当内部 scratch，调用后 **src 内容失效**。结果始终写入 dst（src/dst 不可重叠）。`false`：src 内容保持不变，Reduce 后可继续读 | 误读已破坏的 src |
+
+## 3 Pattern 选择
+
+| tail 类型 | AscendC Pattern | srcShape | 含义 |
+|---------|----------------|----------|------|
+| tail-R | `Pattern::Reduce::AR` | `{aBundle, rBundle}` | 沿内层 R reduce，保留外层 A |
+| tail-A | `Pattern::Reduce::RA` | `{rBundle, aBundle}` | 沿外层 R reduce，保留内层 A |
+
+其中 `aBundle = aUbFactor × innerAProdAlign`，`rBundle = rUbFactorAlign × innerRProdAlign`。
+
+## 4 srcShape 计算
+
+srcShape 是 `uint32_t[2]`，按 **padded 值**计算（含 CeilAlign 因子），与 `srcInnerPad=true` 配合：
+
+- **tail-R**：`srcShape = {aUbFactor × innerAProdAlign, rUbFactorAlign × innerRProdAlign}`
+- **tail-A**：`srcShape = {rUbFactorAlign × innerRProdAlign, aUbFactor × innerAProdAlign}`
+
+## 5 isReuseSource 与 buffer 份数
+
+**本范式统一使用重载 2（带 sharedTmpBuffer）**，`preReduceResultTail` 兼作 sharedTmpBuffer。preReduceResultTail 本就为 Phase A 主尾配对分配，Reduce 时已空闲，复用不增加 UB 开销。
+
+isReuseSource 的选择根据算子特征判定：
+
+- **isReuseSource=true**：Reduce 后不依赖 src（后续计算不读 src），API 把 src 当内部 scratch（调用后 src 内容失效）
+- **isReuseSource=false**：Reduce 后依赖 src（后续计算需读 src），src 内容保持不变
+
+无论 isReuseSource 取何值，buffer 份数固定为 **3 份**：
+
+| buffer | 用途 |
+|---|---|
+| `preReduceResult` | Reduce 的 src |
+| `preReduceResultTail` | 兼作 sharedTmpBuffer（Phase A 配对后空闲） |
+| `cacheBuf` | Reduce 的 dst |
+
+## 6 ReduceSum 内部累加方式
+
+> 本节为内部实现分析，以 arch35 为例，仅供理解 API 行为。范式将 ReduceXxx 视为黑盒，调用方式不受本节内容影响。
+
+ReduceSum 内部采用 **多路并行二叉树折叠**（Multi-way Parallel Binary Tree Folding），非顺序累加。以 AR pattern 为例（fp32，`vlSize = GetVecLen() / sizeof(T)`）。
+
+### 6.1 关键参数
+
+> B64 = 64 位宽类型（如 fp64/int64）；非 B64 = 32 位及以下。每轮加载 16 个寄存器（B64 为 8 个），做 4 级（B64 为 3 级）并行二叉树合并。
+
+| 参数 | 含义 | 计算 |
+|------|------|------|
+| `mainR` | ≤dimR 的最大 2^n | `CalculateMainR(dimR, isAR, vlSize)` |
+| `tailR` | dimR 的非 2 幂尾数 | `dimR - mainR`（isReuseSource=false 且 tailR=0 时强制拆半） |
+| `base` | VL 块数 | `mainR / vlSize` |
+| `folds` | 总折叠层数 | `log2(base)` |
+| `avgFolds` | 每轮主折叠层数 | 非 B64 = 4（16 寄存器 → 1），B64 = 3（8 → 1） |
+| `mainTimes` | 主折叠轮数 | `folds / avgFolds` |
+| `tailFolds` | 尾折叠层数 | `folds % avgFolds` → 选 foldZero/One/Two/Three 之一 |
+
+### 6.2 四步算法
+
+**Step 0 — 尾块合并**（dimR → mainR）：将 tailR 个尾元素加到 mainR 对应位置，剩余 mainR − tailR 个元素原样拷贝到 tmpBuf（isReuseSource=true 则原地写 src）。若 dimR 恰好是 2 的幂（tailR=0），isReuseSource=false 时强制拆半 `mainR /= 2, tailR = mainR`——等价于二叉树第一层。结果：mainR 个元素。
+
+**Step 1 — 主折叠**（`mainTimes` 轮）：每轮加载 16 个寄存器（B64 为 8 个），做 4 级（B64 为 3 级）并行二叉树合并，数据量缩减 16 倍（B64 为 8 倍）：
+
+```
+非 B64（16→1, 4 级）:
+  L1: 8 adds  (16→8)   vreg[i] += vreg[i+8]
+  L2: 4 adds  (8→4)    vreg[i] += vreg[i+4]
+  L3: 2 adds  (4→2)    vreg[i] += vreg[i+2]
+  L4: 1 add   (2→1)    vreg[0] += vreg[1]
+
+B64（8→1, 3 级）:
+  L1: 4 adds  (8→4)
+  L2: 2 adds  (4→2)
+  L3: 1 add   (2→1)
+```
+
+**Step 2 — 尾折叠**（根据 `tailFolds` 选一分支）：
+
+| tailFolds | 分支 | 寄存器 | 树级数 | 操作 |
+|-----------|------|--------|--------|------|
+| 0 | foldZero | 1 | 0 | 直接 Step 3 |
+| 1 | foldOne | 2 | 1 | 1 add → Step 3 |
+| 2 | foldTwo | 4 | 2 | 2 级树 → Step 3 |
+| 3 | foldThree | 8 | 3 | 3 级树 → Step 3 |
+
+> bf16/int8 在 Step 2 中先 Cast 到 fp32/half 再做硬件 Reduce。
+
+**Step 3 — 硬件 Reduce 收尾**：对最后 1 个寄存器（vlSize 个元素）调用 `Reg::ReduceSum` 硬件指令，两两配对相加，归约为 1 个标量写入 dst。
+
+### 6.3 示例
+
+**示例 1**：AR, fp32, dimA=1, dimR=4096, isReuseSource=false（vlSize=64）
+
+| 步骤 | 操作 | 元素数 | VL 块数 |
+|------|------|--------|---------|
+| Step 0 | tailR=0 → 拆半 Add(2048+2048) | 4096→2048 | 32 |
+| Step 1 ×1 | 16-way 4 级树 | 2048→128 | 32→2 |
+| Step 2 | foldOne, 2 regs 1 add | 128→64 | 2→1 |
+| Step 3 | Reg::ReduceSum | 64→1 | — |
+
+**示例 2**：AR, fp32, dimA=1, dimR=131072, isReuseSource=false（vlSize=64）
+
+| 步骤 | 操作 | 元素数 | VL 块数 |
+|------|------|--------|---------|
+| Step 0 | tailR=0 → 拆半 Add(65536+65536) | 131072→65536 | 1024 |
+| Step 1 ×1 | 16-way 4 级树 | 65536→4096 | 1024→64 |
+| Step 1 ×2 | 16-way 4 级树 | 4096→256 | 64→4 |
+| Step 2 | foldTwo, 4 regs 2 级树 | 256→64 | 4→1 |
+| Step 3 | Reg::ReduceSum | 64→1 | — |
+
+### 6.4 与范式二分缓存树的关系
+
+ReduceSum 内部二叉树处理 **单个 rChunk 内** 的 R 维归约（rUbFactorAlign 个元素 → 1 个结果）。范式二分缓存树处理 **跨 rChunk** 的累加（多个 rChunk 的 reduce 结果 → cacheBuf 二分合并）。两者构成两级树：
+
+- **API 级树**（本节）：rChunk 内，多路并行二叉树 + 硬件 Reduce 指令
+- **范式级树**（[reduction-binary-base-kernel-template.md](reduction-template-binary-base/reduction-binary-base-kernel-template.md) §1.1）：rChunk 间，cacheBuf 二分缓存树
+
+范式无需关心 API 内部实现——传入 srcShape，API 返回 dst。API 内部已用树形累加保证单次 reduce 的精度，范式二分缓存树进一步保证跨 chunk 累加精度。

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

@@ -0,0 +1,96 @@
+# reduction 范式 Kernel 入口
+
+> Kernel 入口函数注册、模板分发、TilingData 获取的统一规范
+
+## 1 kernel 入口
+
+**约束**:
+- `DTYPE_IN0` 编译期实例化（dtype 不走 TilingKey）：框架按 REG_OP 输入命名自动生成 `DTYPE_<INPUT_NAME>`（如第一个输入叫 `x` 则框架定义 `DTYPE_X`），按注册的 dtype 列表为每种类型生成独立编译实例
+- `AscendC::TPipe pipe;` 统一在入口申请 TPipe，通过 Init 以指针的方式传入各模板中
+- kernel 入口函数的模板参数，必须与 TilingKey 字段一一对应，顺序一致
+- `__global__` 模板参数仅含 tilingkey 的各字段，**禁止加 `typename D_T`**
+- 入参顺序 = 算子原型定义顺序 + 末尾固定 `workspace` + `tiling`
+
+### 1.1 kernel 入口知识
+
+**内容**：
+- 模板参数与 TilingKey 的对应关系：与 TilingKey 字段一一对应
+- `REGISTER_NONE_TILING` + 各分支 `GET_TILING_DATA_WITH_STRUCT` 获取对应 TilingData（2 份 struct：Base/Group 用 `{OP}TilingData`，Empty 用 `{OP}EmptyTilingData`）
+- `if constexpr` 三路分发到不同 kernel 类（`{OP}` 为算子名，开发时替换为实际算子名，如 `EuclideanNorm`）：
+  - `isEmptyTensor` → `{OP}EmptyKernel<DTYPE_X>`
+  - `isGroup` → `{OP}GroupKernel<DTYPE_X>` 的 `InitGroup` / `ProcessGroup`（Group 模板）
+  - 否则 → `{OP}BaseKernel<DTYPE_X>` 的 `Init` / `Process`（Base 模板）
+
+**规范**：
+- 三个模板物理分文件：`<op>_base.h`（base）、`<op>_group.h`（group）、`<op>_empty.h`（empty）
+
+### 1.2 kernel入口代码
+
+**入口代码**（2 份 TilingData，入口统一 `REGISTER_NONE_TILING`，各分支分别 `GET_TILING_DATA_WITH_STRUCT`）：
+
+```cpp
+template <bool isGroup, bool isEmptyTensor>
+__global__ __aicore__ void {op}(
+    GM_ADDR in0, ..., GM_ADDR out0, ..., GM_ADDR workspace, GM_ADDR tiling)
+{
+    REGISTER_NONE_TILING;
+    AscendC::TPipe pipe;
+
+    if constexpr (isEmptyTensor) {
+        GET_TILING_DATA_WITH_STRUCT({OP}EmptyTilingData, tilingData, tiling);
+        {OP}EmptyKernel<DTYPE_X> op;       // DTYPE_X：X=输入名，框架自动生成
+        op.Init(/*...*/, &tilingData, &pipe);
+        op.Process();
+    } else if constexpr (isGroup) {
+        GET_TILING_DATA_WITH_STRUCT({OP}TilingData, tilingData, tiling);
+        // Group 模板：A×R 2D 分核 Phase 1 → SyncAll → Phase 2 RA mini-kernel
+        {OP}GroupKernel<DTYPE_X> op;
+        op.InitGroup(/*...*/, &tilingData, &pipe);
+        op.ProcessGroup();
+    } else {
+        GET_TILING_DATA_WITH_STRUCT({OP}TilingData, tilingData, tiling);
+        {OP}BaseKernel<DTYPE_X> op;
+        op.Init(/*...*/, &tilingData, &pipe);
+        op.Process();
+    }
+}
+```
+
+> `{OP}` 为算子名 PascalCase（如 `EuclideanNorm`），`{op}` 为算子名 snake_case（如 `euclidean_norm`）。开发时替换为实际算子名。
+
+**多输入算子场景**（如 SyncBatchNormGatherStatsWithCounts 有 6 输入 2 输出）：
+
+```cpp
+template <bool isGroup, bool isEmptyTensor>
+__global__ __aicore__ void sync_batch_norm_gather_stats_with_counts(
+    GM_ADDR mean_all, GM_ADDR invert_std_all, GM_ADDR count_all,
+    GM_ADDR mean_broadcast, GM_ADDR count_sum, GM_ADDR running_var,
+    GM_ADDR invert_std, GM_ADDR running_var_update,
+    GM_ADDR workspace, GM_ADDR tiling)
+{
+    REGISTER_NONE_TILING;
+    AscendC::TPipe pipe;
+
+    if constexpr (isEmptyTensor) {
+        GET_TILING_DATA_WITH_STRUCT(SyncBatchNormGatherStatsWithCountsEmptyTilingData, tilingData, tiling);
+        SyncBatchNormGatherStatsWithCountsEmptyKernel<DTYPE_MEAN_ALL> op;
+        op.Init(mean_all, invert_std_all, count_all, mean_broadcast, count_sum, running_var,
+                invert_std, running_var_update, &tilingData, &pipe);
+        op.Process();
+    } else if constexpr (isGroup) {
+        GET_TILING_DATA_WITH_STRUCT(SyncBatchNormGatherStatsWithCountsTilingData, tilingData, tiling);
+        SyncBatchNormGatherStatsWithCountsGroupKernel<DTYPE_MEAN_ALL> op;
+        op.InitGroup(mean_all, invert_std_all, count_all, mean_broadcast, count_sum, running_var,
+                     invert_std, running_var_update, &tilingData, &pipe);
+        op.ProcessGroup();
+    } else {
+        GET_TILING_DATA_WITH_STRUCT(SyncBatchNormGatherStatsWithCountsTilingData, tilingData, tiling);
+        SyncBatchNormGatherStatsWithCountsBaseKernel<DTYPE_MEAN_ALL> op;
+        op.Init(mean_all, invert_std_all, count_all, mean_broadcast, count_sum, running_var,
+                invert_std, running_var_update, &tilingData, &pipe);
+        op.Process();
+    }
+}
+```
+
+> `DTYPE_<INPUT_NAME>` 取输入名大写化。

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

@@ -0,0 +1,74 @@
+# 存活节点 (Survival Node)
+
+> 算子 Tiling 设计的核心概念。决定 UB buffer 划分，直接影响 tile 大小和性能。
+
+---
+
+## 公共概念
+
+**定义**：在计算或执行的某一时刻，必须同时驻留的独立数据实体（tensor 或 buffer）的数量。对一个算子，取其最优调度下的**峰值**（不是 allocated 总数）作为存活节点数。
+
+**大小 = 峰值**。逐一追踪每步的执行中持有数，取全流程最大值。
+
+**公平基线（L 和 P 共用）**：
+1. 二元及以上操作，不假设 dst 与 src 复用——每个 op 的 src 和 dst 各占独立节点
+2. 单步内不假设 in-place
+3. 跨步的"用完释放"允许——一个节点的所有消费者执行完后从存活列表移除
+
+**追踪方法（L 和 P 共用）**：
+1. 画出完整计算图（含 reduce）
+2. 识别分叉结构（同一数据被多处引用）
+3. 按最优调度逐步追踪每步的**执行中**存活数
+4. 取全流程最大值 = 存活节点数
+5. **互斥分支流（Tuple Reduce）**：按代码结构画一条流——公共步骤出现一次，过程独有步骤用 if/else 分支并列；分支互斥，一处 if/else 的峰值取各分支 max（禁止相加、不按分支单独记账），其余按标准存活区间判定。规则对 L、P 均适用；"不按分支单独记账"只作用于 P，L 仍按公平基线逐 op 计节点。
+
+---
+
+## 逻辑存活节点 (L)
+
+**特有计数域**：计算图 tensor（每个独立数据实体计 1；跨阶段驻留的 tensor 归属其分配阶段，不计入其他阶段——如 reduceResult 驻 cacheBuf，计入 reduce 阶段）
+
+**公平基线即为完整规则**——L 没有额外的物理复用、没有硬件能力，纯粹按计算图拓扑 + 最优调度决定。
+
+**L 对给定计算图是固定的**，不随硬件/API/实现改变。
+
+---
+
+## 物理存活节点 (P)
+
+**特有计数域**：UB buffer。寄存器不在计数域——UB→Reg→UB 是过路中转，中间值留在寄存器时不占 P。buffer 计入其分配阶段的 P，跨阶段复用不占复用阶段的 P（如 reduceResult 驻 cacheBuf，不占 P_post）。独占分配的 buffer（生命周期内不允许与其他 tensor 复用）视为全程驻留，计入 P。
+
+**物理基线 = 逻辑基线 + 以下差异**（只能来自 API/硬件能力）：
+
+| 差异来源 | 公平？ | 说明 |
+|---------|--------|------|
+| 跨步 buffer 复用 | ✓ | 生命周期不重叠可共用物理 buffer，物理侧允许 |
+| MulAddDst 硬件融合 | ✓ | 硬件保证 dst 就地覆写，计为 API 能力 |
+| 软件 StoreAlign 覆写 | ✗ | 逻辑侧/物理基线均不假设 in-place |
+| VF 寄存器链融合 | ✓ | 中间值全程在寄存器（见下文） |
+
+**P 不由计算图唯一确定**——同一计算图，不同 API 策略/融合决策 → 不同 P。寻找在给定约束下可达的**最小峰值**。
+
+### P ≥ L 与例外
+
+MemBase 下 P ≥ L 恒成立——每个 op 的 src 和 dst 各占独立 UB buffer，无硬件能力消掉中间节点。
+
+VF 寄存器链可打破此规律：中间值全程在寄存器，不落 UB。L 仍包含（按 tensor 计数），P 不包含（寄存器不计入 P）。此时 **P < L 合法**。
+
+> 例：reduction preReducePhase 中 `Cast(fp16→fp32) + Square + Add` 全链 VF 融合后，Cast 和 Square 的中间值在寄存器，L=4（输入 + 3 个中间 tensor），P=2（输入 buffer + 输出 buffer）。设计文档必须说明哪些中间值被 VF 消掉。
+
+### Cast 对 P 的影响
+
+reduction 范式中 Cast 使用 `Reg::Cast` 寄存器指令（详见 [common/cast-rules.md](../../common/cast-rules.md) §4.3），在 VF 链内完成类型转换。
+
+- **Cast 参与 VF 融合时**：Cast 在寄存器内完成，src 和 dst 不需要同时占两个 UB buffer。Cast 不额外增加 P。
+- **Cast 不参与 VF 融合时**（独立 Cast 操作）：Cast 的 src 和 dst 是两块独立 UB buffer，纳入物理 trace 取峰值。
+
+### RegBase 对 P 的影响
+
+RegBase 允许数据在寄存器中构造和驻留，**可以降低 P**：
+
+- **常量/标量在寄存器构造**：标量不占 UB
+- **链式中间值留在寄存器**：Reg::Cast→Reg::Mul→Reg::Add 连续计算，中间结果全程在寄存器链上
+
+**不改变的情况**：单次二元操作 src0/s1 本来就在 UB 中，RegBase 仍需 UB→LoadAlign→Reg compute→StoreAlign→UB，UB 需求与 MemBase 相同。