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

package/assets/ops-direct-invoke/skills/ascendc-performance-best-practices/references/common/tail_block_design.md

@@ -0,0 +1,268 @@
+# Tail Block / Data Alignment 优化设计
+
+## 1. 优化目标
+
+在 Convolution、Pooling、Gather 等算子中，输入数据量往往不能被核心数或 tile 大小整除，产生尾块（tail block）。Naive 实现采用固定 tile 处理，导致尾块访问越界、数据竞争或负载不均衡。
+
+本优化通过双轨制计算、向量化尾块处理、多维度 Tiling 尾块分离等手段，确保在所有场景下实现近完美的负载均衡和正确的边界处理。
+
+| 指标 | naive | optimized | 收益 |
+|------|-------|-----------|------|
+| 尾块处理 | 简单截断，可能越界 | 双轨制 norm/tail 核分离 | 避免数据竞争和越界访问 |
+| 尾块计算 | 标量循环处理 | GatherMask 向量化处理 | 一次处理 64 个元素，提升 4-8 倍 |
+| 多核负载 | 尾核空闲或超载 | 动态 costLimit + 容忍度机制 | 非整除场景性能提升 10-30% |
+| 内存对齐 | 未考虑对齐 | 32B/64B 对齐 + DataCopyPad | 避免非对齐访问性能损失 |
+
+
+## 2. 架构概览
+
+### 2.1 存储层级与数据流
+
+Tail Block 处理的数据流：输入数据经 MTE2 从 GM 搬入 UB/L1，分为正常块（normBlock）和尾块（tailBlock）。正常核处理 `defaultUbFactor` 整数倍的数据量，尾核处理剩余数据量。尾块使用 GatherMask 向量化处理或 DataCopyPad 对齐填充，结果经 MTE3 写回 GM，多核竞争场景使用 AtomicAdd 避免数据竞争。
+
+### 2.2 双轨制计算模型
+
+Host 侧将数据分为正常核（normCore）和尾核（tailCore）两组：
+- **正常核**：处理 `defaultUbFactor` 整数倍的数据量
+- **尾核**：处理剩余数据量，单独计算尾块循环次数和尾块大小
+
+Kernel 侧根据 `blockIdx_` 判断自己是正常核还是尾核，选择对应的循环参数。
+
+### 2.3 事件同步模型
+
+| 事件类型 | 含义 | 用途 |
+|---------|------|------|
+| `MTE2_V` | MTE2 搬运完成 → 允许 Vector 读取 | 主数据 tile 就绪 |
+| `V_MTE3` | Vector 完成 → 允许 MTE3 写回 | 尾块计算完成，可写 GM |
+| `PIPE_V` | Vector 管道屏障 | 向量化指令间数据依赖 |
+
+## 3. 关键参数配置
+
+```cpp
+// Host 侧 TilingData
+struct TailBlockTiling {
+    uint32_t normBlockLoop;           // 正常核循环次数
+    uint32_t normBlockTailLoopSize;   // 正常核最后循环大小
+    uint32_t tailBlockLoop;           // 尾核循环次数
+    uint32_t tailBlockTailLoopSize;   // 尾核最后循环大小
+    uint32_t defaultValueUsedCoreNum; // 正常核数量
+    uint32_t defaultUbFactor;         // 默认 UB 处理粒度
+};
+```
+
+### 3.1 Tile 大小选取原则
+
+| 参数 | 典型值 | 说明 |
+|------|--------|------|
+| `defaultUbFactor` | 64 / 128 / 256 | 向量化处理粒度，需对齐 Vector 单元宽度 |
+| `alignCoef` | 32B / 64B | 数据类型相关对齐系数（FP16=32B, FP32=64B） |
+
+**Ascend 对齐约束**：
+
+- Global Memory 访问需 32B 对齐
+- Vector 指令最优访问粒度为 32B（FP16）或 64B（FP32）
+- Cube 矩阵乘需 16x16 或 32x32 对齐
+
+```cpp
+// 对齐计算
+uint32_t numPerBlock = ONE_BLK_SIZE / sizeof(T);  // 32B / sizeof(T)
+uint32_t alignedSize = (size + numPerBlock - 1) / numPerBlock * numPerBlock;
+```
+
+### 3.2 内存预算
+
+尾块处理需要额外的 pattern buffer（用于 GatherMask）和索引 buffer：
+- `tmpPattern` buffer：约 64B（uint32_t/uint16_t pattern）
+- `indexBuf` buffer：6 个索引 × tile 大小（用于 adaptive pooling）
+
+## 4. 核心计算循环
+
+### 4.1 naive 版本（优化前）
+
+```cpp
+// 固定 tile 处理，无尾块特殊处理
+for (uint32_t i = 0; i < this->innerLoops; i++) {
+    CopyIn(i);
+    Compute(i);
+    CopyOut(i);
+}
+// 问题：最后一 tile 可能越界；尾核负载不均
+```
+
+### 4.2 optimized 版本（优化后）：双轨制尾块处理
+
+```cpp
+// Host 侧：计算 norm/tail 核参数
+normBlockLoop_ = Ops::Base::CeilDiv(normCoreHandleDefaultValues_, defaultUbFactor_);
+normBlockTailLoopSize_ = normCoreHandleDefaultValues_ - defaultUbFactor_ * (normBlockLoop_ - 1);
+tailBlockLoop_ = Ops::Base::CeilDiv(tailCoreHandleDefaultValues, defaultUbFactor_);
+tailBlockTailLoopSize_ = tailCoreHandleDefaultValues - defaultUbFactor_ * (tailBlockLoop_ - 1);
+
+// Kernel 侧：根据 blockIdx 选择参数
+loop_ = tilingData_.normBlockLoop;
+tailLoopSize_ = tilingData_.normBlockTailLoopSize;
+if (blockIdx_ == tilingData_.defaultValueUsedCoreNum - 1) {
+    loop_ = tilingData_.tailBlockLoop;
+    tailLoopSize_ = tilingData_.tailBlockTailLoopSize;
+}
+
+// 主循环
+for (uint32_t i = 0; i < loop_; i++) {
+    bool isLastLoop = (i == loop_ - 1);
+    uint32_t currentTileSize = isLastLoop ? tailLoopSize_ : defaultUbFactor_;
+    
+    // 使用 DataCopyPad 处理非对齐尾块
+    if (isLastLoop && currentTileSize != defaultUbFactor_) {
+        DataCopyExtParams copyParams{1, static_cast<uint32_t>(currentTileSize * sizeof(T)), 0, 0, 0};
+        DataCopyPadExtParams<T> padParams{false, 0, 0, 0};
+        DataCopyPad(dataLocal, inTensorsGM[...], copyParams, padParams);
+    } else {
+        DataCopy(dataLocal, inTensorsGM[...], currentTileSize);
+    }
+    
+    Compute(dataLocal, currentTileSize);
+    CopyOut(dataLocal, currentTileSize);
+}
+```
+
+### 4.3 GatherMask 向量化尾块处理
+
+```cpp
+// 对于最后一个输出点的尾块，使用 GatherMask 进行数据重排
+if constexpr (std::is_same_v<T, float>) {
+    LocalTensor<uint32_t> bufPattern = tmpPattern.Get<uint32_t>();
+    int32_t preLeftShift = numPerBlock + lastLeftShift;
+    bufPattern.SetValue(0, (1u << preLeftShift) - (1u << lastLeftShift));
+    GatherMask(outputLocal[gatherOffset], outputLocal[gatherOffset], 
+               bufPattern, true, mask, {1, 1, 8, 8}, rsvdCnt);
+}
+// 避免 atomic 操作开销，正确处理尾块数据布局
+```
+
+### 4.4 非对齐数据的原子操作处理
+
+```cpp
+// 针对数据非 32B 对齐的情况，使用 AtomicAdd 避免数据竞争
+uint64_t mask0 = (1ul << numPerBlock) - (1ul << validDataLen);
+uint64_t mask[2] = {mask0, 0};
+Duplicate<T>(outputLocal, 0, mask, 1, 1, 1);
+SetAtomicAdd<T>();
+DataCopy(outputGlobal[offset], outputLocal, cTailAlign);
+SetAtomicNone();
+```
+
+## 5. 从 naive 到 tail_block 的关键修改点
+
+| 修改项 | naive（优化前） | tail_block（优化后） |
+|--------|---------------|---------------------|
+| 核类型 | 所有核处理相同数据量 | 双轨制：normCore + tailCore |
+| 尾块处理 | 简单截断或越界访问 | GatherMask 向量化 / DataCopyPad 对齐 |
+| 数据竞争 | 无保护，可能写冲突 | AtomicAdd / 边界跳过 |
+| 负载均衡 | 固定分配 | 动态 costLimit + 容忍度机制 |
+| 内存对齐 | 未考虑 | 32B/64B 对齐 + padding |
+| 索引计算 | 运行时除法/取模 | IndexBuffer 预计算复用 |
+
+## 6. 注意事项 / 约束
+
+1. **GatherMask 的 pattern buffer 类型**。float 类型用 uint32_t pattern，half/bfloat16_t 用 uint16_t pattern。
+
+2. **AtomicAdd 的性能开销**。虽然保证正确性，但 atomic 操作有一定性能损失，优先使用 GatherMask 避免竞争。
+
+3. **尾块大小必须 > 0**。若尾块大小为 0，该核应直接返回，避免空循环。
+
+4. **多维度 Tiling 的尾块**。每个维度（Channel、Spatial、Batch）都需独立计算尾块参数。
+
+5. **重叠检测**。Adaptive Pooling 中 kernel 可能重叠，需检测并设置 `isOverLap` 标志，使用 atomic add 保证正确性。
+
+6. **对齐填充的数据正确性**。SkipPad 策略需确保 padding 区域的 0 不会被错误计入后续计算（如方差）。
+
+7. **32B 对齐是硬性要求**。未对齐的 GM 访问可能导致硬件异常或性能下降。
+
+## 7. 实施常见问题与解决方案
+
+### Q1: 尾核处理量远小于正常核，导致尾核很快完成但需等待正常核
+**A**: 使用容忍度机制（tolerance ratio），允许轻微超载以减少碎片。`costLimit` 动态计算为"剩余总代价 / 剩余核数"。
+
+### Q2: GatherMask 的 pattern 计算错误导致数据重排异常
+**A**: 确保 `preLeftShift` 和 `lastLeftShift` 计算正确，pattern 值为 `(1u << preLeftShift) - (1u << lastLeftShift)`。
+
+### Q3: DataCopyPad 的 padding 值污染后续计算
+**A**: 使用 `SkipPadSubMean` 等策略跳过 padding 区域，或在计算前用 `Duplicate` 填充 padding 区域为中性值（如 0 或 MASK_VALUE）。
+
+### Q4: 多核场景下尾块原子加导致结果非确定性
+**A**: 使用确定性模式（deterministic mode），反向处理并检测边界索引冲突，跳过冲突索引由前一个核处理。
+
+## 8. 场景用例
+
+### 8.1 各算子族实例
+
+**Elementwise** `[1000, 128]`, tileRows=256，尾块 232 行，策略 1：
+
+```cpp
+uint32_t loopCount = (rows + tileRows - 1) / tileRows;
+for (uint32_t loop = 0; loop < loopCount; loop++) {
+    uint32_t curRows = (loop == loopCount - 1)
+                           ? (rows - loop * tileRows) : tileRows;
+    uint32_t curLen = curRows * cols;
+    DataCopy(xLocal, xGm[loop * tileRows * cols], curLen);
+    Adds(yLocal, xLocal, 1.0f, curLen);
+    DataCopy(yGm[loop * tileRows * cols], yLocal, curLen);
+}
+```
+
+**MatMul** `M=1023`, blockM=128，尾块 127 行，策略 2+1：
+
+```cpp
+// Host：双轨制分核
+uint32_t mPerCore = CeilDiv(M, coreNum);
+// Kernel：根据 blockIdx 确定 M 范围
+uint32_t localM = (blockIdx < coreNum - 1) ? mPerCore : M - blockIdx * mPerCore;
+uint32_t loopCount = (localM + blockM - 1) / blockM;
+for (uint32_t loop = 0; loop < loopCount; loop++) {
+    uint32_t curM = (loop == loopCount - 1) ? (localM - loop * blockM) : blockM;
+}
+```
+
+**FlashAttention** `seqLen=1025`, tileSeq=1024，尾块 1 行，策略 1+3：
+
+```cpp
+uint32_t kvLoopCount = (kvSeqLen + kvTileSize - 1) / kvTileSize;
+for (uint32_t kvLoop = 0; kvLoop < kvLoopCount; kvLoop++) {
+    uint32_t curKvLen = (kvLoop == kvLoopCount - 1)
+                            ? (kvSeqLen - kvLoop * kvTileSize) : kvTileSize;
+    if (curKvLen % 16 != 0) {  // Cube 输入需对齐
+        DataCopyPad(kLocal, kGm[...], copyParams, padParams);
+    }
+    if (isCausal && qLoop == kvLoopCount - 1) {
+        ApplyCausalMaskPartial(..., curKvLen);  // 尾块 causal mask
+    }
+}
+```
+
+---
+
+## 9. 选型决策与自检清单
+
+### 9.1 选型决策
+
+```
+if (算子包含迭代循环 && 数据量不能被 tile 大小整除):
+    → 启用 tail_block 优化
+    → 计算 normBlockLoop / tailBlockLoop
+    → 尾块使用 DataCopyPad 或 GatherMask
+    → 多核场景使用 AtomicAdd 或确定性模式
+else:
+    → 标准 tile 处理即可
+```
+
+### 9.2 自检清单
+
+- [ ] Host 侧正确计算 normBlockLoop / tailBlockLoop / normBlockTailLoopSize / tailBlockTailLoopSize
+- [ ] Kernel 侧根据 blockIdx_ 正确选择 norm/tail 参数
+- [ ] 尾块大小为 0 时核直接返回
+- [ ] DataCopyPad 参数正确（blockCount, blockLen, srcStride, dstStride）
+- [ ] GatherMask pattern 类型与数据类型匹配（float→uint32_t, half→uint16_t）
+- [ ] 32B/64B 对齐约束满足
+- [ ] AtomicAdd 在 SetAtomicAdd / SetAtomicNone 配对内使用
+- [ ] 确定性模式下反向处理和边界检测正确
+- [ ] 精度校验通过：与 naive 实现对比，误差 < 1e-5（FP32）或 < 1e-3（FP16）

package/assets/ops-direct-invoke/skills/ascendc-performance-best-practices/references/common/ub_resident_design.md

@@ -0,0 +1,342 @@
+# UB/TBuf 常驻复用与 Bank 冲突规避优化设计
+
+## 1. 优化目标
+
+在 Vector 算子中，小尺寸参数（weight、gamma、scale）或跨迭代状态（累加器、递推结果）若每个 tile/loop 都重复从 GM 搬运，会造成大量冗余 MTE2 开销。本优化通过将这类数据常驻 UB/TBuf，在循环外一次初始化、循环内片上读写，**消除重复搬运**。同时，通过地址分配优化和计算逻辑调整**规避 UB bank 冲突**，避免 Vector 计算性能退化。
+
+| 指标 | naive | optimized | 收益 |
+|------|-------|-----------|------|
+| 参数搬运次数 | 每 tile/loop 1 次 | Process 生命周期仅 1 次 | 搬运次数降低 N 倍（N=tile/loop 数） |
+| 临时 buffer 总量 | `sum(stage_buffers)` | `max(concurrent_buffers)` | UB 占用降低 30-60% |
+| Vector 单 Repeat 周期 | 多拍（bank 冲突，因芯片而异） | 1-2 拍（无冲突） | 计算速度提升数倍 |
+| 代码复杂度 | 低 | 中（需生命周期管理） | 常驻 buffer + 分区 offset |
+
+## 2. 架构概览
+
+### 2.1 常驻复用 vs 分时复用
+
+| 策略类型 | 数据生命周期 | 复用方式 | 典型场景 |
+|---------|------------|---------|---------|
+| **常驻复用** | 跨整个 Process 或多层循环 | 循环外搬入，循环内只读/读写 | weight、gamma、scale 小参数 |
+| **分时复用** | 单次 Process 内多阶段串行 | 前一阶段结束，后一阶段覆盖 | RmsNorm→RoPE、SoftMax→后处理 |
+
+### 2.2 UB Bank 结构与冲突原理
+
+以 Ascend 910B 为例：UB (192KB) = 48 bank × 4KB = 16 bank group × 3 bank/group。不同芯片的 bank 数可能不同，需查阅对应硬件手册。
+
+#### 2.2.1 Bank 冲突的硬件原理
+
+Vector 计算单元在一个 Repeat 周期内会并行发出多个 DataBlock 的读写请求。理想情况下，这些请求被分发到不同的 bank/bank group 上并发执行，1 个 Repeat 周期完成全部访问。当多个请求因地址映射关系落到**同一 bank 或同一 bank group** 时，硬件仲裁逻辑会将其串行化，导致单 Repeat 从 1-2 拍退化到多拍（具体拍数因芯片和冲突 DataBlock 数量而异）。
+
+> **注意**：不同芯片的 bank 结构和冲突条件不同，必须查阅对应硬件文档。下文以 NPU 架构版本 220x（Atlas A2/A3 系列）和 Atlas 350 为例说明。
+
+#### 2.2.2 不同芯片的 UB Bank 结构
+
+| 芯片 | UB 大小 | Bank 数 | Bank Group 数 | 每组 Bank 数 | 每 Bank 大小 | 每行大小 |
+|------|---------|---------|---------------|-------------|-------------|---------|
+| DAV_2201 | 192 KB | 48 | 16 | 3 | 4 KB (128 行) | 32 B |
+| DAV_3510 | 256 KB | 16 | 8 | 2 | 16 KB (512 行) | 32 B |
+
+**Bank Group 组成方式**：group 内各 bank 的编号满足 `bank_id % num_groups` 相同。以 220x 为例：
+- group 0: bank 0, 16, 32
+- group 1: bank 1, 17, 33
+- ...
+- group 15: bank 15, 31, 47
+
+**冲突条件差异**（关键区别）：
+
+| 冲突类型 | NPU 220x | Atlas 350 |
+|---------|----------|-----------|
+| 读写冲突 | 同一 **bank** | 同一 **bank** |
+| 写写冲突 | 同一 **bank group** | 同一 **bank group** |
+| 读读冲突 | 同一 **bank group** | 同一 **bank**（两个读操作），或**两个以上**读操作同一 bank group |
+
+> Atlas 350 的 bank group 上有两组读口和写口，因此**两次读操作访问同一 bank group 的不同 bank 时不会冲突**，但 220x 上同一 bank group 内的任意多次并发访问都会冲突。
+
+#### 2.2.3 DataBlock 与 Bank 映射
+
+Vector 指令处理的数据被切分为固定大小的 **DataBlock**，每行长度为 32B。一个 Vector 指令在一个 Repeat 内最多处理 **8 个 DataBlock**（block0~block7）。各 DataBlock 根据起始地址映射到某个 bank，进而归属于某个 bank group。
+
+**映射的核心规律**（由官方示例推导，具体公式以芯片手册为准）：
+- 地址上相邻的 32B 行通常映射到相邻的 bank（按 bank 总数循环）。
+- 因此，**DataBlock 之间的地址差（由 `blk_stride` 决定）直接决定了它们是否落入同一 bank group**。
+
+以 220x 为例：
+- `blk_stride = 16`：相邻 DataBlock 地址差 = 16 × 32B = 512B。bank 编号差 = 16（假设按 32B 行轮询），16 % 16 = 0，即**所有 DataBlock 落入同一 bank group**，8 拍完成一个 Repeat。
+- `blk_stride = 8`：bank 编号差 = 8，block0 和 block2 的 bank 差 = 16，16 % 16 = 0，落入同一 group，4 拍完成一个 Repeat。
+
+#### 2.2.4 冲突判断方法
+
+**步骤 1：识别并发访问的数据源**
+
+一个 Vector 指令（如 `Add(dst, src0, src1)`）在同一 Repeat 内会同时读取 `src0`、`src1` 并写入 `dst`。这三个操作数的 DataBlock 是并发访问的候选冲突源。
+
+**步骤 2：分析地址间隔规律**
+
+- **多操作数之间**：若 `dst`、`src0`、`src1` 的 buffer 起始地址在 UB 内连续分配，且间隔恰好是 bank size 的整数倍，则它们的对应 DataBlock 会周期性地映射到同一 bank/bank group。
+- **单操作数内部**：若 `blk_stride` 使 DataBlock 之间的 bank 差等于 group 数（220x: 16，350: 8）或其倍数，则多个 DataBlock 会回卷到同一 bank group。
+
+**步骤 3：通过官方工具或实验确认**
+
+- **msProf 资源冲突占比分析**：官方提供的 msProf 工具可以采集资源冲突占比数据，直接定位 bank 冲突。具体使用方法参考《算子开发工具》文档。
+- **Profiling 验证**：如果 Vector 计算耗时远高于理论值，且 MTE2 不是瓶颈，则极可能存在 bank 冲突。
+- **实验验证**：对疑似冲突的代码添加 256B padding 或调整 `blk_stride` 后重新 profiling，观察周期数是否下降。
+
+#### 2.2.5 常见冲突场景与规避原理
+
+以下场景来自官方文档的典型示例。
+
+**场景 1：读写冲突 —— src 与 dst 落在同一 bank**
+
+```cpp
+// 假设 x 起始地址在 bank0，y 起始地址也在 bank0（地址差为 bank size 的整数倍）
+Add(dst, src, src2, ...);  // src 读 bank0，dst 写 bank0，读写冲突
+```
+
+**规避**：确保 src 和 dst 的起始地址不在同一 bank。对于 220x，通常给中间 buffer 增加 padding 使地址错开至少一个 bank。
+
+**场景 2：写写冲突 —— dst 的多个 DataBlock 落入同一 bank group**
+
+```cpp
+// 220x 上 blk_stride=16：8 个 DataBlock 全部落入同一 bank group，8 拍完成
+Adds(dst, src, scalar, MASK, 1, {1, 16, 1, 16});
+
+// 220x 上 blk_stride=8：block0 和 block2 落入同一 bank group，4 拍完成
+Adds(dst, src, scalar, MASK, 1, {1, 8, 1, 8});
+```
+
+**规避**：改为 `blk_stride = 1`（连续读），通过 `dst_gap/src_gap` 控制跨 Repeat 的地址增量。
+
+**场景 3：读读冲突 —— 双 src 落入同一 bank group（220x），或同一 bank（350）**
+
+```cpp
+// 220x：x 和 y 起始地址差为 bank size 整数倍，DataBlock 0 同时读同一 bank group
+Add(zLocal, xLocal, yLocal, ...);
+```
+
+**规避**：在 `xBuf` 后增加 256B padding，打破地址周期性，使 `x` 和 `y` 的 DataBlock 分散到不同 bank group。对于 350，还需确保两个 src 不在同一 bank。
+
+**场景 4：连续分配多个 buffer，地址周期性重叠**
+
+```cpp
+// 220x 原始实现：x/y/z 连续分配，起始地址差为 0x4000（16KB）
+// x: bank0, y: bank0（地址差 16KB = 4×bank size），z: bank0
+// 一个 Repeat 内 x 和 y 同时读同一 group，x/y 和 z 同时读写同一 bank
+pipe.InitBuffer(inQueueX, 1, 4096 * sizeof(float));
+pipe.InitBuffer(inQueueY, 1, 4096 * sizeof(float));
+pipe.InitBuffer(outQueueZ, 1, 4096 * sizeof(float));
+```
+
+**规避（220x 官方推荐）**：
+```cpp
+// x 多申请 256B，避免一个 Repeat 内 x 和 y 同时读同一 bank group
+// y 多申请空间，确保 z 不会和 x/y 落入同一个 bank
+pipe.InitBuffer(inQueueX, 1, 4096 * sizeof(float) + 256);
+pipe.InitBuffer(inQueueY, 1, 64 * 1024 - (4096 * sizeof(float) + 256));
+pipe.InitBuffer(outQueueZ, 1, 4096 * sizeof(float));
+```
+
+### 2.3 数据流 — 常驻复用
+
+常驻复用：小尺寸参数（weight、gamma、scale）在 Process 入口通过 MTE2 一次搬入 UB/TBuf，后续整个生命周期内循环只读，全程不再访问 GM。
+
+### 2.4 数据流 — 分时复用（Zone Reuse）
+
+分时复用：单块 TBuf 按阶段划分为多个 zone。前一阶段（如 RmsNorm）使用 zone0/1/2 计算完成后数据失效，后一阶段（如 RoPE）直接复用同一物理空间的 zone0/1/2，无需额外分配 buffer。UB 临时 buffer 总量从 `sum(stage_buffers)` 降为 `max(concurrent_buffers)`。
+
+## 3. 关键参数配置
+
+```cpp
+// 常驻复用参数
+struct ResidentBufferConfig {
+    uint32_t paramSize;       // 常驻参数元素数（如 hidden_size）
+    uint32_t computePrecision; // 计算精度：FP16=2, FP32=4 bytes
+};
+
+// 分时复用参数
+struct ZoneReuseConfig {
+    uint32_t zone0Size;       // 阶段 1 临时 buffer 大小
+    uint32_t zone1Size;       // 阶段 2 临时 buffer 大小
+    uint32_t zone2Size;       // 阶段 3 临时 buffer 大小
+};
+
+// Bank 冲突规避参数
+struct BankConflictConfig {
+    uint32_t dataSize;        // 数据大小（字节）
+    uint32_t paddingSize;     // Padding 大小（通常为 256B）
+};
+```
+
+### 3.1 参数选取原则
+
+| 参数 | 典型值 | 说明 |
+|------|--------|------|
+| `paramSize` | 64 / 128 / 256 / 512 | head_dim 或 hidden_size |
+| `paddingSize` | 256 | 使相邻 buffer 错开 bank group |
+| `zoneOffset` | `rows * headSize` | 按数据量对齐划分 zone |
+
+## 4. 核心计算循环
+
+### 4.1 naive 版本（优化前）
+
+**参数每 tile 重复搬运：**
+```cpp
+for (int64_t bIdx = 0; bIdx < baseB; ++bIdx) {
+    for (int64_t sIdx = 0; sIdx < baseS; ++sIdx) {
+        // 每次 loop 都从 GM 搬运 weight
+        LocalTensor<half> weightLocal = inQueueW.AllocTensor<half>();
+        DataCopyPad(weightLocal, weightGm, copyParams);
+        Cast(weightFp32, weightLocal, RoundMode::CAST_NONE, alignBaseH);
+        Compute(xLocalFp32, weightFp32, ...);
+        inQueueW.FreeTensor(weightLocal);
+    }
+}
+```
+
+**分时复用反例 — 独立分配：**
+```cpp
+// 各阶段独立 buffer，总量 = sum
+pipe.InitBuffer(rmsBuf0, 1, zoneSize);
+pipe.InitBuffer(rmsBuf1, 1, zoneSize);
+pipe.InitBuffer(rmsBuf2, 1, zoneSize);
+pipe.InitBuffer(ropeCosBuf, 1, zoneSize);
+pipe.InitBuffer(ropeSinBuf, 1, zoneSize);
+// 总量 = 5 × zoneSize
+```
+
+**Bank 冲突反例 — 连续分配（220x）：**
+```cpp
+// 问题：x/y/z 连续分配，地址差为 dataSize。
+// 若 dataSize 是 bank size（4KB）整数倍，x/y/z 的对应 DataBlock 周期性地映射到
+// 同一 bank group。Add 指令同时读 x、读 y、写 z，产生严重的读写/读读冲突。
+pipe.InitBuffer(inQueueX, 1, 4096 * sizeof(float));   // addr = 0x0
+pipe.InitBuffer(inQueueY, 1, 4096 * sizeof(float));   // addr = 0x4000
+pipe.InitBuffer(outQueueZ, 1, 4096 * sizeof(float));  // addr = 0x8000
+
+// 问题：220x 上 blk_stride=16，8 个 DataBlock 全部落入同一 bank group（bank 差=16，
+// 16 % 16 = 0），8 拍完成一个 Repeat。
+Adds(dst, src, scalar, MASK, 1, {1, 16, 1, 16});  // 全冲突！
+
+// 问题：220x 上 blk_stride=8，block0 和 block2 落入同一 group（bank 差=16），4 拍。
+Adds(dst, src, scalar, MASK, 1, {1, 8, 1, 8});    // 部分冲突！
+```
+
+### 4.2 optimized 版本（优化后）
+
+**常驻复用 — Process 入口搬入，循环内只读：**
+```cpp
+__aicore__ inline void Process() {
+    // 阶段 0：一次搬入 + Cast，常驻 UB
+    LocalTensor<float> weightFp32 = this->inQueueW.AllocTensor<float>();
+    DataCopyPad(weightLocal, weightGm, copyParams, padParams);
+    Cast(weightFp32, weightLocal, RoundMode::CAST_NONE, alignBaseH);
+
+    // 阶段 1~N：循环内只读常驻 weightFp32
+    for (int64_t bIdx = 0; bIdx < baseB; ++bIdx) {
+        for (int64_t sIdx = 0; sIdx < baseS; ++sIdx) {
+            Compute(xLocalFp32, weightFp32, y0Fp32, y1Fp32, y2Fp32);
+        }
+    }
+    this->inQueueW.FreeTensor(weightFp32);
+}
+```
+
+**分时复用 — Zone 划分：**
+```cpp
+// 单块 TBuf 划分为多 zone
+int64_t xLocalFp32Offset = 0;
+int64_t xSquareLocalOffset = rows * headSize;
+int64_t xSumLocalOffset = rows * headSize * 2;
+
+LocalTensor<float> xLocalFp32 = wsLocal[xLocalFp32Offset];
+LocalTensor<float> xSquareLocal = wsLocal[xSquareLocalOffset];
+LocalTensor<float> xSumLocal = wsLocal[xSumLocalOffset];
+
+// 阶段 1：使用 zone0/1/2
+RmsNorm(xLocalFp32, xSquareLocal, xSumLocal, ...);
+
+// 阶段 2：复用 zone0/1/2 做 RoPE
+LocalTensor<float> ropeCosLocal = wsLocal[xLocalFp32Offset];
+LocalTensor<float> ropeSinLocal = wsLocal[xSquareLocalOffset];
+RoPE(ropeCosLocal, ropeSinLocal, ...);
+```
+
+**Bank 冲突规避 — Padding 错开（220x 官方推荐）：**
+```cpp
+// 原理：x 多申请 256B，使 x 和 y 的 DataBlock 错开 bank group；
+// y 再补齐到 64KB（16 个 bank）边界，确保 z 不与 x/y 同 bank。
+pipe.InitBuffer(inQueueX, 1, 4096 * sizeof(float) + 256);
+pipe.InitBuffer(inQueueY, 1, 64 * 1024 - (4096 * sizeof(float) + 256));
+pipe.InitBuffer(outQueueZ, 1, 4096 * sizeof(float));
+```
+
+**Bank 冲突规避 — 连续读跳写：**
+```cpp
+// 原理：blk_stride=1 使同一操作数内的 8 个 DataBlock 顺序映射到相邻 bank，
+// 避免落入同一 bank group。dst_gap/src_gap 控制跨 Repeat 的地址增量。
+// 220x 上 mask=128（8 DataBlock）时，连续读无自冲突；跳写使 dst 分散。
+UnaryRepeatParams params;
+params.dstBlkStride = 8;
+params.srcBlkStride = 1;
+Adds(dstLocal, srcLocal, 0, 128, 2, params);  // 连续读，跳写
+```
+
+## 5. 从 naive 到 ub_resident 的关键修改点
+
+| 修改项 | naive（优化前） | ub_resident（优化后） |
+|--------|---------------|---------------------|
+| 参数搬运 | 每 tile/loop 重复 MTE2 | Process 入口一次搬入，常驻 UB |
+| 临时 buffer 总量 | `sum(stage_buffers)`（独立分配） | `max(concurrent_buffers)`（分区复用） |
+| UB 地址分配 | 连续分配，无 padding | 256B padding 错开 bank group |
+| Vector stride | 跳读连续写（blk_stride=16） | 连续读跳写（blk_stride=1） |
+| 数据生命周期 | 每阶段独立 buffer | 串行阶段复用同一物理空间 |
+
+## 6. 注意事项 / 约束
+
+1. **常驻 buffer 压缩主数据 tile 空间**：常驻 buffer 会长期占用 UB，需确保剩余空间仍可容纳主数据 tile、双缓冲和临时计算空间。
+
+2. **TBuf/VECCALC 不受队列同步保护**：需要手动使用 PipeBarrier 或明确阶段边界保证一致性。
+
+3. **分时复用需严格串行边界**：各阶段必须具备严格的串行边界，错误判断生命周期会导致后续阶段覆盖仍在使用的数据。
+
+4. **Bank 冲突规避需区分芯片型号**：
+   - NPU 220x（A2/A3）：192KB = 48 bank × 4KB = 16 group × 3 bank，读写/写写/读读冲突条件见 2.2.2 节。
+   - Atlas 350：256KB = 16 bank × 16KB = 8 group × 2 bank，两次读操作同一 group 不同 bank 不冲突。
+   - 具体规格和推荐配置务必查阅对应版本的《Ascend C 算子开发最佳实践》。
+
+5. **Padding 增加 UB 占用**：256B padding 虽然小，但多个 buffer 累积后需计入总 UB 预算。
+
+6. **后续阶段重叠流水时需重算 zone**：若后续优化把串行阶段改造成重叠流水，原有 zone reuse 方案可能失效。
+
+## 7. 实施常见问题与解决方案
+
+| 问题 | 根因 | 解决方案 |
+|------|------|---------|
+| 常驻 buffer 后 UB 溢出 | 常驻 buffer + 主 tile + 双缓冲超预算 | 减小 tile_size 或常驻 buffer 大小；精确计算 UB 预算 |
+| 分时复用数据被覆盖 | 阶段边界判断错误 | 确保前一阶段完全结束后再覆盖；使用 PipeBarrier 明确边界 |
+| Vector 性能仍低 | bank 冲突未解决 | 使用 msProf 采集资源冲突占比确认；按 2.2.5 节场景逐一排查（读写/写写/读读冲突）；确认 padding 后各 buffer 的 DataBlock 不在同一 bank/bank group；检查 `blk_stride` 是否导致 8 个 DataBlock 回卷到同一 group |
+| 累加器精度不足 | FP16 累加溢出 | 常驻累加器使用 FP32 精度 |
+
+## 8. 选型决策与自检清单
+
+### 8.1 选型决策
+
+```
+if (算子包含小尺寸参数 weight/gamma/scale 且跨 loop 不变):
+    → 启用常驻复用：Process 入口搬入，循环内只读
+elif (算子包含多阶段串行计算，临时 buffer 生命周期不重叠):
+    → 启用分时复用：单块 TBuf 分区，阶段间覆盖
+elif (Profiling 显示 Vector 计算时间异常高):
+    → 启用 bank 冲突规避：padding 错开 或 连续读跳写
+else:
+    → 标准分配即可
+```
+
+### 8.2 自检清单
+
+- [ ] 常驻 buffer 大小 + 主 tile + 双缓冲 ≤ UB 容量
+- [ ] 分时复用各阶段有严格的串行边界（PipeBarrier）
+- [ ] Bank 冲突规避：相邻 buffer 间隔 ≥ 256B 或 不在同一 bank group
+- [ ] Vector API 的 blk_stride 避免导致多 DataBlock 落入同一 bank group
+- [ ] 累加器/递推状态使用 FP32 精度
+- [ ] 验证通过：与 naive 实现对比，结果一致