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

package/assets/ops-direct-invoke/skills/ascendc-performance-best-practices/references/conversion/transpose_cut_two_axis.md

@@ -0,0 +1,177 @@
+# Transpose 双轴切分策略 CUT_TWICE(tilingKey = 10003)
+
+> 本文面向性能调优开发者,基于 arch35 `TransposeCutTwoAxis`(`transpose_cut_two_axis.h`,781 行)与 host 侧 `transpose_tiling.cpp` 的实际实现整理,不含臆测。
+>
+> - kernel 类:`Transpose::TransposeCutTwoAxis<T>`
+> - 派发:`transpose_kernel.cpp` 中 `tilingKey == CUT_TWICE(10003)`
+> - host 选择:`DoSplitUB()`(NDDMA 家族),block 切分 `CalcBlockSplitInfoForCutTwice()`,区间 `GetIntervalInfoForCutTwice()`
+> - 数据结构:`TransposeOpTilingData`(`transpose_tiling_data.h`)
+
+CUT_TWICE 属于 NDDMA(N 维 DMA)Transpose 家族。该家族先把逻辑 shape 归约(reduce)、再对齐扩展到固定的 5 维(`NDDMA_MAX_DIM_NUM = 5`),然后依据 UB 容纳能力在**输入方向和输出方向各切一根轴**来搬运并完成转置。
+
+---
+
+## 一、适用场景
+
+### 1.1 为什么要在输入、输出两个方向都切分
+
+Transpose 的本质是「一次搬运 + 换轴写回」。NDDMA 方案把一块数据读进 UB(`DataCopy`,按 `expandedInputShape` 的顺序线性读入),再按目标 perm 的顺序写回 GM(`DataCopyPad` + LoopMode 的多维 stride)。要让搬运高效,进 UB 的这一块必须满足两个约束:
+
+1. **UB 容量约束**:一块的元素数不能超过 `ubElement`(UB 可用元素数)。
+2. **搬出连续度约束**:写回时最内层要尽量凑满一个 cache line / block(32B),否则出现大量小碎片写。
+
+host 侧 `DoSplitUB()` 的做法是:
+
+- `DoSplitUBInput()`:先把 `inUbElement` 设为 `sqrt(ubElement)`(见 `CalcUBSplitInfo` 中 `KEY_NDDMA_BASE` 分支),从**输入最内轴**往外找到第一根装不下的轴,把它作为 `inCutIndex`,切分因子 `inUbFactor`。这保证了「读入方向」的连续块大小合适。
+- 随后在 `DoSplitUB()` 里从**输出最内轴**往外扫,给「写出方向」找一根切分轴 `outCutIndex`、因子 `outUbFactor`,保证写回时每块也不越界、且尽量对齐。
+
+问题在于:输入切的那根轴,在输出的轴序里处于某个位置 `FindOutIndex(inCutIndex)`;输出切的那根轴是 `outCutIndex`。如果这两者不是同一根轴,单切一根轴无法同时满足「读连续」和「写连续/不越界」——**读方向切好了,写方向仍然有一根大轴撑爆 UB 或产生极碎的写**。此时必须两个方向各切一根。
+
+### 1.2 相对 CUT_ONCE,何时必须用双轴切分
+
+判定就在 `DoSplitUB()` 结尾一行:
+
+```cpp
+if (splitInfo_.outCutIndex > FindOutIndex(splitInfo_.inCutIndex)) {
+    tilingKey_ = KEY_CUT_TWICE;   // 10003
+} else {
+    tilingKey_ = KEY_CUT_ONCE;    // 10002
+}
+```
+
+含义:
+
+- `FindOutIndex(inCutIndex)` 是「输入切分轴」映射到输出轴序中的位置。
+- 若为满足 UB 约束而选出的输出切分轴 `outCutIndex`,其位置比输入切分轴在输出里的位置**更靠外(下标更大 = 更外层)**,说明:仅靠切分输入轴对应的那根输出轴还不够,还得再往外切一根独立的输出轴才能把一块塞进 UB。这时才是真正的「双轴」。
+- 反之(`outCutIndex <= FindOutIndex(inCutIndex)`),输入切分轴对应的输出轴自己就够用,单轴切分(CUT_ONCE)即可,`CalcBlockSplitInfoForCutOnce()` 里甚至会把 `outCutIndex` 直接回退到 `FindOutIndex(inCutIndex)`。
+
+典型触发场景:高维、perm 把「大内轴」换到外侧的转置(例如 `[N, H, W, C]` 的复杂重排),单方向切分无法兼顾读写两端的块大小时,双轴切分能把 UB 一块限制在既读连续又写不越界的范围内。
+
+### 1.3 为什么能提升性能
+
+- **两端都可控**:输入方向的块保证 `DataCopy` 读入的连续度;输出方向的块保证 `DataCopyPad` 写回时 `blockLen/blockCount/dstStride` 合理,减少小于 cache line 的碎片写。
+- **多核利用率**:`CalcBlockSplitInfoForCutTwice()` 会用 `outAxiseExceptSplitInAxis * inUbAxis` 估算并行度,若低于 `coreNum_`,则回头在 `inUbFactor` 上从大到小搜索,直到并行度达到 `VEC_CORE_USED_THRES_HOLD` 阈值且不越界(`UbOutOfBoundCheck`)。即在「块足够大」和「核用满」之间取平衡。
+- **NDDMA 一次成型**:借助 5 维 `MultiCopyParams` + LoopMode,一次 API 调用即可完成多维带 stride 的搬运,免去逐轴显式循环拷贝的开销。
+
+---
+
+## 二、kernel 执行流程与关键实现
+
+### 2.1 整体结构
+
+```mermaid
+flowchart TD
+    A[Init: ParseTilingData, SetGlobalBuffer, InitBuffer vecQue_] --> B[Process]
+    B --> C{blockIdx_ >= realCoreNum_?}
+    C -->|是| Z[return 本核不干活]
+    C -->|否| D[按 blkFactor/blkTailFactor 计算本核 srcOffset_ 与 blkProcessNum_]
+    D --> E[ProcessPerCore]
+    E --> F[计算 inputOutputCutIndex_/outputInputCutIndex_/max,minCutIndex_]
+    F --> G[GetCopyOutParams: 求 4 组 loopSize 与 loopDstStride_]
+    G --> H[GetTailAddressOffsetBase: 求各 tail 段的基址偏移]
+    H --> I[outUbLoop_ = 除两切分轴外各轴的 UB 循环数乘积]
+    I --> J[ProcessBlock]
+    J --> M[ProcessMain]
+    J --> N[ProcessInputTail]
+    J --> O[ProcessOutputTail]
+    J --> P[ProcessTail]
+```
+
+### 2.2 Init
+
+```cpp
+blockIdx_ = GetBlockIdx();
+ParseTilingData();                          // 算 expandedInput/OutputCutIndex_
+inputGM_.SetGlobalBuffer((__gm__ T*)x);
+outputGM_.SetGlobalBuffer((__gm__ T*)y);
+pipe->InitBuffer(vecQue_, 1, tiling_->ubSize);   // 单块 buffer(深度 1)
+```
+
+`ParseTilingData()` 把 host 给的 `inCutIndex/outCutIndex`(基于归约后的 dim)平移到 5 维扩展坐标系:
+
+```cpp
+expandedOutputCutIndex_ = outCutIndex + NDDMA_MAX_DIM_NUM - permSize;
+expandedInputCutIndex_  = inCutIndex  + NDDMA_MAX_DIM_NUM - permSize;
+```
+
+### 2.3 多核切分(Process)
+
+按 `blkFactor_ / blkTailFactor_` 把「总 NDDMA 块数」平均分到 `realCoreNum_` 个核。前 `blkTailFactor` 个核各多处理一块。得到本核处理区间 `[srcOffset_, srcOffset_ + blkProcessNum_ - 1]`。这里的「块索引」是一维扁平编号,后面通过混合进制还原成多维偏移。
+
+### 2.4 四个数据区间:main / inputTail / outputTail / tail
+
+因为**同时切了两根轴**,每根轴都可能有尾块(`inTailFactor`、`outTailFactor`),两两组合出 4 类块:
+
+| 区间 | 含义 | 处理函数 | 使用的 UB shape |
+|------|------|----------|-----------------|
+| main | 两轴都取满 factor 的主体块 | `ProcessMain` | `inUbMainSrc/DstShape` |
+| inputTail | 输入切分轴取尾、输出轴取满 | `ProcessInputTail` | `inUbInputTailSrc/DstShape` |
+| outputTail | 输出切分轴取尾、输入轴取满 | `ProcessOutputTail` | `inUbOutputTailSrc/DstShape` |
+| tail | 两轴都取尾(尾中之尾) | `ProcessTail` | `inUbTailSrc/DstShape` |
+
+区间边界由 host `GetIntervalInfoForCutTwice()` 预先算好,放进 tiling 的 `rangeMainEnd / rangeInputTailStart.. / rangeTailStart..`。只有当 `inTailFactor`、`outTailFactor` 非 0 时对应尾区间才存在(host 里有三种组合分支)。
+
+kernel 侧 `ProcessBlock()` 用 `PorcessOffsetRange()` 把本核的 `[srcOffset_, ...]` 与四个全局区间求交,只对落在本核内的那部分区间调用对应 `Process*`:
+
+```cpp
+if (offsetRangeMainRes.end != 0 || blockIdx_ == 0) ProcessMain(...);
+if (offsetRangeInputTailRes.end != 0)              ProcessInputTail(...);
+if (offsetRangeOutputTailRes.end != 0)             ProcessOutputTail(...);
+if (offsetRangeTailRes.end != 0)                   ProcessTail(...);
+```
+
+### 2.5 单块搬运的核心:Process* + SetupLoopInfo
+
+四个 `Process*` 结构完全一致,区别只在用哪套 UB shape 和基址偏移。以 `ProcessMain` 为例,单块流程:
+
+```mermaid
+flowchart LR
+    A[loopidx 混合进制拆解 -> srcAddressOffset, dstAddressOffset] --> B[AllocTensor bindLocalIn]
+    B --> C["DataCopy NDDMA 多维读入 UB (paramsMain)"]
+    C --> D[EnQue]
+    D --> E["SetLoopModePara UB_TO_OUT (换轴 stride)"]
+    E --> F[DeQue bindLocalOut]
+    F --> G["循环 DataCopyPad 写回 outputGM_ (copyOutParams)"]
+    G --> H[ResetLoopModePara + FreeTensor]
+```
+
+关键点:
+
+1. **地址还原(混合进制)**:一维 `loopidx` 通过 `DecimalToMixedBase(loopidx, loopNumArray, mixedBase)` 拆成各外层轴的循环下标,再乘以每轴的 `loopShapeSizeArray`(shape size)累加成 GM 上的 `srcAddressOffset`/`dstAddressOffset`。`GetLoopAddressOffsetImpl` 负责挑出「除切分轴外、循环数 >1」的轴,src 用原轴序、dst 通过 `FindPermIndex` 用 perm 后的轴序,从而实现读写两端各自的地址步进。tail 段还会减去前面区间已消费的块数偏移(如 `ProcessInputTail` / `ProcessTail` 里那串 `loopidx - (...)`),并加上 `GetTailAddressOffsetBase()` 算出的尾块基址。
+
+2. **读入:NDDMA `DataCopy`**
+   ```cpp
+   DataCopy<T, NDDMA_MAX_DIM_NUM, config>(bindLocalIn, inputGM_[srcAddressOffset], paramsMain);
+   ```
+   `paramsMain = {loopInfoMain, constValue}`,`loopInfoMain` 由 `SetupLoopInfo(inUbSrcShape, inUbDstShape)` 生成:5 维的 `loopSize / loopSrcStride / loopDstStride`。其中:
+   - `loopSrcStride` 按 `expandedInputShape` 的后缀连乘得到(输入连续读)。
+   - `loopDstStride` 先按 `inUbDstShape` 后缀连乘,再在 `maxCutIndex_ - 1` 处做 32B 对齐(`BLOCK_SIZE_BYTE`),然后按 `expandedPerm` 重排到目标轴序——这是「换轴」发生的地方。
+   - 三个数组最后 `reverseArray` 反转以适配 API 的维度顺序。
+
+3. **写回:LoopMode + `DataCopyPad`**
+   `GetCopyOutParams()` 预先把 UB→GM 的搬出拆成:内两维用 `DataCopyExtParams`(`blockLen = loopSize[0]*sizeof(T)`、`blockCount = loopSize[1]`、`dstStride = (loopDstStride_[1] - loopSize[0]) * sizeof(T)`),外两维用 `LoopModeParams`(loop1/loop2 的 size 与 src/dst stride),最外一维(`loopSize[4]`)在 kernel 里用显式 `for` + `DataCopyPad` 逐次搬出。`SetLoopModePara(loopParams, DataCopyMVType::UB_TO_OUT)` 设定换轴的两层循环,搬完 `ResetLoopModePara`。
+
+`GetCopyOutParams()` 里对每根切分轴(`inUbMainDstShape[i] != expandedOutputShape[i]` 处)分段累计 `loopSize`,并按 32B 向上对齐算 `loopSrcStride[1]`,保证写回块头部对齐。
+
+### 2.6 用到的关键技术(按代码实况)
+
+- **TQueBind(VECIN+VECOUT)单缓冲**:`vecQue_` 类型是 `TQueBind<VECIN, VECOUT, 1>`,`InitBuffer(vecQue_, 1, ubSize)` 深度为 1。即**同一块 UB 空间既作输入又作输出,无 double buffer**(`BUFFER_NUM=2` 仅在基类常量中,本策略未用于 ping-pong)。同步靠 `EnQue`/`DeQue` 维持 MTE2→MTE3 的依赖。
+- **NDDMA 5 维搬运**:`DataCopy<T, 5, config>` + `MultiCopyParams/MultiCopyLoopInfo`,一次完成多维带 stride 的读入;`config = {false,0,0,false}`。
+- **LoopMode 搬出**:`SetLoopModePara / ResetLoopModePara` + `DataCopyPad`,以 `DataCopyMVType::UB_TO_OUT` 完成换轴写回,支持非对齐尾块 pad。
+- **多核切分**:`blkFactor_/blkTailFactor_/realCoreNum_` 一维扁平分核,`PorcessOffsetRange` 做本核区间与四类块区间求交。
+- **混合进制寻址**:`DecimalToMixedBase` 把扁平 `loopidx` 还原成多维坐标,是「不显式嵌套多层 for」而处理任意维搬运的关键手段。
+- **32B 对齐**:`SetupLoopInfo` 与 `GetCopyOutParams` 中多处按 `BLOCK_SIZE_BYTE=32` 做 `CeilAlign`,保证 stride/块头对齐,避免非对齐访存降速。
+
+---
+
+## 附:关键 tiling 字段(TransposeOpTilingData)
+
+| 字段 | 作用 |
+|------|------|
+| `inCutIndex / outCutIndex` | 输入、输出方向切分轴(归约后坐标) |
+| `inUbFactor / outUbFactor` | 两轴的 UB 切分因子 |
+| `inTailFactor / outTailFactor` | 两轴尾块大小(决定尾区间是否存在) |
+| `realCoreNum / blkFactor / blkTailFactor` | 多核切分参数 |
+| `expandedPerm / expandedInput/OutputShape` | 5 维扩展后的 perm 与 shape |
+| `inUbMain/InputTail/OutputTail/Tail Src/DstShape` | 四类块各自的 UB src/dst 形状 |
+| `rangeMainEnd / rangeInputTail* / rangeOutputTail* / rangeTail*` | 四个扁平块区间边界 |

package/assets/ops-direct-invoke/skills/ascendc-performance-best-practices/references/conversion/transpose_fusion_design.md

@@ -0,0 +1,398 @@
+# Transpose Fusion 优化设计
+
+## 1. 优化目标
+
+Transpose（转置）是深度学习算子中高频出现的内存布局重排操作。Naive 实现通常采用独立的 Transpose 算子或在 GM 上逐元素重排，导致：
+
+- **额外的算子调用开销**：输出后调用独立 Transpose 算子，增加 kernel 启动开销和数据搬运。
+- **跨步访问效率低**：直接按转置维度访问 GM 导致跨步访问（strided access），内存带宽利用率极低。
+- **UB 上手动转置复杂**：在 UB 上通过标量循环实现转置，无法利用向量化指令，且代码复杂度高。
+- **迭代式算法重复转置**：Sinkhorn 等迭代算法中梯度数据需行列交替访问，每次迭代都转置引入大量 DMA 开销。
+
+本优化通过 DataCopy stride 参数实现零拷贝转置融合、TransDataTo5HD 向量化转置、Transpose buffer 常驻复用等手段，将转置操作融入数据搬运流程，消除额外开销。
+
+| 指标 | naive | optimized | 收益 |
+|------|-------|-----------|------|
+| 转置实现方式 | 独立 Transpose 算子 | DataCopy stride 跳写融合 | 消除算子调用和额外搬运 |
+| 内存访问模式 | 跨步访问（strided） | 连续读取+跳写（srcStride=0） | 读取带宽最大化 |
+| UB 转置 | 标量循环重排 | TransDataTo5HD 向量化 | 效率提升 4-8 倍 |
+| 迭代式转置 | 每迭代一次转置+DMA | 首尾各一次转置，中间常驻 UB | 零中间 DMA 开销 |
+| 多维转置 | 多次独立转置 | 单次 stride 参数控制 | 减少指令数 |
+
+> 适用算子族：`conversion` 族所有涉及布局转换的变体，如 `transpose`、`flash_attention` 输出（BNSD→NBSD、TND→NTD）、`gather_elements` 非最后一维 gather 等。
+
+## 2. 架构概览
+
+### 2.1 存储层级与数据流
+
+Transpose 融合的数据流：src 经 MTE2 连续读取到 UB，通过 DataCopy stride 参数（`srcStride=0` 连读、`dstStride=跳步` 跳写）在搬运时完成布局转换，无需独立 Transpose 算子。对于 UB 内向量化转置，使用 TransDataTo5HD 指令。对于迭代式算法，Transpose Buffer 常驻 UB，首尾各一次转置，中间零 DMA。
+
+### 2.2 转置策略矩阵
+
+| 场景 | 优化策略 | 核心 API / 参数 |
+|------|---------|----------------|
+| 输出转置融合 | DataCopy stride 跳写 | `srcStride=0` 连读 + `dstStride=跳步` 跳写 |
+| 头尾块边界处理 | 单独 DataCopy | 头块/尾块单独处理，中间块 stride 跳写 |
+| 变长序列转置 | 动态 tSize/tBase 计算 | `actualSeqLengthsGmQ.GetValue()` 获取变长信息 |
+| UB 向量化转置 | TransDataTo5HD | `TransposeBase16M8` / `TransposeBase16M16` |
+| 迭代式转置常驻 | Transpose Buffer 复用 | `TBuf<TPosition::VECCALC>` 常驻，首尾转置 |
+| 非最后一维 Gather | Transpose-Gather-ReTranspose | 三步法：转置使 gather 维度连续 |
+
+### 2.3 支持的布局转换
+
+| 源布局 | 目标布局 | 适用场景 | stride 计算 |
+|--------|---------|---------|------------|
+| BNSD | NBSD | FlashAttention 输出 | `dstStride = (batchSize * qSeqSize - s1Size) * headDim * sizeof(T) / 32U` |
+| BSND | NBSD | Batch Matmul 输出 | 类似 BNSD，调整 axis 顺序 |
+| BSH | NBSD | 简化 Attention 输出 | 类似 BNSD，S 和 H 合并 |
+| TND | NTD | 变长序列 | `dstStride = (tSize - 1) * headDim * sizeof(T) / 32U` |
+| [row, col] | [col, row] | 通用矩阵转置 | `TransposeBase16M8` / `TransposeBase16M16` |
+| [N, C, D, H, W] | [N, C, D, W, H] | 5D 数据转置 | `TransDataTo5HD` |
+
+## 3. 关键参数配置
+
+```cpp
+// DataCopyParams / DataCopyExtParams 转置参数
+struct DataCopyParams {
+    uint16_t blockCount;   // 块数量（如 gCount）
+    uint16_t blockLen;     // 每块长度（单位：32B）
+    uint16_t srcStride;    // 源地址块间步长（单位：32B）
+    uint16_t dstStride;    // 目的地址块间步长（单位：32B）
+};
+
+// DataCopyExtParams（stride 超过 65535 时使用）
+struct DataCopyExtParams {
+    uint16_t blockCount;
+    uint32_t blockLen;     // 字节为单位
+    uint32_t srcStride;    // 字节为单位
+    uint32_t dstStride;    // 字节为单位
+    uint32_t reserved;
+};
+```
+
+### 3.1 Stride 计算原则
+
+```cpp
+// 通用 stride 转置公式：
+// srcStride = 0 表示连读（源数据连续）
+// dstStride = (目标轴总长度 - 当前块长度) * 元素大小 / 32U
+
+// BNSD → NBSD 示例
+dataCopyParams.blockCount = gCount;  // 处理多少个 G
+dataCopyParams.blockLen = s1Size * headDim * sizeof(OUT_T) / 32U;  // 一个 S1*D
+dataCopyParams.srcStride = 0;  // 连读
+dataCopyParams.dstStride = (batchSize * qSeqSize - s1Size) * headDim * sizeof(OUT_T) / 32U;  // 跳写
+
+// TND → NTD 变长序列示例
+uint64_t tSize = actualSeqLengthsGmQ.GetValue(batchSize - 1);  // 总 T
+uint64_t tBase = (bIdx == 0) ? 0 : actualSeqLengthsGmQ.GetValue(bIdx - 1);  // 当前 batch 的 T 起始
+dataCopyParams.dstStride = (tSize - 1) * headDim * sizeof(OUT_T) / 32U;  // 按 T 跳写
+```
+
+### 3.2 TransDataTo5HD 对齐要求
+
+| 转置类型 | row 对齐 | col 对齐 | 说明 |
+|---------|---------|---------|------|
+| TransposeBase16M8 | 16 | 8 | FP32 场景 |
+| TransposeBase8M16 | 8 | 16 | FP16 场景 |
+| TransposeBase16M16 | 16 | 16 | 通用场景 |
+
+```cpp
+template <typename T>
+__aicore__ inline void TransposeBase16M8(LocalTensor<T>& dstUb, LocalTensor<T>& srcUb, 
+                                         uint64_t rowNum, uint64_t colNum) {
+    uint64_t srcAddrList[TRANS_ADDR_LEN];
+    uint64_t dstAddrList[TRANS_ADDR_LEN];
+    for (uint64_t r = 0; r < rowNum / TRANS_ADDR_LEN; r++) {
+        for (uint64_t i = 0; i < TRANS_ADDR_LEN; i++) {
+            srcAddrList[i] = (uint64_t)(srcUb[r * TRANS_ADDR_LEN * colNum + i * colNum].GetPhyAddr());
+            dstAddrList[i] = (uint64_t)(dstUb[r * TRANS_ADDR_LEN + i / 2 * rowNum + i % 2 * BLOCK_NUM_32].GetPhyAddr());
+        }
+        struct TransDataTo5HDParams transDataParams;
+        transDataParams.repeatTimes = colNum / BLOCK_NUM_32;
+        TransDataTo5HD<float>(dstAddrList, srcAddrList, transDataParams);
+    }
+}
+```
+
+## 4. 核心计算循环
+
+### 4.1 naive 版本（优化前）
+
+```cpp
+// 阶段 1：输出后调用独立 Transpose 算子
+DataCopy(outputGm, attenOutUb, size);  // BNSD 格式
+Transpose(outputGm, tempGm, ...);      // 额外转置操作
+
+// 阶段 2：跨步访问读取转置数据（效率极低）
+for (uint32_t n = 0; n < nSize; n++) {
+    for (uint32_t b = 0; b < batchSize; b++) {
+        for (uint32_t s = 0; s < s1Size; s++) {
+            for (uint32_t d = 0; d < headDim; d++) {
+                // 跨步访问：每次只读一个元素
+                dst[n][b][s][d] = src[b][n][s][d];
+            }
+        }
+    }
+}
+
+// 阶段 3：UB 上标量循环转置
+for (uint64_t i = 0; i < rowNum; i++) {
+    for (uint64_t j = 0; j < colNum; j++) {
+        dstUb[j * rowNum + i] = srcUb[i * colNum + j];
+    }
+}
+
+// 阶段 4：迭代式算法每迭代都转置+DMA
+for (int j = numIters_ - 1; j > 0; --j) {
+    colNormGrad();
+    TransposeX();        // 转置
+    CopyOutTranspose();  // DMA 写出
+    rowNormGrad();
+    TransposeXBack();    // 转置回来
+    CopyOutTransposeBack();  // DMA 写出
+}
+```
+
+### 4.2 optimized 版本（优化后）
+
+```cpp
+// === Variant A: BNSD → NBSD 转置输出融合 ===
+DataCopyParams dataCopyParams;
+dataCopyParams.blockCount = gCount;  // 处理多少个 G
+dataCopyParams.blockLen = s1Size * headDim * sizeof(OUT_T) / 32U;  // 一个 S1*D
+dataCopyParams.srcStride = 0;  // 连读
+dataCopyParams.dstStride = (batchSize * qSeqSize - s1Size) * headDim * sizeof(OUT_T) / 32U;  // 跳写
+
+uint64_t attenOutOffset = n2Idx * gSize * batchSize * qSeqSize * headDim +  // N2轴
+                          gStartIdx * batchSize * qSeqSize * headDim +       // G轴
+                          bIdx * qSeqSize * headDim;                         // B轴
+DataCopy(attentionOutGm[attenOutOffset], attenOutUb, dataCopyParams);
+
+// === Variant B: 头尾块单独处理 ===
+bool hasHeadBlock = (s1StartIdx != 0);
+bool hasTailBlock = ((s1EndIdx + 1) != s1Size);
+
+if (hasHeadBlock) {
+    DataCopyParams dataCopyParamsHead;
+    dataCopyParamsHead.blockCount = 1;
+    dataCopyParamsHead.blockLen = (s1Size - s1StartIdx) * headDim * sizeof(OUT_T) / 32U;
+    dataCopyParamsHead.dstStride = 0;  // 单块无需跳写
+    DataCopy(attentionOutGm[offset], attenOutUb, dataCopyParamsHead);
+    attenOutUbOffset += (s1Size - s1StartIdx) * headDim;
+}
+
+DataCopyParams dataCopyParams;
+dataCopyParams.blockCount = gCount - hasHeadBlock - hasTailBlock;
+dataCopyParams.dstStride = (batchSize * qSeqSize - s1Size) * headDim / 32U;
+DataCopy(attentionOutGm[offset], attenOutUb[attenOutUbOffset], dataCopyParams);
+
+if (hasTailBlock) {
+    DataCopyParams dataCopyParamsTail;
+    dataCopyParamsTail.blockCount = 1;
+    dataCopyParamsTail.blockLen = (s1EndIdx + 1) * headDim * sizeof(OUT_T) / 32U;
+    DataCopy(attentionOutGm[offset], attenOutUb[attenOutUbOffset], dataCopyParamsTail);
+}
+
+// === Variant C: TND → NTD 变长序列转置 ===
+uint64_t tSize = actualSeqLengthsGmQ.GetValue(batchSize - 1);  // 总 T
+uint64_t tBase = (bIdx == 0) ? 0 : actualSeqLengthsGmQ.GetValue(bIdx - 1);  // 当前 batch 的 T 起始
+
+DataCopyParams dataCopyParams;
+dataCopyParams.blockCount = gCountOneS1;
+dataCopyParams.blockLen = headDim * sizeof(OUT_T) / 32U;
+dataCopyParams.dstStride = (tSize - 1) * headDim * sizeof(OUT_T) / 32U;  // 按 T 跳写
+
+uint64_t attenOutOffset = n2Idx * gSize * tSize * headDim +  // N2轴
+                          gIdx * tSize * headDim +            // G轴
+                          tBase * headDim +                   // B轴（动态）
+                          s1Idx * headDim;                    // S1轴
+DataCopy(attentionOutGm[attenOutOffset], attenOutUb[attenOutUbOffset], dataCopyParams);
+
+// === Variant D: TransDataTo5HD 向量化转置 ===
+template <typename T>
+__aicore__ inline void TransposeBase16M8(LocalTensor<T>& dstUb, LocalTensor<T>& srcUb, 
+                                         uint64_t rowNum, uint64_t colNum) {
+    uint64_t srcAddrList[TRANS_ADDR_LEN];
+    uint64_t dstAddrList[TRANS_ADDR_LEN];
+    for (uint64_t r = 0; r < rowNum / TRANS_ADDR_LEN; r++) {
+        for (uint64_t i = 0; i < TRANS_ADDR_LEN; i++) {
+            srcAddrList[i] = (uint64_t)(srcUb[r * TRANS_ADDR_LEN * colNum + i * colNum].GetPhyAddr());
+            dstAddrList[i] = (uint64_t)(dstUb[r * TRANS_ADDR_LEN + i / 2 * rowNum + i % 2 * BLOCK_NUM_32].GetPhyAddr());
+        }
+        struct TransDataTo5HDParams transDataParams;
+        transDataParams.repeatTimes = colNum / BLOCK_NUM_32;
+        TransDataTo5HD<float>(dstAddrList, srcAddrList, transDataParams);
+    }
+}
+
+// === Variant E: Transpose Buffer 常驻复用 ===
+TBuf<TPosition::VECCALC> gradTransposeBuf_;
+void Process() {
+    TransposeXIn();      // 首次转置到 UB
+    for (int j = numIters_ - 1; j > 0; --j) {
+        colNormGrad();   // 原地读写 gradTransposeBuf_
+        rowNormGrad();   // 原地读写 gradTransposeBuf_
+    }
+    TransposeXOut();     // 最后一次转置回并搬出
+    CopyOut(offset);
+}
+
+// === Variant F: Transpose-Gather-ReTranspose 三步法 ===
+__aicore__ inline void Process() {
+    for (size_t preDimId = 0; preDimId < curGroupPreDim; preDimId++) {
+        for (size_t postDimPartId = 0; postDimPartId < postDimPartNum; postDimPartId++) {
+            TransposeProcess(xBaseOffset, idxBaseOffset, carryNumAlign_, ...);
+            this->MTE3ToMTE2Sync();
+            GatherProcess(carryNumAlign_);
+            this->MTE3ToMTE2Sync();
+            ReTransposeProcess(idxBaseOffset, carryNumAlign_);
+        }
+    }
+}
+```
+
+## 5. 从 naive 到 transpose_fusion 的关键修改点
+
+| 修改项 | naive（优化前） | transpose_fusion（优化后） |
+|--------|---------------|---------------------------|
+| 转置实现 | 独立 Transpose 算子 | DataCopy stride 参数零拷贝融合 |
+| 内存读取 | 跨步访问（strided） | srcStride=0 连续读取 |
+| 内存写回 | 连续写出 | dstStride=跳步 实现布局转换 |
+| UB 转置 | 标量循环重排 | TransDataTo5HD 向量化指令 |
+| 迭代式转置 | 每迭代转置+DMA | 首尾各一次，中间常驻 UB |
+| 头尾边界 | 统一处理（可能错误） | 头块/尾块单独 DataCopy |
+| 变长序列 | 固定长度假设 | 动态 tSize/tBase 计算 |
+| Gather 维度 | 直接跨步 gather（低效） | Transpose→Gather→ReTranspose 三步法 |
+
+## 6. 注意事项 / 约束
+
+1. **DataCopyParams stride 为 uint16_t**：最大 65535（单位：32B）。若 stride 超过此限制，需切换到 `DataCopyExtParams`（uint32_t，范围更大）。
+
+2. **blockLen 单位为 32B**：`DataCopyParams.blockLen` 的单位是 32B，计算时需 `sizeof(T) * elementCount / 32U`。使用 `DataCopyExtParams` 时单位为字节。
+
+3. **仅适用于单维度转置**：多维度复杂重排需要组合多次 stride 搬运或使用 Gather。例如 [B, N, S, D] → [N, B, S, D] 可通过一次 stride 跳写完成，但 [B, N, S, D] → [D, S, N, B] 需要多次操作。
+
+4. **Transpose buffer 常驻的 UB 占用**：`gradTransposeBuf_` 占用 `tAlign_ × n_ × n_ × 4` 字节，n 较大时成为 tiling 瓶颈。仅在迭代次数较多（≥3）时收益明显。
+
+5. **TransDataTo5HD 对齐要求**：row 和 col 必须满足对应转置类型的对齐要求（16/8/16）。未对齐时需 padding 或降级为标量处理。
+
+6. **变长序列需要从 GM 读取 actual sequence 信息**：TND 场景下每个 batch 的 T 大小不同，需从 `actualSeqLengthsGmQ` 动态获取，引入额外的 GM 读取开销。
+
+7. **stride 跳写效率低于连续搬运**：虽然消除了 Transpose 算子，但 stride 模式的写回效率仍略低于连续搬运。需权衡消除算子调用 vs stride 写回开销。
+
+8. **头尾块增加 DataCopy 指令数量**：头块和尾块各需一次额外的 DataCopy，逻辑复杂度增加，但保证输出正确性。
+
+## 7. 常见问题与解决方案
+
+### Q1: DataCopyParams 和 DataCopyExtParams 如何选择？
+
+```cpp
+// DataCopyParams：stride 为 uint16_t（单位：32B），适合大多数场景
+DataCopyParams params;
+params.dstStride = (batchSize * qSeqSize - s1Size) * headDim * sizeof(OUT_T) / 32U;
+// 若上述值 > 65535，则必须使用 DataCopyExtParams
+
+// DataCopyExtParams：stride 为 uint32_t（单位：32B），适合大 stride 场景
+DataCopyExtParams extParams;
+extParams.dstStride = (batchSize * qSeqSize - s1Size) * headDim * sizeof(OUT_T) / 32U;  // 32B
+```
+
+### Q2: 如何计算 BNSD → NBSD 的 dstStride？
+
+```cpp
+// BNSD: [Batch, NumHead, SeqLen, HeadDim]
+// NBSD: [NumHead, Batch, SeqLen, HeadDim]
+// 目标：将 N 轴提取到最外层
+
+// 在 GM 上，NBSD 的相邻 batch 间隔为 batchSize * qSeqSize * headDim 字节
+// 当前块写完后，下一个 N 的位置需要跳过 (batchSize * qSeqSize - s1Size) * headDim
+dstStride = (batchSize * qSeqSize - s1Size) * headDim * sizeof(OUT_T) / 32U;
+```
+
+### Q3: TransposeBase16M8 和 TransposeBase16M16 如何选择？
+
+| 数据类型 | 推荐转置类型 | 原因 |
+|---------|------------|------|
+| FP32 | TransposeBase16M8 | row 对齐 16，col 对齐 8（32B） |
+| FP16/BF16 | TransposeBase16M16 | row 对齐 16，col 对齐 16（32B） |
+
+```cpp
+if constexpr (is_same<TGrad, float>::value) {
+    TransposeBase16M8(gradTranUb, gradUb, params_.singleCoreNc, block_.dohowoAlign8);
+} else {
+    TransposeBase16M16(gradTranUb, gradUb, params_.singleCoreNc, block_.dohowoAlign16);
+}
+```
+
+### Q4: 迭代式算法中 Transpose Buffer 常驻的收益如何评估？
+
+收益 = 节省的 DMA 次数 × 每次 DMA 开销 - 额外 UB 占用成本
+
+- 迭代次数 ≥ 3：通常收益明显
+- 迭代次数 = 1：无收益，反而增加首尾转置开销
+- buffer 大小 > UB 容量 50%：可能成为 tiling 瓶颈，需评估
+
+### Q5: 多维度复杂重排如何处理？
+
+单次 stride 搬运仅支持单维度转置。多维度重排需组合多次操作：
+
+```cpp
+// 示例：[B, N, S, D] → [D, S, N, B]
+// 步骤 1: [B, N, S, D] → [B, N, D, S]  (S↔D 转置)
+// 步骤 2: [B, N, D, S] → [N, B, D, S]  (B↔N 转置)
+// 步骤 3: [N, B, D, S] → [D, S, N, B]  (复杂重排，可能需要 Gather)
+```
+
+对于复杂重排，考虑使用 Gather 指令或预先在 Host 端重组数据布局。
+
+## 8. 选型决策与自检清单
+
+### 8.1 选型决策
+
+```
+if (算子输出需要布局转换):
+    → 启用 transpose_fusion
+    
+    if (转换可表达为单维度 stride 跳写):
+        → 使用 DataCopy stride 参数零拷贝融合
+        → srcStride = 0（连读）
+        → dstStride = 跳步值（按目标布局计算）
+        
+        if (存在头尾块边界不对齐):
+            → 头块/尾块单独 DataCopy，中间块 stride 跳写
+    
+    else if (需要 UB 上向量化转置):
+        → 使用 TransDataTo5HD
+        → 选择 TransposeBase16M8 / 16M16 按数据类型
+        → 确保 row/col 满足对齐要求
+    
+    else if (迭代式算法需行列交替访问):
+        → 使用 Transpose Buffer 常驻复用
+        → 评估迭代次数 ≥ 3 且 buffer 大小可控
+        → 首尾各一次转置，中间原地读写
+    
+    else if (非最后一维 Gather):
+        → Transpose-Gather-ReTranspose 三步法
+        → 转置使 gather 维度连续
+    
+    else:
+        → 使用独立 Transpose 算子或 Host 端预处理
+else:
+    → 标准 DataCopy 连续写出
+```
+
+### 8.2 自检清单
+
+- [ ] 转置通过 DataCopy stride 参数实现，非独立 Transpose 算子
+- [ ] `srcStride = 0` 确保读取连续，最大化 MTE2 带宽
+- [ ] `dstStride` 正确计算，按目标布局跳写
+- [ ] DataCopyParams stride ≤ 65535，超限使用 DataCopyExtParams
+- [ ] blockLen 单位正确（DataCopyParams 为 32B，DataCopyExtParams 为字节）
+- [ ] 头尾块边界单独处理，保证输出正确性
+- [ ] TransDataTo5HD 的 row/col 满足对齐要求（16/8/16）
+- [ ] Transpose Buffer 常驻时，迭代次数 ≥ 3 且 UB 占用可控
+- [ ] 变长序列场景动态获取 tSize/tBase，非固定长度假设
+- [ ] TND 场景从 GM 读取 actualSeqLengths，评估额外读取开销
+- [ ] 多维度重排评估是否可分解为多次单维度 stride 搬运
+- [ ] 精度校验通过：与 naive Transpose 对比，数据一致性 100%