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

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

@@ -0,0 +1,192 @@
+/**
+ * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+ * CANN Open Software License Agreement Version 2.0 (the "License").
+ * Please refer to the License for details. You may not use this file except in compliance with the License.
+ * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+ * See LICENSE in the root of the software repository for the full text of the License.
+ */
+
+/*!
+ * \file transpose_tiling_data.h
+ * \brief POD TilingData for the <<<>>> direct-launch Transpose op.
+ *
+ * This replaces the framework-generated (BEGIN_TILING_DATA_DEF ...) struct used by the
+ * original arch35 op. The field names, types and array lengths match TransposeOpTilingData
+ * in transpose_tiling_arch35.h exactly, so the arch35 kernel headers read it unchanged via
+ * plain member access (tilingData_->field). The struct is a plain-old-data blob copied
+ * verbatim from host to the kernel `tiling` GM argument.
+ */
+#ifndef TRANSPOSE_TILING_DATA_H
+#define TRANSPOSE_TILING_DATA_H
+
+#include <cstdint>
+
+#ifndef TRANSPOSE_MAX_AXIS_NUM_TD
+#define TRANSPOSE_MAX_AXIS_NUM_TD 8
+#endif
+#ifndef NDDMA_MAX_DIM_NUM_TD
+#define NDDMA_MAX_DIM_NUM_TD 5
+#endif
+
+#pragma pack(push, 8)
+struct TransposeOpTilingData {
+    int64_t permSize;
+    int64_t inCutIndex;
+    int64_t outCutIndex;
+    int64_t inUbFactor;
+    int64_t outUbFactor;
+    int64_t inTailFactor;
+    int64_t outTailFactor;
+    int64_t realCoreNum;
+    int64_t blkFactor;
+    int64_t blkTailFactor;
+    int64_t ubSize;
+    int64_t totalNddmaNum;
+    int64_t rangeMainEnd;
+    int64_t rangeInputTailStart;
+    int64_t rangeInputTailEnd;
+    int64_t rangeOutputTailStart;
+    int64_t rangeOutputTailEnd;
+    int64_t rangeTailStart;
+    int64_t rangeTailEnd;
+    int64_t inputShape[TRANSPOSE_MAX_AXIS_NUM_TD];
+    int64_t outputShape[TRANSPOSE_MAX_AXIS_NUM_TD];
+    int64_t perm[TRANSPOSE_MAX_AXIS_NUM_TD];
+    int64_t baseInShape[TRANSPOSE_MAX_AXIS_NUM_TD];
+    int64_t baseNddmaShape[NDDMA_MAX_DIM_NUM_TD];
+    int64_t nddmaIdx[NDDMA_MAX_DIM_NUM_TD];
+    int64_t expandedPerm[NDDMA_MAX_DIM_NUM_TD];
+    int64_t expandedInputShape[NDDMA_MAX_DIM_NUM_TD];
+    int64_t expandedOutputShape[NDDMA_MAX_DIM_NUM_TD];
+    int64_t inUbMainSrcShape[NDDMA_MAX_DIM_NUM_TD];
+    int64_t inUbMainDstShape[NDDMA_MAX_DIM_NUM_TD];
+    int64_t inUbInputTailSrcShape[NDDMA_MAX_DIM_NUM_TD];
+    int64_t inUbInputTailDstShape[NDDMA_MAX_DIM_NUM_TD];
+    int64_t inUbOutputTailSrcShape[NDDMA_MAX_DIM_NUM_TD];
+    int64_t inUbOutputTailDstShape[NDDMA_MAX_DIM_NUM_TD];
+    int64_t inUbTailSrcShape[NDDMA_MAX_DIM_NUM_TD];
+    int64_t inUbTailDstShape[NDDMA_MAX_DIM_NUM_TD];
+};
+
+// Wrapper struct kept for parity with the original TransposeTilingData layout,
+// so the kernel entry can pass &tilingData.transposeOpTiling like the original.
+struct TransposeTilingData {
+    TransposeOpTilingData transposeOpTiling;
+};
+
+// ===================== Accelerator-strategy TilingData (POD) =====================
+// These mirror the framework (BEGIN_TILING_DATA_DEF ...) structs used by the
+// gather / vconv(5hd) / 021vconv arch35 kernels. Field names/types/order match the
+// originals exactly so the kernel headers read them unchanged via plain member access.
+
+#ifndef GATHER_UB_MAX_DIM_NUM_TD
+#define GATHER_UB_MAX_DIM_NUM_TD 6
+#endif
+#ifndef GATHER_MAX_TRANS_AXIS_NUM_TD
+#define GATHER_MAX_TRANS_AXIS_NUM_TD 8
+#endif
+
+struct GatherTransposeTilingData {
+    uint64_t tilingKey;
+    uint32_t dataTensorSize;
+    uint32_t indexTensorSize;
+    uint32_t usedCoreCnt;
+    int8_t blkAxesCnt;
+    int8_t blkInUbCutPos;
+    int8_t blkOutUbCutPos;
+    int8_t ubAxesCnt;
+    int8_t inUbInCutPos;
+    int8_t inUbOutCutPos;
+    int8_t outUbInCutPos;
+    int8_t outUbOutCutPos;
+    int64_t blkFactor;
+    int64_t blkTailFactor;
+    int64_t inUbCutAxisSize;
+    int64_t outUbCutAxisSize;
+    int32_t inUbCutAxisFactor;
+    int32_t outUbCutAxisFactor;
+    int64_t axis0InSrcStride;
+    int64_t axis1InSrcStride;
+    int64_t axis2InSrcStride;
+    int64_t axis0OutDstStride;
+    int64_t axis1OutDstStride;
+    int64_t axis2OutDstStride;
+    int64_t blkAxes[GATHER_MAX_TRANS_AXIS_NUM_TD];
+    int64_t blkAxesInAOffset[GATHER_MAX_TRANS_AXIS_NUM_TD];
+    int64_t blkAxesOutAOffset[GATHER_MAX_TRANS_AXIS_NUM_TD];
+    int32_t inUbAxes[GATHER_UB_MAX_DIM_NUM_TD];
+    int32_t outUbAxes[GATHER_UB_MAX_DIM_NUM_TD];
+    int8_t ubPerm[GATHER_UB_MAX_DIM_NUM_TD];
+};
+
+struct CoreSplitPara {
+    int64_t AlignBlockFactor;
+    int64_t BlockFactor;
+    int64_t BlockCount;
+    int64_t AlignBlockTailFactor;
+    int64_t BlockTailFactor;
+};
+
+struct UbSplitPara {
+    int64_t MainCoreUbAlignFactor;
+    int64_t MainCoreUbFactor;
+    int64_t MainCoreUbCount;
+    int64_t MainCoreTailUbAlignFactor;
+    int64_t MainCoreTailUbFactor;
+    int64_t TailCoreUbAlignFactor;
+    int64_t TailCoreUbFactor;
+    int64_t TailCoreUbCount;
+    int64_t TailCoreTailUbAlignFactor;
+    int64_t TailCoreTailUbFactor;
+};
+
+struct TransposeVCONVTilingData {
+    int64_t AvailableUbSize;
+    int64_t UsedCoreNum;
+    int64_t MainCoreLoopCount;
+    int64_t TailCoreLoopCount;
+    int64_t RLen;
+    int64_t CLen;
+    int64_t RAlignBlock;
+    int64_t CAlignBlock;
+    int64_t RAlignBlockElem;
+    int64_t CAlignBlockElem;
+    bool IsRSplit;
+    bool IsRCSplit;
+    CoreSplitPara rSplitPara;
+    CoreSplitPara cSplitPara;
+    UbSplitPara rUbSplitPara;
+    UbSplitPara cUbSplitPara;
+};
+
+struct Transpose021UbSplitPara {
+    int64_t UbAlignFactor;
+    int64_t UbFactor;
+    int64_t UbCount;
+    int64_t UbTailAlignFactor;
+    int64_t UbTailFactor;
+};
+
+struct Transpose021VCONVTilingData {
+    int64_t AvailableUbSize;
+    int64_t UsedCoreNum;
+    int64_t NLen;
+    int64_t HLen;
+    int64_t WLen;
+    int64_t HAlignBlockElem;
+    int64_t WAlignBlockElem;
+    int64_t NPerCore;
+    int64_t NTailCore;
+    int64_t UbLoopCount;
+    bool UseRConv;
+    bool UseHSplit;
+    int64_t HPerCore;
+    int64_t HTailCore;
+    Transpose021UbSplitPara rUbSplitPara;
+    Transpose021UbSplitPara cUbSplitPara;
+};
+#pragma pack(pop)
+
+#endif // TRANSPOSE_TILING_DATA_H

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

@@ -0,0 +1,220 @@
+# Transpose 性能调优参考:BIG_DIM(高维转置)
+
+- 策略名:BIG_DIM(高维转置)
+- tilingKey:10005(`transpose_kernel.cpp` 中宏 `BIG_DIM 10005`)
+- kernel 实现:`arch35/transpose_big_dim.h`,类 `TransposeBigDim`
+- host 选择/切分:`transpose_tiling.cpp` 中 `EntryTilingTemplate`、`DoSplitUBBigDim`、`FlushBaseNumForBigDim`、`CalcBlockSplitInfoForBigDim`
+
+本文面向性能调优开发者,内容以上述代码为准。
+
+---
+
+## 一、适用场景
+
+### 为什么需要专门的高维策略
+
+其它 NDDMA 系列策略(NDDMA_BASE、CUT_ONCE、CUT_TWICE 等)依赖硬件 NDDMA(N 维 DMA)搬运指令,一次搬运能描述的维数受硬件上限约束。代码中该上限为常量:
+
+```cpp
+// transpose_base.h
+constexpr int64_t NDDMA_MAX_DIM_NUM = 5;   // NDDMA 一次最多描述 5 维
+```
+
+kernel 侧的多维搬运参数结构也被固定成 `NDDMA_MAX_DIM_NUM` 维:`MultiCopyLoopInfo<NDDMA_MAX_DIM_NUM>`、`MultiCopyParams<T, NDDMA_MAX_DIM_NUM>`。也就是说,一条 NDDMA 指令的 loop 描述最多只有 5 个维度(loopSize / src stride / dst stride)。
+
+当算子的 reduce 之后维度(`shapeInfo_.dim`)超过 5 时,无法用一条 NDDMA 指令覆盖全部维度。`EntryTilingTemplate` 中的分派逻辑正是据此选择:
+
+```cpp
+// transpose_tiling.cpp EntryTilingTemplate()
+if (shapeInfo_.dim <= NDDMA_MAX_DIM_NUM) {
+    tilingKey_ = KEY_NDDMA_BASE;   // <=5 维,单指令可覆盖
+} else {
+    tilingKey_ = KEY_BIG_DIM;      // >5 维,走高维专用策略
+}
+```
+
+前置条件:只有当总数据量达到阈值(`totalVolumeActual * eleLenInBytes >= SMALL_SHAPE_BYTES_THRES_HOLD`)且不满足 N_LAST 特例时,`dim > 5` 才会落到 BIG_DIM;否则走 SMALL_SHAPE 等策略。
+
+### 它解决什么问题
+
+BIG_DIM 解决的核心问题是:**维数超过 NDDMA 硬件上限(5)时,如何仍然用 NDDMA 高效完成任意 perm 的转置**。
+
+思路是把高维转置拆成两层:
+
+1. **外层软件循环(host + kernel 协同)**:把「不进 NDDMA 的那些维度」以及被切分维度的分块,折叠成一个一维的 `loopIdx` 计数,由多核和 kernel 内循环遍历。每个 `loopIdx` 对应一次 NDDMA 搬运。
+2. **内层 NDDMA 硬件搬运**:每个 `loopIdx` 内,用一条最多 5 维的 NDDMA 指令搬运一块连续/带 stride 的子张量,由硬件完成这 5 维范围内的重排。
+
+### 为什么能提升性能
+
+- 内层仍然使用 NDDMA 硬件多维搬运,享受硬件带 stride 的多维搬运能力,避免退化为逐元素 gather/标量搬运。
+- 外层把无法放进 NDDMA 的维度折叠成一维 `loopIdx`,天然可按 `loopIdx` 做多核均分(`CalcBlockSplitInfoForBigDim` + `ParseMultiCoreRange`),核间负载均衡。
+- UB 分块因子(`outUbFactor`)在 host 侧按 UB 容量和核数联合寻优,尽量让核用满(`VEC_CORE_USED_THRES_HOLD`),兼顾单次搬运粒度与并行度。
+
+---
+
+## 二、kernel 执行流程与关键实现
+
+### 维度映射:哪 5 维进 NDDMA(host `FlushBaseNumForBigDim`)
+
+host 侧需要从 >5 维中,挑出「最内侧的、连续的」维度交给 NDDMA。按输出维序从最内(`dim-1`)向外遍历,填充 `nddmaIdx_`(记录进 NDDMA 的是原 perm 的哪个轴)与 `baseNddmaShape_`(该轴在 NDDMA 输出内的 stride 基数),同时累计 `totalNddmaNum_`(一次 NDDMA 搬运的元素总量):
+
+```cpp
+// transpose_tiling.cpp FlushBaseNumForBigDim() 关键片段
+for (int64_t i = shapeInfo_.dim - 1; i >= 0; i--) {
+    baseInShape_[i] = baseInNum;
+    baseInNum *= shapeInfo_.reducedInShape[i];
+    if (i > splitInfo_.outCutIndex) {          // 切分点更内侧:整轴进 NDDMA
+        nddmaIdx_[idxNum] = shapeInfo_.reducedPerm[i];
+        tmpNddmaShape[idxNum] = totalNddmaNum_;
+        totalNddmaNum_ *= shapeInfo_.reducedOutShape[i];
+        idxNum--;
+    } else if (i == splitInfo_.outCutIndex) {  // 切分轴:只进 outUbFactor 份
+        nddmaIdx_[idxNum] = shapeInfo_.reducedPerm[i];
+        tmpNddmaShape[idxNum] = totalNddmaNum_;
+        totalNddmaNum_ *= splitInfo_.outUbFactor;
+        idxNum--;
+    } else if (idxNum >= 0) {                   // 切分点外侧:折叠到外层 loopIdx
+        nddmaIdx_[idxNum] = shapeInfo_.reducedPerm[i];
+        tmpNddmaShape[idxNum] = totalNddmaNum_;
+        idxNum--;
+    }
+}
+std::sort(std::begin(nddmaIdx_), std::end(nddmaIdx_));  // 按原始轴号排序
+// 排序后重建 baseNddmaShape_ 与 nddmaIdx_ 的对应关系
+```
+
+要点:
+- `outCutIndex`(输出切分轴)以内的维度整轴进 NDDMA;切分轴本身只取 `outUbFactor` 份进 NDDMA;更外侧维度不进 NDDMA,交给外层 `loopIdx`。
+- `nddmaIdx_` 最终经 `std::sort` 排序,`baseNddmaShape_` 随之重排,使 NDDMA 内部按输入侧轴序索引一致。
+- UB 分块由 `DoSplitUBBigDim` 决定:从最内维往外找,直到 `ubElement < reducedOutShape[i]` 或剩余可用 NDDMA 维数(`dimSize`,初始 `NDDMA_MAX_DIM_NUM-1`)耗尽,确定 `outCutIndex / outUbFactor / outTailFactor`。
+
+### Init
+
+```cpp
+// transpose_big_dim.h
+void Init(...) {
+    blockIdx_ = GetBlockIdx();
+    tiling_ = tilingData;
+    inputGM_.SetGlobalBuffer((__gm__ T*)x);
+    outputGM_.SetGlobalBuffer((__gm__ T*)y);
+    pipe->InitBuffer(vecQue_, 1, tiling_->ubSize);   // 单块 UB
+}
+```
+
+注意:`vecQue_` 使用 `TQueBind<VECIN, VECOUT, 1>`,buffer 深度为 1(单缓冲,in/out 复用同一块 UB),本策略未使用 double buffer。
+
+### Process 主流程
+
+```mermaid
+flowchart TD
+    A[Process] --> B[ParseMultiCoreRange: 按 blockIdx 分配 loopIdx 区间]
+    B -->|本核无任务| Z[return]
+    B --> C[SetLoopInfo: 构建 NDDMA 5 维 loop 描述]
+    C --> D[构造 copyOut 参数 main/tail]
+    D --> E[组装 paramsMain / paramsTail]
+    E --> F[ProcessPerCore]
+    F --> G[预计算 mixedBase / dstLoopStride / srcLoopStride]
+    G --> H{遍历 loopIdx}
+    H -->|尾块| I[CopyIn paramsTail + CopyOut Tail]
+    H -->|主块| J[CopyIn paramsMain + CopyOut Main]
+```
+
+多核切分:`ParseMultiCoreRange`(在 `transpose_base.h`)根据 `realCoreNum / blkFactor / blkTailFactor` 把外层 `loopIdx` 空间均分给各核,返回本核区间 `[blkProcessIdxStart_, blkProcessIdxEnd_)`;`blockIdx_ >= realCoreNum` 的核直接返回不参与。
+
+### SetLoopInfo:构建 NDDMA 5 维搬运描述
+
+为每个 NDDMA 维打标 `nddmaFlag`,区分三类:
+
+- `== -1`:该 NDDMA 轴正好是被切分的输出轴(`perm[outCutIndex]`)→ loopSize 取 `outUbFactor`,记录 `cutIdx_`。
+- `== 1`:该轴位于切分点之后(属于 NDDMA 内部整搬运的轴)→ loopSize 取输入 shape,src stride 取 `baseInShape`,dst stride 取 `baseNddmaShape`。
+- 其它:loopSize=1,仅带 dst stride。
+
+```cpp
+// transpose_big_dim.h SetLoopInfo() 核心分支
+if (nddmaFlag[...] == 1) {
+    loopInfo.loopSize[i]      = tiling_->inputShape[nddmaIdx];
+    loopInfo.loopSrcStride[i] = tiling_->baseInShape[nddmaIdx];
+    loopInfo.loopDstStride[i] = tiling_->baseNddmaShape[...];
+} else if (nddmaFlag[...] == -1) {
+    cutIdx_ = i;
+    loopInfo.loopSize[i]      = tiling_->outUbFactor;
+    loopInfo.loopSrcStride[i] = tiling_->baseInShape[nddmaIdx];
+    loopInfo.loopDstStride[i] = tiling_->baseNddmaShape[...];
+} else {
+    loopInfo.loopSize[i] = 1; loopInfo.loopSrcStride[i] = 1;
+    loopInfo.loopDstStride[i] = tiling_->baseNddmaShape[...];
+}
+```
+
+`loopLpSize/loopRpSize`(左右 pad)全部置 0,本策略不做 padding。
+
+### 主块 / 尾块
+
+`outCutIndex` 轴被 `outUbFactor` 切分,末尾可能剩余 `outTailFactor` 份:
+
+```cpp
+copyOutParamsMain.blockLen = tiling_->totalNddmaNum * sizeof(T);
+copyOutParamsTail.blockLen =
+    tiling_->totalNddmaNum / tiling_->outUbFactor * tiling_->outTailFactor * sizeof(T);
+// 尾块把 cutIdx_ 维的 loopSize 改成 outTailFactor
+if (tiling_->outTailFactor != 0) {
+    loopInfo.loopSize[cutIdx_] = tiling_->outTailFactor;
+}
+```
+
+`ProcessPerCore` 中判定:当 `outTailFactor != 0` 且 `(loopIdx+1) % outCutLoopSize == 0` 时走尾块参数,否则走主块。`outCutLoopSize = CeilDiv(outputShape[outCutIndex], outUbFactor)`。
+
+### 索引映射:loopIdx → 混合进制 → GM 地址(CopyIn/CopyOut)
+
+外层 `loopIdx` 是把「切分轴的分块 + 切分点外侧各维」折叠成的一维计数。`ProcessPerCore` 先预计算每一位的进制 `dstAddressOffsetMixedBase_` 与各维步长 `dstLoopStride_ / srcLoopStride_`:
+
+```cpp
+// 逐维累乘构造 stride,切分轴步长再乘 outUbFactor
+if (i >= 1) {
+    dstLoopStride_[i] = dstLoopStride_[i-1] * tiling_->outputShape[permSize - i];
+    srcLoopStride_[i] = srcLoopStride_[i-1] * tiling_->inputShape[permSize - i];
+}
+dstLoopStride_[permSize-1-outCutIndex]           *= outUbFactor;
+srcLoopStride_[permSize-1-perm[outCutIndex]]     *= outUbFactor;
+```
+
+`DecimalToMixed` 把一维 `loopIdx` 按混合进制展开成各维坐标 `dstAddressOffsetMixedBaseRes_`(十进制 → 混合进制转换):
+
+```cpp
+void DecimalToMixed(int64_t num, int64_t bases[], int64_t mixedBase[]) {
+    for (int64_t i = 0; i < permSize; i++) {
+        mixedBase[i] = num % bases[i];
+        num /= bases[i];
+        if (num == 0) break;
+    }
+}
+```
+
+- CopyIn:用 perm 把输出坐标映射回输入坐标,累加得 `srcAddressOffset`,再发 NDDMA `DataCopy<T, NDDMA_MAX_DIM_NUM, config>` 把子张量搬进 UB。
+- CopyOut:直接用输出坐标累加 `dstAddressOffset`,`DataCopyPad` 把 UB 结果写回 `outputGM_`。
+
+```cpp
+// CopyIn:输出坐标 -> 输入偏移(perm 逆映射)
+srcAddressOffset += dstAddressOffsetMixedBaseRes_[i] *
+                    srcLoopStride_[permSize - 1 - perm[permSize - 1 - i]];
+// CopyOut:输出坐标 -> 输出偏移
+dstAddressOffset += dstAddressOffsetMixedBaseRes_[i] * dstLoopStride_[i];
+```
+
+维度重排本身由内层 NDDMA 依据 `loopSrcStride/loopDstStride`(源按输入布局带 stride 读、目的按 NDDMA 连续布局写)完成;外层负责把「装不进 NDDMA 的高维」逐块定位到正确 GM 地址。
+
+### 关键技术小结(按代码实际)
+
+- **NDDMA 多维搬运**:内层 `DataCopy<T, NDDMA_MAX_DIM_NUM, config>` + `DataCopyPad`,一次最多 5 维带 stride 搬运,完成 NDDMA 范围内的重排。
+- **维度折叠 + 混合进制索引**:`FlushBaseNumForBigDim`(host)划定进 NDDMA 的维度,`DecimalToMixed`(kernel)把外层一维 `loopIdx` 还原为多维坐标,突破 5 维硬件上限。
+- **多核切分**:按外层 `loopIdx` 空间用 `ParseMultiCoreRange` 均分,`CalcBlockSplitInfoForBigDim` 在 host 按核数寻优 `outUbFactor`(阈值 `VEC_CORE_USED_THRES_HOLD`)。
+- **主/尾块处理**:切分轴非整除时用 `outTailFactor` 单独构造 tail 参数。
+- **UB 缓冲**:单块 UB(`InitBuffer(vecQue_, 1, ubSize)`),in/out 复用,**未使用 double buffer**。
+
+---
+
+## 调优提示
+
+- 若观察到核利用率不足,关注 host 侧 `outUbFactor` 是否被 `VEC_CORE_USED_THRES_HOLD` 逻辑压小以换取更多并行块;单块搬运粒度(`totalNddmaNum`)过小会拉低 NDDMA 效率。
+- BIG_DIM 单缓冲、无 double buffer,搬入搬出串行;其性能主要取决于每块 NDDMA 的连续度与多核均衡,而非流水掩盖。
+- 维数恰为 5 时不会进入 BIG_DIM(走 NDDMA_BASE);只有 reduce 后维度 > 5 才触发本策略。

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

@@ -0,0 +1,175 @@
+# Transpose 单轴切分策略 (CUT_ONCE) 性能调优参考
+
+- 策略名:CUT_ONCE(单轴切分)
+- tilingKey:`10002`
+- kernel 实现:`transpose_cut_one_axis.h`,类 `TransposeCutOneAxis<T>`
+- 派发入口:`transpose_kernel.cpp`(`tilingKey == CUT_ONCE`)
+- host 选择逻辑:`transpose_tiling.cpp`(`DoSplitUB` / `CalcBlockSplitInfoForCutOnce` / `CalcInUbShapeInfoForCutOnce`)
+
+本文面向性能调优开发者,描述 CUT_ONCE 在什么场景下被选中、为何能提升性能,以及 kernel 侧的执行流程与关键实现。所有结论以上述源码为准。
+
+---
+
+## 一、适用场景
+
+### 1. Transpose 为什么要切分 UB
+
+Transpose(转置/permute)本质是把输入按 `perm` 重排到输出,只搬字节、不做算术。arch35 的 NDDMA 家族用一次 `DataCopy`(MTE2,支持多维 stride 的搬入)把一块数据搬进 UB,再用 `DataCopyPad`(MTE3)按目标布局搬出,从而在一次 in/out 中完成维度重排。
+
+问题在于 UB 容量有限:整块 shape 通常放不下。因此 host 侧需要沿某些轴做切分,让每次进 UB 的 tile 既能放下、又能让多核充分并行。切分策略的核心矛盾就是 **UB 容量 vs shape 大小**。
+
+### 2. host 侧如何切分并区分 CUT_ONCE / CUT_TWICE
+
+NDDMA 家族(`KEY_NDDMA_BASE` 分支)在 `CalcUBSplitInfo` 里先把 UB 可容纳的元素数开平方作为输入侧的初始预算:
+
+```cpp
+splitInfo_.inUbElement = sqrt(splitInfo_.ubElement);
+DoSplitUB();
+```
+
+`DoSplitUB` 分两步:
+
+1. `DoSplitUBInput()`:从输入最内轴往外走,能整轴放下就整轴吃掉、更新剩余预算;放不下的那一轴成为 **输入切分轴 `inCutIndex`**,并确定 `inUbFactor`(该轴每次进 UB 的份数)、`inTailFactor`(尾块)。剩余 UB 预算 `outUbElement = ubElement / inUbActual` 留给输出侧。
+2. 沿输出轴(按 `reducedPerm` 从内往外)继续切,选出 **输出切分轴 `outCutIndex`** 与 `outUbFactor`,同时兼顾多核数量(`coreNum_`)。
+
+关键的策略判定在 `DoSplitUB` 末尾:
+
+```cpp
+if (splitInfo_.outCutIndex > FindOutIndex(splitInfo_.inCutIndex)) {
+    tilingKey_ = KEY_CUT_TWICE;   // 10003
+} else {
+    tilingKey_ = KEY_CUT_ONCE;    // 10002
+}
+```
+
+`FindOutIndex(inCutIndex)` 返回输入切分轴在输出(perm)序中的位置。含义:
+
+- **CUT_ONCE(本策略)**:当输出侧需要切分的位置 `outCutIndex` 不比输入切分轴在输出序中的位置更靠外(`outCutIndex <= FindOutIndex(inCutIndex)`),说明**一根轴的切分即可同时满足输入与输出的 UB 约束**——输入切分轴投影到输出序上的那次切分,已经覆盖了输出侧需要的切分,无需在输出侧再引入独立的第二次切分。此时只需一次切分,数据在 UB 里是连续/规整的,搬入搬出的 loop 结构简单。
+- **CUT_TWICE**:当 `outCutIndex > FindOutIndex(inCutIndex)`,输入和输出各自需要在不同的轴上切分,一次切分无法同时满足两侧,必须切两次(输入一次、输出一次),并额外处理 input-tail / output-tail / tail 三类边界(见 `GetIntervalInfoForCutTwice`),loop 与地址计算都更复杂。
+
+### 3. 为什么 CUT_ONCE 能提升性能
+
+- 只需单轴切分,`CalcInUbShapeInfoForCutOnce` 生成的 UB tile 布局规整,搬出时的 `DataCopyPad` loop 层级更浅(`CopyOut` 里的 `endIndex` 之后一般只剩少数几层 loop),MTE3 指令数少。
+- 相比 CUT_TWICE 没有 input-tail/output-tail 的交叉边界组合,尾块处理只有一种(`outTailFactor`),分支简单、气泡少。
+- `CalcBlockSplitInfoForCutOnce` 会在核数不足时(`outUbAxis < coreNum_`)回退调小 `outUbFactor` 以拆出更多可并行的块,尽量把 `VEC_CORE_USED_THRES_HOLD` 之上的多核利用率吃满,同时用 `UbOutOfBoundCheck` 保证不超 UB。
+
+### 4. 多核块划分要点(`CalcBlockSplitInfoForCutOnce`)
+
+- 若输入切分轴恰好就是输出切分轴对应的输入轴(`inCutIndex == reducedPerm[outCutIndex]`),把 `outUbFactor *= inUbFactor` 合并,尾块随之更新。
+- 若 `outUbFactor` 已等于整轴长度,则改用 `FindOutIndex(inCutIndex)` 作为输出切分轴,`outUbFactor = inUbFactor`。
+- 总并行块数 `outUbAxis = CeilDiv(outShape[outCutIndex], outUbFactor) * (outCutIndex 之前、perm<inCutIndex 的轴乘积)`,再交给 `SetRealCoreNumAndBlkFactor` 换算 `realCoreNum / blkFactor / blkTailFactor`。当块数不足核数时,从大到小回退 `outUbFactor` 找到满足多核阈值又不超 UB 的因子。
+
+---
+
+## 二、kernel 执行流程与关键实现
+
+kernel 侧仅使用一块 UB 队列做 in→out 直通搬运,不含 vector 计算。核心类 `TransposeCutOneAxis<T>` 继承自 `TransposeBase<T>`。
+
+### 1. 缓冲与队列
+
+```cpp
+TQueBind<QuePosition::VECIN, QuePosition::VECOUT, 1> vecQue_;  // depth = 1
+GlobalTensor<T> inputGM_, outputGM_;
+```
+
+- 用 `TQueBind<VECIN, VECOUT, 1>`:同一块 UB 既作搬入(VECIN)又作搬出(VECOUT)的绑定队列,搬入 `EnQue` 后直接 `DeQue` 搬出,中间不做运算。
+- 队列深度为 1,`InitBuffer(vecQue_, 1, tiling_->ubSize)` 只分配一块 buffer。**注意:本策略未开启 double buffer**(深度=1、buffer 数=1),`BUFFER_NUM=2` 常量在此 kernel 未被使用;流水靠 MTE2/MTE3 与队列同步驱动,而非双缓冲乒乓。
+
+### 2. Init 流程
+
+```cpp
+Init(x, y, tilingData, pipe):
+    blockIdx_ = GetBlockIdx();
+    tiling_ = tilingData;
+    ParseTilingData();                       // expandedOutputCutIndex_ = outCutIndex + 5 - permSize
+    inputGM_.SetGlobalBuffer(x);
+    outputGM_.SetGlobalBuffer(y);
+    pipe->InitBuffer(vecQue_, 1, tiling_->ubSize);
+```
+
+`ParseTilingData` 把 host 的 `outCutIndex` 映射到 NDDMA 固定 5 维(`NDDMA_MAX_DIM_NUM=5`)展开后的下标 `expandedOutputCutIndex_`(host 侧对不足 5 维的 shape 做了右对齐扩展,见 `NDDMADimExpand`)。
+
+### 3. Process / ProcessPerCore 流程
+
+```mermaid
+flowchart TD
+    A[Process] --> B{ParseMultiCoreRange<br/>blockIdx < realCoreNum?}
+    B -- 否 --> Z[本核无任务, return]
+    B -- 是 --> C[ProcessPerCore]
+    C --> D[GetLoopParams 逐轴<br/>算 main/tail 的 loopSize 与 stride]
+    C --> E[GetLoopAndStride<br/>算 src/dst 全局地址 stride 与 loopSize]
+    C --> F[SetupLoopInfo main<br/>构造 MTE2 MultiCopy 参数]
+    C --> G[循环 loopIdx = start..end]
+    G --> H{是否 tail?<br/>outTailFactor!=0 且 loopIdx+1 是 outCutLoop 边界}
+    H -- 是 --> I[SetupLoopInfo tail + CopyIn + CopyOut tail]
+    H -- 否 --> J[CopyIn main + CopyOut main]
+```
+
+- **多核范围** `ParseMultiCoreRange`(基类):由 `blkFactor / blkTailFactor` 计算本核负责的 `[blkProcessIdxStart_, blkProcessIdxEnd_)`。前 `blkTailFactor` 个核多分 1 个块,做到负载均衡;`blockIdx >= realCoreNum` 的核直接返回。
+- **loop 参数** `GetLoopParams` 逐轴(reverse 下标)填 `loopSizeMain_/loopSizeTail_` 及 `loopSrcStrideMain_/loopDstStrideMain_`。在输出切分轴对应位置(`n == NDDMA_MAX_DIM_NUM - expandedOutputCutIndex_`)对 src stride 做 32B(`BLOCK_SIZE_BYTE`)对齐(`CeilAlign`),保证 UB 内每行按 block 对齐。
+- **地址 stride** `GetLoopAndStride` 用 `expandedInputShape/expandedOutputShape` 反推各维全局 stride,并在切分轴上乘 `outUbFactor` 得到块间步长;`srcLoopSize_/dstLoopSize_` 是各维的块数(`CeilDiv(shape, ubShape)`),供混合进制地址换算使用。
+
+### 4. 搬入 CopyIn(MTE2, NDDMA DataCopy)
+
+```cpp
+CopyIn(loopIdx, params):
+    DecimalToMixed(loopIdx, dstLoopSize_, dstAddressOffsetMixedBase_);   // 线性块号 -> 多维块坐标
+    for i in 0..5:
+        srcAddressOffsetMixedBase_[perm[i]] = dstAddressOffsetMixedBase_[i];
+        srcAddressOffset += ... * srcLoopStride_[perm[i]];               // 按 perm 反查输入地址
+    localIn = vecQue_.AllocTensor();
+    DataCopy<T, 5, config>(localIn, inputGM_[srcAddressOffset], params); // 多维 stride 搬入
+    vecQue_.EnQue(localIn);
+```
+
+- `DecimalToMixed` 把线性 `loopIdx` 按各维块数 `dstLoopSize_` 拆成混合进制的多维块坐标(输出视角)。
+- 通过 `perm` 把输出块坐标映射回输入,累加得到输入起始地址 `srcAddressOffset`——**这一步就是转置:搬入即按输入布局取,搬出按输出布局写。**
+- `DataCopy<T, 5, config>` 是 NDDMA 的多维搬运,`params`(`MultiCopyParams`)由 `SetupLoopInfo` 生成,携带每维 `loopSize / loopSrcStride / loopDstStride`。`SetupLoopInfo` 里对输出切分轴前一维的 dst stride 做 32B 对齐,并用 `expandedPerm` 把 dst stride 重排到输出序;最后 `reverseArray` 把 5 维数组翻转以匹配 NDDMA 的维序约定。
+
+### 5. 搬出 CopyOut(MTE3, DataCopyPad + LoopMode)
+
+```cpp
+CopyOut(loopIdx, loopSize, loopSrcStride, loopDstStride):
+    dstAddressOffset = Σ dstAddressOffsetMixedBase_[i] * dstLoopStride_[i];
+    copyOutParams.blockLen = sizeof(T);
+    // 从最内维累乘 blockLen,直到遇到 “被切分/不整轴” 的维 -> endIndex
+    ... 设定 blockCount / dstStride ...
+    // endIndex 之后剩余维用 LoopModeParams 的 loop1/loop2 承载
+    localOut = vecQue_.DeQue();
+    DataCopyPad(outputGM_[dstAddressOffset], localOut, copyOutParams);   // 带 pad 的多维搬出
+    vecQue_.FreeTensor(localOut);
+```
+
+- 通过扫描 `expandedOutputShape[i] != inUbMainDstShape[i]` 找到第一处“非整轴”维 `endIndex`,把它之内的连续维合并成一次 `blockLen` 的连续搬出,`blockCount / dstStride` 描述次外层,更外层用 `LoopModeParams` 的 `loop1/loop2`(必要时再套一层 `loop4` 手动循环)承载。这样把多维搬出压成尽量少的 `DataCopyPad` 调用。
+- `SetLoopModePara(..., UB_TO_OUT)` / `ResetLoopModePara` 成对使用,配置 MTE3 的多重循环搬运模式。
+- CUT_ONCE 因为只切一轴,`endIndex` 之后残余维通常很少,`DataCopyPad` loop 层级浅,MTE3 效率高。
+
+### 6. main / tail 分流
+
+`ProcessPerCore` 主循环里:
+
+```cpp
+outCutLoopSize = CeilDiv(expandedOutputShape[expandedOutputCutIndex_], outUbFactor);
+if (outTailFactor != 0 && (loopIdx + 1) % outCutLoopSize == 0)  // 该切分轴的最后一块 -> tail
+    CopyIn(paramsTail); CopyOut(tail);
+else
+    CopyIn(paramsMain); CopyOut(main);
+```
+
+切分轴无法整除时,每一轮切分的最后一个块用 tail 参数(`inUbTailSrcShape/inUbTailDstShape` + `loopSizeTail_` 等),其余用 main 参数。CUT_ONCE 只有这一种尾块分支,不像 CUT_TWICE 需要 input-tail/output-tail/tail 四类组合。
+
+---
+
+## 关键技术小结
+
+| 技术点 | 是否使用 | 说明 |
+|---|---|---|
+| 多核切分 `ParseMultiCoreRange` | 是 | 按 `blkFactor/blkTailFactor` 均衡分块 |
+| `TQueBind<VECIN,VECOUT,1>` | 是 | in→out 直通,单块 buffer,无运算 |
+| double buffer | 否 | 队列深度=1,未开启乒乓双缓冲 |
+| NDDMA `DataCopy`(MTE2) | 是 | 多维 stride 搬入,搬入即完成 perm 取址 |
+| `DataCopyPad` + LoopMode(MTE3) | 是 | 多维带 pad 搬出,loop 层级浅 |
+| 混合进制地址换算 `DecimalToMixed` | 是 | 线性块号 → 多维块坐标 → 经 perm 反查输入地址 |
+| 32B 对齐(`CeilAlign`/`BLOCK_SIZE_BYTE`) | 是 | UB 内行按 block 对齐,保证搬运效率 |
+
+调优时重点关注:切分轴选择是否让 `outUbFactor` 足够大以摊薄 MTE3 开销、同时块数是否达到 `realCoreNum` 以吃满多核;当 shape 使得输入/输出需在不同轴切分时会退化为 CUT_TWICE,此时 loop 与尾块开销更高。