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

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

@@ -0,0 +1,176 @@
+# Transpose TilingData 结构与参数说明
+
+本文说明 Transpose 各 tiling 策略所用的 TilingData 结构体(POD blob,host 计算后原样拷入 kernel 的 `tiling` GM 参数)。结构体定义见 [`templates/transpose_tiling_data.template`](templates/transpose_tiling_data.template)。
+
+## 使用方式
+
+1. 根据实际入参(dtype、shape、perm),对照 [`guide.md`](guide.md) 策略速查表选择 tiling 策略。
+2. 直接引用 [`templates/dav3510/`](templates/dav3510/) 下对应策略的 kernel 模板文件(见下表映射),按需微调。
+3. host 侧计算 TilingData 时,参照本文各字段含义填充。
+
+## 策略 → kernel 模板 → TilingData 结构 映射
+
+| 策略 | kernel 模板文件 | TilingData 结构 | 参考文档 |
+|------|-------------|-----------------|----------|
+| TENSOR_MOVE | `templates/dav3510/transpose_tensor_move.template` | `TransposeOpTilingData` | [transpose_tensor_move.md](transpose_tensor_move.md) |
+| SMALL_SHAPE | `templates/dav3510/transpose_small_shape.template` | `TransposeOpTilingData` | [transpose_small_shape.md](transpose_small_shape.md) |
+| CUT_ONCE | `templates/dav3510/transpose_cut_one_axis.template` | `TransposeOpTilingData` | [transpose_cut_one_axis.md](transpose_cut_one_axis.md) |
+| CUT_TWICE | `templates/dav3510/transpose_cut_two_axis.template` | `TransposeOpTilingData` | [transpose_cut_two_axis.md](transpose_cut_two_axis.md) |
+| N_LAST_TRANSPOSE | `templates/dav3510/transpose_n_last.template` | `TransposeOpTilingData` | [transpose_n_last.md](transpose_n_last.md) |
+| BIG_DIM | `templates/dav3510/transpose_big_dim.template` | `TransposeOpTilingData` | [transpose_big_dim.md](transpose_big_dim.md) |
+| GATHER_TRANSPOSE | `templates/dav3510/transpose_with_gather.template` | `GatherTransposeTilingData` | [transpose_gather.md](transpose_gather.md) |
+| VCONV_TRANSPOSE (5HD) | `templates/dav3510/transpose_transdata_5hd.template` | `TransposeVCONVTilingData` | [transpose_vconv_5hd.md](transpose_vconv_5hd.md) |
+| VCONV_021_TRANSPOSE | `templates/dav3510/transpose_transdata_5hd_021axis.template` | `Transpose021VCONVTilingData` | [transpose_vconv_021.md](transpose_vconv_021.md) |
+
+> NDDMA 家族共用同一个 `TransposeOpTilingData`;加速策略(gather/vconv/021)各有独立结构。所有结构均 `#pragma pack(push, 8)` 8 字节对齐。
+
+## 外部依赖(CANN toolkit 头文件)
+
+kernel 代码依赖以下 toolkit 头(不在本目录,由 CANN 环境提供):
+
+- `kernel_operator.h` — AscendC 核心 API(TPipe/TQue/DataCopy 等)
+- `op_kernel/platform_util.h`、`op_kernel/math_util.h` — 平台常量与 CeilDiv/FloorDiv 等
+- `simt_api/asc_simt.h` — SMALL_SHAPE 的 SIMT 逐元素模型
+- `reg_compute/kernel_reg_compute_datacopy_intf.h` — GATHER 的 MicroAPI/Reg 寄存器编程与 `DataCopyGatherImpl`(仅 dav-3510)
+
+---
+
+## 一、TransposeOpTilingData(NDDMA 家族)
+
+NDDMA 家族把逻辑 shape 归约后对齐到固定 5 维(`NDDMA_MAX_DIM_NUM=5`),用带 stride 的多维 DMA 完成搬运 + 换轴。字段分四组。
+
+### 1.1 轴与切分基础
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `permSize` | int64 | 归约后有效维数(perm 长度)。5 维扩展偏移 = `NDDMA_MAX_DIM_NUM - permSize`。 |
+| `inCutIndex` | int64 | 输入方向切分轴下标(归约后坐标)。 |
+| `outCutIndex` | int64 | 输出方向切分轴下标(归约后坐标)。CUT_TWICE 判定:`outCutIndex > FindOutIndex(inCutIndex)`。 |
+| `inUbFactor` | int64 | 输入切分轴的 UB 分块因子(每块取多少元素)。 |
+| `outUbFactor` | int64 | 输出切分轴的 UB 分块因子。 |
+| `inTailFactor` | int64 | 输入切分轴尾块大小(`inCutAxisSize % inUbFactor`),0 表示无尾块。 |
+| `outTailFactor` | int64 | 输出切分轴尾块大小,0 表示无尾块。 |
+| `ubSize` | int64 | 本策略可用的 UB 字节数(已按 double buffer 等预留后的值)。 |
+
+### 1.2 多核切分
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `realCoreNum` | int64 | 实际参与计算的核数(`blockIdx >= realCoreNum` 的核直接返回)。 |
+| `blkFactor` | int64 | 每核处理的 NDDMA 块数(基础值)。 |
+| `blkTailFactor` | int64 | 前 `blkTailFactor` 个核各多处理一块,用于均衡余数。见 `ParseMultiCoreRange`。 |
+| `totalNddmaNum` | int64 | 总 NDDMA 块数(一维扁平编号总数),供多核均分。 |
+
+### 1.3 CUT_TWICE 的四类块区间(扁平 loopidx 边界)
+
+同时切两轴 → main/inputTail/outputTail/tail 四类块。区间边界由 host `GetIntervalInfoForCutTwice` 预算,kernel 用本核范围与之求交。仅当对应尾 factor 非 0 时区间存在。
+
+| 字段 | 含义 |
+|------|------|
+| `rangeMainEnd` | main(两轴都取满)区间结束。 |
+| `rangeInputTailStart` / `rangeInputTailEnd` | inputTail(输入取尾、输出取满)区间。 |
+| `rangeOutputTailStart` / `rangeOutputTailEnd` | outputTail(输出取尾、输入取满)区间。 |
+| `rangeTailStart` / `rangeTailEnd` | tail(两轴都取尾)区间。 |
+
+### 1.4 Shape 与 UB 布局数组
+
+| 字段 | 长度 | 含义 |
+|------|------|------|
+| `inputShape` / `outputShape` | 8 | 归约后输入/输出逻辑 shape(`TRANSPOSE_MAX_AXIS_NUM_TD=8`)。 |
+| `perm` | 8 | 归约后 perm。 |
+| `baseInShape` | 8 | 输入各维的元素步长(后缀连乘),用于 GM 地址还原。 |
+| `baseNddmaShape` / `nddmaIdx` | 5 | BIG_DIM 专用:折叠后 NDDMA 各维的基数与原始轴映射(见 `FlushBaseNumForBigDim`)。 |
+| `expandedPerm` | 5 | 5 维扩展后的 perm(换轴 stride 依据)。 |
+| `expandedInputShape` / `expandedOutputShape` | 5 | 5 维扩展后的输入/输出 shape。 |
+| `inUbMainSrcShape` / `inUbMainDstShape` | 5 | main 块进/出 UB 的 5 维形状(src=读入布局,dst=换轴写回布局)。 |
+| `inUbInputTailSrcShape` / `inUbInputTailDstShape` | 5 | inputTail 块的 UB src/dst 形状。 |
+| `inUbOutputTailSrcShape` / `inUbOutputTailDstShape` | 5 | outputTail 块的 UB src/dst 形状。 |
+| `inUbTailSrcShape` / `inUbTailDstShape` | 5 | tail 块的 UB src/dst 形状。 |
+
+> TENSOR_MOVE / SMALL_SHAPE / N_LAST / CUT_ONCE / BIG_DIM 只用到与自身相关的子集,四类块的 UB 形状数组主要服务 CUT_TWICE;其余策略对应字段可能为 0 或退化值。
+
+外层封装 `TransposeTilingData { TransposeOpTilingData transposeOpTiling; }` 仅为与原始 layout 对齐,kernel 入口传 `&tilingData.transposeOpTiling`。
+
+---
+
+## 二、GatherTransposeTilingData(GATHER_TRANSPOSE)
+
+见 [`transpose_gather.md`](transpose_gather.md)。UB 内向量 gather 重排,MTE2/MTE3 两端连续大 burst。
+
+### 2.1 标量控制
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `dataTensorSize` | uint32 | 单份 data buffer 字节数(×2 ping-pong ×2 in/out 后须放进 UB)。 |
+| `indexTensorSize` | uint32 | gather index buffer 字节数(容纳所有相位的 index)。 |
+| `usedCoreCnt` | uint32 | 实际用核数,要求 `>= coreNum/2` 否则该策略放弃。 |
+
+### 2.2 轴切分位置(int8 下标,-1 表示该方向不被切分)
+
+| 字段 | 含义 |
+|------|------|
+| `blkAxesCnt` | block 轴数量(UB 分块之上、分给核的轴)。 |
+| `blkInUbCutPos` / `blkOutUbCutPos` | 输入/输出切轴是否被 block 切分且除不尽(决定尾块相位是否存在)。 |
+| `ubAxesCnt` | 进 UB 参与重排的轴数。 |
+| `inUbInCutPos` / `inUbOutCutPos` | 输入侧在 UB 内的切分/连续边界位置。 |
+| `outUbInCutPos` / `outUbOutCutPos` | 输出侧在 UB 内的切分/连续边界位置(`ubAxesCnt - outUbOutCutPos` = 需 gather 的维数,≤3)。 |
+
+### 2.3 分块因子与 stride
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `blkFactor` / `blkTailFactor` | int64 | 每核 / 末核处理的 block 数。 |
+| `inUbCutAxisSize` / `outUbCutAxisSize` | int64 | 输入/输出切轴的总大小。 |
+| `inUbCutAxisFactor` / `outUbCutAxisFactor` | int32 | 输入/输出切轴的 UB 分块因子;尾块 = size % factor。 |
+| `axis0/1/2InSrcStride` | int64 | MTE2 搬入的多层 GM 源步长(最多 3 层循环)。 |
+| `axis0/1/2OutDstStride` | int64 | MTE3 搬出的多层 GM 目的步长。 |
+
+### 2.4 轴数组
+
+| 字段 | 长度 | 含义 |
+|------|------|------|
+| `blkAxes` | 8 | 各 block 轴大小(`GATHER_MAX_TRANS_AXIS_NUM_TD=8`)。 |
+| `blkAxesInAOffset` / `blkAxesOutAOffset` | 8 | 各 block 轴对应的输入/输出 GM 地址偏移基数(`CalcBlkAddr` 用)。 |
+| `inUbAxes` / `outUbAxes` | 6 | UB 内输入/输出各轴大小(`GATHER_UB_MAX_DIM_NUM_TD=6`)。 |
+| `ubPerm` | 6 | UB 内轴序(int8),生成 gather index 与循环用。 |
+
+---
+
+## 三、TransposeVCONVTilingData(VCONV_TRANSPOSE 5HD,仅 16bit)
+
+见 [`transpose_vconv_5hd.md`](transpose_vconv_5hd.md)。2D 末轴交换,片上 `TransDataTo5HD` 做 16×16 块转置。
+
+辅助结构 `CoreSplitPara`(核间切分:`AlignBlockFactor`/`BlockFactor`/`BlockCount`/尾块)与 `UbSplitPara`(UB 内切分:主核/尾核的 UB align/factor/count),被下表按 R/C 方向各引用一份。
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `AvailableUbSize` | int64 | 可用 UB 字节数。 |
+| `UsedCoreNum` | int64 | 实际用核数。 |
+| `MainCoreLoopCount` / `TailCoreLoopCount` | int64 | 主核 / 尾核的 UB 循环次数。 |
+| `RLen` / `CLen` | int64 | 转置矩阵的行(R)/列(C)长度。 |
+| `RAlignBlock` / `CAlignBlock` | int64 | R/C 向 16 对齐后的块数。 |
+| `RAlignBlockElem` / `CAlignBlockElem` | int64 | R/C 对齐后的元素数。 |
+| `IsRSplit` / `IsRCSplit` | bool | 切分模式:仅切 R / R 和 C 都切(都为 false = 仅切 C)。三种模式覆盖不同 UB 容量。 |
+| `rSplitPara` / `cSplitPara` | CoreSplitPara | R/C 方向的核间切分参数。 |
+| `rUbSplitPara` / `cUbSplitPara` | UbSplitPara | R/C 方向的 UB 内切分参数。 |
+
+---
+
+## 四、Transpose021VCONVTilingData(VCONV_021_TRANSPOSE,支持 8/16/32bit)
+
+见 [`transpose_vconv_021.md`](transpose_vconv_021.md)。`perm=[0,2,1]` 保 batch 转置,按 batch 维循环 + `TransDataTo5HD`。
+
+辅助结构 `Transpose021UbSplitPara`(`UbAlignFactor`/`UbFactor`/`UbCount`/`UbTailAlignFactor`/`UbTailFactor`),被 R/C 方向各引用一份。
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `AvailableUbSize` | int64 | 可用 UB 字节数。 |
+| `UsedCoreNum` | int64 | 实际用核数。 |
+| `NLen` / `HLen` / `WLen` | int64 | batch(N)/ 后两维 H / W 的长度。 |
+| `HAlignBlockElem` / `WAlignBlockElem` | int64 | H/W 对齐后的元素数。 |
+| `NPerCore` / `NTailCore` | int64 | 按 N 维多核切分时每核 / 尾核的 N 数。 |
+| `UbLoopCount` | int64 | UB 循环次数。 |
+| `UseRConv` | bool | H≥W 时为 true,选 R 为主转置轴(影响 R/C 主轴选择)。 |
+| `UseHSplit` | bool | 是否按 H 维(而非 N 维)做多核切分。 |
+| `HPerCore` / `HTailCore` | int64 | 按 H 切分时每核 / 尾核的 H 数。 |
+| `rUbSplitPara` / `cUbSplitPara` | Transpose021UbSplitPara | R/C 方向的 UB 内切分参数。 |

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

@@ -0,0 +1,206 @@
+# Transpose 021 TransData 策略性能调优参考
+
+- **策略名**:VCONV_021_TRANSPOSE / 021 TransData（基于 `TransDataTo5HD`）
+- **tilingKey**:`10008`
+- **支持数据类型宽度**:8-bit（int8/uint8）、16-bit（half/bfloat16）、32-bit（float/int32）
+- **kernel 类**:`Transpose::KernelTransDataTo5HD021<T>`（`arch35/transpose_transdata_5hd_021.h`）
+- **host tiling**:`transpose_host::Transpose021WithVCONV::DoTiling`（`transpose_tiling_021.cpp/.h`）
+- **命中判定**:`TransposeNddmaTiling::Is021VConvValid`（`transpose_tiling.cpp`）
+
+---
+
+## 一、适用场景
+
+### 1.1 什么是 021 转置
+
+021 指 `perm = [0, 2, 1]`：把一个三维张量 `[N, H, W]` 变换为 `[N, W, H]`。
+第 0 维（batch/N）保持不变，只交换后两维 H 与 W。它是标准的“逐 batch 的 2D 矩阵转置”，
+每个 batch 内部就是一个 `H × W → W × H` 的转置，batch 之间彼此独立。
+
+判定入口 `Is021VConvValid` 中的 perm 条件：
+
+```cpp
+// reducedPerm[0]==0 && reducedPerm[1]==2 && reducedPerm[2]==1
+if (!(shapeInfo_.reducedPerm[0] == 0 &&
+      shapeInfo_.reducedPerm[DIM_ONE] == VCONV_DIM_NUM /*=2*/ &&
+      shapeInfo_.reducedPerm[DIM_TWO] == 1)) {
+    return false;
+}
+```
+
+### 1.2 为什么可以用 VCONV / TransData 加速
+
+朴素的转置是“逐元素散射/聚集”式的搬运，DMA stride 极不友好，带宽利用率低。
+昇腾提供了向量转置指令 `TransDataTo5HD`（俗称 VCONV / TransData），它在 UB 内一次性完成
+一个 `16 × blockElem` 分块的转置：以 16 行为一组、按数据块（block）为列粒度做硬件转置，
+把“逐元素搬运”变成“分块硬件转置 + 规整 DMA”，从而显著提升转置吞吐。
+
+其中每次转置处理的行数固定为 `TRANSELEM_021 = 16`，列粒度 `blockElem` 随位宽变化（一个 32B block 内的元素数）：
+
+```cpp
+static constexpr int64_t blockElem = (sizeof(T) == 1) ? 32 :   // 8-bit
+                                     (sizeof(T) == 4) ? 8  :   // 32-bit
+                                                        16;    // 16-bit
+```
+
+### 1.3 与 5HD 策略（10007）的区别
+
+| 项 | 5HD VCONV（tilingKey=10007） | 021 TransData（tilingKey=10008） |
+|---|---|---|
+| perm | 2D 末轴交换 `[1,0]` | 3D 保 batch `[0,2,1]` |
+| 维度 | `dim == 2` | `dim == 3` |
+| 支持位宽 | 仅 16-bit（派发处 `sizeof(T)==sizeof(int16_t)` 才实例化） | **8/16/32-bit 全支持** |
+
+派发入口 `transpose_kernel.cpp`：
+
+```cpp
+} else if (tilingKey == VCONV_021_TRANSPOSE) { // 10008
+    // 021 VCONV kernel supports 8/16/32-bit element widths.
+    if constexpr (sizeof(T) == sizeof(int8_t) || sizeof(T) == sizeof(int16_t) ||
+                  sizeof(T) == sizeof(int32_t)) {
+        Transpose021VCONVTilingData lt; LoadTiling(tiling, lt);
+        Transpose::KernelTransDataTo5HD021<T> op;
+        op.Init(x, y, &lt, &pipe);
+        op.Process();
+    }
+}
+```
+
+021 策略针对不同位宽在 kernel 内走了不同分支：8-bit 走 `Compute8BitCore`（奇偶行拆分 + high/low half 处理），
+16/32-bit 走 `ComputeRConvGeneric` / `ComputeCConvGeneric`（32-bit 额外用 `dstStrideFactor=2` 处理跨 block）。
+
+### 1.4 命中条件（`Is021VConvValid`）
+
+除 perm=[0,2,1] 与 `dim==3` 外，还需同时满足：
+
+- 位宽为 8 / 16 / 32-bit（`eleLenInBytes` ∈ {1,2,4}）。
+- `H > 8` 且 `W > 8`（`DIM_EIGHT`），过滤掉极小边长。
+- `H * W >= HW_MIN_PRODUCT`（转置面积下限）。
+- 有效元素占对齐后面积比例不能太低：`H*W > hAlign*wAlign/2`（`hAlign/wAlign` 按 16 对齐），
+  避免为凑对齐引入过多 padding 浪费。
+- 总字节量 `totalVolumeActual * eleLenInBytes >= 70000`（`SMALL_SHAPE_BYTES_THRES_HOLD_DAV_5102_021`），
+  小 shape 不走此路径（启动/搬运开销占比过高，收益不足）。
+
+### 1.5 为什么能提升性能
+
+- 用硬件向量转置指令替代逐元素搬运，UB 内转置吞吐高。
+- CopyIn/CopyOut 均通过 `DataCopyPad` 做规整的分块 DMA，配合 stride 参数直接完成 gap/padding 处理。
+- 多核按 batch（N）或按 H 切分并行，见 1.6。
+- Double buffer（`BUFFER_NUM=2`）流水，搬入/计算/搬出重叠。
+- 命中门槛（面积、字节量、对齐利用率）保证只在收益为正的 shape 上启用。
+
+---
+
+## 二、kernel 执行流程与关键实现
+
+### 2.1 host tiling 关键决策（`transpose_tiling_021.cpp`）
+
+`CalcBasicInfo` 计算基本量后有三个关键开关：
+
+- **`UseRConv = (HLen >= WLen)`**：H 不小于 W 时以 “R（行/H）为转置主轴” 走 `ComputeRConv`；
+  否则以 “C（列/W）为主轴” 走 `ComputeCConv`。目的是让 `repeatTimes` 落在较大的那一维，提高单次指令效率。
+- **`UseHSplit`**：当 `NLen < 5 && !UseRConv && HLen >= NLen*16` 时启用“按 H 切分多核”，
+  用于 batch 数很少、H 很大的场景把并行度提上去；注意 `CalcUbSplitHSplit` 中 8-bit 直接 `return false`（HSplit 不支持 8-bit）。
+- **UB 切分**：`AvailableUbSize = ubSize/2/BUFFER_NUM`。分 `CalcUbSplitRConv` / `CalcUbSplitCConv` / `CalcUbSplitHSplit`：
+  若整块 `HAlign*WAlign` 能放进 UB 则 `UbLoopCount=1`（不切分）；否则沿主轴切成多份 UB loop。
+  若连一个 `TRANSELEM(16) × 对齐边` 都放不下，则 tiling 失败返回 false（回退其它策略）。
+
+多核切分：非 HSplit 时 `CalcNSplitInfo` 按 N 均分（`NPerCore` + 尾核 `NTailCore`）；
+HSplit 时 `CalcHSplitInfo` 按 H 对齐后均分（`HPerCore` + `HTailCore`）。`tilingKey` 固定写为 10008，`blockDim = UsedCoreNum`。
+
+最终参数写入 `Transpose021VCONVTilingData`（含 `rUbSplitPara` / `cUbSplitPara` 两组 UB 切分因子）。
+
+### 2.2 Init
+
+```cpp
+srcGlobal / dstGlobal 绑定 GM 输入输出;
+if (UseHSplit) { 按 blockIdx 分配 hStart_/hCount_，nStart_=0, nCount_=NLen }
+else           { 按 blockIdx 分配 nStart_/nCount_（区分整核/尾核） }
+pipe->InitBuffer(inQueueSrc,  BUFFER_NUM, AvailableUbSize);
+pipe->InitBuffer(outQueueDst, BUFFER_NUM, AvailableUbSize);
+```
+
+两条 TQue：`inQueueSrc`(VECIN) / `outQueueDst`(VECOUT)，各 `BUFFER_NUM=2` 块，形成 double buffer。
+
+### 2.3 Process 主循环
+
+```mermaid
+flowchart TD
+    A[Process] --> B{blockIdx >= UsedCoreNum?}
+    B -->|是| Z[return 空转核]
+    B -->|否| C{UseHSplit?}
+    C -->|是| D[for n in 0..nCount_:<br/>ProcessOneBatchHSplit n]
+    C -->|否| E[for n in 0..nCount_:<br/>ProcessOneBatch nStart_+n]
+    D --> F[每 batch: for ubLoop in UbLoopCount]
+    E --> F
+    F --> G[CopyIn]
+    G --> H[Compute]
+    H --> I[CopyOut]
+```
+
+`ProcessOneBatch` / `ProcessOneBatchHSplit` 内部按 `UbLoopCount` 循环，最后一次 loop 使用尾块因子
+（`UbTailFactor` / `UbTailAlignFactor`），其余用整块因子（`UbFactor` / `UbAlignFactor`）。
+每次 loop 都是 `CopyIn → Compute → CopyOut` 三段式，天然被 double buffer 流水化。
+
+### 2.4 CopyIn：GM → UB
+
+用 `DataCopyPad` + `DataCopyExtParams copyInParams_` 搬入。根据 W 是否对齐（`WLen % wAlignCheck`，
+8-bit 检查 `blockElem`，其余检查 16）分两条路：
+
+- **`CopyInWAligned`**:W 对齐时尽量整段搬（`blockCount=1`），或按行搬（`blockCount=actualValidRows`）设置行间 `srcStride`。
+- **`CopyInWUnaligned`**:W 非对齐时逐行搬有效宽度 `validW`，用 `dstStride` 在 UB 内补齐到对齐宽度（`WAlignBlockElem`）。
+
+`UseRConv` 时按 `rUbSplitPara` 偏移并计算 `actualValidRows`（防越界取 `min`）；否则按 `cUbSplitPara` 偏移。
+
+### 2.5 Compute：UB 内 TransDataTo5HD 转置
+
+`Compute` 按 `UseRConv` 分派到 `ComputeRConv` / `ComputeCConv`；两者再按位宽分派：
+
+- **8-bit → `Compute8BitCore`**:关键在于 8-bit 一个 block 有 32 个元素而转置组只有 16 行，
+  故把 32 行拆成 **偶数组 / 奇数组**（`evenUbCount`/`oddUbCount`），并借助 `srcHighHalf`（low/high half）
+  两次遍历完成一个 `32-elem block` 的转置；组间用 `PipeBarrier<PIPE_V>()` 保证依赖顺序。
+- **16-bit → `ComputeRConvGeneric` / `ComputeCConvGeneric`**:构造 `srcList[16]` / `dstList[16]` 地址表，
+  设置 `repeatTimes / srcRepStride / dstRepStride` 后调用 `TransDataTo5HD<T>`，沿 `cAlign`（或 `rAlign`）循环。
+- **32-bit → 同上 Generic 分支但走 `dstStrideFactor=2` 路径**:32-bit 一个 block 只有 8 个元素，
+  转置目的地址需按 `dstStrideFactor` 拆成两半（`dstList[2k]` / `dstList[2k+1]` 分别指向 block 内前后段），
+  正确处理 16 行跨两个 32-bit block 的排布。
+
+`ComputeRConv` 与 `ComputeCConv` 的区别在于把 `repeatTimes` 放在 R 还是 C 方向，
+以及 `srcRepStride/dstRepStride` 的取值（`repeatTimes==1` 时 stride 置 0）。
+
+指令使用示意（16-bit Generic 分支）：
+
+```cpp
+TransDataTo5HDParams p;
+p.repeatTimes  = r / TRANSELEM_021;                 // 16 行一组
+p.dstRepStride = (p.repeatTimes == 1) ? 0 : dstStrideFactor;
+p.srcRepStride = (p.repeatTimes == 1) ? 0 : cAlign * TRANSELEM_021;
+for (j = 0; j < cAlign; j++) {
+    for (i = 0; i < 16; i++) srcLocalList[i] = srcLocal[i*c + j*blockElem].GetPhyAddr();
+    // 组装 dstLocalList[16] ...
+    TransDataTo5HD<T>(dstLocalList, srcLocalList, p);
+}
+```
+
+计算前 `DeQue<T>` 取输入、`AllocTensor<T>` 取输出，计算后 `EnQue` 输出并 `FreeTensor` 释放输入。
+
+### 2.6 CopyOut：UB → GM
+
+同样用 `DataCopyPad` + `copyOutParams_`，按 H、W 是否都对齐分 `CopyOutAligned` / `CopyOutUnaligned`：
+
+- 转置后维度变为 `[W, H]`，故 `dstStride` 以 `HLen` 为行跨度回填 GM。
+- `UseRConv` 与否影响 `blockCount/blockLen`（整段 vs 逐列），非对齐时用 `validLen/validCount` 裁掉 padding。
+- HSplit 走独立的 `CopyInHSplit` / `CopyOutHSplit`，按 `hStart_` 定位 GM 的 H 段。
+
+### 2.7 关键技术小结（均以代码为准）
+
+- **`TransDataTo5HD` 向量转置指令**:16 行一组的硬件分块转置，是加速核心。
+- **Double buffer**:`BUFFER_NUM=2`，`InitBuffer` 分配双缓冲，CopyIn/Compute/CopyOut 流水重叠。
+- **TQue 管理**:`inQueueSrc`(VECIN) / `outQueueDst`(VECOUT)，`AllocTensor/EnQue/DeQue/FreeTensor` 生命周期管理。
+- **`PipeBarrier<PIPE_V>()`**:仅在 8-bit 奇偶组/half 切换处插入，保证 vector 转置的写后读依赖。
+- **R/C 主轴自适应**:`UseRConv = HLen>=WLen`，让 repeat 落在较长维度。
+- **位宽自适应**:`blockElem`(32/16/8)、`dstStrideFactor`(32-bit=2) 按 `sizeof(T)` 编译期确定。
+- **多核切分**:N 切分为主；batch 少而 H 大时切换 H 切分（HSplit，不支持 8-bit）。
+- **`DataCopyPad` + stride**:搬运阶段直接处理对齐 gap 与 padding，避免额外 pad 计算指令。
+
+> 注意:文中未出现的技术（如 MTE/L1 缓存、mask、reduce 等）本策略并未使用，请勿据此推断。

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

@@ -0,0 +1,179 @@
+# Transpose 策略参考:VCONV_TRANSPOSE / 5HD TransData
+
+- **策略名**:VCONV_TRANSPOSE(5HD TransData 向量转置)
+- **tilingKey**:`10007`
+- **kernel 类**:`Transpose::KernelTransDataTo5HD<T>`(`arch35/transpose_transdata_5hd.h`)
+- **重要约束**:**仅支持 16bit 元素宽度**(`eleLenInBytes == 2`,如 fp16/bf16/int16)。派发处用 `if constexpr (sizeof(T) == sizeof(int16_t))` 保护;host 侧命中条件也强制 `eleLenInBytes == VCONV_DSIZE(=2)`。
+
+---
+
+## 一、适用场景
+
+### 1.1 什么是 5HD / VCONV 转置
+
+本策略把一次「二维矩阵转置」映射到 AscendC 的向量转置指令 `TransDataTo5HD` 上完成。`TransDataTo5HD` 原本用于 ND 与 5HD(NC1HWC0)之间的格式转换,其硬件本质是在 Vector 单元内对一个 **16 × 16 的元素块**做转置。由于每个 16bit 元素恰好让一个 block(32B)容纳 16 个元素,16×16 的方块转置可以被向量单元一条指令高效吞掉,因此把整块矩阵拆成若干 16×16 子块,逐块调用 `TransDataTo5HD` 即可完成整体转置。
+
+相比走 DMA/NDDMA 的搬运式转置,VCONV 路径把转置计算放在片上 UB 中由 Vector 单元完成,搬入搬出都是**连续或规则跨步**的 `DataCopyPad`,避免了细粒度、非连续的 GM 随机访问,因此在命中场景下带宽利用率更高。
+
+### 1.2 为什么 2D 末轴交换的 16bit 数据能用 VCONV 加速
+
+- **16×16 块对齐天然契合 16bit**:`TransDataTo5HD` 一次处理 16 行 × 16 列。16bit 元素下,16 个元素 = 32B = 1 个 UB block,转置后的写出也天然对齐,无需额外的位宽拼接/拆分。这也是它只支持 16bit 的原因。
+- **末轴交换 (perm=[1,0]) 即纯二维转置**:输入 `[R, C]` 输出 `[C, R]`,访问模式规整,能整齐地切成 16×16 网格。
+- **性能收益来源**:
+  - 转置在片上完成,GM 侧读写是大块连续搬运(`DataCopyPad` 带规则 stride),而非逐元素散读。
+  - 借助 `TQue` 双缓冲(`BUFFER_NUM = 2`),搬入 / 计算 / 搬出三级流水互相掩盖。
+  - 多核按 16 行/列块粒度均分,充分利用全部 AI Core。
+
+### 1.3 命中条件(host 侧 `TryVCONVTiling`)
+
+在 `transpose_tiling.cpp` 的 `TryVCONVTiling` 中,同时满足以下条件才进入本策略(`transpose_tiling_5hd.cpp` 的 `DoTiling`):
+
+```cpp
+shapeInfo_.reducedPerm[0] == 1 && shapeInfo_.reducedPerm[1] == 0 &&  // 二维末轴交换
+shapeInfo_.dim == VCONV_DIM_NUM (== 2) &&                            // reduce 后为 2D
+shapeInfo_.eleLenInBytes == VCONV_DSIZE (== 2) &&                    // 16bit
+shapeInfo_.reducedInShape[0] > DIM_FIVE (> 5)                        // R 轴长度 > 5
+```
+
+即:经过 `RemoveAxisV2` / `MergeAxisV2` 归约后是一个二维、末轴交换、16bit、且 R(第 0 轴)长度大于 5 的转置。`R > 5` 用于排除过小的 shape(此类小 shape 交给通用路径更划算)。若 `DoTiling` 因 UB 放不下(见下文 `CalcRCNotFullLoadUbSplitInfo` 的失败分支)返回 false,则回退到其他策略。
+
+---
+
+## 二、Tiling 切分逻辑(host 侧)
+
+记输入为 `[R=RLen, C=CLen]`。以下常量:`TRANSELEM = 16`(块边长),`BUFFER_NUM = 2`(双缓冲),`BUFFER_TENSOR_NUM = 2`(输入+输出各一块)。
+
+### 2.1 基础信息 `CalcBasicInfo`
+
+```cpp
+AvailableUbSize = ubSize / BUFFER_TENSOR_NUM / BUFFER_NUM;   // 单块可用 UB (in/out 各一块、双 buffer)
+RAlignBlock  = CeilDiv(RLen, 16);   RAlignBlockElem = RAlignBlock * 16;   // R 向上对齐到 16
+CAlignBlock  = CeilDiv(CLen, 16);   CAlignBlockElem = CAlignBlock * 16;   // C 向上对齐到 16
+```
+
+即把 R、C 都向上对齐到 16 的倍数,按 16×16 块组织。
+
+### 2.2 三种切分模式(`CalcBlockAndUbSplitInfo`)
+
+按「哪一维能在 UB 内整列/整行放下」决定核间切分维与 UB 内切分维:
+
+| 判断条件 | 核切分维 | UB 全载维 | 标志 |
+|---|---|---|---|
+| `16 * CAlignBlockElem * 2 <= AvailableUbSize` | R 轴切核 (`CalcRSplitInfo`) | C 全载 (`CalcCFullLoadRUbSplitInfo`) | `IsRSplit=true` |
+| 否则若 `16 * RAlignBlockElem * 2 <= AvailableUbSize` | C 轴切核 (`CalcCSplitInfo`) | R 全载 (`CalcRFullLoadCUbSplitInfo`) | `IsRSplit=false` |
+| 否则(两维都放不下一个 16 条带) | R 轴切核 | R、C 均需再切 (`CalcRCNotFullLoadUbSplitInfo`) | `IsRCSplit=true` |
+
+- **R-split / C 全载**:一次处理若干整行(R 方向,16 的倍数),C 方向整列全载。若 `BlockFactor 行 × C 全载` 一次装不下 UB,则进一步按 `MainCoreUbFactor` 沿 R 分多个 UB 循环(`MainCoreLoopCount`)。
+- **C-split / R 全载**:对称地,一次处理若干整列,R 全载,必要时沿 C 分 UB 循环。
+- **RC 双切 (`IsRCSplit`)**:R、C 都装不下时,核间按 R 切,UB 内先固定 R 的 `BlockFactor`,再沿 C 用 `MainCoreUbFactor` 分块循环。若连 `BlockFactor(16行) × 16 × 2B` 都超过 `AvailableUbSize`,`CalcRCNotFullLoadUbSplitInfo` 返回 false,`DoTiling` 失败并回退到其它策略。
+
+核间切分(`CalcRSplitInfo` / `CalcCSplitInfo`)以 16 对齐块为单位在 `coreNum` 个核间均分,得到主核 `BlockFactor` 与尾核 `BlockTailFactor`,`UsedCoreNum = BlockCount`。UB 内切分则用 `MainCore*` / `TailCore*` × (`Ub` / `TailUb`) 一套四组因子覆盖「主核/尾核 × 主UB循环/尾UB循环」的所有边界。这些因子最终由 `WriteTilingData` 写入 `TransposeVCONVTilingData`(结构见 `transpose_tiling_data.h`:`rSplitPara/cSplitPara` 为 `CoreSplitPara`,`rUbSplitPara/cUbSplitPara` 为 `UbSplitPara`)。
+
+---
+
+## 三、Kernel 执行流程与关键实现
+
+### 3.1 Init
+
+```cpp
+blockIdx_   = GetBlockIdx();
+fullCoreNum = UsedCoreNum - 1;                       // [0, fullCoreNum-1] 主核, 其余尾核
+loopCount   = (blockIdx_ <= fullCoreNum-1) ? MainCoreLoopCount : TailCoreLoopCount;
+isRsplit    = IsRSplit;   isRCSplit = IsRCSplit;
+pipe->InitBuffer(inQueueSrc,  BUFFER_NUM, AvailableUbSize);   // VECIN 双缓冲
+pipe->InitBuffer(outQueueDst, BUFFER_NUM, AvailableUbSize);   // VECOUT 双缓冲
+```
+
+用两条 `TQue`(`TPosition::VECIN` / `VECOUT`),各开 `BUFFER_NUM=2` 块,实现搬入/计算/搬出的 double buffer 流水。
+
+### 3.2 Process 主循环
+
+```mermaid
+flowchart TD
+    A[Process] --> B{blockIdx_ >= UsedCoreNum?}
+    B -- 是 --> Z[空转返回]
+    B -- 否 --> C{blockIdx_ < fullCoreNum?}
+    C -- 主核 --> D[loop i in 0..loopCount]
+    C -- 尾核 --> E[loop i in 0..loopCount]
+    D --> F{i < loopCount-1?}
+    F -- 是 --> G[BaseProcess: MainCoreUbFactor]
+    F -- 否/尾UB --> H[BaseProcess: MainCoreTailUbFactor]
+    E --> I{i < loopCount-1?}
+    I -- 是 --> J[BaseProcess: TailCoreUbFactor]
+    I -- 否/尾UB --> K[BaseProcess: TailCoreTailUbFactor]
+```
+
+`Process` 依据「主核/尾核」× 「主 UB 循环/尾 UB 循环」四种组合,取对应的 `r/c/rAlign/cAlign` 因子,先 `SetBasePocessData` 算出本次的 GM/UB 偏移,再走 `BaseProcess`。多余核(`blockIdx_ >= UsedCoreNum`)直接返回。
+
+### 3.3 BaseProcess:搬入 → 计算 → 搬出
+
+```cpp
+BaseProcess(process, r, c, rAlign, cAlign) {
+    BaseCopyIn(process);              // DataCopyPad: GM -> inQueueSrc
+    BaseCompute(r, c, rAlign, cAlign);// TransDataTo5HD 转置
+    BaseCopyOut(process);             // DataCopyPad: outQueueDst -> GM
+}
+```
+
+- **BaseCopyIn**:`AllocTensor` → `SetCopyInParams`(按 `isRCSplit/isRsplit/否` 分派为 `SetRCSplitCopyInParams` / `SetRSplitCopyInParams` / `SetCSplitCopyInParams`,分别设置 `blockCount / blockLen / srcStride`)→ `DataCopyPad(srcLocal, srcGlobal[gmOffset+copyInCoreOffset], Params, padParams)` → `EnQue`。注意 `SetRSplitCopyInParams` 对 `CLen % 16 == 0` 走单块连续搬运,否则按行 `blockCount` 搬运。
+- **BaseCopyOut**:对称,`SetCopyOutParams` 分派设置写回的 `blockCount/blockLen/dstStride`,`DataCopyPad` 写回 `dstGlobal`。
+
+### 3.4 核心计算:`TransDataTo5HD` 16×16 块转置
+
+`BaseCompute` 按 `r >= c` 选择两条对称路径:
+
+```cpp
+if (r >= c) ComputeRConv(r, c, cAlign);   // 沿 C 方向循环转置
+else        ComputeCConv(r, c, rAlign);   // 沿 R 方向循环转置
+```
+
+**`ComputeRConv`(r ≥ c)**关键实现:
+
+```cpp
+TransDataTo5HDParams p;
+p.repeatTimes = r / 16;                                  // 一次处理 r/16 个 16 行块
+p.dstRepStride = (p.repeatTimes == 1) ? 0 : 1;
+p.srcRepStride = (p.repeatTimes == 1) ? 0 : cAlign * 16;
+for (int j = 0; j < cAlign; j++) {                       // 沿列方向 16 列一组
+    LocalTensor<T> srcLocalList[16], dstLocalList[16];
+    for (int i = 0; i < 16; i++)
+        srcLocalList[i] = srcLocal[i * c + j * 16];      // 源 16 行地址
+    for (int i = 0; i < 16; i++)
+        dstLocalList[i] = dstLocal[i * r + j * 16 * r];  // 目的地址(已转置布局)
+    TransDataTo5HD(dstLocalList, srcLocalList, p);
+}
+```
+
+- 每次 `TransDataTo5HD` 处理一个 16 列宽、`repeatTimes` 个 16 行块的条带,把该条带内每个 16×16 方块转置。`srcLocalList[16]` / `dstLocalList[16]` 是 16 个行指针(高低半 `dstHighHalf/srcHighHalf` 均 false)。
+- `srcRepStride = cAlign*16` 让 repeat 在源上跳过整行对齐宽度;`dstRepStride = 1` 让转置结果落到目的的连续块位置。目的偏移 `i*r + j*16*r` 体现「转置后行列互换」的地址布局。
+- `ComputeCConv` 与之对称(`repeatTimes = c/16`,`dstRepStride = rAlign*16`,`srcRepStride = 1`,外层沿 `rAlign` 循环)。选择 `r>=c` 与否是为了让 `repeatTimes` 取较大的那一维,减少外层循环次数、提升单条指令的吞吐。
+
+计算完 `outQueueDst.EnQue(dstLocal)` 并 `inQueueSrc.FreeTensor(srcLocal)`,交回给 double buffer 流水。
+
+### 3.5 关键技术小结
+
+- **向量转置指令 `TransDataTo5HD`**:片上 16×16 块转置,是本策略性能核心;16bit 元素与 16-block 对齐是其使用前提。
+- **16×16 分块 + 16 对齐**:R、C 向上对齐到 16,按块组织搬运与转置。
+- **Double buffer**:`inQueueSrc` / `outQueueDst` 各 `BUFFER_NUM=2`,搬入/计算/搬出流水掩盖。
+- **`TQue` (VECIN/VECOUT)** 管理 UB 张量生命周期(`AllocTensor/EnQue/DeQue/FreeTensor`)。
+- **`DataCopyPad` 规则搬运**:配合 `CoreSplitPara/UbSplitPara` 的 stride 参数,GM 侧读写为大块规则搬运而非散读。
+- **三种切分(RSplit / CSplit / RCSplit)** 覆盖 C 全载、R 全载、双切三类 UB 容量场景,主核/尾核 + 主UB/尾UB 因子处理所有边界。
+
+---
+
+## 附:tilingKey 与派发
+
+`transpose_kernel.cpp` 中:
+
+```cpp
+} else if (tilingKey == VCONV_TRANSPOSE /* 10007 */) {
+    if constexpr (sizeof(T) == sizeof(int16_t)) {          // 仅 16bit 实例化
+        TransposeVCONVTilingData lt; LoadTiling(tiling, lt);
+        Transpose::KernelTransDataTo5HD<T> op;
+        op.Init(x, y, &lt, &pipe);
+        op.Process();
+    }
+}
+```
+
+注意:tilingKey 10008 (`VCONV_021_TRANSPOSE`) 是相邻的 021 三维 VCONV 策略(支持 8/16/32bit),与本文的 10007 是不同 kernel(`KernelTransDataTo5HD021`),不要混淆。