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

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/index/patterns.md

@@ -0,0 +1,199 @@
+# Index 类算子场景路由
+
+> 本文档用于**场景判定**和**策略选择**。确定场景后，按链接进入对应详细文档。
+> 本文档与各 Pattern 文档面向 **A2/A3 代际**（910B / 910C，`arch22`，`dav_c220` / `DAV_2201`，
+> 单核 UB 192KB），实测基线为 Ascend 910B3 / CANN 9.0.0。
+
+---
+
+## 场景判定流程
+
+Index（索引类）：以索引为核心访问数据——index 决定"从输入哪里取数"或"数据写到输出哪里"，存在跨元素寻址，输出形状/写位置不独立于 index。典型算子：Gather、GatherElements、IndexSelect、Take、Scatter、ScatterElements、ArgMax/ArgMin（返回索引）。
+
+```
+给定: N 个输入 shape（value + index）+ M 个输出 shape
+
+Step 1 — 数据访问方向判定（决定数据流形态）:
+  index 决定从输入哪里取数（输出形状由 index 形状决定）？
+    ├─ YES → 读索引型（Gather 系）→ Step 2
+    └─ NO  → index 决定数据写到输出的哪里（index 形状 == 输出形状）？
+        ├─ YES → 写索引型（Scatter 系）→ Step 3
+        └─ NO  → 归约同时返回极值索引（ArgMax/ArgMin）？
+            ├─ YES → 归约索引型 → [../reduction/with-index.md](../reduction/with-index.md)
+            └─ NO  → 无 index 输入，输出位置由 repeats 解析确定（RepeatInterleave）？
+                ├─ YES → P7 [repeat_interleave.md](repeat_interleave.md)
+                └─ NO  → 待补充场景
+```
+
+```
+Step 2 — 读索引型（Gather 系）:
+  index 的形状与输出形状的关系？
+    ├─ index 与输出同形（每行一份 index，需按行分解前导维坐标）→ P2 [gather.md](gather.md)
+    ├─ index 是 1-D 全行共享（源行查找纯算术、输出行连续）→ P5 [index_select.md](index_select.md)
+    ├─ index 展平为 1D 连续取数（Take / Gather 展平取数）→ P1
+    └─ 其他取数形态 → 待补充
+```
+
+```
+Step 3 — 写索引型（Scatter 系）:
+  index 的形状？
+    ├─ index 与输出同形（逐元素映射）→ 按是否冲突分流:
+    │    ├─ 无冲突 / 后写覆盖（ScatterUpdate / ScatterElements）→ P3 [scatter.md](scatter.md)
+    │    └─ 有冲突需归约合并（ScatterReduce）→ P4 [scatter.md](scatter.md)
+    │   （P3/P4 共用同一分核与核内流程，仅写出语义不同）
+    └─ index 沿轴 1-D（一行 index 影响整个 inner 块）+ 累加语义（IndexAdd）→ P6 [index_add.md](index_add.md)
+```
+
+---
+
+## Pattern 清单
+
+> 各 Pattern 的详细设计文档**逐个补充**，补充前状态为"待补充"。
+
+| 编号 | 场景 | 典型算子 | 判定条件 | 状态 | 详细文档 |
+|------|------|---------|---------|------|---------|
+| P1 | 扁平索引取数 | Take, Gather(展平) | index 展平为 1D，按 offset 连续取数 | 待补充 | - |
+| P2 | 沿轴索引取数 | Gather, GatherElements | index 与输出同形，沿指定轴取数、需按行分解前导维坐标 | 已补充（三档模式：mode0 批量 / mode1 双轴分片，indexAxis 无上限 / mode2 scalar） | [gather.md](gather.md) |
+| P3 | 写索引覆盖 | ScatterUpdate, ScatterElements | index 形状与输出一致，写位置无归约冲突 | 已补充（按输出元素空间 64B 整块分核 + **UB 内 RMW 散写 + 批量回写**，快原生 3.2x） | [scatter.md](scatter.md) |
+| P4 | 写索引归约 | ScatterReduce | 同一写位置多次命中，需归约合并 | 已补充（与 P3 共用分核：输出元素单属主，累加无需原子） | [scatter.md](scatter.md) |
+| P5 | 沿轴单索引取数 | **IndexSelect** | index 为 1-D 全行共享，输出行连续、源行查找纯算术 | 已补充（mode0 纯搬运行/段拷贝 / mode1 Gather 向量化 + kSplit 防空核） | [index_select.md](index_select.md) |
+| P6 | 沿轴索引累加 | **IndexAdd** | index 沿轴 1-D，一行 index 影响整个 inner 块，累加语义 | 已补充（t-tile slab RMW + 选择性 upd 行搬入 + **per-core 命中表**，实测 1.04~17.50x） | [index_add.md](index_add.md) |
+| P7 | 沿轴重复展开 | **RepeatInterleave** | 无 index 输入，展开位置由 repeats 解析确定（前缀和） | 已补充（不物化 index → bit-exact；mode0 段拷贝 / mode1 展开下标 + Gather） | [repeat_interleave.md](repeat_interleave.md) |
+
+---
+
+## 通用规则
+
+以下规则适用于所有 Index 分支。
+
+- **UB 预算**：value 与 index 都需要搬入 UB，UB 预算需同时计入两者（index 通常为 int32）
+- **index 与 value 的依赖**：取数/写数的目标位置由 index 值决定，无法像 EleWise 一样按地址连续性直接流水，切分策略需围绕 index 的布局设计
+- **多核对齐 / 切分基准**：读索引型按行或按元素总量分核（输出与 index 一一对应，无写冲突）；
+  写索引型按**输出元素空间**分核（见下条红线）
+- **🛑 写索引型的多核切分基准是「输出元素空间」，不是 index 元素空间**：
+  AI Core 标量写 GM 时，两个核并发写同一条 64B cache line 的不同 32B sector 会丢失其中一个
+  sector（表现为某些元素完全未写入、且无错值）。读索引型（Gather）按 index 元素量分核是安全的
+  （输出与 index 一一对应），但写索引型必须按输出空间按 64B 对齐整块分核、每核独占连续整块。
+  详见 [scatter.md §3](scatter.md)
+- **🛑 写索引型不要用标量直接写 GM，要在 UB 内散写后整片回写**：
+  散射地址由 index 值决定、无法连续 `DataCopy` 搬出，标量写不可避免；但**标量写的目标应是 UB**
+  （GM 标量写延迟约 55 cycles/迭代，UB 标量写快一个数量级）。流程：
+  `DataCopyPad` 从**输入**整片读入基准片 → 向量化「负索引修正 + 片基址重定位」→ 标量 UB 散写 →
+  `DataCopyPad` 整片回写输出。实测把 scatter 从 0.45x 提到 3.2x。详见 [scatter.md §2/§4](scatter.md)
+- **🛑 不要用 `clone` 给输出做初值：kernel 直接「读 x 写 y」，torch 侧 `at::empty_like`**：
+  需要保留输入原值再改写的 Pattern（如 IndexAdd、Scatter 覆盖写）若先 `var.clone()` 再原地改，
+  会多一次全量设备拷贝（读+写），且 clone 是 torch 算子、会 enqueue 进延迟队列，
+  对 kernel 可能不可见（竞态）。正确做法是 kernel 直接从 x 读基准、把结果写独立输出 y——
+  前提是**工作单元划分恰好覆盖整个输出空间**：IndexAdd 的 `units = outer*tTiles*iTiles` 满足；
+  Scatter 按输出元素空间 64B 对齐分核同样满足，但**核内必须遍历输出的全部行**——
+  index 前部维小于输入时输出存在「无对应 index 行」的行（如 `x=(8,32,16)` /
+  `index=(4,16,8)` / `dim=1`），这些行要按输入原值整片回写，只遍历 index 行会漏写
+  （实测 Max diff 5.24，详见 [scatter.md §3/§4](scatter.md)）。
+  纯读型（IndexSelect / RepeatInterleave）输出全新、本来就不需要 clone，用 `at::empty` 即可。
+  详见 [index_add.md](index_add.md)
+- **🛑 `stream(true)` 必须在「所有 torch 侧算子之后」调用**：
+  `NPUStream::stream(true)` → `stream()` → `MakeSureQueueEmpty()`，会清空 torch_npu 的
+  延迟任务队列、把此前 enqueue 的 torch 算子真正下发。若先取 stream 再执行 `fill_`/`clone`，
+  这些算子会留在队列里没下发，kernel 读到 `at::empty` 的**未初始化内存** →
+  表现为「**首调用随机错、重跑即好、加 synchronize 即好**」。
+  诊断特征：失败集每次不同 + 对失败用例重复 5 次恒为「第 1 次失败后 4 次全过」。
+  详见 [index_add.md](index_add.md)
+- **⚠️ 单元内含「扫描全部 index」的 Pattern，成本 ∝ 单元数 × index 长度**：
+  当 UB 放不下整行导致单元数激增（如 `tTiles` 大）且 index 长时，标量扫描会成为瓶颈，
+  而非搬运（诊断：固定 shape 扫 index 长度，耗时线性增长即为扫描放大）。
+  缓解：branchless compaction（`selp[nSel]=k; nSel += hit;`）+ 4 路展开；
+  根治：每核只扫一次 index 并按 tile 分桶（per-core 命中表）。详见 [index_add.md §5](index_add.md)
+- **🛑 index 类型必须 host / kernel 一致，统一按 int32**：
+  host 侧 `index.to(at::kInt)`，kernel 侧 `GlobalTensor<int32_t>`；上游为 int64 时
+  （PyTorch 默认）须转换并**核对索引上界 < 2^31**（int32 溢出会越界读）。
+  UB 侧 `indexBuf` 容量也按 `sizeof(int32_t)` 计算（早期按 `sizeof(int64_t)` 的写法已废弃）
+- **⚠️ `DataCopyExtParams::blockLen` 是 `uint16_t`**（单次搬运 ≤ 65535 字节），
+  超过会报 `-Wc++11-narrowing` 编译错。片长（gather `chunkLen`、scatter `pieceCap`、
+  repeat_interleave 段长）**必须由 host 侧约束**，不能指望 kernel 内自适应
+- **⚠️ stride 单位**：`DataCopyExtParams::srcStride/dstStride` 在 **GM 侧为字节、UB 侧为 32B DataBlock**；
+  `DataCopyParams::stride` 是**块间隔**语义（不是字节偏移）。连续数据 stride 填 0。
+  最常见的写错：UB 侧 stride 用了字节（应除以 32）
+- **⚠️ 同步纪律：单缓冲 + 方向明确的事件同步，热路径禁用 `PipeBarrier<PIPE_ALL>()`**：
+  `PIPE_ALL` 会阻塞全部流水、把可并行的搬运与计算串行化。用 `SyncM2toV` / `SyncVtoM2` /
+  `SyncM2toM3` / `SyncVtoM3` 等方向明确的替代。**每一次「分片搬入」之前必须有对应的
+  `Sync?toM2`** —— 上一片的向量/标量计算仍在读该缓冲时被 MTE2 覆盖，会导致大 indexAxis
+  用例**稳定错位**（固定位置出错、输出 0.0）。
+  **单缓冲 + 大 chunk 优于双缓冲**：给 index/x 加双缓冲会挤占 chunk 长度、使同步轮数
+  增大 30~70%，净亏（瓶颈是**同步次数与搬运延迟**，不是带宽——实测带宽利用率仅 0.7~1.5 GB/s）
+- **⚠️ 不要忽视 host 固定开销**：小 shape 上 kernel 可能比 torch 快 2x 而端到端更慢，
+  瓶颈是 `at::empty` + launch（kernel 在途时 allocator 需延迟回收）。用输出缓冲池复用显存，
+  详见 [index_select.md](index_select.md) §Host 固定开销与输出缓冲池
+
+---
+
+## 常见问题排查
+
+| 现象 | 可能原因 | 解决方案 |
+|------|---------|---------|
+| 输出数据错位 | 缺少同步 | 搬入后补方向明确的事件同步（见各 Pattern 的同步链） |
+| 部分数据为 0 / 随机值 | 异步操作未完成 | 同上；`printf` 能"解决"只是因为它有延迟，不是正确做法 |
+| 行间数据串扰 | stride 计算错误 | 核对 srcStride/dstStride 单位（GM 字节 / UB 32B 块） |
+| 多核结果错误 | 分核方式错 | 读索引型按行或元素总量；写索引型按输出空间 64B 整块 |
+| 累加结果丢失/错误 | 多核写同一 cache line | **按输出元素空间 64B 对齐整块分核**，不要用 `SetAtomicAdd` |
+| 小 shape 端到端比 torch 慢但 kernel 更快 | host 固定开销（alloc + launch） | 用输出缓冲池复用输出显存 |
+| 大 `nidx` 的 mode0 index_add 慢 | 每单元扫描全部 index，放大 = 单元数 | 走 per-core 命中表 |
+| 3D+ 非尾轴行映射错位（2D 正常） | 行号→坐标分解顺序错 | 最后一个前导维变化最快，必须**从最后一维往前**分解 |
+| 大 shape 段错误 | 坐标分解顺序错 | 线性索引→多维坐标必须**从前到后**循环 |
+| `DataCopy` 搬出越界 / OOM（长度非 32B 对齐） | `DataCopy` 要求 32B 对齐，会按对齐长度多搬 | 改用 `DataCopyPad`（按字节精确搬出），`blockLen = 元素数 * sizeof(T)` |
+| 用了 `index.accessor<int64_t,1>()` 编译/运行失败，或 host 侧校验后耗时暴涨 | accessor 只支持 CPU 张量；`index.to(CPU)` 触发 **NPU→CPU 同步**（Host 从 ~20us 升到 9000+us） | **不要在 host 读 index 值**做数据级校验，只做 shape 级校验；范围校验放 kernel 端（见 [scatter.md](scatter.md) §7） |
+
+---
+
+## 验证与性能测量纪律
+
+索引类算子的正确性判定与性能测量有统一口径，避免误判。
+
+### 正确性口径
+
+- **bit-exact（逐位一致，max diff = 0）**：索引类算子的输出是**纯搬运 / 选值**，
+  不含浮点运算，因此默认要求逐位一致。
+- **例外：IndexAdd 用 `allclose`**：index_add 是累加，浮点累加顺序不同会引入末位差异，
+  用 `allclose`（而非 bit-exact）判定。
+- **负索引专项**：`torch.gather` **不支持负索引**，因此负索引用例的 golden 需单独用
+  `index % axis` 修正后再比对，不能直接用 `torch.gather` 当 golden。
+- **用例分层**：小 shape（功能）/ 大 shape（性能）/ 双轴分片专项 / 负索引专项 / 空 tensor。
+
+### 性能测量纪律
+
+- **多轮取最小值**：`bench(fn, iters=50, warmup=20, rounds=5)`，**取 min-of-5**。
+  每次采集前 `torch.npu.synchronize()`。
+- **设备波动**：NPU 共用设备波动可达 ±30% 常态（实测出现离散度 729%、1008%）。
+  离散度 > 10% 需复采；4 组取 min + 中位数交叉裁定。
+  **单次平均值会误判优化方向** —— 曾把噪声误读为「UB 预算变大导致变差」，
+  改用 min-of-5 后稳定提升（±1%）才显现。
+- **跨进程漂移可达 2~5x，必须同进程交错对照**：同一 case 的 custom/torch 耗时在不同进程间
+  漂移极大（index_select 实测 18us ↔ 49us），**跨进程比较会得出互相矛盾的结论**。
+  做 A/B 对照（如命中表 hit vs nohit）时必须：**同进程内交错执行各方案 + 提高轮次取 min
+  （rounds=25）**，否则无法归因。
+- **C++ 侧消融开关不能用 `static` 缓存 `getenv`**：若把 `getenv("XXX")` 的结果缓存进
+  `static` 变量，Python 侧运行中改 `os.environ` 后**不生效**，A/B 会全部跑到同一分支。
+  消融开关必须每次调用都重新读 `getenv`（去掉 `static`）。
+- **直调通路只验功能、不验性能**：直调 exe 的单次 launch 被**进程级冷启动**支配
+  （微小 shape 输出 512 元素仍耗 8.6ms）。权威性能数据取 **PyTorch 通路**。
+- **带宽口径**：`GB/s = (x.numel() + y.numel()) * element_size / 耗时`。
+  910B 的 L2 = 192MB，流量小于 L2 时测得的是 **L2 带宽**而非 HBM 带宽。
+
+---
+
+## 参考实现
+
+以下工程均已在 Ascend 910B3 上编译、上板验证：
+
+- `/data/fr/operator/gather_custom` - gather（三档 mode0/1/2）
+- `/data/fr/operator/index_custom` - index_select
+- `/data/fr/operator/index_add_custom` - index_add
+- `/data/fr/operator/scatter_custom` - scatter / scatter_add
+- `/data/fr/operator/repeat_interleave_custom` - repeat_interleave
+
+---
+
+## 跨场景参考
+
+| 主题 | 文档 |
+|------|------|
+| 归约索引型（ArgMax/ArgMin 返回极值索引） | [../reduction/with-index.md](../reduction/with-index.md) |

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/index/repeat_interleave.md

@@ -0,0 +1,251 @@
+# P7: 沿轴重复展开（RepeatInterleave）
+
+> 状态：已补充（2026-09-24，基于 RepeatInterleave 算子 910B（dav_c220）实战验证）
+> 硬件基线：Ascend 910B3 / dav_c220 / 40 个 AIV core / 单核 UB 192KB / L2 192MB / CANN 9.0.0
+>
+> **精度状态：bit-exact（max diff = 0）—— 这是结构性保证，不是调出来的**
+> **性能状态：大 shape 稳定领先（1.29~2.31x），`dim=None`（flatten）34~36x；
+> 小 shape 受 host 固定开销支配，两轮结果会翻转**
+
+## 适用场景
+
+```
+out = x.index_select(dim, arange(axis).repeat_interleave(repeats))
+```
+
+维度分解（与 P5/P6 同构）：
+
+- `outer = prod(shape[:dim])`
+- `axis = shape[dim]`
+- `inner = prod(shape[dim+1:])`
+- `total = sum(repeats)`
+
+元素映射：
+
+```
+x[(o * axis + t) * inner + i]  ->  y[(o * total + k) * inner + i]
+```
+
+即把 `dim` 轴上的第 `t` 个元素重复 `repeats[t]` 次后依次铺开，其余维度不变。
+
+- 典型算子：`torch.repeat_interleave`（`repeats` 可为标量或 1-D tensor）
+- **与 P5（IndexSelect）的区别**：IndexSelect 的 index 是外来的、任意的；
+  RepeatInterleave 的「index」是 `arange(axis).repeat_interleave(repeats)`——**有序且可解析**，
+  因此**不物化 index**（见下）
+
+**实现路线（路线 B：直接按 repeats 连续写）**：不物化 `srcIndex`，kernel 直接按
+「第 `t` 个输入元素占据输出区间 `[prefix[t], prefix[t]+r[t])`」推进输出行号。
+无 Cast、无浮点算术 → **精度 bit-exact 是结构性保证**。
+
+## 模式总览：两档动态策略
+
+| 模式 | 触发条件 | 策略 | UB buffer |
+|------|---------|------|-----------|
+| mode0 | `inner ≥ 2` | **段拷贝**：纯 MTE2 搬入 + 标量寻址 + MTE3 搬出，**无输出 buffer、无 `PIPE_V`** | `xBuf` + `tBuf` |
+| mode1 | `inner == 1` | **UB 内构造展开下标 + `Gather`**（与 gather / index_select 的 mode1 同构） | `xBuf` + `idxBuf` + `yBuf` + `tBuf` |
+
+> 分界点与 P5 一致：`inner == 1` 时连续搬运粒度只有 1 个元素，搬运动词退化成逐行标量，
+> 改用「UB 内构造展开下标 + 向量 `Gather`」一次处理整块。
+
+## 核心思路
+
+### 1. 两条路线，选「不物化 index」
+
+- **路线 A（物化 srcIndex）**：先算出 `arange(axis).repeat_interleave(repeats)` 存成 index 张量，
+  再走 index_select 的路子 —— 多一次全量 index 的构建与读写。
+- **路线 B（按 repeats 连续写）**：直接用前缀和推进输出行号，**不物化 index**。
+  本实现采用路线 B，也因此**没有任何浮点运算**，bit-exact 是结构性的。
+
+### 2. mode0 实现要点（段拷贝，主力路径）
+
+搬运单位是 **`(t, s)`**：`t` 为 `axis` 维下标，`s` 为 `inner` 维段下标（共 `segPerRow` 段）。
+
+1. **UB 只放「一批源行的同一段」**：`batchT * rowStride * es`，**与 `inner` 解耦**。
+   这是关键设计 —— 若按「一批源行的全部段」开 UB，当**单行段总字节 > UB 预算**时
+   `batchT` 会被钳到 1 仍然越界（WB-10 缺陷）。逐段循环复用则天然安全：
+   单段字节 `rowStride * es ≤ 65536 < avail`，`batchT` 天然 ≥ 2，**不存在 `B == 0` 越界路径**。
+2. **MTE2 只搬一次源行批次**：一批 `batchT` 个源行搬入后，MTE3 依次写出 `r[t]` 个
+   **连续输出行**的对应段。
+3. **输出行号用 `k` 累加器推进**（`k += r`），**禁止逐行做 `k / r` 整数除法**。
+   各段起点均为同一个 `kBase`，段处理完返回 `kBase + Σr`（各段一致）。
+4. **`r == 0` 直接 `continue`**，不产生任何 store。
+5. **同步红线**：每段独立 `load → SyncM2toM3 → store → SyncM3toM2`。
+   `SyncM2toM3` 等本段 x 搬入完成；`SyncM3toM2` 在下一段 load 覆盖 `xBuf` 前等本段 store 读完。
+
+```cpp
+for (uint32_t o = oStart; o < oEnd; ++o) {
+    uint32_t k = kStart;                       // 输出行累加器（无整数除法）
+    for (uint32_t tb = tStart; tb < tEnd; tb += batchT) {
+        uint32_t nT = min(tEnd - tb, batchT);
+        LoadBatchRepeats(tb, nT);
+        uint32_t kBase = k;
+        for (uint32_t s = 0; s < segPerRow; ++s) {
+            LoadBatchSegments(o, tb, nT, s);   // 逐行发起第 s 段搬入
+            SyncM2toM3();                      // 等本段 x 搬入完成（红线）
+            k = StoreBatchSegments(o, kBase, nT, s);  // 返回 kBase + Σr
+            SyncM3toM2();                      // 下一段 load 覆盖前，等本段 store 读完（红线）
+        }
+    }
+}
+```
+
+> **穿刺结论（不要重走）**：曾尝试用 `DataCopyPad` 多块复制写（`blockCount = r`、`srcStride = 0`）
+> 替代逐行搬出。**`srcStride` 的语义是「相邻数据块的间隔」，`srcStride = 0` 表示 UB 侧块间连续，
+> 并不等于「重复读同一 UB 段」** —— 因此多块复制写**不能**替代逐行搬出
+> （O5 穿刺失败，保留开关 `RI_USE_MULTIBLOCK_STORE` 默认 0）。
+
+### 3. mode1 实现要点（展开下标 + Gather）
+
+1. **x 块按 `t` 贪心分块**：从当前 `t` 起向后累加 `r`，直到 `K = Σr > kChunk` 为止；
+   块内 `t` 数 `L ≤ kChunk`。**单个 `t` 的 `r > kChunk`** 时拆成 `ceil(r / kChunk)`
+   次同值展开（每次 `chunk = min(remaining, kChunk)`）。
+2. **索引块每块构建一次、块内跨 `o` 复用**（O3）：`idxBuf` 存的是**展开后的源字节偏移**
+   （局部 `t` 下标 × `es`），与 `o` 无关，因此一个块内循环所有 `o` 时**只构建一次**。
+3. **Gather 后整块一次搬出**（O4）：`Gather(yLocal, xLocal, offsetLocal, 0, alignUp(K))`，
+   再一次 `DataCopyPad` 写 `K` 个元素。
+4. **`BuildIndexBlock` 两趟（满足 UB 向量访问 32B 对齐硬约束）**：
+   - **Pass 1（标量）**：写各 run 的**对齐头部**（每 run 最多 7 个元素）+ 尾部补 0；
+   - **Pass 2（向量）**：用 `Duplicate` 写各 run 的**对齐主体**（与 Pass 1 的头部区间不相交）。
+   - 标量步数是 `O(L)`，**不随 `outer` 增长** —— 这是该设计能扩展到大 `outer` 的关键。
+5. **同步链**：`SyncVtoS`（上一块 Gather 读完 `idxBuf` 后才能被标量覆盖）→
+   `SyncStoV`（标量写 `idxBuf` → 向量读）→ 每个 `o`：`SyncVtoM2` / `SyncM2toV`（Gather 前等 x）/
+   `SyncM3toV`（上一个 `o` 的 MTE3 读完 `yBuf`）/ `SyncVtoM3`（`yBuf` 就绪）。
+
+### 4. 分核：前缀和分核表（`tParts × oParts` 二维）
+
+因为每行展开后的长度可能不同（tensor repeats），分核**不能按行均分**，
+而要按**展开后的输出元素空间**均衡切分。
+
+```cpp
+uint32_t Q = (core < outer) ? core : outer;        // o 维分片数
+if (Q == 0) Q = 1;
+uint32_t P = core / Q;                             // t 维分片数
+if (P < 1) P = 1;
+if (P > RI_MAX_T_PARTS) P = RI_MAX_T_PARTS;
+t.tParts = P;  t.oParts = Q;  t.blockNum = P * Q;
+t.oPerCore = (outer + Q - 1) / Q;
+// kernel：core c → p = c / oParts（t 分片），q = c % oParts（o 分片，oStart = q * oPerCore）
+```
+
+**分核表 `coreTable`**（内联进 tiling，`2*(RI_MAX_T_PARTS+1)` 个 uint32）：
+`coreTable[2p] = tStart_p`、`coreTable[2p+1] = kStart_p`（`p ∈ [0, P]`，单调非降），
+末尾固定 `coreTable[2P] = axis`、`coreTable[2P+1] = total`。
+
+| 形态 | 分核表求法 |
+|------|-----------|
+| **int repeats** | **解析式**：`tStart_p = axis * p / P`，`kStart_p = r * tStart_p` |
+| **tensor repeats** | `prefix` 单调非降 → **单次线性扫描**（`O(axis)`）找首个 `prefix[tp] >= total * p / P` 的 `tp` |
+
+> **收尾**：张量形态强制把末项置为 `(axis, total)` —— 尾部的 `r == 0` 元素不产生输出，
+> 覆盖它们无副作用。
+
+### 5. 关键常量（`repeat_interleave_tiling.h`）
+
+```cpp
+constexpr uint32_t RI_MAX_COPY_BYTES   = 65535;      // DataCopyPad blockLen 上限（字节，不放开到 2MB）
+constexpr uint32_t RI_UB_BUDGET        = 176 * 1024; // 910B 单核 UB 192KB，取 176KB 留余量
+constexpr uint32_t RI_ALIGN            = 8;          // 向量 count / int32 8 对齐（32B 块 = 8 个 int32）
+constexpr uint32_t RI_ALIGN_BYTES      = 32;         // UB 地址 32B 对齐硬约束
+constexpr uint32_t RI_MAX_BLOCK_COUNT  = 4095;       // DataCopyExtParams::blockCount 上限
+constexpr uint32_t RI_MODE0_MAX_BATCH  = 4096;       // mode0 每批源行数上限
+constexpr uint32_t RI_MAX_K_CHUNK      = 8192;       // mode1 单块输出元素上限
+constexpr uint32_t RI_MODE1_MIN_CHUNK  = 64;         // mode1 单块元素下限（64 对齐）
+constexpr uint32_t RI_MAX_T_PARTS      = 64;         // 分核表最大 t 分片数（>= 最大核数）
+```
+
+### 6. 双接口
+
+```cpp
+// 标量 repeats
+npu::repeat_interleave_int_custom(at::Tensor input, int64_t repeats, int64_t? dim = None);
+// 张量 repeats（逐元素不同重复次数）
+npu::repeat_interleave_tensor_custom(at::Tensor input, at::Tensor repeats, int64_t? dim = None);
+```
+
+- `dim = None` 时先把输入展平为 1-D（`axis = numel`）再展开（对应 PyTorch 的 flatten 语义）。
+- 张量形态：`repeats` 必须 **1-D**、`numel == axis`、**int32/int64**（int64 在 host 侧转 int32）。
+- 标量形态：kernel 的 `repeats` 指针传 `xPtr` **占位**（kernel 不解引用，`repeatsInt` 常量生效）。
+
+### 7. host 侧实现要点（固定开销相关）
+
+1. **`stream(true)` 必须在所有 torch 侧算子之后**：`contiguous` / `to` 都必须在取 stream 之前；
+   tensor 形态要在 `stream(true)` **之后**才做 `repeats` 的 D2H 读取，才能读到已算完的数据。
+2. **核数查询 `static` 缓存**：`aclrtGetDeviceInfo(ACL_DEV_ATTR_VECTOR_CORE_NUM)` 的结果缓存，
+   避免每次 launch 重复查询。
+3. **tiling device buffer 静态复用 + 内容比较跳过 H2D**：固定分配一次；
+   `memcmp` 比对内容，**仅当 tiling 变化时才发 H2D**（H2D memcpy 约 **40us**，
+   是固定开销主要来源；shape/repeats 稳定的推理循环里可完全省掉）。
+4. **退化输入提前返回**：`numel == 0 || total == 0` 时直接返回空输出，**跳过 launch**（避免空指针）。
+5. **输出用 `at::empty`**：纯读型算子不需要初值，不要用 `zeros_like`
+   （多一次 kernel 且顺序语义易踩坑）。
+6. **`total` 上界校验**：`total <= UINT32_MAX`（tiling 中 `total` 为 uint32）。
+
+### 8. 踩坑（实测）
+
+- **UB 越界 → 错误码 507035**：mode1 构造展开下标时，分片长度须受 `RI_MAX_K_CHUNK` /
+  `RI_MODE1_MIN_CHUNK` 约束；下标数组长度按 `total` 而非 `axis` 估算，否则 UB 溢出。
+- **输出行累加器未回传**：mode0 逐行累加输出偏移时，行内累加器必须在换行时回写/重置，
+  否则后续行的输出位置错位。
+- **UB 按「一批源行的全部段」开会越界（WB-10）**：单行段总字节 > UB 预算时 `batchT` 被钳到 1
+  仍越界。正解是**逐段循环复用 `xBuf`**（`batchT * rowStride * es`，与 `inner` 解耦）。
+- **多块复制写不能替代逐行搬出（O5 穿刺失败）**：`DataCopyParams::srcStride` 是「相邻数据块的
+  间隔」，`srcStride = 0` 表示 UB 侧块间**连续**，**不是**「重复读同一 UB 段」。
+- **`idxBuf` 需额外对齐余量**：`BuildIndexBlock` 按 8 对齐写 `Duplicate` 主体，
+  容量取 `RiCeilAlign(kChunk, 8) + 8`，否则对齐写入越界。
+
+## Tiling 字段
+
+| 字段 | 含义 |
+|------|------|
+| mode | 0：`inner ≥ 2` 段拷贝；1：`inner == 1` 展开下标 + Gather |
+| outer / axis / inner / total | 语义分解参数与展开后轴长 |
+| tParts / oParts / oPerCore / blockNum | `t × o` 二维分核（blockNum = P × Q） |
+| coreTable[] | 分核表：`[2p]=tStart_p`、`[2p+1]=kStart_p`，末项固定为 `(axis, total)` |
+| batchT | mode0 每批源行数 |
+| segPerRow / rowStride | `inner` 分段数 / UB 行步长（32B 对齐） |
+| kChunk | mode1 单块展开元素数上限（≤ `RI_MAX_K_CHUNK`） |
+| repeatsIsTensor / repeatsInt | 张量 repeats 标志 / 标量 repeats 值 |
+
+## 已验证场景（910B / CANN 9.0.0）
+
+8 条用例 **bit-exact 全通过**（max diff = 0），覆盖标量 repeats / tensor repeats /
+`dim ∈ {0, 1, -1, None}` / `inner ≥ 2` 与 `inner == 1` 两档。
+
+**性能（vs 原生 `torch.repeat_interleave`）**：wall-clock、`iters=50, warmup=20, rounds=5`
+取 min-of-5，每轮前 `torch.npu.synchronize()`。两轮独立 bench：
+
+| 用例 | 第 1 轮 custom/torch | 对比 | 第 2 轮 custom/torch | 对比 | loc |
+|------|---------------------|------|---------------------|------|-----|
+| inner≥2 1024x4096 d0 r=2 | 0.0429 / 0.0251 | 0.59x | 0.0435 / 0.0400 | 0.92x | L2 |
+| inner≥2 4096x4096 d0 r=2 | 0.0527 / 0.0680 | 1.29x | 0.0626 / 0.0816 | 1.30x | HBM |
+| inner==1 1024x4096 d-1 r=2 | 0.1997 / 0.1593 | 0.80x | 0.2006 / 0.1646 | 0.82x | L2 |
+| inner==1 4096x4096 d-1 r=2 | 0.2967 / 0.5937 | 2.00x | 0.3034 / 0.7014 | 2.31x | HBM |
+| mid-axis 8x32x16 d1 r=2 | 0.0448 / 0.0247 | 0.55x | 0.0458 / 0.0484 | 1.06x | L2 |
+| flatten 8x32x16 dNone r=2 | 0.0429 / 1.4827 | **34.54x** | 0.0417 / 1.5097 | **36.24x** | L2 |
+| tensor 4096x4096 d0 r[4096] | 0.2171 / 0.4659 | 2.15x | 0.2301 / 0.4602 | 2.00x | HBM |
+| tensor 4096x4096 d0 mixed0 | 0.2078 / 0.3929 | 1.89x | 0.2125 / 2.8824 | 13.57x | HBM |
+
+（对比 = torch 耗时 / custom 耗时，>1 表示本实现更快。）
+
+**结论**：
+
+- **大 shape 稳定领先**：`inner≥2 4096² d0` 1.29~1.30x；`inner==1 4096² d-1` 2.00~2.31x；
+  tensor repeats `r[4096]` 2.00~2.15x。
+- **`dim=None`（flatten）压倒性优势 34~36x**：原生 torch 在 flatten 路径退化严重
+  （1.48ms vs 0.042ms）。
+- **小 shape 在波动区间**：`1024x4096 d0` 0.59→0.92x、`mid-axis 8x32x16` 0.55→1.06x，
+  **两轮翻转说明这些用例被 host 固定开销 + 设备波动支配**，绝对差距 ≤ 0.02ms，
+  不是算法问题（参见 [index_select.md](index_select.md) §Host 固定开销与输出缓冲池）。
+- **`tensor mixed0` 第 2 轮 13.57x 是噪声**：该用例两轮离散度分别 14.3% / **729.5%**，
+  原生耗时 0.39ms ↔ 2.88ms 剧烈漂移，**不可作为结论**（按测量纪律需复采）。
+
+> **口径提醒**：`loc = L2` 表示流量 < L2 容量（192MB），测得的是 **L2 带宽**而非 HBM 带宽。
+
+## 与相邻 Pattern 的区分
+
+- **P5（IndexSelect）**：index 由外部给定、任意无序，必须物化并搬入；
+  RepeatInterleave 的展开位置**由 repeats 解析确定**，可不物化 index，因此 bit-exact。
+- **P2（Gather）**：index 与输出同形、每行独立，需要坐标分解；
+  RepeatInterleave 的 `outer/axis/inner` 分解与 P5/P6 一致，**不需要 transpose**。
+- **P1（扁平索引取数）**：`dim = None` 时语义等价于在展平后的 1-D 张量上展开，
+  但实现上仍走本 Pattern 的 mode0/mode1（不物化 index），不走 P1 的扁平取数路径。