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

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/common/sync-and-consistency.md

@@ -0,0 +1,315 @@
+# 同步与数据一致性
+
+> Ascend 950 Vector 核同步机制。仅讨论 TBuf（手动同步），基于 TPipe-TQue 框架编程范式。
+
+## 1 核间同步
+
+`SyncAll()` 用于多核间的全局同步。所有启动核必须都调用，否则挂死。
+
+**约束**：
+- 调用 `SyncAll()` 的算子，host 端 Tiling 必须 `SetScheduleMode(1)`，告诉框架需要等 `usedCoreNum` 个核都空闲时才启动该算子
+- `SyncAll()` 自身包含 fence 语义，无需额外跨核同步原语
+
+**典型场景**：Reduce Group 模板 Phase 1 各核写 workspace，Phase 2 各核读 workspace。必须在 Phase 1 末尾、Phase 2 之前调用 `SyncAll()`：
+
+```cpp
+void ProcessGroup() {
+    Phase1Process();        // 各核写 workspace
+    SyncAll();              // 全核同步，保证 workspace 写完
+    Phase2Process();        // 各核读 workspace
+}
+```
+
+**host 端配合**：
+
+```cpp
+if (isGroup) {
+    OP_CHECK_IF(context->SetScheduleMode(1) != ge::GRAPH_SUCCESS,
+                OP_LOGE(context, "Failed to set ScheduleMode!"),
+                return ge::GRAPH_FAILED);
+}
+```
+
+## 2 核内同步
+
+### 2.1 概览
+
+Vector 核内部有 4 个异步并行执行的单元，共享同一片 UB（Local Memory）：
+
+| 流水 | 含义 |
+|------|------|
+| PIPE_S | 标量流水线，GetValue/SetValue 等标量操作 |
+| PIPE_V | 矢量计算流水线，Add/Mul/Reduce 等 |
+| PIPE_MTE2 | GM→UB 数据搬运流水线 |
+| PIPE_MTE3 | UB→GM 数据搬运流水线 |
+
+4 条流水异步并行执行，当访问同一片 UB 时可能存在数据依赖，需通过同步机制协调时序。典型数据流：MTE2 搬入 → V 计算 → MTE3 搬出。
+
+**同步分两类**：
+- **多流水同步**：不同类型流水间的数据依赖。使用 SetFlag/WaitFlag 接口。
+- **单流水同步**：同一类型流水内的数据依赖。使用 PipeBarrier 接口，保证前序指令所有读写完成后后续指令才开始。Ascend950 上不同的 VF 间硬件保证串行，不需要 PipeBarrier。注意 PipeBarrier 不支持 PIPE_S。
+
+**TBuf 需手动同步**：TBuf 不像 TQue 那样通过 EnQue/DeQue 隐式插入 fence。使用 TBuf 时，所有跨流水同步必须开发者手动插入。
+
+### 2.2 核内同步方法
+
+#### 2.2.1 SetFlag / WaitFlag
+
+同一核内不同流水线之间的同步。具有数据依赖的不同流水线指令之间需要插此同步。
+
+**同步 = 跨流水线的数据依赖。** 同一个 buffer，流水线 A 写、流水线 B 读（RAW），或流水线 A 读、流水线 B 写（WAR）——就必须同步。同流水线内自动串行（RAR/WAW 同流水线不需同步）。不同 buffer 互不干扰。
+
+**接口**：
+
+```cpp
+template <HardEvent event>
+__aicore__ inline void SetFlag(int32_t eventID);
+
+template <HardEvent event>
+__aicore__ inline void WaitFlag(int32_t eventID);
+```
+
+- `event`：模板参数，HardEvent 枚举值，命名规则 `源流水_目标流水`（如 `MTE2_V` = MTE2 是源，V 是目标——V 等 MTE2）
+- `eventID`：事件 ID。通过 `GetTPipePtr()->FetchEventID(HardEvent::XXX)` 获取，不可硬编码
+- **SetFlag/WaitFlag 必须成对出现**
+
+**Vector 算子常用事件**：
+
+| HardEvent | 含义 | 场景 |
+|-----------|------|------|
+| `MTE2_V` | MTE2→V，V 等 MTE2 | MTE2 写完 UB → V 要读该 UB |
+| `V_MTE2` | V→MTE2，MTE2 等 V | V 正在读 UB → MTE2 要覆盖该 UB |
+| `V_MTE3` | V→MTE3，MTE3 等 V | V 写完 UB → MTE3 要读该 UB |
+| `MTE3_V` | MTE3→V，V 等 MTE3 | 上轮 MTE3 读 UB → 下轮 V 要写该 UB（跨迭代 WAR） |
+| `MTE3_MTE2` | MTE3→MTE2，MTE2 等 MTE3 | 上轮 MTE3 读 UB → 下轮 MTE2 要覆盖该 UB |
+
+**正向同步**（循环内）：生产者→消费者。如 MTE2→V（搬完才能算）、V→MTE3（算完才能搬出）。
+
+**反向同步**（循环间）：下一轮迭代的生产者等上一轮迭代的消费者完成。如 V→MTE2（V 读完 buffer 后 MTE2 才能覆盖）、MTE3→MTE2（MTE3 读完 buffer 后下轮 MTE2 才能覆盖）、MTE3→V（MTE3 读完 buffer 后下轮 V 才能覆写）。首轮跳过 Wait，末轮跳过 Notify。
+
+**Event ID 管理**：
+- Ascend950（arch 3510）上 `QUE_MAX_EVENT = 8`，即每种 HardEvent 类型有独立的 8 个 eventID slot
+- eventID 池按 HardEvent 类型独立分配：`FetchEventID(HardEvent::MTE2_V)` 在 `MTE2_V` 类型的池中分配，`FetchEventID(HardEvent::V_MTE3)` 在 `V_MTE3` 类型的池中独立分配
+- `FetchEventID` 返回该类型池中第一个空闲 slot（0–7），同类型只用 1 个时每次返回同一个值
+- 不同类型事件各自独立池，不会冲突
+- 通过 `FetchEventID()` 获取，在 `Init()` 或 `Process()` 开头统一获取，避免运行时重复调用
+
+**调用模式**：
+
+**场景 1**：单 buffer 贯穿 CopyIn → Compute(in-place) → CopyOut，跨迭代 MTE3→MTE2 / MTE3→V WAR：
+
+```cpp
+// Init 或 Process 开头获取 eventID
+int32_t evMTE2toV = static_cast<int32_t>(
+    GetTPipePtr()->FetchEventID(HardEvent::MTE2_V));
+int32_t evVtoMTE3 = static_cast<int32_t>(
+    GetTPipePtr()->FetchEventID(HardEvent::V_MTE3));
+int32_t evMte3toV = static_cast<int32_t>(
+    GetTPipePtr()->FetchEventID(HardEvent::MTE3_V));
+int32_t evMTE3toMTE2 = static_cast<int32_t>(
+    GetTPipePtr()->FetchEventID(HardEvent::MTE3_MTE2));
+
+// 典型循环：每轮 CopyIn → Compute → CopyOut，inBuf 贯穿三阶段
+for (int64_t flat = start; flat < end; flat++) {
+    // ── 跨迭代反向：上轮 CopyOut(MTE3 读 inBuf) → 本轮 CopyIn(MTE2 覆写) / Compute(V 覆写) ──
+    // 首轮跳过 WaitFlag（没有上一轮）
+    if (flat != start) WaitFlag<HardEvent::MTE3_MTE2>(evMTE3toMTE2);
+    if (flat != start) WaitFlag<HardEvent::MTE3_V>(evMte3toV);    // MTE3 读完 inBuf，V 才可覆写
+
+    // ── 正向同步：CopyIn(MTE2 写 inBuf) → Compute(V 读 inBuf) ──
+    DataCopy(inBuf, gm[flat * TILE], TILE);       // MTE2 写 inBuf
+    SetFlag<HardEvent::MTE2_V>(evMTE2toV);        // MTE2→V
+    WaitFlag<HardEvent::MTE2_V>(evMTE2toV);
+    AscendC::Add(inBuf, inBuf, inBuf, TILE);      // V 读写 inBuf（in-place）
+
+    // ── 正向同步：Compute(V 写 inBuf) → CopyOut(MTE3 读 inBuf) ──
+    SetFlag<HardEvent::V_MTE3>(evVtoMTE3);        // V→MTE3
+    WaitFlag<HardEvent::V_MTE3>(evVtoMTE3);
+    DataCopy(gm[flat * TILE], inBuf, TILE);       // MTE3 读 inBuf
+
+    // ── 跨迭代反向：本轮 CopyOut(MTE3 读 inBuf) → 下轮 CopyIn(MTE2 覆写) / Compute(V 覆写) ──
+    // 末轮跳过 SetFlag（没有下一轮）
+    if (flat != end - 1) SetFlag<HardEvent::MTE3_MTE2>(evMTE3toMTE2);
+    if (flat != end - 1) SetFlag<HardEvent::MTE3_V>(evMte3toV);    // MTE3 流标记读完 inBuf
+}
+```
+
+**场景 2**：内层循环中 buffer 被 V 读后，下一轮迭代被 MTE2 覆写（V→MTE2 WAR）：
+
+```cpp
+// 多见于 reduction 等式的 R chunk 循环：每轮 CopyIn → CastSquare(V) → Reduce(V)，
+// inBuf 被下一轮 CopyIn 覆写
+int32_t evVtoMTE2 = static_cast<int32_t>(
+    GetTPipePtr()->FetchEventID(HardEvent::V_MTE2));
+
+for (int64_t rIdx = 0; rIdx < rEnd; ++rIdx) {
+    // ── 跨迭代反向：上轮 V 读 inBuf → 本轮 CopyIn 覆写 inBuf ──
+    // 首轮跳过 WaitFlag
+    if (rIdx != 0) WaitFlag<HardEvent::V_MTE2>(evVtoMTE2);
+
+    // CopyIn → V 链（MTE2_V 正向同步略）
+    DataCopy(inBuf, ...);
+    SetFlag<HardEvent::MTE2_V>(evMTE2toV);
+    WaitFlag<HardEvent::MTE2_V>(evMTE2toV);
+    Vf1(inBuf, ...);    // V 读 inBuf
+    Vf2(...);            // V，不访问 inBuf -> tmpBuf
+
+    // ── 跨迭代反向：本轮 V 读 inBuf → 下轮 CopyIn 覆写 inBuf ──
+    // 末轮跳过 SetFlag
+    if (rIdx != rEnd - 1) SetFlag<HardEvent::V_MTE2>(evVtoMTE2);
+}
+```
+
+> **反向同步要点**：
+> - `MTE3_MTE2`：SetFlag 在本轮 CopyOut 之后（MTE3 读完），WaitFlag 在下轮 CopyIn 之前（MTE2 等覆写）
+> - `V_MTE2`：SetFlag 在本轮 V 链最后一步之后（V 读完 buffer），WaitFlag 在下轮 CopyIn 之前（MTE2 等覆写）
+> - 首轮跳过 WaitFlag，末轮跳过 SetFlag
+> - 同类型事件可共用 1 个 eventID——前一个 WaitFlag 清零后后一个 SetFlag 可复用
+>
+> ⚠ **同步点必须由持有法则 trace 推导得出**，禁止跳过 trace 直接编写同步代码。trace 中不存在的 RAW/WAR crossing 不得插入 SetFlag/WaitFlag。详见 §2.2.2。
+
+#### 2.2.2 持有法则
+
+> SetFlag/WaitFlag 的配套分析工具。通过逐行标注 buffer 持有三态，推导每个 buffer 的跨流水 RAW/WAR 依赖，精准定位同步点。
+
+**执行动作与读写**：
+
+| 动作 | 流水线 | 对 UB 的行为 |
+|------|--------|-------------|
+| CopyIn | MTE2 | **写** buffer — 从 GM 搬入新数据 |
+| Compute | V | **读** src buffer + **写** dst buffer |
+| CopyOut | MTE3 | **读** buffer — 搬出到 GM，对 UB 是最后一次读 |
+
+- **写**：向 buffer 写入新数据。写入后 buffer 是否保留在持有中，取决于新数据有无未来消费者。
+- **读**：从 buffer 读取数据。读本身不改变持有，但读完后该 buffer 少了一个未来消费者。如果是最后一个消费者，执行后 buffer 从持有消失。
+- **原地读写**（如 MulAddDst、Muls）：buffer 被读的同时也被写，新数据覆盖旧数据。按写处理。
+
+**持有** = buffer 的当前数据会被 Kernel 全生命周期中未来某步读，不可释放。判定依据是全局视角：扫描当前动作之后的所有步骤，如果任何一个步骤会读这个 buffer，该 buffer 就在持有列表中。无未来消费者的 buffer 执行后自然从持有列表消失。有未来消费者的保留。
+
+**三态标注**：每个执行动作标注在代码行上方：
+
+```
+// 执行前: 持有=[...]
+// 执行中: 持有=[...]
+// 执行后: 持有=[...]
+代码;
+```
+
+| 态 | 含义 |
+|----|------|
+| 执行前持有 | 上一动作执行后留下的持有列表 |
+| 执行中持有 | 执行前 + 当前动作新占用的 buffer（dst 写入 + src 正在被读尚未释放）。buffer 占用峰值时刻 |
+| 执行后持有 | 执行中 − 当前动作后无未来消费者的 buffer |
+
+前一动作的执行后 = 下一动作的执行前。第一步执行前为 `[]`。
+
+**从持有推导同步点**：遍历每个 buffer 的生命周期，标记每一次跨流水线的 RAW/WAR，即为同步点。持有法则的每行动作注释直接暴露依赖。
+
+**RAW 示例**（生产者写→消费者读，正向）：
+
+```
+// 执行后: 持有=[UB0]                          ← MTE2 写完了 UB0
+CopyOneInput(coord, IN0, UB0);
+// 执行前: 持有=[UB0]
+// 执行中: 持有=[UB0, UB2]                     ← V 要读 UB0 (RAW)
+AscendC::Mul(buf_[UB2].Get<T>(), buf_[UB0].Get<T>(), buf_[UB0].Get<T>(), count);
+```
+→ 插 `MTE2_V`：SetFlag 在 Mul 之前，WaitFlag 等 MTE2 写完 UB0。
+
+**WAR 示例**（消费者在读→生产者要覆盖，反向）：
+
+```
+// 执行后: 持有=[UB0, UB2]                     ← V 还在持有 UB0(in0)
+AscendC::Mul(buf_[UB2]..., buf_[UB0]..., buf_[UB0]..., count);
+//                   ↓ V 读 UB0
+// 执行中: 持有=[UB0, UB2, UB3]               ← MTE2 要写 UB0(data_m) 覆盖 in0 (WAR)
+CopyOneInput(coord, IN2, UB0);
+```
+→ 插 `V_MTE2`：SetFlag 在 Mul 之后（V 读完 UB0），WaitFlag 在 CopyIn 之前（MTE2 等 V）。
+
+**验证**：
+- 任意执行中持有数不超过该算子分配的 buffer 总数
+- 执行后持有与释放时机一致
+
+### 2.3 单流水同步 PipeBarrier
+
+同一流水线内具有数据依赖的指令之间的同步。作用是保证前序指令中所有数据读写全部完成后，后序指令才开始执行。
+
+**接口**：
+
+```cpp
+template <pipe_t pipe>
+__aicore__ inline void PipeBarrier();
+```
+
+**模板参数 pipe**：指定阻塞的流水，支持 PIPE_V / PIPE_MTE2 / PIPE_MTE3 / PIPE_ALL，不支持 PIPE_S（Scalar 流水由硬件自动保证）。
+
+**约束**：
+- arch35/Ascend 950 上连续 Vector 计算之间、连续 VF 之间硬件保证顺序，无需手动 PipeBarrier<PIPE_V>()
+- `PipeBarrier<PIPE_ALL>()` 会等待所有流水线完成，对性能影响大，能用单流水 PipeBarrier 解决时不要用 PIPE_ALL
+- **MTE2/MTE3 搬运地址重叠时需手动插入**：硬件不保证搬运地址重叠时的串行化，需手动 `PipeBarrier<PIPE_MTE2>()`（UB 目的地址重叠）或 `PipeBarrier<PIPE_MTE3>()`（GM 目的地址重叠）
+
+**示例**：
+
+```cpp
+// MTE3 搬运目的地址重叠，需手动插入
+DataCopy(dstGm[0], srcLocal, count);
+PipeBarrier<PIPE_MTE3>();              // 保证前一个 DataCopy 完成
+DataCopy(dstGm[overlap], srcLocal2, count);  // 目的地址与前一个重叠
+```
+
+### 2.4 VF LocalMemBar
+
+LocalMemBar 是 VF 函数（`__simd_vf__`）内部的同步指令，用于 Reg 矢量计算中 UB 读写流水线间的保序。
+
+**接口**：
+
+```cpp
+template <MemType src, MemType dst>
+__simd_callee__ inline void LocalMemBar();
+```
+
+**MemType 取值**：
+
+| MemType | 含义 |
+|---------|------|
+| VEC_STORE | VF 内矢量写 UB（StoreAlign/StoreUnAlign/Store） |
+| VEC_LOAD | VF 内矢量读 UB（LoadAlign/LoadUnAlign/Load） |
+| SCALAR_STORE | VF 内标量写 UB |
+| SCALAR_LOAD | VF 内标量读 UB |
+| VEC_ALL | VF 内所有矢量读写 UB |
+| SCALAR_ALL | VF 内所有标量读写 UB |
+
+**原理**：dst 流水线等待 src 流水线上所有指令完成后才执行。当读指令和写指令使用**不同寄存器**访问**同一 UB 地址**时，硬件不保证顺序，需插入 LocalMemBar。
+
+**不需要 LocalMemBar 的情况**：读写指令使用**相同寄存器**时，硬件自动触发寄存器保序，指令按代码顺序执行。
+
+**典型场景**：VF 循环内 in-place 操作（同一 UB 地址跨迭代读写）：
+
+```cpp
+__simd_vf__ inline void InPlaceAddVF(__ubuf__ T* addr, ..., uint16_t repeatTimes) {
+    for (uint16_t i = 0; i < repeatTimes; i++) {
+        // 第二次迭代读 addr 需等第一次迭代写 addr 完成
+        LocalMemBar<VEC_STORE, VEC_LOAD>();  // VEC_LOAD 等 VEC_STORE
+        LoadAlign(srcReg, addr);
+        Add(dstReg, srcReg, srcReg, mask);
+        StoreAlign(addr, dstReg, mask);       // in-place 写回同一地址
+    }
+}
+```
+
+**常见错误**：在标准 elewise 循环（每次迭代目标地址不同）末尾加 LocalMemBar 是多余的——地址不同无依赖。
+
+### 2.5 不需要同步的情况
+
+| 场景 | 是否需要同步 | 原因 |
+|------|-------------|------|
+| 同一流水线内连续 Vector 计算 | 不需要 | arch35/Ascend 950 上连续 Vector 计算之间硬件保证顺序 |
+| 同一流水线内连续 VF 调用 | 不需要 | arch35/Ascend 950 上连续 VF 之间硬件保证顺序 |
+| MTE2/MTE3 搬运地址重叠 | **需要 PipeBarrier** | 硬件不保证搬运地址重叠时的串行化，需手动 `PipeBarrier<PIPE_MTE2>()` 或 `PipeBarrier<PIPE_MTE3>()` |
+| 不同 buffer 互不干扰 | 不需要 | 无数据依赖，各流水独立执行 |
+| 无跨流水线数据依赖 | 不需要 | 如 V 写 buffer0、MTE2 写 buffer1，互不干扰 |
+| MTE2 写 UB → V 读同一 UB | **需要 SetFlag/WaitFlag** | 跨流水线 RAW，插 `MTE2_V` |
+| V 写 UB → MTE3 读同一 UB | **需要 SetFlag/WaitFlag** | 跨流水线 RAW，插 `V_MTE3` |
+| V 读 UB → MTE2 覆写同一 UB | **需要 SetFlag/WaitFlag** | 跨流水线 WAR（反向），插 `V_MTE2` |
+| MTE3 读 UB → MTE2 覆写同一 UB | **需要 SetFlag/WaitFlag** | 跨流水线 WAR（反向，跨迭代），插 `MTE3_MTE2` |

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/common/value-depend-process.md

@@ -0,0 +1,40 @@
+# 值依赖分析
+
+> 算子输入是否在 Tiling 阶段需要读取值（如 axes tensor），影响框架三处契约声明。
+
+## 1 值依赖判定法则
+
+**infershape 或 tiling 阶段要解引用该张量的 `GetData<T>()` → 必须值依赖。** 反之（只读 shape/dtype）→ 不需要。
+
+| 输入语义 | 是否值依赖 |
+|---------|----------|
+| 主数据张量 `x` | ❌ |
+| 轴号张量 `axes` / `dims` | ✅ |
+| 标量参数张量（mean/var/scale） | ❌（一般） |
+| shape 描述张量（如 reshape 的 target_shape） | ✅ |
+
+## 2 三处契约声明（缺一不可）
+
+值依赖张量必须在以下三处同时声明，缺一会导致 infershape/tiling 阶段拿不到数据：
+
+| # | 位置 | 声明 |
+|---|------|------|
+| 1 | `op_def.cpp` 输入定义 | `this->Input("axes").ParamType(REQUIRED).ValueDepend(OPTIONAL)...` |
+| 2 | `IMPL_OP_INFERSHAPE` 注册块 | `.InputsDataDependency({idx})` |
+| 3 | `IMPL_OP_OPTILING` 注册块 | `.TilingInputsDataDependency({idx})` |
+
+- `idx` = 该输入在 Input 链中的索引（从 0 开始）
+- `ValueDepend(OPTIONAL)`：该输入可以是图编译期常量或运行期张量
+- `ValueDepend(REQUIRED)`：强制该输入是常量
+
+## 3 典型范式示例
+
+| 范式 | 值依赖 | 说明 |
+|------|--------|------|
+| reduction | axes tensor | `this->Input("axes").ParamType(REQUIRED).ValueDepend(OPTIONAL)` |
+| layout_transform | target_shape tensor | reshape 类算子的目标形状张量 |
+
+## 4 一致性约束
+
+- **infershape 与 tiling 对同一输入的值依赖声明必须一致**：若 infershape 声明了值依赖而 tiling 漏配，tiling 阶段 `GetInputTensor` 拿不到 data
+- **空 tensor 不在 infershape 端短路**：output shape 自然带 0 维，由 tiling/kernel 端处理

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/common/vf-programming-rules.md

@@ -0,0 +1,150 @@
+# VF 编程规则
+
+> regbase VF 编程的 API 速查、循环范式、硬约束。
+
+## 1 命名空间与核心类型
+
+| 类型 | 说明 |
+|------|------|
+| `AscendC::Reg::RegTensor<T>` | 向量寄存器，VL=256B。b16→128 元素，b32→64 元素 |
+| `AscendC::Reg::MaskReg` | 掩码寄存器 |
+| `__ubuf__ T*` | UB 地址指针，由 `localTensor.GetPhyAddr()` 获取 |
+
+## 2 Load / Store
+
+**API 选型**：新代码统一走 `LoadAlign` / `StoreAlign`（地址要求 32B 对齐）。
+
+```cpp
+// Load: UB → 寄存器（无 mask；srcAddr 必须 32B 对齐）
+AscendC::Reg::LoadAlign(vReg, ubPtr + offset);
+
+// Load b16→f32: DIST_UNPACK_B16 只加载 VL/2 字节 (64 half = 128B)
+AscendC::Reg::LoadAlign<T, AscendC::Reg::LoadDist::DIST_UNPACK_B16>(tReg, tPtr + offset);
+
+// Store: 寄存器 → UB（带 mask；dstAddr 必须 32B 对齐）
+AscendC::Reg::StoreAlign(ubPtr + offset, vReg, maskReg);
+
+// Store fp32→b16: DIST_PACK_B32 与 DIST_UNPACK_B16 对称
+AscendC::Reg::StoreAlign<T, AscendC::Reg::StoreDist::DIST_PACK_B32>(ubPtr + offset, vReg, maskReg);
+```
+
+**约束**：
+- 地址非 32B 对齐时用 `LoadUnAlign` / `StoreUnAlign` + `UnalignRegFor[Load|Store]` 状态对象配对
+- b16 加载必须 `DIST_UNPACK_B16`，写出必须 `DIST_PACK_B32`
+- int8/uint8 加载 `DIST_UNPACK4_B8`，写出 `DIST_PACK4_B32`（详见 [cast-rules.md](cast-rules.md) §5）
+
+## 3 UpdateMask
+
+```cpp
+template <typename T>
+__simd_callee__ inline MaskReg UpdateMask(uint32_t& scalarValue);
+```
+
+**关键**：`scalarValue` 是引用传递，内部自动递减 VL_T（float:64，half:128）。**调用后不可再手动递减**。
+
+```cpp
+uint32_t remaining = static_cast<uint32_t>(totalElems);
+for (uint16_t i = 0; i < repeatTime; ++i) {
+    maskReg = AscendC::Reg::UpdateMask<float>(remaining);
+    // remaining 已被自动递减，不可再写 remaining -= 64  // ❌ 会变成每轮减 2×VL
+}
+```
+
+## 4 MaskMergeMode
+
+| 模式 | 说明 |
+|------|------|
+| `ZEROING` | mask 外元素置零（常用） |
+| `MERGING` | mask 外元素保持原值 |
+
+## 5 计算操作速查
+
+```cpp
+// Binary: dst = src0 op src1
+AscendC::Reg::Add/Sub/Mul/Div/Max/Min(dstReg, src0Reg, src1Reg, maskReg);
+// 带 MaskMergeMode:
+AscendC::Reg::Add<T, AscendC::Reg::MaskMergeMode::ZEROING>(dst, src0, src1, mask);
+
+// Scalar: dst = src op scalar（无 Subs，用 Adds 负值代替）
+AscendC::Reg::Adds/Muls(dstReg, srcReg, scalarVal, maskReg);
+
+// Unary
+AscendC::Reg::Sqrt/Abs/Exp/Ln/Neg/Relu(dstReg, srcReg, maskReg);
+
+// Duplicate
+AscendC::Reg::Duplicate(dstReg, scalarValue);
+
+// Cast
+AscendC::Reg::Cast<DstT, SrcT, castTrait>(dstReg, srcReg, maskReg);
+```
+
+## 6 LocalMemBar 使用规则
+
+`LocalMemBar<VEC_STORE, VEC_LOAD>()` 保证之前所有 VEC_STORE 写入对后续 VEC_LOAD 可见。仅作用于 Vector 单元内部。
+
+| 场景 | 是否需要 |
+|------|---------|
+| 每次迭代读写**不同地址**（`off = i * VL`） | **不需要** |
+| 同一迭代内 load-modify-store 同一地址 | **不需要** |
+| 跨不同 buffer（src→dst elewise） | **不需要** |
+| 连续迭代读写**同一地址**（in-place reduce） | **需要** |
+| 内层循环写，外层下次循环读同一地址 | **需要** |
+
+**常见错误**：在标准 elewise 循环末尾加 `LocalMemBar` 是多余的——每次迭代目标地址都不同。
+
+## 7 VF 循环范式
+
+```cpp
+constexpr uint32_t kRepF32 = 256 / sizeof(float);  // = 64
+uint16_t repeatTime = static_cast<uint16_t>(
+    (static_cast<uint32_t>(totalElems) + kRepF32 - 1) / kRepF32);
+for (uint16_t i = 0; i < repeatTime; ++i) {
+    int32_t offset = static_cast<int32_t>(i) * kRepF32;
+    // ...
+}
+```
+
+**约束**：`offset` 用 `static_cast<int32_t>(i) * kRepF32`，避免 `uint16_t` × `int32_t` 隐式转换。
+
+## 8 `__simd_vf__` 函数 + `asc_vf_call` 调用范式
+
+```cpp
+// __simd_vf__ 函数：C 函数格式，不能是类成员函数
+template <typename T>
+__simd_vf__ inline void XxxVfImpl(
+    __ubuf__ T* src, __ubuf__ T* dst,
+    uint32_t totalElems, uint16_t repeatTime)
+{
+    AscendC::Reg::RegTensor<T> aReg;
+    AscendC::Reg::MaskReg mask;
+    uint32_t remaining = totalElems;
+    for (uint16_t i = 0; i < repeatTime; ++i) {
+        int32_t off = static_cast<int32_t>(i) * static_cast<int32_t>(VL);
+        mask = AscendC::Reg::UpdateMask<T>(remaining);
+        AscendC::Reg::LoadAlign(aReg, src + off);
+        // ... 计算
+        AscendC::Reg::StoreAlign(dst + off, aReg, mask);
+    }
+}
+
+// 调用侧：asc_vf_call 显式传递所有模板参数
+asc_vf_call<XxxVfImpl<T>>(src, dst, totalElems, repeatTime);
+```
+
+## 9 VF 7 条硬约束
+
+1. **for 循环必须从 0 开始**
+2. **VF 内最多 4 层 for**
+3. **循环控制变量必须是 `uint16_t`**
+4. **VF 内禁止数组**
+5. **VF 内禁止访问类的"对象级"成员变量**（在 `asc_vf_call` 调用侧提取为临时变量/参数传入）
+6. **VF 内禁止运行时 `if/else`**（用 `if constexpr` 代替）
+7. **使用 `asc_vf_call` 启动 SIMD VF 函数**
+
+## 10 `__simd_vf__` 函数约束
+
+- C 函数格式，**不能是类成员函数**
+- **不能引用外部模板**（如 `Reducer::identity` 需作为参数传入）
+- 支持模板参数（如 `typename T` / `bool isTailR`）
+- 支持内部 `if constexpr`
+- `asc_vf_call` 显式传递所有模板参数

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/example-routes.yaml

@@ -0,0 +1,31 @@
+# ----------------------------------------------------------------------------------------------------------
+# 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.
+# ----------------------------------------------------------------------------------------------------------
+
+# example-routes.yaml — 范式 → 参考实现路由表（按语言维度）
+#
+# 根据 op.paradigms + op.language 路由到对应语言适配层的参考实现示例代码。
+# 路径相对于 ops-design-paradigms skill 根目录。
+#
+# 匹配规则：
+#   op.paradigms 列表逐项匹配，结果自动去重；
+#   每个范式条目为 {语言: [路径]} 映射，按 op.language 选择
+#   （语言缺失或未知时不选择适配层）；
+#   兼容旧扁平格式（范式条目直接为路径列表，视为 ascendc 专属）。
+#
+# 兜底机制：
+#   当 op.paradigms 在本表中没有任何匹配时，返回空，不强制注入通用示例；
+#   语言已注册但该语言暂无参考实现时，同样返回空并提示，
+#   不回退其他语言的参考实现（语言适配层互斥）。
+
+routes:
+  paradigms:
+    Broadcast:
+      ascendc:
+        - references/paradigms/broadcast/adapters/ascendc/example/xdivy_custom_package

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/general-methodology-dsl.md

@@ -0,0 +1,11 @@
+# CANNBotDSL 算子通用设计方法
+
+当某个范式没有 DSL 专用适配层时，依据调用方提供的规格、目标设备事实和 DSL API 资料完成设计。本文只给方法，不规定产物文件名或工作流路径。
+
+1. **语义与接口**：写清数学公式、公开 Python 参数、shape/dtype/layout 推导、空输入与错误行为。设备值计算和输出归属必须可追溯到规格。
+2. **执行路径**：区分静态配置、编译期特化与运行时参数。只为算法或数据通路有实质差异的情况拆分路径，并说明判定顺序、互斥性和支持域覆盖。
+3. **Host 与 Launch**：说明元数据检查、输出和 workspace 分配、零拷贝视图、任务划分、资源预算和 Launch 顺序。资源数值从目标平台证据取得。
+4. **DSL Kernel**：从公式推导阶段、任务坐标、搬运、计算、写回、Channel/Buffer 生命周期和同步。按实际路径选择 Cube、Vector 或单一路径；不套样例配置。
+5. **验证**：用独立 Golden 覆盖支持的 dtype、shape、layout、分支、尾块、特殊值和错误路径。记录所用 API 的来源与尚待验证的设备行为。
+
+设计中的分支 ID 只用于文档引用。Host 与 Kernel 的参数契约由实际 Python/DSL 调用确定，不需要 AscendC 的 TilingKey、TilingData、OpDef 或 C++ Kernel 结构。

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/general-methodology.md

@@ -0,0 +1,94 @@
+# Ascend C 算子 Tiling 通用设计方法论
+
+> 当 spec.yaml 的 `op.paradigms` 在本 skill 的 `references/paradigm-refs.yaml` 中
+> 没有匹配的范式路由时，使用本文档作为 Tiling 设计的兜底方法论。命中具体范式时，
+> 优先按对应的 `references/<paradigm>/patterns.md` 进行设计；本文档仅作为通用基线。
+
+---
+
+## 一、通用设计要素（所有算子类别必须完成）
+
+### 1. 多核切分策略
+
+**核心问题**：任务如何分配给多个 AI Core？
+
+**设计要点**：
+- **负载均衡**：每个核处理的任务量尽量相等；不均匀负载会让快核空等慢核。
+- **数据局部性**：相邻数据尽量分配给同一核，减少跨核同步与重复搬运。
+- **粒度适中**：tile 不能太小（调度开销大），也不能太大（并行度低）。
+- **尾块处理**：总任务量不被核数整除时，需要明确尾块归属（最后一个核多吃、轮转分配等）。
+
+**输出清单**：
+- [ ] 总任务切分方式（按哪个维度切、切多少份）
+- [ ] 每个 AI Core 处理的任务量（含尾块策略）
+- [ ] 使用的 AI Core 数量（与目标芯片的 vector / cube 核数对齐）
+
+### 2. UB 切分策略
+
+**核心问题**：单次能在 UB 中处理多少数据？
+
+**设计要点**：
+- **UB 容量限制**：DAV_2201 ≈ 192 KB、DAV_3510 ≈ 248 KB。具体可用容量需扣除 stack、
+  workspace、double buffer 等开销，按目标芯片实测预算编排。
+- **单次处理数据量**：根据 UB 预算反推每次 `DataCopy` / 计算批量的元素数。
+- **是否分 chunk**：单核任务量超出 UB 时需要切 chunk 串行处理；chunk 大小决定循环次数与
+  pipeline 深度。
+- **dtype 转换余量**：若 Compute 阶段需要升精度（fp16 → fp32），UB 预算要预留临时 buffer。
+
+**输出清单**：
+- [ ] 单次处理的数据量（元素数 + 字节数）
+- [ ] 是否需要分 chunk、chunk 数量与剩余尾 chunk 处理
+- [ ] chunk 大小计算公式（含 UB 预算、dtype 字节数、buffer 数量等变量）
+
+### 3. Buffer 规划
+
+**核心问题**：需要哪些 buffer？各多大？总 UB 占用是否超限？
+
+**设计要点**：
+- **输入 buffer（inQueue）**：每路输入一个 inQueue；多输入算子可共用 inQueue 或独立 inQueue。
+- **输出 buffer（outQueue）**：每路输出一个 outQueue。
+- **中间计算 buffer（tmpBuf / workBuf）**：保存中间结果、升精度中转、reduce 树等。
+- **Double Buffer**：搬运/计算重叠优化，启用时 inQueue / outQueue 容量翻倍。
+- **总和校验**：所有 buffer 字节数之和必须 ≤ 该芯片可用 UB（含 double buffer 倍数）。
+
+**输出清单**：
+- [ ] Buffer 列表及用途（名称 + 类型 + 容量 + 是否启用 double buffer）
+- [ ] 各 buffer 大小计算公式（含 dtype、对齐、double buffer 倍数）
+- [ ] 总 UB 使用量及与芯片预算的差额
+
+### 4. 分支场景覆盖
+
+**核心问题**：算子需要处理哪些不同场景？每种场景的策略分别是什么？
+
+**常见分支维度**：
+- **数据类型**：FP32 / FP16 / BF16 / INT8 / INT32 等；不同 dtype 的字节数、API 支持、
+  累加器选择都可能不同。
+- **Shape 大小**：大 shape（按通用 chunk 路径）、小 shape（fullload 路径），切分公式分支。
+- **数据对齐**：32 字节对齐（DataCopy 直通）/ 非对齐（需要 padding 或非对齐搬运变体）。
+- **边界情况**：reduce 轴长度为 1、空 tensor、rank=0 标量、最大/最小 shape、特殊数值
+  （NaN / Inf / 极值）。
+- **架构差异**：DAV_2201 / DAV_3510 等不同芯片的 UB 容量、API 可用性、并行度差异。
+
+**输出清单**：
+- [ ] 分支决策条件（按上述分支维度逐项列出）
+- [ ] 各分支的处理策略（差异点 + 复用点）
+- [ ] 边界测试用例（对应到 spec.yaml 的 `boundary_conditions` / `extreme_inputs`）
+
+---
+
+## 二、TilingKey 与 Tiling 字段
+
+**核心问题**：上述分支决策如何在 host 侧编码为 `TilingKey`？哪些参数作为 Tiling 字段
+随 TilingData 下发到 kernel？
+
+**设计要点**：
+- 每个独立分支路径分配唯一 TilingKey；TilingKey 的位域规划由架构师决定（通常把 dtype
+  / shape 级别 / 对齐情况编码进高位）。
+- Tiling 字段最小化原则：能在 kernel 内推导的不要放进 TilingData。
+- Tiling 字段命名与单位（元素数 / 字节数 / 块数）必须在 DESIGN.md 与 `op_def.cpp` 中保持
+  一致。
+
+**输出清单**：
+- [ ] TilingKey 取值集合及对应分支
+- [ ] Tiling 字段表（名称 + 类型 + 单位 + 取值范围）
+- [ ] Tiling 函数关键计算公式（多核切分、UB 切分、buffer 大小）