cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-ops-tune/ops-family/references/broadcast/nddma_design.md

@@ -0,0 +1,53 @@
+# 实现①：NDDMA 搬入即广播
+
+> 主文档：[broadcast_design.md](broadcast_design.md)　|　参考代码：[`code/broadcast_tiling_common.h`](code/broadcast_tiling_common.h)（`MakeNddmaParams` / `BroadcastNddma`）
+
+## 思路
+
+用多维 DMA（NDDMA）一次搬运，把广播轴的源 stride 置 0 → DMA 引擎在 GM→UB 过程中自动复制。**不占 Vector 单元**（只走 MTE2）。
+
+## 适用
+
+有广播轴、广播轴落在 UB tile **内**（切分轴或其下的尾轴），且**不满足 ③ 的条件**：
+- 大 dtype（FP32/INT32 等，不在 {INT8,UINT8,FP16,BF16,INT16,UINT16}）；
+- 或 B8/B16 但尾轴**非对齐**。
+
+判定走 ① 还是 ② 看 `outputStrides[ubSplitAxis] != inputStrides[ubSplitAxis]`——这表示 **UB tile 内 split 轴跨度不一致**（切分轴广播，或切分轴连续但其下尾轴广播，如 `[M,1]→[M,N]`），此时走 ① DMA 复制；tile 内完全连续（广播轴全在外层）则退化为 ②。
+
+## Kernel 写法
+
+```cpp
+// 每核外循环（节选，完整见 code/broadcast_add_kernel.cpp）
+for (int64_t loop = 0; loop < ubLoopNum; loop++) {
+    if (loop != 0) UpdateAxesIndices(axes, outputDims, ubSplitAxis, ubOuter);
+    int64_t rows = (axes[ubSplitAxis] == ubOuter - 1) ? ubTail : ubFormer;
+    int64_t off  = GetGmOffset(axes, inputStrides[i], ubSplitAxis, ubFormer);
+    LocalTensor<T> ub = que.AllocTensor<T>();
+    BroadcastNddma(xGm[off], ub, outputDims, outputStrides, inputStrides[i],
+                   shapeLen, ubSplitAxis, /*ubSplitSize=*/rows);   // ← code/broadcast_tiling_common.h
+    que.EnQue(ub);
+    // ... 计算 + CopyOut
+}
+```
+
+`BroadcastNddma` 内部（`code/broadcast_tiling_common.h`）：
+
+```cpp
+if (outputStrides[ubSplitAxis] != inputStrides[ubSplitAxis]) {       // tile 内 split 轴跨度不一致 → ①
+    auto params = MakeNddmaParams<T>(...);                           // 广播轴 loopSrcStride=0
+    static constexpr AscendC::MultiCopyConfig cfg = {false, 0, 0, false};  // 必须 static：模板参为 const&
+    AscendC::DataCopy<T, NDDMA_DIM, cfg>(ub, gm, params);            // 多维 DMA
+} else {                                                             // tile 内完全连续 → 落 ②
+    AscendC::DataCopyPad(ub, gm, ext, pad);
+}
+```
+
+参数装配 `MakeNddmaParams`：从尾轴往前填 `NDDMA_DIM(=5)` 个轴，广播轴的 `loopSrcStride` 天然为 0（因 `inputStrides[广播轴]=0`）→ 引擎复制；非广播轴填真实 stride。高位不足补 `loopSize=1` 的轴。
+
+## 注意
+
+- `NDDMA_DIM = 5`：单次多维 DMA 最多 5 维。`rank = shapeLen - ubSplitAxis > 5` 时 `MakeNddmaParams` 的 `axisInsideUb` 会变负越界。官方 atvoss 走 with-loop NDDMA（按融合轴拆，`BroadcastNddmaWithLoop`）；**本样例未实现 with-loop，因此 Host 选型在 rank>5 时回退 ③ BRC_UB**（见 `broadcast_add_tiling.cpp` 的 rank 兜底）。
+- 广播轴 `loopSrcStride = 0` 是复制关键；非广播轴填真实 stride。
+- `MultiCopyParams` 的 `constValue` 仅 pad 场景用，正常广播取 0。
+- 与 ② 共用同一段 kernel：是否进 ① 由运行期 `outputStrides[ubSplitAxis] != inputStrides[ubSplitAxis]`（tile 内 split 轴跨度不一致）决定，不等同于"切分轴是广播轴"。
+- `cfg` 必须是 `static constexpr`：`DataCopy` 第三模板参为 `const MultiCopyConfig&`，需静态存储期，局部 `constexpr` 编不过。

package/skills/asc-tools/tool-ops-tune/ops-family/references/broadcast/onedim_design.md

@@ -0,0 +1,114 @@
+# 实现④：OneDim 合轴塌一维快路径（标量广播）
+
+> 主文档：[broadcast_design.md](broadcast_design.md)　|　原语：[`code/broadcast_tiling_common.h`](code/broadcast_tiling_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 tiling;
+    ComputeOneDimTiling(tiling, dimLen, scalarFlag, dtSize, coreNum, ubSize, /*aliveBuf=*/IN_NUM + 1);
+    // 写 tiling 进 tilingData，tilingKey 标记走 OneDim 分支
+    return;
+}
+// 否则：ComputeTiling(...) + 逐输入 PickBroadcastMode(...)（见 broadcast_design.md §1）
+```
+
+`ComputeOneDimTiling`（`code/broadcast_tiling_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_tiling_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/skills/asc-tools/tool-ops-tune/ops-family/references/broadcast/ub_broadcast_design.md

@@ -0,0 +1,67 @@
+# 实现③：UB 内 Broadcast 指令
+
+> 主文档：[broadcast_design.md](broadcast_design.md)　|　参考代码：[`code/broadcast_tiling_common.h`](code/broadcast_tiling_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_tiling_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/skills/asc-tools/tool-ops-tune/ops-family/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++) {
+    IndexType idx0 = indLocal.GetValue(i * INDICES_LAST_DIM);
+    IndexType 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%

package/skills/asc-tools/tool-ops-tune/ops-family/references/common/index.md

@@ -0,0 +1,9 @@
+# 公共优化能力（跨算子族）
+
+| 优化类型 | 适用场景 | 文档 |
+|---------|---------|------|
+| 尾块处理（Tail Block） | 数据量不能被 tile 整除 | `common/tail_block_design.md` |
+| 数据搬运（DataCopy） | 非对齐、小批量多次搬运 | `common/datacopy_optimization_design.md` |
+| UB/TBuf 常驻复用与 Bank 冲突规避 | 多 tile 重复从 GM 搬运、冗余 MTE2 | `common/ub_resident_design.md` |
+
+> 三篇为跨族公共优化能力的入口索引；正文按各篇结构建设（M1.5 补全）。