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

package/assets/ops-direct-invoke/skills/npu-arch/references/npu-hardware-params.md

@@ -0,0 +1,248 @@
+# NPU 硬件参数真值参考
+
+> **数据源**：`${ASCEND_HOME_PATH}/<arch>/data/platform_config/*.ini`（arch 如 `aarch64-linux`、`x86_64-linux`、`arm64-linux`），参数值以运行时 `PlatformAscendC` 接口返回为准。
+>
+> **DAV_3510 官方规格真源**：《[昇腾950 NPU架构白皮书](https://public-download.obs.cn-east-2.myhuaweicloud.com/ascend/%E6%98%87%E8%85%BE950%20NPU%E6%9E%B6%E6%9E%84%E7%99%BD%E7%9A%AE%E4%B9%A6.pdf)》——表3-1（950PR/950DT 各 SKU 核数、算力、Memory、L2）、表4-2（Memory 层次各 Buffer 物理容量）。
+>
+> **数据可信度约定**：本文档中「INI 字段」/「实测」均指从 ini 读取到的静态配置值。**ini 文件是发现硬件参数的必要不充分条件** — 并非每个 ini 都对应真实量产芯片，部分配置可能来自工程样片、仿真平台或规划中的 SKU。文档聚焦架构级常量（§1、§2）和关键差异速查（§3），变化参数仅以典型量产 SKU 举例。
+
+---
+
+## 0. 产品映射表
+
+按 NpuArch 列出 Ascend NPU 全代际的产品系列、SocVersion 与具体芯片型号。**本表为 SKILL.md 与 `npu-arch-guide.md` 共用的真源，需要修改芯片清单时仅在此处更新。**
+
+| 产品系列 | SocVersion | NpuArch | __NPU_ARCH__ | 芯片型号 |
+|---------|-----------|---------|:---:|---------|
+| Atlas 训练系列 | ASCEND910 | DAV_1001 | 1001 | Ascend910 |
+| Atlas 推理系列 | ASCEND310P | DAV_2002 | 2002 | Ascend310P1, Ascend310P3, Ascend310P5, Ascend310P7 |
+| Atlas A2 训练/推理 | ASCEND910B | DAV_2201 | 2201 | Ascend910B1~B4, Ascend910B2C |
+| Atlas A3 训练/推理 | ASCEND910B | DAV_2201 | 2201 | Ascend910_93 |
+| Atlas 200I/500 A2 推理 | ASCEND310B | DAV_3002 | 3002 | Ascend310B1~B4 |
+| Atlas A5 训练 | ASCEND950 | DAV_3510 | 3510 | Ascend950DT (Decode) |
+| Atlas A5 推理 | ASCEND950 | DAV_3510 | 3510 | Ascend950PR (Prefill) |
+| Mate80、Pura90等系列 | Kirin9030 | DAV_3113 | 3113 | Kirin9030 |
+| MatePad Edge、MateBookPro等系列 | KirinX90 | DAV_3003 | 3003 | KirinX90 |
+
+> **一对多关系**：一个 NpuArch 可对应多个 SocVersion / 芯片型号。例如 `DAV_2201` 对应 Ascend910B1~B4、Ascend910B2C、Ascend910_93。
+>
+> **950 系列定位**（950 白皮书 §2/§3）：**Ascend950PR** 面向高性能推荐、大模型 **Prefill** 及多模态推理；**Ascend950DT** 覆盖预训练、后训练及推理（含 **Decode** 与 Prefill）全流程（Memory 规格见典型 SKU 示例）。上表中的 (Decode)/(Prefill) 为场景侧重标注，并非唯一用途。
+>
+> **运行时映射**：`Ascend910_93` 的 SocVersion 字符串在运行时映射到 `SocVersion::ASCEND910B`（非独立枚举值）。源码中虽存在 `SocVersion::ASCEND910_93` 枚举值（platform_ascendc.h），但 convertMap 中 `"Ascend910_93"` 映射到的是 `ASCEND910B`，该枚举仅在少数内部模块使用。NpuArch 同为 `DAV_2201`。
+
+---
+
+## 1. 服务器跨架构一致参数
+
+以下参数在所有已验证的**服务器** Ascend NPU 架构上保持一致（Kirin 端侧平台除外）：
+
+| 参数 | INI 字段 | 值 | 说明 |
+|------|---------|:---:|------|
+| L0A | `[AICoreSpec] l0_a_size` | 64 KB (65536) | Cube 左矩阵操作数 |
+| L0B | `[AICoreSpec] l0_b_size` | 64 KB (65536) | Cube 右矩阵操作数 |
+| Cube MAC 阵列 | `cube_m_size / cube_k_size / cube_n_size` | 16×16×16 | 一个周期完成 4096 次 MAC |
+
+> **注意**：即便以上参数通常一致，代码中仍应通过 `GetCoreMemSize` 获取，避免硬编码。Kirin 端侧平台（DAV_3003/DAV_3113）Cube MAC 阵列不同，DAV_3113 L0A/L0B 更小，详见 §2.6/§2.7。
+
+---
+
+## 2. 各架构参数（子型号间通常一致）
+
+通常同 NpuArch 的子型号中，以下参数值一致：
+
+### 2.1 DAV_1001 — Ascend910 系列
+
+| 参数 | INI 字段 | 值 |
+|------|---------|:---:|
+| NpuArch | `NpuArch` | 1001 |
+| L1 | `l1_size` | 1 MB (1048576) |
+| L0C | `l0_c_size` | 256 KB (262144) |
+| UB | `ub_size` | 256 KB (262144) |
+| L2 | `l2_size` | 32 MB (33554432) |
+| BT | `bt_size` | — (不存在) |
+| 稀疏 | `sparsity` | — (不存在) |
+| 核心类型 | `core_type_list` | `AICore`（无独立 VectorCore） |
+| 核间关系 | — | VectorCore 不存在，ai_core 内聚 Cube+Vector 功能 |
+
+### 2.2 DAV_2002 — Ascend310P 系列
+
+| 参数 | INI 字段 | 值 |
+|------|---------|:---:|
+| NpuArch | `NpuArch` | 2002 |
+| L1 | `l1_size` | 1 MB (1048576) |
+| L0C | `l0_c_size` | 256 KB (262144) |
+| UB | `ub_size` | 256 KB (262144) |
+| L2 | `l2_size` | 16 MB (16777216) |
+| Memory | `memory_size` | 24 GB (24000000000) |
+| BT | `bt_size` | — (不存在) |
+| 稀疏 | `sparsity` | — (不存在) |
+| 核心类型 | `core_type_list` | `AICore,VectorCore`（无独立 CubeCore） |
+| 核间关系 | — | Cube 功能集成在 AICore 内，AICore 与 VectorCore 非 1:2 关系 |
+
+### 2.3 DAV_2201 — Ascend910B / Ascend910_93 系列
+
+| 参数 | INI 字段 | 值 |
+|------|---------|:---:|
+| NpuArch | `NpuArch` | 2201 |
+| L1 | `l1_size` | 512 KB (524288) |
+| L0C | `l0_c_size` | 128 KB (131072) |
+| UB | `ub_size` | 192 KB (196608) |
+| BT | `bt_size` | 1 KB (1024) |
+| 稀疏 | `sparsity` | 1（支持 4:2） |
+| 核心类型 | `core_type_list` | `CubeCore,VectorCore` |
+| 核间关系 | — | CubeCore : VectorCore = 1 : 2 |
+
+### 2.4 DAV_3002 — Ascend310B 系列
+
+| 参数 | INI 字段 | 值 |
+|------|---------|:---:|
+| NpuArch | `NpuArch` | 3002 |
+| L1 | `l1_size` | 1 MB (1048576) |
+| L0C | `l0_c_size` | 128 KB (131072) |
+| UB | `ub_size` | 248 KB (253952) |
+| BT | `bt_size` | 1 KB (1024) |
+| L2 | `l2_size` | 4 MB (4194304) |
+| 稀疏 | `sparsity` | 1（支持 4:2） |
+| 核心类型 | `core_type_list` | `AICore,VectorCore,CubeCore`（三合一） |
+| 核心数 | `ai_core_cnt / cube_core_cnt / vector_core_cnt` | 均为 1（单核集成） |
+
+### 2.5 DAV_3510 — Ascend950DT / Ascend950PR 系列
+
+| 参数 | INI 字段 | 值 |
+|------|---------|:---:|
+| NpuArch | `NpuArch` | 3510 |
+| L1 | `l1_size` | 512 KB (524288) |
+| L0C | `l0_c_size` | 256 KB (262144) |
+| UB | `ub_size` | 248 KB (253952) |
+| BT | `bt_size` | 4 KB (4096) |
+| 稀疏 | `sparsity` | 0（不再支持 4:2） |
+| 核心类型 | `core_type_list` | `CubeCore,VectorCore` |
+| 核间关系 | — | CubeCore : VectorCore = 1 : 2 |
+
+> **与 950 白皮书对照**：白皮书表4-2 的物理容量标注为 L1 512KB / L0A/L0B 64KB / L0C 256KB per AI Core，与 INI 一致；**UB 标注为 512KB per AI Core**，与 INI 对齐的解读是按 AI Core 组（1 AIC + 2 AIV）计的物理容量（每 AIV 物理 256KB × 2，"按组计"口径为推断）。INI `ub_size` 248KB 为每 AIV 用户可用值——物理 256KB − 8KB 预留 = 248KB = 253952B，与 INI 精确吻合（本地 CANN 全部 950PR/950DT SKU 已核实一致）。完整证据链见 `npu-arch-guide.md` §Buffer 容量。
+
+### 2.6 DAV_3003 — KirinX90 端侧系列
+
+> **重要说明**：KirinX90 端侧平台使用，架构代号 `dav-l300`。
+
+| 参数 | INI 字段 | 值 | 与服务器版差异 |
+|------|---------|:---:|------|
+| NpuArch | `NpuArch` | 3003 | 新架构，不在旧版映射表中 |
+| AIC_version | `AIC_version` | AIC-L-300 | 端侧专用版本标识 |
+| 核数 | `ai_core_cnt` | 1 | **单核**（服务器版多核） |
+| VectorCore | `vector_core_cnt` | 1 | 单 VectorCore |
+| L1 | `l1_size` | 1 MB (1048576) | 与 DAV_1001/2002/3002 相同 |
+| L0A | `l0_a_size` | 64 KB (65536) | **与服务器版相同**（DAV_3113 为 32 KB） |
+| L0B | `l0_b_size` | 64 KB (65536) | **与服务器版相同**（DAV_3113 为 32 KB） |
+| L0C | `l0_c_size` | 128 KB (131072) | 与 DAV_2201/3002 相同 |
+| UB | `ub_size` | 128 KB (131072) | **比服务器版小**（DAV_2201=192KB, DAV_3510=248KB） |
+| L2 | `l2_size` | 0 | **无 L2 Cache** |
+| BT | `bt_size` | 1 KB (1024) | 与 DAV_2201/3002/3113 相同 |
+| Cube MAC 阵列 | `cube_m/n/k_size` | 16×8×16 | **N 维减半，服务器版为 16×16×16** |
+| 稀疏 | `sparsity` | 1（支持 4:2） | 与 DAV_2201/3002/3113 相同 |
+| 核心类型 | `core_type_list` | `AICore,VectorCore` | Cube 功能集成在 AICore 内 |
+| vec_calc_size | `vec_calc_size` | 128 | 向量计算单元大小 |
+
+> **开发注意事项**：
+> - UB 容量仅 128 KB，Tiling 设计时需特别注意 UB 切分大小
+> - 无 L2 Cache，数据搬运策略需考虑 GM 直通
+> - Cube 阵列 N=8（而非 16），矩阵乘法输出维度不同
+> - 单核设计，无多核切分需求
+> - L0A/L0B 与服务器版相同（64KB），但 UB/L0C 较小，需注意 Cube 输出到 UB 的搬运策略
+
+
+
+### 2.7 DAV_3113 — Kirin9030 端侧系列
+
+> **重要说明**：Kirin 端侧平台使用 `mobile-station` 版 CANN，开发依赖 simulator 而非实际硬件。架构代号 `dav-l311`，`__NPU_ARCH__=3113`。
+
+| 参数 | INI 字段 | 值 | 与服务器版差异 |
+|------|---------|:---:|------|
+| NpuArch | `NpuArch` | 3113 | 新架构，不在旧版映射表中 |
+| AIC_version | `AIC_version` | AIC-L-311 | 端侧专用版本标识 |
+| 核数 | `ai_core_cnt` | 1 | **单核**（服务器版多核） |
+| VectorCore | `vector_core_cnt` | 1 | 单 VectorCore |
+| L1 | `l1_size` | 512 KB (524288) | 与 DAV_2201/3510 相同 |
+| L0A | `l0_a_size` | 32 KB (32768) | **服务器版的一半** |
+| L0B | `l0_b_size` | 32 KB (32768) | **服务器版的一半** |
+| L0C | `l0_c_size` | 64 KB (65536) | **服务器版的一半** |
+| UB | `ub_size` | 128 KB (131072) | **比 DAV_2201(192KB) 和 DAV_3510(248KB) 都小** |
+| L2 | `l2_size` | 0 | **无 L2 Cache** |
+| BT | `bt_size` | 1 KB (1024) | 与 DAV_2201/3002 相同 |
+| Cube MAC 阵列 | `cube_m/n/k_size` | 16×8×16 | **服务器版 16×16×16 的变体，N 维减半** |
+| 稀疏 | `sparsity` | 1（支持 4:2） | 与 DAV_2201/3002 相同 |
+| 核心类型 | `core_type_list` | `AICore,VectorCore` | Cube 功能集成在 AICore 内 |
+| vec_calc_size | `vec_calc_size` | 128 | 向量计算单元大小 |
+
+> **开发注意事项**：
+> - UB 容量仅 128 KB，Tiling 设计时需特别注意 UB 切分大小
+> - 无 L2 Cache，数据搬运策略需考虑 GM 直通
+> - Cube 阵列 N=8（而非 16），矩阵乘法输出维度不同
+> - 单核设计，无多核切分需求
+
+> **关于 UB 容量**：表内值为 INI `ub_size` 字段，即 `GetCoreMemSize(CoreMemType::UB, ...)` 返回的用户可用容量。**运行时始终以该接口返回值分块**，禁止硬编码。
+>
+> **FB（Fix Buffer）**：FixPipe 量化 scale 存储区。INI 字段 `fb0_size` / `fb1_size` / `fb2_size` / `fb3_size`；`GetCoreMemSize(FB)` 返回 `fb0_size`。
+
+---
+
+### 子型号变化参数
+
+> **同一 NpuArch 内，核数、频率、L2、Memory 等参数可能随子型号不同而变化。**
+>
+> `platform_config/*.ini` 涵盖多种配置（含工程样片、仿真配置），ini 文件是发现硬件参数的必要不充分条件，因此**不在此处枚举"参数范围"**。算子代码**必须通过 `PlatformAscendC` 接口运行时获取**。
+>
+> 作为参考，以下为有 archXX 特化开发路径的架构典型量产 SKU 示例（数据来源：对应 ini 文件）：
+>
+> | 架构 | 示例型号 | CubeCore | VectorCore | 频率 | L2 | Memory |
+> |------|---------|:---:|:---:|:---:|:---:|:---:|
+> | DAV_2201 | Ascend910B2 | 24 | 48 | 1.8 GHz | 192 MB | 64 GB |
+> | DAV_3510 (PCIE) | Ascend950PR_957b | 28 | 56 | 1.65 GHz | 112 MB | 112 GB |
+> | DAV_3510 (Server) | Ascend950PR_9589 | 32 | 64 | 1.65 GHz | 128 MB | 128 GB |
+>
+> > 注：DAV_2201 / DAV_3510 中 CubeCore : VectorCore = 1 : 2。
+> >
+>
+> **Ascend950DT**（950 白皮书表3-1）：Cube 36/32/28 核、Vector 72/64/56 核三档；Memory 144/96 GB @ 4TB/s；L2 128MB；Cube BF16 486/432/378T、FP8 族 973/865/756T、MXFP4 1946/1730/1513T；Vector FP16/BF16 60/54/47T（三档，每档 FP16=BF16）。950PR 为 32/28 核两档（128/112GB @ 1.6/1.4TB/s，L2 128/112MB），与上表 INI 数据一致。
+
+
+---
+
+## 3. 架构关键差异速查
+
+| 特征 | DAV_1001 | DAV_2002 | DAV_2201 | DAV_3002 | DAV_3510 | DAV_3003 (Kirin) | DAV_3113 (Kirin) |
+|------|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
+| 核心类型 | AICore | AICore+VectorCore | CubeCore+VectorCore | AICore+VectorCore+CubeCore | CubeCore+VectorCore | AICore+VectorCore | AICore+VectorCore |
+| Cube:Vec 比例 | N/A (无Vec) | 非 1:2 | 1:2 | N/A (单核) | 1:2 | N/A (单核) | N/A (单核) |
+| L1 | 1 MB | 1 MB | 512 KB | 1 MB | 512 KB | 1 MB | 512 KB |
+| L0A | 64 KB | 64 KB | 64 KB | 64 KB | 64 KB | 64 KB | **32 KB** |
+| L0B | 64 KB | 64 KB | 64 KB | 64 KB | 64 KB | 64 KB | **32 KB** |
+| L0C | 256 KB | 256 KB | 128 KB | 128 KB | 256 KB | 128 KB | 64 KB |
+| UB | 256 KB | 256 KB | 192 KB | 248 KB | 248 KB | 128 KB | 128 KB |
+| BT | — | — | 1 KB | 1 KB | 4 KB | 1 KB | 1 KB |
+| 稀疏 4:2 | — | — | 支持 | 支持 | 不支持 | 支持 | 支持 |
+| Cube 阵列 | 16³ | 16³ | 16³ | 16³ | 16³ | **16×8×16** | **16×8×16** |
+
+---
+
+## 4. 基于公开资料与经验值的规格
+
+以下信息无法从当前安装的 INI 直接推导，数据来源于公开资料或工程经验积累。**自《[昇腾950 NPU架构白皮书](https://public-download.obs.cn-east-2.myhuaweicloud.com/ascend/%E6%98%87%E8%85%BE950%20NPU%E6%9E%B6%E6%9E%84%E7%99%BD%E7%9A%AE%E4%B9%A6.pdf)》（下称"950白皮书"）发布后，其中已被白皮书证实的条目在"信息来源"列标注对应章节**：
+
+> **位置标注约定**：本表"文档位置"列使用章节锚点（如 `Guide §5`），不使用行号，以避免文档行号漂移导致引用失效。
+
+| # | 内容 | 文档位置 | 信息来源 |
+|---|------|---------|---------|
+| 1 | SIMT Register File 128KB | Guide §5 SIMT vs SIMD | 公开资料 / 经验值 |
+| 2 | SIMT DCache 最大 128KB | Guide §5 SIMT vs SIMD | 同上 |
+| 3 | SSBuffer 256KB | Guide §3 Buffer 容量 / SKILL.md §DAV_3510 关键变化 | 同上 |
+| 4 | CV 直通通路：L0C→UB、UB→L1、SSBuffer 消息 | Guide §4 关键数据通路改动 / SKILL.md §DAV_3510 关键变化 | L0C→UB（含随路量化）与 L1↔UB 直连：950白皮书 §4.1.1/§4.1.4；SSBuffer 消息通路：公开资料 / 经验值 |
+| 5 | L1→GM 和 GM→L0A/L0B 通路已删除 | Guide §4 关键数据通路改动 | 公开资料 / 经验值 |
+| 6 | BufferID 取代 set/wait 同步 | Guide §4 指令序列与 BufferID 同步 / SKILL.md §DAV_3510 关键变化 | 950白皮书 §4.1.6 |
+| 7 | 多核同时访问 GM 同地址性能优化 | Guide §4 MTE 数据搬运引擎 | 公开资料 / 经验值 |
+| 8 | SIMD-Regbase：OOO 指令双发 | Guide §6 SIMD-Regbase | 950白皮书 §3/§4.1.2/§4.1.3 |
+| 9 | Warp Scheduler 每 AIV 4 个 | Guide §5 SIMT vs SIMD | 公开资料 / 经验值 |
+| 10 | NDDMA + ND-DMA Cache 规格 | Guide §8 NDDMA 高维 DMA | 950白皮书 §4.1.5 |
+| 11 | CCU 三种通信范式及 KFC 调度变化 | Guide §9 CCU 通算融合 | CCU 硬件架构与算法支持：950白皮书 §4.6.4；三种通信范式与 KFC 调度细节：公开资料 / 经验值 |
+| 12 | Vector 算力 950PR Server=54T / PCIE=47T：基准 27T/23.7T × 双发 2，但并非所有 Vector 指令均支持双发 | Guide §3 算力与系统规格 → Vector 算力推导 | 950白皮书 表3-1 + §3/§4.1.2/§4.1.3 |
+| 13 | Memory 带宽 Server 1.6 TB/s / PCIE 1.4 TB/s | Guide §3 算力与系统规格 | 950白皮书 表3-1/§4.3.1；910B2 带宽仍为公开资料 / 经验值 |

package/assets/ops-direct-invoke/skills/npu-arch/references/simt-arch-guide.md

@@ -0,0 +1,303 @@
+# SIMT 架构概念参考
+
+> SIMT vs SIMD 的核心差异、混合编程和选型指南已在 `npu-arch-guide.md` 中覆盖，此处不再重复。
+
+---
+
+## SIMT 线程层次结构
+
+### 概述
+
+AscendC SIMT 编程模型采用三级线程层次：
+
+| 层级 | 概念 | 对应 CUDA | 设置方式 |
+|------|------|----------|---------|
+| 启动核数 | Block 数量 | Grid 中的 Block 数 | tiling 侧 `SetBlockDim` |
+| 启动线程数 | 单核线程数 | 单 Block 线程数 | kernel 侧 `constexpr` 常量 |
+| Warp | 32 线程分组 | Warp | 硬件自动分组 |
+
+### 核数（Block Dim）
+
+- 通过 tiling 侧 `SetBlockDim` 接口设置
+- 对应 CUDA 中的 Block 概念
+- 切分公式：`总核数 = ceil(输出元素总数 / 单核最少处理元素数)`
+
+### 线程数
+
+- 单核最大支持 **2048** 线程
+- **必须在编译期确定**（使用 `constexpr` 或字面量）
+- 禁止从 tiling 数据动态获取
+- `LAUNCH_BOUND(N)` 和 `Simt::Dim3(N)` 必须使用同一个编译期常量
+- 默认值: 1024，建议范围根据数据量和计算复杂度调整
+
+### Warp 调度
+
+- 内部按 **32 线程** 分组形成 warp
+- Warp 是硬件调度的最小单位
+- 每个 AIV 核包含 4 个 Warp Scheduler，调度器编号为 `warp_id % 4`
+- 同一时刻一个 AIV 核只执行一个线程块任务
+- 线程块内多个 Warp 被依次调度执行
+
+---
+
+## Warp 调度机制
+
+### 基本概念
+
+- 每 **32 个线程** 组成一个 Warp
+- Warp 是硬件调度的最小单位
+- Warp 内每个线程称为 Lane，编号 0~31
+
+### 硬件调度
+
+- 每个 AIV 核包含 **4 个 Warp Scheduler**，调度器编号为 `warp_id % 4`
+- 同一时刻一个 AIV 核只执行一个线程块任务
+- 线程块内多个 Warp 被依次调度到 AI Core 执行
+
+### SIMT 执行语义
+
+- Warp 内所有线程执行**相同指令**（SIMT 语义）
+- 分支发散（Branch Divergence）时串行执行各分支路径
+  - 若 warp 内部分线程走 if 分支，部分走 else 分支
+  - 硬件先执行 if 路径（else 线程等待），再执行 else 路径（if 线程等待）
+  - 导致流水线气泡，降低有效利用率
+
+### 分支发散优化
+
+- 减少同一 warp 内的分支分化
+- 将运行时分支提升到编译期（`if constexpr` / 模板参数）
+- 同一 warp 内线程尽量走相同执行路径
+
+---
+
+## SIMT 内存空间
+
+### 概述
+
+AscendC SIMT 编程模型包含三类内存空间：
+
+| 内存类型 | 说明 | 访问范围 | 地址空间修饰符 |
+|---------|------|---------|--------------|
+| 寄存器和栈 | 每个线程独立 | 线程私有 | 无（默认） |
+| Unified Buffer (UB) | 本地内存 | 核内共享 | `__ubuf__` |
+| Global Memory (GM) | 全局内存 | 所有线程可访问 | `__gm__` |
+
+### 寄存器和栈
+
+- 每个线程独享一组寄存器
+- 寄存器数量受线程数影响（参见 `launch_bounds_registers.md`）
+- 超出寄存器容量的变量会栈溢出
+
+### Unified Buffer (UB)
+
+- 核内共享的本地内存
+- 总量 256KB，按分区使用（详见 `ub_partition.md`）
+- SIMT 算子不能使用全部 UB 空间，需为 DCache 预留 ≥32KB
+- 可用 UB = 256KB - 8KB(预留) - 32KB(DCache) = **216KB**
+- 在 SIMT VF 中通过 `__ubuf__` 指针访问
+
+### Global Memory (GM)
+
+- 所有核所有线程均可访问
+- SIMT VF 支持直接读写 GM，无需显式 Load/Store
+- 通过 `__gm__` 指针访问
+- 在 kernel 入口通过 `GM_ADDR` 参数传入
+
+### 与 SIMD 的差异
+
+| 维度 | SIMD | SIMT |
+|------|------|------|
+| 数据搬运 | 需显式 Load/Store | 支持直接读写 GM 和 UB |
+| GM 访问 | 不支持直接到寄存器 | 支持直接访问 |
+
+---
+
+## UB 内存分区
+
+### 总量
+
+Unified Buffer 总量 **256KB**，从低地址到高地址依次分区：
+
+| 区域 | 大小 | 说明 |
+|------|------|------|
+| 静态内存 | 编译期确定 | `__ubuf__` 数组声明，混合编程中用于 SIMD/SIMT 共享数据 |
+| 动态内存 | tiling 侧 `SetLocalMemory` 设置 | TBuf/LocalTensor 申请，混合编程中通过 `<<<>>>` 的 dynUBufSize 指定 |
+| 预留空间 | 固定 8KB | 编译器预留，不可使用 |
+| Data Cache | = 256KB - 静态 - 动态 - 8KB | SIMT 专有 DCache |
+
+### 关键约束
+
+- **SIMT 算子不能使用全部 UB 空间**，需为 DCache 预留 ≥32KB
+- 若 DCache < 32KB，编译校验报错
+- 可用 UB = 256KB - 8KB - 32KB = **216KB**
+
+### Tiling 侧设置
+
+定义 `DCACHE_SIZE` 为 128KB，使用 `SetLocalMemorySize` 设置参数为 `ubsize - DCACHE_SIZE`：
+
+```cpp
+constexpr uint64_t DCACHE_SIZE = 128 * 1024;
+uint64_t ubsize = 256 * 1024;
+context->SetLocalMemorySize(ubsize - DCACHE_SIZE);
+```
+
+### 静态内存 vs 动态内存
+
+| 类型 | 声明方式 | 适用场景 |
+|------|---------|---------|
+| 静态内存 | `__ubuf__ T buffer[SIZE];` | 编译期已知大小的共享 buffer |
+| 动态内存 | `TBuf<QuePosition::VECCALC>` + `pipe_->InitBuffer()` | 运行时按需分配 |
+
+---
+
+## 数据类型速查
+
+### 按位宽分类
+
+| 位宽 | 数据类型 |
+|------|---------|
+| b8 | bool, int8_t, uint8_t, hifloat8_t, fp8_e5m2_t, fp8_e4m3fn_t |
+| b16 | int16_t, uint16_t, **half**, **bfloat16_t** |
+| b32 | int32_t, uint32_t, **float**, complex32 |
+| b64 | int64_t, uint64_t, double, complex64 |
+
+### SIMT VF 函数参数支持类型
+
+#### 标量类型
+
+bool, int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, uint64_t, float, half, bfloat16_t
+
+#### 指针类型
+
+- `__gm__ T*` — Global Memory 指针
+- `__ubuf__ T*` — Unified Buffer 指针
+
+#### 返回值
+
+必须是 `void`
+
+### 特殊值宏
+
+| 宏名 | 描述 | 头文件 |
+|------|------|--------|
+| ASCRT_INF_BF16 | bfloat16 正无穷 | asc_bf16.h |
+| ASCRT_MAX_NORMAL_BF16 | bfloat16 最大值 | asc_bf16.h |
+| ASCRT_NAN_BF16 | bfloat16 NaN | asc_bf16.h |
+| ASCRT_INF_F16 | half 正无穷 | asc_fp16.h |
+| ASCRT_MAX_NORMAL_F16 | half 最大值 | asc_fp16.h |
+| ASCRT_NAN_F16 | half NaN | asc_fp16.h |
+| ASCRT_INF_F32 | float 正无穷 | asc_simt.h |
+| ASCRT_MAX_NORMAL_F32 | float 最大值 | asc_simt.h |
+
+---
+
+## 函数调用层级
+
+### 层级结构
+
+```
+核函数 (__global__ __aicore__)
+  ├── __aicore__ 函数
+  ├── SIMD VF (__simd_vf__) ← 通过 asc_vf_call 调用
+  │     └── __simd_callee__ 子函数
+  └── SIMT VF (__simt_vf__) ← 通过 VF_CALL 调用
+        └── __simt_callee__ 子函数
+```
+
+### 各层级说明
+
+#### 核函数
+
+```cpp
+__global__ __aicore__ void {op_name}(GM_ADDR x, GM_ADDR y, GM_ADDR workspace, GM_ADDR tiling)
+```
+
+- 算子入口，由框架调用
+- 负责 tiling 数据解析和场景分发
+- 通过 `REGISTER_TILING_DEFAULT` + `GET_TILING_DATA_WITH_STRUCT` 获取 tiling
+
+#### __aicore__ 函数
+
+```cpp
+__aicore__ inline void Process(GM_ADDR x, GM_ADDR y, const TilingData* tilingData)
+```
+
+- 核内主逻辑函数
+- 负责 UB buffer 初始化、GM 地址转换
+- 调用 `Simt::VF_CALL` 启动 SIMT VF
+
+#### SIMT VF 函数
+
+```cpp
+__simt_vf__ __aicore__ LAUNCH_BOUND(THREAD_NUM) inline void OpComputeSimt(...)
+```
+
+- 线程级并行计算函数
+- 每个线程独立执行，以 stride 间隔遍历数据
+- 可调用 `__simt_callee__` 子函数和 `constexpr` 函数
+
+#### __simt_callee__ 子函数
+
+```cpp
+__simt_callee__ inline void HelperFunc(...)
+```
+
+- SIMT VF 内部的辅助函数
+- 必须带 `__simt_callee__` 修饰符
+- 可被 `__simt_vf__` 函数调用
+
+### 调用约束
+
+- `__simt_vf__` 内只能调用 `__simt_callee__` 函数和 `constexpr` 函数
+- `__simd_vf__` 内只能调用 `__simd_callee__` 函数和 `constexpr` 函数
+- 不可跨模式调用（SIMT VF 不能调用 SIMD callee，反之亦然）
+
+---
+
+## LAUNCH_BOUND 与寄存器数量
+
+### 寄存器数量映射
+
+`__launch_bounds__(N)` 限定每个 VF Block 使用的最大线程数，线程数直接影响每线程可用寄存器数：
+
+| 线程数范围 | 每线程可用寄存器数 |
+|-----------|-----------------|
+| 1025~2048 | 16 |
+| 513~1024 | 32 |
+| 257~512 | 64 |
+| 1~256 | 127 |
+
+### 使用原则
+
+- 寄存器用于存储线程局部变量
+- 超出寄存器容量则栈溢出，影响性能
+- 建议 `__launch_bounds__(N)` 的 N 与实际启动线程数一致
+- `LAUNCH_BOUND(N)` 和 `Simt::Dim3(N)` 必须使用同一个编译期常量
+
+### 声明语法
+
+```cpp
+__simt_vf__ __aicore__ LAUNCH_BOUND(512) inline void YourKernel(...);
+```
+
+- `LAUNCH_BOUND(thread_num)` 可选，默认 1024
+- 参数必须是 `constexpr` 常量或字面量
+
+### 线程数选择参考
+
+| 算子类型 | 建议线程数 | 原因 |
+|---------|-----------|------|
+| 搬运类算子 | 2048 / 1024 | 内存带宽受限，更多线程隐藏延迟 |
+| 计算类算子 | 512 / 1024 | 寄存器压力较大，需平衡并行度和寄存器 |
+
+### 寄存器压力与线程数调优
+
+寄存器压力随 VF 复杂度增加而增大：
+
+| VF 复杂度 | uint32_t 索引线程数 | uint64_t 索引线程数 |
+|-----------|-------------------|-------------------|
+| 极低（NONE/1D） | 1024 | 512 |
+| 中低（2D） | 1024 | 512 |
+| 中等（3D） | 1024 | 512 |
+| 较高（4D） | 1024 | 512 |
+| 最高（ND运行时循环） | 256 | 128 |

package/assets/ops-direct-invoke/skills/ops-design-paradigms/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ops-design-paradigms
+description: 当需要设计或修订 Broadcast、Reduction 等算子范式方案，或查询对应算法、资源规划、语言实现约束和故障经验时使用；提供 Ascend C regbase 与 CANNBotDSL 的设计依据、适用条件和验证要点。
+---
+
+# 算子通用设计知识与范式指导
+
+根据算子语义和开发语言提供范式知识，支持方案设计、实现选择与问题定位。内容分为语言中立的算法模型和语言专用的实现约束，按当前问题读取。
+
+## 输入与输出
+
+- 输入：算子规格或等价的数学语义与范式信息、明确的开发语言（`ascendc` 或 `dsl`）、目标平台，以及待解决的设计或实现问题。文件路径由调用方提供。
+- 缺少语言或范式信息时，返回具体缺项；确认后再选择专用参考。
+- 输出：适用的算法与实现建议、约束及其依据、资源与同步分析、尚待验证的事实。产物格式和保存位置由调用方确定。
+
+## 范式与语言选择
+
+1. 先读取 [知识索引](references/index.md)，按当前问题选择入口。
+2. 当 `op.paradigms` 同时包含 `Contraction`、`Reduction`、`Broadcast` 时，先核对实际公式。公式包含注意力分数计算、行归一化与加权值聚合时，读取 [FA 组合范式](references/paradigms/FA/patterns.md)；其余组合按范式索引逐项读取。标签匹配按集合包含关系判断，顺序及额外标签不影响匹配。
+3. 其余情况统一按 [范式索引表](references/paradigms/routes.yaml) 逐项查找。多个范式覆盖不同设计维度，分别按需读取；未注册范式使用对应语言的通用方法。
+4. 每个范式的 `patterns.md` 根据调用方提供的语言选择适配层。只读取通用层和对应语言的适配层，缺少适配层时保留通用算法，语言 API 与设备能力依据调用方提供的资料确认。
+
+## 参考选择
+
+| 当前问题 | 入口 |
+|---|---|
+| Broadcast、Reduction 方案与资源规划 | [范式索引表](references/paradigms/routes.yaml) |
+| Ascend C regbase 开发方法 | [开发指导](references/knowledge/regbase_development_guide.md) |
+| Ascend C API、实现模式、精度风险或开发经验 | [知识分类索引](references/knowledge/index.md) |
+| 缺少专用范式或语言适配层 | [Ascend C 通用方法](references/paradigms/general-methodology.md)、[DSL 通用方法](references/paradigms/general-methodology-dsl.md) |
+| 选择现有 Ascend C 实现作为参考 | [开源算子表](references/reference-ops/open_source_operator_table.md) |
+
+`knowledge/` 与 `reference-ops/` 是 Ascend C regbase 资料，DSL 问题仅使用相关通用层和 DSL 适配资料。
+
+## 使用约束
+
+- 进入 `api/`、`patterns/`、`pitfalls/` 或 `dev-experience/` 时先读目录索引，按 `purpose`、`read_when`、`keywords` 选取叶子文档。单个子问题最多展开 5 份，仍未解决则拆分问题。
+- 能力谓词以对应语言的 `capability-mapping.md` 为依据；标注“待验证”的项须作为假设和验证义务输出。
+- 实现参考用于核对 API 与组织方式；名称或类型匹配不能证明可以直接复制或融合，算法与参数需依据当前规格判断。
+- 明确资料对应的平台。兼容性经验不能直接作为 `ascend950 / regbase` 的已验证结论。
+- 设计输出应能追溯到规格和参考资料；缺少 API、资源或运行证据时报告具体缺口。

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

@@ -0,0 +1,32 @@
+# 算子范式知识索引
+
+按具体设计问题、知识类型和开发语言选择参考。本模块提供算法、实现约束与验证依据。
+
+## 检索规则
+
+1. 先应用 Skill 入口的组合范式规则；未命中组合时，统一从 [范式索引表](paradigms/routes.yaml) 查找 `op.paradigms`，不通过扫描目录推断注册状态。
+2. 范式入口按调用方明确提供的 `op.language` 选择适配层。缺失或未知时返回输入缺项，不默认选择 Ascend C。
+3. 读取语言中立的通用层和一个对应语言的适配层。DSL 范式没有专用适配层时，使用 [DSL 通用方法](paradigms/general-methodology-dsl.md) 并核实所需 API 和设备事实。
+4. 进入知识分类目录后先读该目录的 `index.md`；单个子问题最多展开 5 份叶子文档。
+
+## 按问题选择
+
+| 问题 | 参考 |
+|---|---|
+| Broadcast 算法、形状归一化与切分 | [Broadcast 入口](paradigms/broadcast/patterns.md) |
+| Reduction 归约轴、缓存树与资源规划 | [Reduction 入口](paradigms/reduction/patterns.md) |
+| Contraction、Reduction、Broadcast 组合 | [FA 组合范式](paradigms/FA/patterns.md) |
+| Ascend C regbase 开发方法 | [开发指导](knowledge/regbase_development_guide.md) |
+| API 约束与签名 | [API 索引](knowledge/api/index.md) |
+| Kernel、VF 与 Reg-MicroAPI 组织 | [实现模式](knowledge/patterns/index.md) |
+| 精度、数值稳定性和错误定位 | [常见问题](knowledge/pitfalls/index.md) |
+| 构建、验证与上下文恢复 | [开发经验](knowledge/dev-experience/index.md) |
+| 选择现有 Ascend C 实现 | [开源算子表](reference-ops/open_source_operator_table.md) |
+
+## 平台与语言范围
+
+- `ascend950 / regbase`：根据问题读取 [知识分类索引](knowledge/index.md) 下的 API、模式和经验。
+- `ascend910b / membase`：只在明确的兼容性问题中参考对应资料，核对适用平台。
+- `dsl / CANNBotDSL`：从范式入口选择 DSL 适配层。`knowledge/` 和 `reference-ops/` 属于 Ascend C regbase，不作为 DSL 默认参考。
+
+算子表只用于筛选可检查的实现；能否复用必须结合具体代码、规格和平台约束判断。