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

package/assets/ops-direct-invoke/skills/ascendc-performance-best-practices/references/broadcast/onedim_design.md

@@ -0,0 +1,114 @@
+# 实现④：OneDim 合轴塌一维快路径（标量广播）
+
+> 主文档：[broadcast_design.md](broadcast_design.md)　|　原语：[`code/broadcast_common.h`](code/broadcast_common.h)（`TryOneDim` / `ComputeOneDimTiling` / `OneDimCalcCore` / `OneDimLoadInput`）
+> 端到端样例：[Host](code/onedim_add_tiling.cpp) + [Kernel](code/onedim_add_kernel.cpp)（`z = x + y`，y 为标量）
+
+## 思路
+
+很多广播在**合轴**（把相邻、广播状态一致的轴乘到一起）后会塌成一维：此时每个输入要么是**满 shape 的连续大块**，要么是**纯标量**（一个值）。这类场景没必要套多维 NDDMA 参数装配、也不必调 UB `Broadcast` 指令——
+
+- **满 shape 输入**：一维连续，逐块 `DataCopyPad` 搬入即可；
+- **标量输入**：**首块用 `Duplicate` 把那一个值铺满 UB，后续块直接复用**，完全不走逐块 DMA。
+
+这是 `z = x + lr`、`z = x * scale`、`alpha·x + y` 这类「标量参与 elementwise」以及同 shape elementwise 的最快写法。固定成本也最低：tiling 退化成一维（只需 1D 总长 / 块大小 / 核数），切分让 kernel 运行期自己推。
+
+> 对标 atvoss `SCH_MODE_ONE_DIM_ADVANCE`（schMode 202）：tiling 极简（`dimLen/tileNum/blockNum/scalarFlag`）、kernel 运行期派生 `ubOuter/ubTail/blockFormer/blockTail`，省去结构体拷贝与多维下标还原。atvoss 在入出参 >4 或 DAG 带 Var 标量属性时退回普通 `SCH_MODE_ONE_DIM`（201，Host 预切分），本指导只吸收 Advance 形态——纯 AscendC 下没有 Var 概念，运行期标量属性由算子自行经 tiling 传入即可。
+
+## 适用
+
+合轴后能塌成一维，即**每个输入都满足「纯标量」或「满 shape 连续」之一**：
+
+- ✅ `z = x + scalar`（标量广播）；
+- ✅ `z = x op y`，x、y 同 shape（无广播，纯 elementwise）；
+- ✅ 多输入混合：部分满 shape、部分标量。
+- ❌ `[M,1] → [M,N]`、`[1,N] → [M,N]` 这类**部分轴广播**：合轴后仍是多维，**不属本路径**，回到 ①②③ 选型。
+
+判定见 `TryOneDim`：逐输入算元素总数，`==1` 记为标量（置 `scalarFlag` 对应位），`==dimLen` 是满 shape，二者皆非则不能塌一维。
+
+## Host：选型 + 极简 Tiling
+
+OneDim 是在三类选型**之前**的前置分流：先 `TryOneDim`，命中就走 OneDim，否则才进 §1.3 的 `PickBroadcastMode`。
+
+```cpp
+// 节选，完整见 code/onedim_add_tiling.cpp。在通用切分 / PickBroadcastMode 之前先试 OneDim
+int64_t dimLen; int32_t scalarFlag;
+if (TryOneDim(td, dimLen, scalarFlag)) {                 // 合轴塌一维（每输入满 or 标量）
+    OneDimTilingData ot;
+    ComputeOneDimTiling(ot, dimLen, scalarFlag, dtSize, coreNum, ubSize, /*aliveBuf=*/IN_NUM + 1);
+    // 写 ot 进 tilingData，tilingKey 标记走 OneDim 分支
+    return;
+}
+// 否则：ComputeTiling(...) + 逐输入 PickBroadcastMode(...)（见 broadcast_design.md §1）
+```
+
+`ComputeOneDimTiling`（`code/broadcast_common.h`）只算三个量，**不预切分**：
+
+```cpp
+tileNum  = AlignDown(ubSize / (aliveBuf * dtSize * DB_LOOP), alignEle);  // 单块元素数
+ubOuter  = ceil(dimLen / tileNum);                                       // 共几块
+blockNum = min(coreNum, ubOuter);                                        // 块数不足核数则减核（小 shape 自适应）
+// dimLen / tileNum / blockNum / scalarFlag 即全部 tiling；ubTail/blockFormer/blockTail 交给 kernel
+```
+
+> 极简 TilingData 是 Advance 形态的精髓：搬运/切分细节全在 kernel 运行期由这几个标量推出，tiling 体积小、下发开销低。
+
+## Kernel 写法
+
+每核循环参数由 `OneDimCalcCore` 运行期推导；标量输入用单块 `TBuf`（首块 `Duplicate` 一次、后续复用），满 shape 输入用 `TQue` 双缓冲。
+
+```cpp
+// 节选，完整见 code/onedim_add_kernel.cpp。z = x + y，x 满 shape、y 可能是标量（scalarFlag bit1）
+__aicore__ inline void Process() {
+    bool xScalar = ot_.scalarFlag & (1 << 0);
+    bool yScalar = ot_.scalarFlag & (1 << 1);
+    OneDimCoreParam cp = OneDimCalcCore(ot_.dimLen, ot_.tileNum, ot_.blockNum);  // baseOffset/loops/tailLen
+    int64_t off = cp.baseOffset;
+    for (int64_t loop = 0; loop < cp.loops; loop++) {
+        int64_t len = (loop == cp.loops - 1) ? cp.tailLen : ot_.tileNum;         // 最后一块可非对齐
+
+        LocalTensor<T> xl = xScalar ? xBuf_.Get<T>() : qx_.AllocTensor<T>();
+        OneDimLoadInput(xl, xGm_, off, len, xScalar, /*firstTile=*/loop == 0);   // 标量仅首块 Duplicate
+        if (!xScalar) qx_.EnQue(xl);
+        LocalTensor<T> yl = yScalar ? yBuf_.Get<T>() : qy_.AllocTensor<T>();
+        OneDimLoadInput(yl, yGm_, off, len, yScalar, loop == 0);
+        if (!yScalar) qy_.EnQue(yl);
+
+        LocalTensor<T> xv = xScalar ? xl : qx_.DeQue<T>();
+        LocalTensor<T> yv = yScalar ? yl : qy_.DeQue<T>();
+        LocalTensor<T> zv = qz_.AllocTensor<T>();
+        AscendC::Add(zv, xv, yv, len);
+        qz_.EnQue(zv);
+        if (!xScalar) qx_.FreeTensor(xv);
+        if (!yScalar) qy_.FreeTensor(yv);
+
+        LocalTensor<T> zo = qz_.DeQue<T>();
+        AscendC::DataCopyExtParams ext{1, (uint32_t)(len * sizeof(T)), 0, 0, 0};
+        AscendC::DataCopyPad(zGm_[off], zo, ext);                                // 一维连续写回
+        qz_.FreeTensor(zo);
+        off += ot_.tileNum;
+    }
+}
+```
+
+`OneDimLoadInput` 内部（`code/broadcast_common.h`）：
+
+```cpp
+if (isScalar) {
+    if (firstTile) AscendC::Duplicate(dst, gm.GetValue(0), len);   // 标量值铺满 UB；之后块复用同一块
+} else {
+    DataCopyPadCompact(gm[offset], dst, len);                      // 满输入：一维连续搬，非对齐 Pad 兜底
+}
+```
+
+## 注意
+
+- **标量不进双缓冲队列**：标量首块铺满后整轮复用，应放单块 `TBuf`；若误塞进 depth=2 的 `TQue` 并每轮 Alloc，会丢掉"只填一次"的收益，还要处理 ping/pong 两块各填一次。
+- **标量首块的 `len`**：首块用 `Duplicate(dst, val, len)` 铺当前块长度即可；后续块直接复用 `dst`，无需重铺（各块长度只有最后一块可能更短，复用块多出的尾部不参与计算/写回，无害）。
+- **尾块非对齐**：一维总长 `dimLen` 常非 `alignEle` 倍数，最后一块 `tailLen` 非对齐——`DataCopyPad` 自动兜底，计算指令 `count` 传真实 `len` 即可（同 [advanced_tiling.md](advanced_tiling.md) §3）。
+- **小 shape 减核**：`ubOuter < coreNum` 时 `ComputeOneDimTiling` 把 `blockNum` 降到 `ubOuter`，避免空核；`OneDimCalcCore` 的 `blockFormer/blockTail` 据此自洽。
+- **UB 预算**：标量块按 1 份（非双缓冲）、满输入/输出按双缓冲计入 `aliveBuf`；示例取 `IN_NUM+1` 为保守上界。
+- **double**：`GetValue`/`Duplicate` 标量对 double 需按位转 int64 处理（同 atvoss 对 `double` 的 reinterpret），其余 dtype 直接用。
+
+## 与 ①②③ 的关系
+
+OneDim 是**合轴塌一维时的前置快路径**，优先级高于三类选型——命中即用，命中不了才进 `PickBroadcastMode`。三类处理的是"合轴后仍多维"的部分轴广播（`[M,1]`/`[1,N]` 等）。决策树见 [broadcast_design.md](broadcast_design.md) §3。

package/assets/ops-direct-invoke/skills/ascendc-performance-best-practices/references/broadcast/ub_broadcast_design.md

@@ -0,0 +1,67 @@
+# 实现③：UB 内 Broadcast 指令
+
+> 主文档：[broadcast_design.md](broadcast_design.md)　|　参考代码：[`code/broadcast_common.h`](code/broadcast_common.h)（`UbBroadcast` / `FillUbShape`）
+
+## 思路
+
+先把紧凑源 `DataCopyPad` 搬进 UB，再用 `AscendC::Broadcast` 矢量指令在 UB 内展开到目标 shape。占 Vector 单元，但对**尾轴对齐 + 小字节类型**吞吐最高。还是唯一能广播**中间计算结果**的实现（① ② 只能广播 GM 输入）。
+
+## 适用
+
+**前提：tile 内要有 UB Broadcast 能展开的维（`dShape>sShape`）。** 两种会出 nan 的反例（cann-bench Maximum case 18 实测）：
+1. 广播轴**严格在外层**（`brcInTile=false`）：UB 展不了外层轴 → 必须走 ②（offset 寻址）。
+2. 广播轴是切分轴**但 `ubFormer==1`**：tile 内仅 1 行，`dShape==sShape` 空广播 → 必须走 ① NDDMA。
+
+即需 `inTileExpandable`（切分轴以下某轴广播，或切分轴广播且 `ubFormer>1`）。满足后任一成立即用 ③：
+- 尾轴对齐且 dtype ∈ {INT8, UINT8, FP16, BF16, INT16, UINT16}（B8/B16）；
+- 或 BigNLast：非尾轴广播且尾轴字节 ≥ `nddma dcache/2`（源码注释 ~4096B）；
+- 或广播的是上游计算结果而非 GM 输入。
+
+## Kernel 写法
+
+```cpp
+// 节选，完整见 code/broadcast_add_kernel.cpp
+LocalTensor<T> src = bufSrc_.Get<T>();
+// 源长度按"源 shape"算，不能用展开后的输出 tile 长度（否则 [M,1] 尾轴广播会多搬 N 倍）
+int64_t srcLen = UbSrcLen(inputStrides[i], inputDims[i], ubSplitAxis, shapeLen, rows);
+DataCopyPadCompact(yGm[off], src, srcLen);                                     // ① 紧凑搬入
+UbBroadcast(dst, src, outputDims, inputDims[i], ubSplitAxis, shapeLen, rows);  // ② UB 内展开
+```
+
+`UbBroadcast` 内部（`code/broadcast_common.h`）：
+
+```cpp
+uint32_t dShape[8], sShape[8];
+FillUbShape(dShape, sShape, outputDims, inDims, ubSplitAxis, shapeLen, curRows); // 首轴随主/尾块变
+int64_t rank = shapeLen - ubSplitAxis;
+// ★退化守卫：所有 dShape==sShape（无可展开维，如尾块 rows==1）→ 直接 UB→UB 拷贝，否则空广播出 nan
+bool anyExpand = false; int64_t cnt = 1;
+for (int k = 0; k < rank; k++) { if (dShape[k] > sShape[k]) anyExpand = true; cnt *= dShape[k]; }
+if (!anyExpand) {                                       // 无可展开维 → dtype 无关 UB→UB 拷贝
+    int32_t alignEle = 32 / sizeof(T);
+    int32_t cntAlign = ((int32_t)cnt + alignEle - 1) / alignEle * alignEle;  // 向上对齐，buffer=elemNum 不越界
+    AscendC::DataCopy(dst, src, cntAlign); return;
+}
+AscendC::BroadcastTiling bt;
+AscendC::GetBroadcastTilingInfo<T>(rank, dShape, sShape, false, bt);
+AscendC::Broadcast<T>(dst, src, dShape, sShape, &bt);   // ← UB 矢量广播指令
+```
+
+## rank（R）
+
+- `R = shapeLen - ubSplitAxis`（UB tile 内参与广播的维数）。
+- 静态已知且 ≤4 → 可用编译期 `Broadcast<T, R>` / `GetBroadcastTilingInfo<T, R>`，性能更好；
+- 动态或超阈值 → 运行期 `Broadcast<T>`（如样例，R 作为运行期实参）。
+- 尾块需把 `dstShape[0]`/`srcShape[0]` 改成 `ubTail` / 源尾块长度（`FillUbShape` 已按 `curRows` 处理）。
+
+## 中间结果广播
+
+若广播的是上游计算节点的输出（不是 GM 输入），**跳过 `DataCopyPadCompact`**，直接对上游 UB tensor 调 `UbBroadcast`。这是 ③ 相对 ① ② 的独占能力。
+
+## 注意
+
+- **退化守卫**：`UbBroadcast` 内先检查是否存在 `dShape>sShape` 的维；若无（如尾块 `rows==1` 或选型漏判），直接 `DataCopy(dst,src,对齐cnt)` 做 dtype 无关的 UB→UB 拷贝（不用 `Adds`，避免 int64 等不支持），而非调 `Broadcast`，防空广播出 nan。这是兜底，正确选型应优先在 host 侧避免（见上"前提"）。
+- UB 预算要**多留一块紧凑源 buffer**（样例的 `bufSrc_`）：③ 是 src + dst 两块，① 只需一块。tiling 的 `aliveBuf` 要含这块。
+- **每个走 ③ 的输入要各自一块 `bufSrc`**：若多个输入都可能 ③（如 binary 的 x1/x2 都广播），共用一块 `TBuf` 会 RAW 冒险（第二个输入的 `DataCopyPadCompact` 覆盖第一个的紧凑源）。binary 算子应配 `bufSrc1_/bufSrc2_`，`aliveBuf` 相应增大（cann-bench Maximum 落地经验）。
+- `GetBroadcastTilingInfo` 的 rank 必须与 `Broadcast` 调用一致。
+- src/dst shape 的首轴是 UB 切分轴方向的行数，后续轴是尾轴及以下；广播轴在 src 上填 1。

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

@@ -0,0 +1,126 @@
+# 小 Shape 核数裁剪（Core Shrink）优化设计
+
+## 1. 优化目标
+
+Ascend C 算子按 `core_num` 切分并行。对小 Shape 算子，**全量占用所有 AI Core 反而更慢**：核启动 / 调度 / 同步开销随核数近似线性增长，而总计算量不变，导致每核分摊的计算量过小，启动开销占比超过计算收益。
+
+本优化通过**仅占用部分核，并限制每个核的最小计算行数（min rows per core）**，在核启动开销与计算开销之间取得最优平衡，缩短整体 `aiv_time`。
+
+| 指标 | naive（全核） | optimized（裁剪核数） | 收益 |
+|------|-------------|---------------------|------|
+| 使用核数 | `满核` | `min(满核, ceil(A1 / min_rows_per_core))` | 去掉无效核的启动/同步开销 |
+| 每核承担行数 | 可能 < 1 行（严重碎片化） | 下界由 `min_rows_per_core` 保证 | 计算充分掩盖启动，负载更均衡 |
+| 核间同步次数 | 随核数增长 | 随核数减少 | 同步开销下降 |
+| 整体 aiv_time | 高（启动为主导） | 更低 | 小 Shape 下显著 |
+
+> **核心判断**：`A1 / core_num`（每核行数）过小时，启动开销占主导 → 应裁剪核数；`A1 / core_num` 足够大时，计算占主导 → 保持全核。裁剪核数**不等于**多用核数，两者方向相反。
+
+---
+
+## 2. 适用场景
+
+- **小 Shape 算子**：`A1`（并行切分维度的总行数 / 总任务量）相对满核很小，如 `A1 < 满核 × min_rows_per_core`。
+- **Vec 类 / tunable 归约类算子**（Elementwise、Broadcast、Reduction、Norm 等）：切分维度为行/块级任务，核数可自由收缩。
+- **核启动 + 同步开销不可忽略**：涉及 `SyncAll`、跨核归并、多 pass 的算子（如 LayerNorm/RMSNorm 多核归约），核数越多同步越贵。
+
+> 反面：Cube 类（MatMul 等）核数由 L1 切分决定，一般不靠"裁核"来优化；多核同步算子（sort 等）裁核需与跨核归并轮数（`ceil(log(core_num))`）联合评估。
+
+---
+
+## 3. 关键参数配置
+
+```cpp
+struct CoreShrinkConfig {
+    int64_t minRowsPerCore;   // 每个核的最小计算行数（下界），经验值见 §3.1
+    int64_t fullCoreNum;      // 芯片可用满核数
+    int64_t totalRows;        // 并行切分维度总任务量（如 A1）
+};
+// 裁剪后的核数
+//   usedCoreNum = min(fullCoreNum, ceil(totalRows / minRowsPerCore))
+//   usedCoreNum = max(usedCoreNum, 1)
+```
+
+### 3.1 `min_rows_per_core` 参数选取原则
+
+| 参数 | 典型值 | 说明 |
+|------|--------|------|
+| `minRowsPerCore` | 与单核 tile 行数同量级，常取 8 ~ 64 行 | 保证每核至少有一轮可被计算掩盖的稳定工作量 |
+| 收敛判据 | 逐 shape 扫描 `usedCoreNum` 的不同取值，取 `aiv_time` 最低者 | 边界处性能对核数敏感，实测校准 |
+
+**经验规律**：`usedCoreNum` 应尽量取 `totalRows` 的**整数因子**（或接近满核的、能整除的核数），避免撕裂产生额外尾块负载不均。当 `totalRows` 远小于满核时，可先取 `usedCoreNum = totalRows`（每个核恰好 1 行）作为**搜索起点**——这等价于公式中 `minRowsPerCore=1` 的特例（`min(fullCoreNum, ceil(totalRows/1))`，当 `totalRows < fullCoreNum` 时）。
+
+> 与 3.1 典型取值（`minRowsPerCore = 8 ~ 64`）**并不矛盾**：二者只是同一个公式下 `minRowsPerCore` 的不同取值，典型值针对"单行计算过轻，需要多行聚合才能掩盖每核启动开销"的场景；当**单行计算已足以掩盖启动开销**时，`minRowsPerCore` 可下探到 `1`（即 `usedCoreNum = totalRows`）。应逐 shape 扫描 `minRowsPerCore ∈ [1, 64]`（等价于扫描 `usedCoreNum` 各候选），取 `aiv_time` 最低者，而非无条件套用某一端。
+
+---
+
+## 4. 多核切分改造（Tiling 侧）
+
+改造集中在 **Host 侧 TilingData 计算**，影响 `core_num` 与每核行数推导，kernel 侧通常仅在读 `core_num` 字段处无需改动（或仅需按 `core_num` 循环）：
+
+```cpp
+// naive：默认用满核
+int64_t coreNum = fullCoreNum;
+
+// optimized：限制每核最小行数，裁剪核数
+int64_t coreNum = std::min(
+    fullCoreNum,
+    std::max<int64_t>(1, (totalRows + minRowsPerCore - 1) / minRowsPerCore));
+
+// 每核行数（下界有保证）
+int64_t rowsPerCore = (totalRows + coreNum - 1) / coreNum;
+```
+
+> 使用 `GetBlockNum()` / `GetBlockIdx()` 分发的算子，kernel 侧会按 `coreNum` 下限循环，多余核直接返回（`if (blockIdx >= coreNum) return;`），无需额外改动。
+
+---
+
+## 5. 从 naive 到 Core Shrink 的关键修改点
+
+| 修改项 | naive（优化前） | Core Shrink（优化后） |
+|--------|---------------|----------------------|
+| `core_num` | `满核` | `min(满核, ceil(totalRows / minRowsPerCore))` |
+| 每核行数 | 可能过小（< 1 行碎片化） | 下界由 `minRowsPerCore` 保证 |
+| 核启动/同步开销 | 随核数增长 | 随核数减少 |
+| 负载均衡 | 小 Shape 下不均 | 取整数因子核数更均衡 |
+| 适用算子 | 全部 | 小 Shape 的 Vec/归约类算子 |
+
+---
+
+## 6. 注意事项 / 约束
+
+1. **仅对小 Shape 生效**：`totalRows / fullCoreNum` 足够大（每核任务量充足）时，裁核反而降低并行度，必须保持全核。通过 `minRowsPerCore` 阈值自动切换，用 `if constexpr` / 编译期分支避免运行时开销。
+2. **与"多核同步算子"联合评估**：若算子含跨核归并（sort、部分 Norm），裁核会改变归并轮数 `ceil(log(core_num))`，需重新建模，不能只看单核核数。
+3. **避免运行时分支死代码**：若用普通 `if` 在 hot loop 里按核数切负载，编译器会保留未走分支的代码，增大 icache，削弱收益。优先用编译期模板参数（`if constexpr`）或把核数选择收敛到 Tiling 侧。
+4. **与 Zone Reuse / UB 常驻叠加时先验证**：裁核改变每核行数，可能影响 UB 常驻 buffer 的复用收益，需组合验证。
+5. **实测校准**：`minRowsPerCore` 的最优值与芯片（核数、启动延迟）和算子流水深度相关，用 profiling 逐 shape 扫描 `core_num` 取值确认。
+
+---
+
+## 7. 选型决策与自检清单
+
+### 7.1 选型决策
+
+```
+if (算子为 Vec/归约类 且 totalRows 相对满核很小):   // 小 Shape
+    → 裁剪核数：coreNum = min(满核, ceil(totalRows / minRowsPerCore))
+    → minRowsPerCore 取 8~64，逐 shape 扫描校准
+elif (算子含跨核归并):
+    → 裁核后重算归并轮数 ceil(log(coreNum))，联合调优
+else:   // 每核任务量充足
+    → 保持全核
+```
+
+### 7.2 自检清单
+
+- [ ] 小 Shape 场景下 `core_num` 已按 `minRowsPerCore` 裁剪，而非无条件用满核
+- [ ] `rowsPerCore = ceil(totalRows / coreNum)` 满足每核最小行数下界
+- [ ] 核数选择收敛到 Tiling 侧 / 编译期分支，hot loop 无运行时 `if` 死代码
+- [ ] 含跨核归并的算子已重算归并轮数
+- [ ] 与 Zone Reuse / UB 常驻叠加时已组合验证，未产生回归
+- [ ] 验证通过：与 naive 全核对比，小 Shape 下 `aiv_time` 下降，且结果一致
+
+---
+
+## 8. 实测示例（x_l2norm_gated）
+
+`x_l2norm_gated`（Norm/归约类，Vec）在小 Shape 下实测：全核时核启动 + 同步开销大于单核计算量，`aiv_time` 反而升高；裁剪 `core_num` 并设置每核最小行数后，`aiv_time` 显著下降。该算子同时验证了：裁核收益与真实模型 icache、Zone Reuse 等优化必须分开验证，避免叠加回归。

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

@@ -0,0 +1,351 @@
+# DataCopy Optimization 优化设计
+
+## 1. 优化目标
+
+数据搬运（DataCopy）是 Ascend C 算子中最基础也最频繁的操作。Naive 实现通常采用简单的逐块搬运，未充分利用硬件 DMA 引擎的带宽潜力，导致：
+
+- **非对齐访问惩罚**：数据未按设备最优粒度对齐时，DMA 效率大幅下降。以 Ascend 910B 实测为例，32B 对齐的带宽约为 512B 对齐的 70%，不同设备的最优对齐值需实测确认。
+- **小批量多次搬运**：循环内每次迭代独立 DataCopy，DMA 启动开销累积。
+- **格式转换额外开销**：ND→NZ 格式转换需要独立的 TransData 算子，增加一次 L1 读写往返。
+- **非连续内存访问低效**：Scatter/Gather 场景下逐元素访问无法利用 SIMD 并行性。
+- **内存访问模式未优化**：跨步访问（strided access）导致大量小传输（< 256B），DMA 设置成本占主导。
+
+本优化通过 DataCopyPad 自动对齐、ND2NZ 融合格式转换、Scatter/Gather 向量化、批量 DataCopy 合并、按设备最优粒度的 GM 对齐等手段，将数据搬运效率最大化。
+
+| 指标 | naive | optimized | 收益 |
+|------|-------|-----------|------|
+| 对齐访问带宽 | 未按最优粒度对齐: ~70% | 按设备最优粒度对齐 | 带宽提升最高 30%（Ascend 910B 实测） |
+| DMA 启动次数 | loopCount 次 | 1 次（批量合并） | 显著降低指令发射开销 |
+| ND→NZ 转换 | 独立 TransData 算子 | 搬运时融合完成 | 省去一次 L1 读写往返 |
+| Scatter/Gather | 逐元素 GetValue/SetValue | 向量化 Gather/Scatter 指令 | 性能提升 5-20 倍 |
+| 非连续列提取 | 搬运全部数据后裁剪 | blockLen+srcStride 一次提取 | 减少无效数据搬运 |
+
+> 适用算子族：`conversion` 族所有涉及数据搬运、格式转换、内存布局重排的变体，如 `transpose`、`concat`、`split`、`gather`、`scatter`、`nd2nz` 等。
+
+## 2. 架构概览
+
+### 2.1 存储层级与数据流
+
+DataCopy 优化覆盖数据从 GM 到 UB/L1 的全链路：通过 DataCopyPad 实现非对齐数据自动填充对齐；通过 Nd2NzParams 在搬运时融合 ND→NZ 格式转换；通过 DataCopyExtParams 的 blockLen+srcStride 实现非连续列一次提取；通过批量合并减少 DMA 启动次数；通过 Gather/Scatter 偏移表实现向量化离散访问；通过按设备最优粒度的 GM 对齐（如 Ascend 910B 为 512B）最大化带宽利用率。
+
+### 2.2 优化策略矩阵
+
+| 场景 | 优化策略 | 核心 API / 参数 |
+|------|---------|----------------|
+| 非对齐数据搬运 | DataCopyPad 自动填充 | `DataCopyPadExtParams{isPad, leftPadding, rightPadding, paddingValue}` |
+| ND→NZ 格式转换 | 搬运时融合 | `Nd2NzParams{nValue, dValue, srcDValue, dstNzC0Stride, dstNzNStride}` |
+| 非连续列提取 | blockLen + srcStride | `DataCopyExtParams{blockCount, blockLen, srcStride, dstStride}` |
+| 批量输出合并 | 循环内累积，循环外统一写回 | 累积到 UB，循环结束后一次性 DataCopy |
+| 向量化 Gather | 预计算偏移表 + Gather 指令 | `Gather(dst, src, offsetTable, 0, count)` |
+| 向量化 Scatter | 索引计算 + DataCopyPad | `inputStride0_ / inputStride1_` 非连续寻址 |
+| GM 带宽最大化 | 按设备最优粒度对齐（如 512B） | `AlignUp(offset, 512)` |
+
+### 2.3 DMA 效率阈值
+
+以下阈值基于 Ascend 910B 实测经验，不同设备的 DMA 控制器、总线宽度和缓存行大小不同，具体数值需参考对应硬件手册或实测确认。
+
+| 传输大小 | 效率 | 说明 |
+|---------|------|------|
+| < 32 bytes | 极低 | 对齐开销占主导 |
+| 32-256 bytes | 差 | DMA 设置成本显著 |
+| 256-4096 bytes | 中等 | 大多数场景可接受 |
+| > 4096 bytes | 好 | 总线带宽充分利用 |
+| > 65536 bytes | 极佳 | 接近峰值吞吐 |
+
+## 3. 关键参数配置
+
+```cpp
+// DataCopyExtParams 结构（多维批量传输）
+struct DataCopyExtParams {
+    uint16_t blockCount;   // 块数量
+    uint32_t blockLen;     // 每块字节数
+    uint32_t srcStride;    // 源地址块间步长（字节）
+    uint32_t dstStride;    // 目的地址块间步长（字节）
+    uint32_t reserved;     // 保留
+};
+
+// DataCopyPadExtParams 结构（自动填充）
+template <typename T>
+struct DataCopyPadExtParams {
+    bool isPad;            // 是否启用填充
+    uint8_t leftPadding;   // 左侧填充字节数
+    uint8_t rightPadding;  // 右侧填充字节数（最大 255）
+    T paddingValue;        // 填充值
+};
+
+// Nd2NzParams 结构（ND→NZ 格式转换）
+struct Nd2NzParams {
+    uint32_t nValue;       // N 维大小
+    uint32_t dValue;       // D 维大小
+    uint32_t srcDValue;    // 源 D 维步长
+    uint32_t dstNzC0Stride; // 目的 NZ C0 维步长（需对齐：fp16 为 16，fp8 为 32）
+    uint32_t dstNzNStride; // 目的 NZ N 维步长
+};
+```
+
+### 3.1 对齐参数计算
+
+| 数据类型 | 32B 对齐元素数 | 512B 对齐元素数 | 说明 |
+|---------|--------------|----------------|------|
+| FP32 | 8 | 128 | 地址/长度需为 8 的倍数 |
+| FP16/BF16 | 16 | 256 | 地址/长度需为 16 的倍数 |
+| INT8 | 32 | 512 | 地址/长度需为 32 的倍数 |
+
+```cpp
+// 32B 对齐
+uint32_t align32 = (size + 31) / 32 * 32;  // 或 CeilAlign(size, 32)
+// 按设备最优粒度对齐（如 Ascend 910B 为 512B）
+uint32_t align512 = (offset + 511) / 512 * 512;
+```
+
+### 3.2 Padding 限制
+
+- `rightPadding` 为 `uint8_t`，最大补零 255 字节
+- `blockLen` 单位为字节，需注意数据类型大小转换
+- 补零后的数据参与后续计算，需确保补零不影响算法正确性（如 ReduceSum 场景补零安全，但 ReduceMax 可能受影响）
+
+## 4. 核心计算循环
+
+### 4.1 naive 版本（优化前）
+
+```cpp
+// 阶段 1：简单 DataCopy，无对齐处理
+AscendC::DataCopy(xLocal, xGm[offset], this->tileSize);
+
+// 阶段 2：ND→NZ 需要独立 TransData 算子
+AscendC::DataCopy(l1Tensor, gmTensor, size);
+TransData(l1Tensor, nzTensor, ...);  // 额外算子
+
+// 阶段 3：循环内每次独立 DataCopy 写回
+for (int i = 0; i < loopCount; i++) {
+    Compute();
+    DataCopy(gm[offset], ub, size);  // 每次 16 个元素
+}
+
+// 阶段 4：逐元素 Scatter 写入
+for (int64_t i = 0; i < loadCount; i++) {
+    IndexT idx0 = indLocal.GetValue(i * INDICES_LAST_DIM);
+    IndexT idx1 = indLocal.GetValue(i * INDICES_LAST_DIM + 1);
+    int64_t gmOffset = idx0 * inputStride0_ + idx1 * inputStride1_;
+    // 逐行搬出，每次只搬 1 行
+    DataCopy(inputGm_[gmOffset], updLocal[i * updateRowElements_], updateDimSize_);
+}
+
+// 阶段 5：逐元素 Gather 读取
+for (uint32_t j = 0; j < idxGatherDim; j++) {
+    int32_t gatherIdx = idxLocal.GetValue(idxRowOffset + j);
+    float value = xLocal.GetValue(xRowOffset + gatherIdx);
+    yLocal.SetValue(yRowOffset + j, value);
+}
+
+// 阶段 6：非连续列提取——搬运全部数据后裁剪
+DataCopy(fullLocal, gmSrc, fullSize);  // 搬运全部数据
+for (int i = 0; i < rows; i++) {
+    ExtractColumn(local[i], fullLocal[i], colStart, colLen);  // UB 上裁剪
+}
+```
+
+### 4.2 optimized 版本（优化后）
+
+```cpp
+// === Variant A: DataCopyPad 自动对齐填充 ===
+uint32_t attenMaskSizeAlign = Align(info.s2dealNum, 32U);
+DataCopyExtParams dataCopyParams;
+dataCopyParams.blockCount = s1EndIdx - s1StartIdx;
+dataCopyParams.blockLen = info.s2dealNum;
+dataCopyParams.srcStride = info.attenMaskStride - info.s2dealNum;
+dataCopyParams.dstStride = 0;
+DataCopyPadExtParams<bool> padParams{true, 0,
+    static_cast<uint8_t>(attenMaskSizeAlign - info.s2dealNum), 0};
+DataCopyPad(attenMaskUb, srcGmAddr[maskOffset], dataCopyParams, padParams);
+
+// === Variant B: ND→NZ 融合格式转换 ===
+template<typename INPUT_T>
+__aicore__ inline void CopyToL1Nd2Nz(const LocalTensor<INPUT_T> &l1Tensor,
+    const GlobalTensor<INPUT_T> &gmTensor,
+    uint32_t nValue, uint32_t dValue, uint32_t srcDValue) {
+    Nd2NzParams gm2L1Nd2NzParams;
+    gm2L1Nd2NzParams.nValue = nValue;
+    gm2L1Nd2NzParams.dValue = dValue;
+    gm2L1Nd2NzParams.srcDValue = srcDValue;
+    gm2L1Nd2NzParams.dstNzC0Stride = (nValue + 15) >> 4 << 4;  // fp16 对齐 16
+    gm2L1Nd2NzParams.dstNzNStride = 1;
+    DataCopy(l1Tensor, gmTensor, gm2L1Nd2NzParams);
+}
+
+// === Variant C: 批量 DataCopy 合并输出 ===
+LocalTensor<int32_t> nInt32Out = outputQue2.template AllocTensor<int32_t>();
+for (uint32_t i = 0; i < loopCount; i++) {
+    DealBmm1ResBaseBlock(info, nInt32Out, ...);  // 不包含 DataCopy
+}
+outputQue2.EnQue(nInt32Out);
+outputQue2.DeQue<int32_t>();
+uint32_t dealRowCount = (loopCount - 1) * gSplitSize + tailSplitSize;
+DataCopy(nUpdateGm[...], nInt32Out, dealRowCount);  // 一次性写回
+
+// === Variant D: 预计算偏移表 + Gather 提取 ===
+// Init 阶段预计算（只执行一次）
+for (uint32_t i = 0; i < V1_BASE_T; i++) {
+    for (uint32_t j = 0; j < N_; j++)
+        preOffsetBuf_.SetValue(offset1++, curOffset * sizeof(P));
+    curOffset += N_;
+    for (uint32_t j = 0; j < N_; j++)
+        postOffsetBuf_.SetValue(offset2++, curOffset * sizeof(P));
+    curOffset += nSquare;
+}
+// 后续通过 Gather 提取
+Gather(hPreBuff_, matmulRes_, preOffsetBuf_, 0, lenT * N_);
+Gather(hPostBuff_, matmulRes_, postOffsetBuf_, 0, lenT * N_);
+
+// === Variant E: Stride 非连续列提取 ===
+DataCopyExtParams copyParams{
+    static_cast<uint16_t>(ubFactor),
+    static_cast<uint32_t>(RMS_NORM_LENGTH * sizeof(KV_DTYPE)),
+    static_cast<uint32_t>(ROPE_LENGTH * sizeof(KV_DTYPE)),
+    0, 0};
+DataCopyPad(xLocal, kvGm[kvGlobalMemoryOffset], copyParams, padParams);
+
+// === Variant F: GM 按设备最优粒度对齐带宽优化 ===
+// 以下数据为 Ascend 910B 实测结果，不同设备的最优对齐粒度可能不同。
+uint32_t offset = AlignUp(rawOffset, 512);  // 910B 上 512B 为最优粒度
+DataCopy(ubTensor, gmTensor[offset], dataSize);
+// 实测带宽对比（GM→UB，Ascend 910B）：
+// 按最优粒度（512B）对齐: ~100% 带宽效率
+// 256B 对齐: ~90% 带宽效率
+// 32B 对齐:  ~70% 带宽效率（最差情况）
+```
+
+## 5. 从 naive 到 datacopy_optimization 的关键修改点
+
+| 修改项 | naive（优化前） | datacopy_optimization（优化后） |
+|--------|---------------|-------------------------------|
+| 非对齐搬运 | 简单 DataCopy（可能非对齐） | DataCopyPad 自动填充对齐 |
+| ND→NZ 转换 | 独立 TransData 算子 | 搬运时融合 Nd2NzParams |
+| 循环输出 | 每次迭代独立 DataCopy | 循环内累积，循环外统一写回 |
+| Scatter 写入 | 逐元素 SetValue | 向量化 DataCopyPad 逐行写出 |
+| Gather 读取 | 逐元素 GetValue | 预计算偏移表 + Gather 指令 |
+| 非连续列提取 | 搬运全部后裁剪 | blockLen+srcStride 一次提取 |
+| GM 地址对齐 | 无特殊处理 | 按设备最优粒度对齐最大化带宽 |
+| DMA 传输大小 | 多次小传输（< 256B） | 合并为大传输（> 4096B） |
+
+## 6. 注意事项 / 约束
+
+1. **DataCopyPad rightPadding 限制**：`rightPadding` 为 `uint8_t`，最大补零 255 字节。超过此限制需手动分块处理。
+
+2. **补零数据的安全性**：补零后的数据参与后续计算，需确保补零不影响算法正确性。例如 ReduceSum 场景补零安全（0 不影响求和），但 ReduceMax 可能受影响（0 可能改变最大值）。
+
+3. **ND2NZ 对齐要求**：`dstNzC0Stride` 需按数据类型对齐——fp16 为 16 元素，fp8 为 32 元素。不同数据类型对齐基数不同，需条件编译。
+
+4. **DataCopyParams stride 为 uint16_t**：最大 65535；超限需切换到 `DataCopyExtParams`。
+
+5. **Scatter 逐行写出 MTE3 效率低**：每次只搬 1 行，适合 update 行数较少的场景。行数多时考虑批量处理或重组数据布局。
+
+6. **Gather 偏移表 UB 占用**：偏移表占用 UB 空间（元素数 × 4 字节），子张量数量多时占用显著。offset 必须是字节偏移且 Gather 要求源数据在 UB 中连续。
+
+7. **GM 按设备最优粒度对齐**：Kernel 入参（包括 Workspace/Tiling）地址通常已保证对齐，开发者需关注偏移量是否保持该设备的最优对齐粒度（如 Ascend 910B 为 512B，其他设备需查阅手册或实测确认）。
+
+8. **DMA 效率阈值**：传输大小 < 256B 时 DMA 设置成本显著；> 4096B 时总线带宽充分利用。避免过度 tiling 导致每次 DMA 传输过小。具体阈值因设备 DMA 控制器特性而异，需参考对应硬件手册。
+
+9. **列提取时 srcStride 和 blockLen 必须满足 32B 对齐**：每次提取一个子字段需多次搬运调用。
+
+10. **批量 DataCopy 的 UB 空间管理**：循环内累积需要额外 UB 空间，需确保总占用小于 UB 容量。首次迭代可能有额外判断逻辑。
+
+## 7. 常见问题与解决方案
+
+### Q1: DataCopyPad 的 padding 值如何设置？
+
+```cpp
+// 一般场景：补零
+DataCopyPadExtParams<T> padParams{true, 0, rightPadding, 0};
+
+// 需要特定填充值的场景（如 mask 填充）
+DataCopyPadExtParams<T> padParams{true, 0, rightPadding, MASK_VALUE};
+
+// 不启用填充（数据已对齐）
+DataCopyPadExtParams<T> padParams{false, 0, 0, 0};
+```
+
+### Q2: ND2NZ 转换时不同数据类型的对齐基数？
+
+| 数据类型 | C0 对齐基数 | 计算公式 |
+|---------|-----------|---------|
+| FP16 | 16 元素 | `(nValue + 15) >> 4 << 4` |
+| FP8 | 32 元素 | `(nValue + 31) >> 5 << 5` |
+
+### Q3: 批量 DataCopy 合并时如何处理尾块？
+
+```cpp
+uint32_t dealRowCount = (loopCount - 1) * gSplitSize + tailSplitSize;
+DataCopy(nUpdateGm[...], nInt32Out, dealRowCount);
+```
+
+尾块大小 `tailSplitSize` 通常小于标准块 `gSplitSize`，需在 Host 侧 tiling 时计算并传递。
+
+### Q4: Gather 偏移表如何预计算？
+
+偏移表在 `Init` 阶段只计算一次，后续迭代复用：
+```cpp
+// Init 阶段
+for (uint32_t i = 0; i < V1_BASE_T; i++) {
+    for (uint32_t j = 0; j < N_; j++)
+        preOffsetBuf_.SetValue(offset1++, curOffset * sizeof(P));
+    curOffset += N_;
+    // ...
+}
+// Process 阶段（每次迭代）
+Gather(hPreBuff_, matmulRes_, preOffsetBuf_, 0, lenT * N_);
+```
+
+### Q5: 如何诊断 DMA 效率问题？
+
+Profiling 关注以下指标：
+- `aiv_mte2_time` / `aiv_mte3_time` 异常高 → 检查对齐和传输大小
+- 带宽利用率低 → 检查是否大量小传输（< 256B）
+- 大量 DMA 操作 → 检查是否可合并为批量传输
+
+## 8. 选型决策与自检清单
+
+### 8.1 选型决策
+
+```
+if (算子涉及数据搬运或格式转换):
+    → 启用 datacopy_optimization
+    
+    if (数据未对齐 32B):
+        → 使用 DataCopyPad 自动填充
+    
+    if (需要 ND→NZ 格式转换):
+        → 使用 Nd2NzParams 搬运时融合转换
+    
+    if (循环内多次 DataCopy 写回):
+        → 合并为批量 DataCopy，循环外统一写回
+    
+    if (需要按索引提取子张量):
+        → 预计算偏移表 + Gather 指令
+    
+    if (需要非连续列提取):
+        → 使用 blockLen + srcStride 一次提取
+    
+    if (多核并行访问 GM):
+        → 确保按设备最优粒度对齐，必要时错位访问或行切分
+    
+    if (传输大小 < 256B):
+        → 考虑合并传输或调整 tiling 策略
+else:
+    → 标准 DataCopy 即可
+```
+
+### 8.2 自检清单
+
+- [ ] 所有数据搬运满足 32B 对齐，未对齐时使用 DataCopyPad
+- [ ] GM 地址偏移保持设备最优对齐粒度（如 512B）以最大化带宽，不同设备需实测确认
+- [ ] ND→NZ 转换使用 `Nd2NzParams`，`dstNzC0Stride` 按数据类型对齐
+- [ ] 循环内多次 DataCopy 已合并为批量输出
+- [ ] Gather 偏移表在 Init 阶段预计算，Process 阶段复用
+- [ ] Scatter 逐行写出时评估 MTE3 效率，行数多时考虑优化
+- [ ] DataCopyPad 的 `rightPadding` ≤ 255 字节
+- [ ] 补零数据不影响算法正确性（ReduceMax 场景特别注意）
+- [ ] `DataCopyParams` 的 stride ≤ 65535，超限使用 `DataCopyExtParams`
+- [ ] 传输大小 > 256B（以 Ascend 910B 为例），避免大量小 DMA 传输，不同设备阈值可能不同
+- [ ] UB 空间预算充足，批量累积不超出容量
+- [ ] 精度校验通过：与 naive 实现对比，数据一致性 100%