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

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: ascendc-regbase-best-practice
+description: 当需要为 DAV_3510 RegBase 算子确认 API 约束、实现结构、排查常见陷阱或选择真实参考算子时使用。
+---
+
+# Ascend C RegBase 开发
+
+该能力解决 RegBase 路线下的四类问题：API 约束确认、实现结构参考、常见陷阱排查、真实参考算子选择。
+
+`reference-ops` 子树是轻量参考资产。算子名称或基础类型匹配只表示“值得查看的候选参考”，不能证明目标任务可以直接复用、融合或复制该实现。是否复用必须重新做 RegBase 专项设计判断。
+
+## 何时使用
+
+满足以下任一条件时使用该能力：
+
+- Architect 在方案决策中把 RegBase 作为候选路线。
+- 用户、DESIGN.md 或代码明确出现 RegBase / RegTensor / asc_vf_call / __simd_vf__ 等信号。
+- Developer 或 Reviewer 需要确认 RegBase 专属 API、实现结构、陷阱或参考实现。
+
+不要把该能力当成默认算子开发路径的通用替代品。技术路线未决时，由 Architect 完成 SIMD/MemBase 与 RegBase 的方案决策。
+
+## 阅读入口
+
+- 端到端开发主线：`references/regbase_development_guide.md`
+- API 约束和签名：`references/api/index.md`
+- 陷阱和精度风险：`references/pitfalls/index.md`
+- 工程经验和路线判断：`references/dev-experience/index.md`
+- 算子范式设计：`references/paradigms/`，每个范式以自身 `patterns.md` 为入口，按需渐进展开更深层参考、示例和模板。
+- 真实参考实现：`references/reference-ops/open_source_operator_table.md`
+
+## 按阶段选择
+
+- 方案决策：`references/regbase_development_guide.md`、`references/dev-experience/index.md`
+- 设计：`references/regbase_development_guide.md`、`references/api/index.md`、按范式名路由的 `references/paradigms/<paradigm>/patterns.md`
+- 实现：`references/api/index.md`、`references/dev-experience/regbase_programming_notes.md`、`references/reference-ops/open_source_operator_table.md`
+- 审查：`references/pitfalls/index.md`、`references/dev-experience/index.md`
+- 修复和调试：`references/pitfalls/symptom_to_cause.md`、`references/dev-experience/index.md`
+
+进入 `api/`、`pitfalls/` 或 `dev-experience/` 后，先读该目录的 `index.md`，再打开叶子文档。针对一个子问题，最多展开 5 篇叶子文档；仍不够时拆分问题，而不是一次加载整个子树。
+
+## 约束
+
+- 引用 API 前必须检查 API 白名单、API reference 或官方文档；不要凭函数名猜测。
+- 设计伪代码不能直接当作可编译实现；写代码时必须回到真实工程模板和 API 签名。
+- 编写新 RegBase 算子前，必须通过 `open_source_operator_table.md` 定位候选目录，并阅读至少一个经确认包含 RegBase 证据的真实实现。
+- 看到 `RegTensor` / `MaskReg` / `asc_vf_call` / `__simd_vf__` 等关键词时，优先检查 API 层和 pitfalls 层。
+- 架构判断必须显式说明。如果某条经验来自兼容路径而不是主路径 `DAV_3510 / RegBase`，需要说清楚。

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/evals/evals.json

@@ -0,0 +1,115 @@
+{
+  "eval_mode": "text",
+  "evals": [
+    {
+      "id": 2,
+      "title": "RegBase 开发的参考资源",
+      "config": {
+        "max_tokens": 100000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "在进行 RegBase 算子开发时有哪些可用的参考资源？我需要查阅哪些文档来提升开发效率？如果我想参考已有的算子实现，应该从哪里入手？不需要执行任何工具调用。",
+      "expected_output": "回复应列出 RegBase 开发可参考的资源类型，包括文档、社区实现和用例等，供开发者参考学习。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 3,
+      "title": "UpdateMask 计数变量只能有一个推进者",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请加载并使用 ascendc-regbase-best-practice 技能回答以下问题（可阅读该技能文档，但不要实际运行脚本或修改代码）。RegBase VF tail 循环写成 `uint32_t remaining = cols; for (...) { auto mask = UpdateMask<float>(remaining); remaining -= VL; }`，并声称这样可以显式推进循环。请依据该技能文档记录的当前 SDK RegBase header 声明回答：(1) 这个循环错在哪里——UpdateMask 的签名与计数推进语义是什么、同一个进度变量出现了几个推进者；(2) 给出两种合法修复：一种让 UpdateMask(remaining) 独自推进，另一种让 UpdateMask(active) 与独立的 remaining/索引推进配合。",
+      "expected_output": "1. 应指出当前 SDK 的 RegBase header 把 UpdateMask<T> 声明为 UpdateMask(uint32_t&)，会通过引用（post-update 语义）推进传入的计数，不能把它当作只读的 mask 工厂。\n2. 应指出在 UpdateMask(remaining) 之后又手工执行 remaining -= VL 属于 double-decrement：同一个进度变量出现两个推进者，会跳过 slice/tail。\n3. 应给出两种可区分的合法修复：① 由 UpdateMask(remaining) 独自推进，循环体不再修改 remaining，索引用不变的 offset/步长计算；② 先保存 step、把 active 传给 UpdateMask(active)，再用未被更新的 step 推进 remaining 和 offset，不能读取更新后的局部值推导下一次偏移。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 4,
+      "title": "新 RegBase 算子的参考实现选择流程",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我要在 DAV_3510 上写一个 fp16 的逐元素缩放算子，想先从开源仓找一个值得阅读的参考实现再动手。请问应如何定位候选算子目录，以及需要确认哪些证据才能判断该目录真的包含 RegBase 实现？我希望按规范一步步来。可阅读该技能文档获取规范，但不要实际去 clone 仓库或修改代码。",
+      "expected_output": "1. 应说明通过 references/reference-ops/open_source_operator_table.md 按算子名与基础类型定位候选算子目录（查看「代码路径」找到最接近的实现子树），并指出命中只表示「值得阅读的候选」，既不证明可直接复用、也不证明目录一定包含 RegBase 实现。\n2. 应列出确认目录包含 RegBase 实现需要核对的证据：op_kernel/arch35/*regbase*、*_apt.cpp、__VEC_SCOPE__、__simd_vf__、RegTensor 或 AscendC::MicroAPI::*。\n3. 应给出固定阅读顺序 kernel entry（TILING_KEY_IS(...) 路由、dtype route）→ Init（GM/UB binding、pipe/queue/buffer）→ Process（tile loop、tail、CopyIn -> Compute -> CopyOut）→ VF body（RegTensor、MaskReg、LoadDist、StoreDist、API family），并说明参考实现只证明某种结构可行，仍需按当前任务的 shape、dtype、tail 与 API 适配性重新判断。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 5,
+      "title": "VF body 内误用 DataCopy 等 MemBase API",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我在写 RegBase 算子的 VF body，打算在 __simd_vf__ 函数里直接调用 DataCopy 把数据从 GM 搬到 UB 再计算，同事说这样不行。请问在 VF 函数内到底该用什么 API 搬运数据，以及在使用任何 RegBase API 之前需要先做哪些确认？可阅读该技能文档获取规范，但不要实际执行修改代码。",
+      "expected_output": "必须指出 DataCopy / DataCopyPad 属于 GM/UB 搬运（MTE），只能放在 CopyIn/CopyOut 的 kernel 侧，不能写进 __simd_vf__。进入 VF 后应使用 AscendC::Reg::*（开源代码中常写作 AscendC::MicroAPI::*，是同一 VF-safe family）的 LoadAlign / StoreAlign / Load / Store 等 API，在 UB address 与 RegTensor 之间搬运。引用 API 前必须检查 regbase_api_whitelist.md 与 SDK header（如 basic_api/reg_compute/），不要凭函数名猜测；VF 入口保持 __simd_vf__ + asc_vf_call 结构。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 6,
+      "title": "RegBase 算子整体结构分层设计",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我第一次写 RegBase 算子，觉得既然计算核心是寄存器级，那把整个 kernel 写成一个大的 VF 函数就够了，不需要 TPipe、TQue 那些队列。这个想法对吗？正确的分层结构应该怎么组织？可阅读该技能文档获取规范，但不要实际执行修改代码。",
+      "expected_output": "1. 应指出把整个 kernel 写成一个大的 VF 函数是常见错误；RegBase 不是「不需要 TPipe/TQue/LocalTensor」，不能因为计算核心是寄存器级就省掉队列。\n2. 应给出四层模型：Host/tiling 层、Kernel outer shell（管理 TPipe、GlobalTensor、TQue、LocalTensor、Init/Process）、UB 层数据流（CopyIn -> Compute -> CopyOut）、VF 寄存器计算内层（__VEC_SCOPE__ / __simd_vf__ 内使用 RegTensor、MaskReg、LoadDist、StoreDist）。\n3. 应说明 RegBase 的身份来自 Compute 的数学核心进入寄存器级 VF body（看到 TQue/LocalTensor 不是判定 MemBase 的依据），outer shell 仍用 TQue/LocalTensor 做 UB staging，且 Compute 通过 asc_vf_call 调用 __simd_vf__ 入口。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 7,
+      "title": "VF body 里用 SyncAll / SetFlag 修本地 stage 顺序",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我写了一个 RegBase 算子，VF body 里 LoadAlign 之后觉得数据还没就绪，就在 __simd_vf__ 里加了 SyncAll 和 SetFlag/WaitFlag 想确保顺序，但编译总报错。我应该怎么做才是对的？可阅读该技能文档获取规范，但不要实际执行修改代码。",
+      "expected_output": "必须指出 SyncAll、SetFlag、WaitFlag 属于 outer shell 的同步/事件机制，不能写进 __simd_vf__ 的默认 callable surface；普通 LoadAlign -> Reg 计算 -> StoreAlign 寄存器链不需要 barrier。MaskReg 是有效通道控制、LoadDist/StoreDist 是 load/store 分布描述，都不是同步 fence，用它们修本地 stage ordering 是同步陷阱。VF 内出现真实 producer/consumer 顺序风险时才考虑 AscendC::Reg::LocalMemBar，并按 MemType 确认使用边界。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 8,
+      "title": "设计含 TQue/LocalTensor 是否意味着不是 RegBase",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "Reviewer 看了我的 RegBase 设计方案，发现外层用了 TPipe、TQue 和 LocalTensor 做数据搬运，就说这其实是 MemBase 而不是 RegBase，让我重写。我该怎么判断和回应？可阅读该技能文档获取规范，但不要实际执行修改代码。",
+      "expected_output": "应说明 RegBase outer shell 使用 TPipe、TQue、LocalTensor 做 UB staging 是允许的，这不等于 MemBase；RegBase 与 MemBase 的区别在于 Compute 的数学核心是否进入寄存器级 VF body（__VEC_SCOPE__ 内使用 RegTensor/MaskReg），而不是外层是否用队列。不应因为出现 TQue 就否定 RegBase；也不要一边声明 asc_vf_call 一边给出 MemBase API 伪代码。应重新画 Host/Kernel/UB/VF 分层，区分 UB staging 与 VF compute，并对不确定的 API 回到白名单和参考实现验证。",
+      "expectations": [],
+      "files": []
+    }
+  ],
+  "skill_name": "ascendc-regbase-best-practice"
+}

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/api/arithmetic_and_reduce.md

@@ -0,0 +1,228 @@
+---
+title: 算术与归约
+purpose: 选择标量、广播式、归约 API 家族，并记录 repeat 和 shape 约束。
+read_when:
+  - 正在 `Duplicate + Add`、标量 helper、repeat 广播形态或归约家族之间选择。
+  - 算子数学已经明确，但算术或归约 API 家族不清楚。
+not_for:
+  - 构建或打包问题。
+  - 高层 kernel structuring。
+keywords:
+  - arithmetic
+  - reduce
+  - repeat limits
+  - scalar helpers
+next_reads:
+  - compute_api_membase_vs_regbase.md
+  - regbase_api_whitelist.md
+  - ../pitfalls/precision_guide.md
+depth: intermediate
+topic_type: api
+---
+
+# 算术与归约
+
+本卡片合并两类通常决定 RegBase kernel 形状的 API 家族：标量 / 广播算术，以及本地或模式化归约。
+
+## 算术选择
+
+单行或标量化工作中，优先使用标量 helper：
+
+- 使用 `Adds`，不要默认写成 `Duplicate + Add`。
+- 使用 `Muls`，不要默认写成 `Duplicate + Mul`。
+
+重复行广播时，使用带 `BinaryRepeatParams` 的 repeat 形态，并设置 `src1RepStride = 0`，让一个源操作数被复用，而不是物化广播缓冲。
+
+## Reg Compute 代表签名
+
+本节只列 RegBase VF 侧常用形态，签名来自 CANN 9.0.0 `basic_api/reg_compute/` header。它用于避免只写 API 名称；最终 dtype 支持、模板默认值和平台条件仍以当前 SDK header 为准。
+
+签名中的 `__simd_callee__` 保留 SDK 原样，表示这些 API 可被 VF body 调用；新算子的 VF 入口仍应按工程模板写成 `__simd_vf__` 并通过 `asc_vf_call` 进入。
+
+### 标量 helper
+
+来源：`kernel_reg_compute_vec_binary_scalar_intf.h`。
+
+```cpp
+template <typename T = DefaultType, typename U, MaskMergeMode mode = MaskMergeMode::ZEROING, typename S>
+__simd_callee__ inline void Adds(S& dstReg, S& srcReg, U scalarValue, MaskReg& mask);
+
+template <typename T = DefaultType, typename U, MaskMergeMode mode = MaskMergeMode::ZEROING, typename S>
+__simd_callee__ inline void Muls(S& dstReg, S& srcReg, U scalarValue, MaskReg& mask);
+```
+
+用法边界：
+
+- `dstReg` 与 `srcReg` 是 register object，通常是 `RegTensor<T>` 或同类 reg container。
+- `scalarValue` 是标量操作数，不要为了标量加/乘先物化广播缓冲。
+- `mask` 控制 active lanes；tail 应在调用前通过 `MaskReg` 准备好。
+
+### 二元算术
+
+来源：`kernel_reg_compute_vec_binary_intf.h`。
+
+```cpp
+template <typename T = DefaultType, MaskMergeMode mode = MaskMergeMode::ZEROING, typename U>
+__simd_callee__ inline void Add(U& dstReg, U& srcReg0, U& srcReg1, MaskReg& mask);
+
+template <typename T = DefaultType, MaskMergeMode mode = MaskMergeMode::ZEROING, typename U>
+__simd_callee__ inline void Sub(U& dstReg, U& srcReg0, U& srcReg1, MaskReg& mask);
+
+template <typename T = DefaultType, MaskMergeMode mode = MaskMergeMode::ZEROING, typename U>
+__simd_callee__ inline void Mul(U& dstReg, U& srcReg0, U& srcReg1, MaskReg& mask);
+
+template <typename T = DefaultType, auto mode = MaskMergeMode::ZEROING, typename U>
+__simd_callee__ inline void Div(U& dstReg, U& srcReg0, U& srcReg1, MaskReg& mask);
+```
+
+用法边界：
+
+- 两个输入寄存器必须来自同一 VF lane 语义，不要把 `LocalTensor` 直接传入 VF 侧 API。
+- `MaskMergeMode::ZEROING` 这类模板参数影响 inactive lane 的合并语义，设计文档应写清楚 tail 结果是否需要保留旧值。
+
+### 比较 / 选择
+
+来源：`kernel_reg_compute_vec_cmpsel_intf.h`。
+
+```cpp
+template <typename T = DefaultType, CMPMODE mode = CMPMODE::EQ, typename U>
+__simd_callee__ inline void Compare(MaskReg& dst, U& srcReg0, U& srcReg1, MaskReg& mask);
+
+template <typename T = DefaultType, CMPMODE mode = CMPMODE::EQ, typename U, typename S>
+__simd_callee__ inline void Compares(MaskReg& dst, U& srcReg, S scalarValue, MaskReg& mask);
+
+template <typename T = DefaultType, typename U>
+__simd_callee__ inline void Select(U& dstReg, U& srcReg0, U& srcReg1, MaskReg& mask);
+```
+
+用法边界：
+
+- `Compare` / `Compares` 的结果是 `MaskReg`，它可以继续控制后续 `Select` 或 store，不是 event sync。
+- `CMPMODE` 必须在设计中明确，例如等于、大于、小于等；不要只写“比较得到 mask”。
+- `Select` 的两个源寄存器要有同一 dtype 路线和 lane 布局。
+
+## Repeat 限制
+
+很多 vector repeat 形态 API 的 `repeatTime` 是 `uint8_t`，实际限制是 255。
+
+如果某个 tile 可能超过这个限制，应在进入 kernel 循环前拆分工作，而不是让 repeat 计数器溢出。
+
+## Reduce 选择
+
+Reduction 在 RegBase 中需要同时考虑 reduce 维度、tile 切分、partial result 和 dtype accumulation。不要只写一个 `ReduceSum` 名称就结束设计。
+
+设计前先回答四个问题：
+
+1. reduce 维度是哪一个，内存是否连续。
+2. 一个 tile 能否覆盖完整 reduce 维度。
+3. partial result 存在 register、UB 还是 GM。
+4. accumulation dtype 是什么，最终何时 cast。
+
+根据 shape 和 alignment 选择 reduce family：
+
+- row-local reduction：例如 softmax、layernorm 风格的行内归约，选择 level-2 reduce。
+- cross-row 或 batch-oriented reduction：输入已经对齐且 pattern 合适时，选择 pattern reduce。
+
+RegBase VF 侧归约的代表签名来自 `kernel_reg_compute_vec_reduce_intf.h`：
+
+```cpp
+template <ReduceType type = ReduceType::SUM, typename T = DefaultType, typename U = DefaultType,
+          MaskMergeMode mode = MaskMergeMode::ZEROING, typename S, typename V>
+__simd_callee__ inline void Reduce(S& dstReg, V srcReg, MaskReg mask);
+
+template <ReduceType type = ReduceType::SUM, typename T = DefaultType,
+          MaskMergeMode mode = MaskMergeMode::ZEROING, typename U>
+__simd_callee__ inline void ReduceDataBlock(U& dstReg, U srcReg, MaskReg mask);
+
+template <PairReduce type = PairReduce::SUM, typename T = DefaultType,
+          MaskMergeMode mode = MaskMergeMode::ZEROING, typename U>
+__simd_callee__ inline void PairReduceElem(U& dstReg, U srcReg, MaskReg mask);
+```
+
+`ReduceType` / `PairReduce` 决定 sum、max、min 等归约语义；`MaskReg` 决定参与归约的有效 lanes。不要把普通 kernel 侧 `ReduceSum` / `WholeReduceSum` 的 `LocalTensor` 形态直接套到 VF 侧 `Reduce` 上。
+
+常见方案：
+
+| 场景 | 方案 |
+|---|---|
+| reduce 维度在一个 tile 内 | VF 内 reduce，结果写回 UB |
+| reduce 维度跨多个 tile | 每 tile 生成 partial，再在 UB 或后续 pass 合并 |
+| reduce 后继续 elementwise | 尽量在寄存器或 UB 中保留 partial，减少 GM 往返 |
+| mean / variance | sum 与 count 要同时明确，除法和 epsilon 在精度策略里说明 |
+
+tail 和 mask 要求：
+
+- reduce tail 必须用 `MaskReg` 控制无效通道。
+- padding 值必须符合 reduce 语义，例如 max 的 padding 不能影响结果。
+- partial result 合并时要说明是否包含 tail count。
+
+## Level-2 Reduce 规则
+
+- temporary buffer type 必须与被 reduce 的数据类型匹配。
+- `count` 是 effective elements 数量，不是 padded row length。
+- row offset 应使用 padded row stride，不是 logical row length。
+
+## Pattern Reduce 规则
+
+- source shape 必须使用 aligned columns。
+- 优先使用 explicit shared temporary buffer form。
+- 如果接口要求 temporary space，调用前必须预留。
+- 只有 shape 与 alignment 已经受控时才使用 pattern reduce。
+
+## Compare 约束
+
+`Compare` 不是任意 shape 的自由回退。它用于兼容路径时，工作区必须 padding，使被比较的 `count` 占据 256-byte 对齐区间。
+
+- 调用 `Compare` 前，把 working buffer pad 到 256-byte boundary。
+- compare span 按 padded size 对齐，不按 logical unpadded count。
+- compare 结果产生后，只 copy out effective elements。
+- 当 compare 语义依赖 neutral element 时，padding 要使用明确 extreme values。
+
+经验规则：
+
+- ArgMax-style compare：padding 使用 active dtype 的最小可表示值。
+- ArgMin-style compare：padding 使用 active dtype 的最大可表示值。
+
+## 非可编译结构示例
+
+```cpp
+// scalar adjustment: 优先找 scalar helper，mask 覆盖有效 lanes。
+// AscendC::Reg::Adds<float>(dstReg, srcReg, alpha, mask);
+
+// repeated row-wise broadcast: 用 repeat form 复用一侧 operand。
+// BinaryRepeatParams params;
+// params.src1RepStride = 0;
+// Add(dst, src0, src1, repeatTime, params);
+
+// VF 侧 reduction: mask 表示有效 lanes，ReduceType 表示归约语义。
+// AscendC::Reg::Reduce<ReduceType::SUM>(dstReg, srcReg, mask);
+```
+
+具体参数顺序、模板参数和 mask 约定必须回到当前 CANN 版本的 SDK 文档或 header 验证。
+
+## 实用决策树
+
+1. 只是对单行做 scalar adjustment？用 `Adds` 或 `Muls`。
+2. 是重复 row-wise broadcast？用 repeat form，并保持 `src1RepStride = 0`。
+3. 是 row-local reduction？用 level-2 reduce API。
+4. 是 cross-row 或 patterned batch reduction？在 shape aligned 且 temporary buffer 明确时用 pattern reduce。
+
+## 常见错误
+
+- scalar helper 一条指令能完成时，仍使用 `Duplicate`。
+- 忘记 `repeatTime` 可能溢出。
+- reduce API 期望 effective count，却传入 padded count。
+- 在 unaligned shape 上使用 pattern reduce，并期待 API 自动修复。
+- API 要求 `dst` 与 `tmpBuffer` 分离时，复用同一 buffer。
+- 没有说明 reduce 是否跨 tile。
+- accumulation dtype 不明确。
+- padding 值可能改变 max/min/sum 语义。
+- 把 reduction API 当作已存在但没有文档依据。
+
+## 相关文档
+
+- [[regbase_api_reference]]
+- [[compute_api_membase_vs_regbase]]
+- [[regbase_api_whitelist]]
+- [[pipeline_and_buffer]]
+- [[../pitfalls/precision_guide]]

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/api/compute_api_membase_vs_regbase.md

@@ -0,0 +1,107 @@
+---
+title: MemBase 与 RegBase 计算 API 对照
+purpose: 对比 LocalTensor 中心的 MemBase 写法与 RegTensor 中心的 RegBase 写法，帮助选择正确 API 层级。
+read_when:
+  - 设计或代码需要把 MemBase 计算链迁移到 RegBase。
+  - 不确定某个 compute API 应该写成 `LocalTensor` vector API 还是 `AscendC::Reg::*` API。
+  - 审查发现 `LocalTensor` compute 和 `RegTensor` compute 混用。
+not_for:
+  - 只判断 GM/UB 搬运对齐。
+  - 纯 Host tiling 结构设计。
+keywords:
+  - membase
+  - regbase
+  - LocalTensor
+  - RegTensor
+  - AscendC::Reg
+next_reads:
+  - regbase_api_reference.md
+  - arithmetic_and_reduce.md
+  - datacopy_best_practices.md
+  - ../pitfalls/regbase_vs_membase_confusions.md
+depth: foundation
+topic_type: api
+---
+
+# MemBase 与 RegBase 计算 API 对照
+
+MemBase 和 RegBase 可以共享 Host、tiling、queue、UB staging 的部分结构，但 compute 核心不是同一套 API surface。迁移或审查时，先判断当前代码在哪一层计算。
+
+| 维度 | MemBase / LocalTensor 写法 | RegBase / RegTensor 写法 |
+|---|---|---|
+| 计算对象 | `LocalTensor<T>` | `RegTensor<T>` |
+| 入口形态 | kernel 普通成员函数或 `Process/Compute` 中调用 vector API | `Compute` 通过 `asc_vf_call` 进入 `__simd_vf__` |
+| 输入来源 | `LocalTensor` 已经代表 UB buffer | `__ubuf__ T*` 先经 `Reg::Load*` 进入 `RegTensor` |
+| 计算 API | `AscendC::Add/Mul/Exp/...` 等 kernel-side vector API | `AscendC::Reg::Add/Mul/Exp/...` 或 `AscendC::MicroAPI::*` |
+| tail 控制 | API 的 count / mask / repeat 参数，依具体接口而定 | `MaskReg` 控制 active lanes |
+| 中间值 | 常物化为 UB 上的 `LocalTensor` 临时区 | 尽量保留在短生命周期 `RegTensor` 中 |
+| 输出 | 写到 `LocalTensor` 后再 copy out | `Reg::Store*` 写回 UB address 后再 copy out |
+
+## 逐元素计算对照
+
+MemBase 写法通常围绕 `LocalTensor`：
+
+```cpp
+// 示意：LocalTensor 上直接调用 vector API。
+AscendC::LocalTensor<float> x = inQueue.DeQue<float>();
+AscendC::LocalTensor<float> y = outQueue.AllocTensor<float>();
+AscendC::Muls(y, x, scale, count);
+```
+
+RegBase 写法先进入 VF body，再在 `RegTensor` 上计算：
+
+```cpp
+__simd_vf__ inline void ScaleVf(__ubuf__ float* in, __ubuf__ float* out, uint32_t count)
+{
+    AscendC::Reg::RegTensor<float> xReg;
+    AscendC::Reg::RegTensor<float> yReg;
+    AscendC::Reg::MaskReg mask = AscendC::Reg::UpdateMask<float>(count);
+
+    AscendC::Reg::LoadAlign(xReg, in);
+    AscendC::Reg::Muls(yReg, xReg, scale, mask);
+    AscendC::Reg::StoreAlign(out, yReg, mask);
+}
+```
+
+关键区别：MemBase 的 API 参数通常是 `LocalTensor` 和元素数；RegBase 的 API 参数是 `RegTensor` 和 `MaskReg`。
+
+## 常见 API 映射
+
+这些名称可能相同，但对象和签名不同。不能只按函数名迁移。
+
+| 需求 | MemBase 倾向 | RegBase 倾向 | 审查点 |
+|---|---|---|---|
+| unary | `Abs(dstLocal, srcLocal, count)`、`Exp(...)` | `Reg::Abs(dstReg, srcReg, mask)`、`Reg::Exp(...)` | RegBase 输入输出必须是 `RegTensor` |
+| binary | `Add(dstLocal, aLocal, bLocal, count)` | `Reg::Add(dstReg, aReg, bReg, mask)` | 两个输入寄存器 lane layout 一致 |
+| scalar | `Adds` / `Muls` kernel-side vector API | `Reg::Adds(dstReg, srcReg, scalar, mask)` / `Reg::Muls(...)` | 不要为了 scalar 物化 broadcast UB buffer |
+| compare | `Compare` 产生 LocalTensor / mask-like 结果，依接口而定 | `Reg::Compare(maskOut, aReg, bReg, mask)` | compare 结果是 `MaskReg` |
+| select | `Select` 消费 LocalTensor 或 mask tensor | `Reg::Select(dstReg, trueReg, falseReg, mask)` | true/false source 要同 dtype route |
+| cast | kernel-side `Cast` 处理 `LocalTensor` | `Reg::Cast(dstReg, srcReg, mask)` | cast trait、round、saturation 必须验证 |
+| reduce | `ReduceSum` / `WholeReduceSum` 等 LocalTensor API | `Reg::Reduce` / `ReduceDataBlock` / `PairReduceElem` | 不要把 LocalTensor reduce 签名套到 VF-side reduce |
+
+## 迁移规则
+
+从 MemBase 迁到 RegBase 时，不是给原 API 加 namespace，而是重写 compute 层：
+
+1. 保留可复用的 Host tiling、GM/UB staging 和 queue 结构。
+2. 把原 `LocalTensor` compute 链拆成 `__simd_vf__` 函数。
+3. 在 VF 入口把 `__ubuf__` 地址 load 到 `RegTensor`。
+4. 使用 `AscendC::Reg::*` / `AscendC::MicroAPI::*` 完成计算链。
+5. 用 `MaskReg` 表示 tail，不把 padding 当作有效 lane。
+6. store 回 UB，再由外层 `CopyOut` 写回 GM。
+
+## 不要这样写
+
+- 不要在 `__simd_vf__` 里直接调用只接受 `LocalTensor` 的 vector API。
+- 不要把 `AscendC::Reg::Add` 当成 `AscendC::Add` 的命名空间替换；它们的对象、mask 和签名不同。
+- 不要让 `RegTensor` 跨 tile 或跨 VF 作用域保存状态。
+- 不要因为 outer shell 使用 `TQue` / `LocalTensor` 就判定它不是 RegBase；关键看热计算链是否进入 `RegTensor`。
+- 不要把设计伪代码中的 `Reg::` API 当成无需验证的可编译签名。
+
+## 相关文档
+
+- [[regbase_api_reference]]
+- [[arithmetic_and_reduce]]
+- [[datacopy_best_practices]]
+- [[../pitfalls/regbase_vs_membase_confusions]]
+- [[../dev-experience/regbase_programming_notes]]

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/api/datacopy_best_practices.md

@@ -0,0 +1,139 @@
+---
+title: RegBase DataCopy 分层
+purpose: 区分 RegBase 中 GM/UB 搬运与 UB/寄存器搬运，避免把 kernel-side DataCopy 写进 VF body。
+read_when:
+  - 需要设计 RegBase 的 CopyIn、Compute、CopyOut 数据流。
+  - 不确定 `DataCopyPad`、`Reg::LoadAlign`、`Reg::StoreAlign` 应该放在哪一层。
+  - 审查发现 GM/UB、UB/Register 两类搬运语义混在一起。
+not_for:
+  - 纯 MemBase / LocalTensor 算子实现。
+  - 只做 Host tiling 参数推导。
+keywords:
+  - datacopy
+  - DataCopyPad
+  - LoadAlign
+  - StoreAlign
+  - RegTensor
+next_reads:
+  - regbase_api_reference.md
+  - compute_api_membase_vs_regbase.md
+  - ../dev-experience/regbase_programming_notes.md
+depth: foundation
+topic_type: api
+---
+
+# RegBase DataCopy 分层
+
+RegBase 算子的 data movement 分两层。名字都像“copy”，但作用域、对象类型、执行管线和 tail 处理完全不同。
+
+| 层级 | 数据方向 | 典型 API | 对象 | 放置位置 | 关键语义 |
+|---|---|---|---|---|---|
+| GM/UB staging | GM -> UB、UB -> GM | `DataCopy`、`DataCopyPad` | `GlobalTensor<T>`、`LocalTensor<T>` | `CopyIn` / `CopyOut` | MTE 搬运，解决全局内存到 UB tile 的准备和写回 |
+| UB/Register VF 搬运 | UB address -> `RegTensor`、`RegTensor` -> UB address | `AscendC::Reg::LoadAlign`、`AscendC::Reg::StoreAlign`、`Load`、`Store` | `__ubuf__ T*`、`RegTensor<T>`、`MaskReg` | `__simd_vf__` / `__VEC_SCOPE__` 内 | 寄存器级 load/store，配合 `MaskReg` 控制 active lanes 和 tail |
+
+设计文档里应同时写清这两层。只写“DataCopy 到寄存器”或“从 UB 复制到 RegTensor”都不够精确。
+
+## 标准 RegBase 数据流
+
+RegBase 推荐结构：
+
+1. `CopyIn`：使用 `DataCopy` / `DataCopyPad` 把 GM tile 搬到 UB。
+2. `Compute`：取得 UB address、count 和 loop 信息，通过 `asc_vf_call<...>` 进入 `__simd_vf__`。
+3. VF body：使用 `AscendC::Reg::LoadAlign` / `Load` 把 UB address load 到 `RegTensor`。
+4. VF body：使用 `AscendC::Reg::*` 在 `RegTensor` 上计算。
+5. VF body：使用 `AscendC::Reg::StoreAlign` / `Store` 把 `RegTensor` store 回 UB address。
+6. `CopyOut`：使用 `DataCopy` / `DataCopyPad` 把 UB tile 写回 GM。
+
+## GM/UB 搬运：`DataCopy` / `DataCopyPad`
+
+`DataCopy` / `DataCopyPad` 是 kernel 侧搬运 API，用于 `GlobalTensor<T>` 与 `LocalTensor<T>` 之间的数据交换。它们不应该出现在 `__simd_vf__` 函数内，也不直接生成 `RegTensor`。
+
+常见 copy-in / copy-out 形态：
+
+```cpp
+// CopyIn: GM -> UB
+AscendC::DataCopyExtParams copyInParams{1, (uint32_t)(count * sizeof(float)), 0, 0, 0};
+AscendC::DataCopyPadExtParams<float> padInParams{false, 0, 0, 0.0f};
+AscendC::DataCopyPad(localUb, xGm[progress], copyInParams, padInParams);
+
+// CopyOut: UB -> GM
+AscendC::DataCopyExtParams copyOutParams{1, (uint32_t)(count * sizeof(float)), 0, 0, 0};
+AscendC::DataCopyPad(yGm[progress], localUb, copyOutParams);
+```
+
+使用规则：
+
+- 对齐和 tail 不确定时，GM -> UB 优先考虑 `DataCopyPad`，并写清 padding 是否影响数学语义。
+- `DataCopyExtParams.blockLen` 描述当前 GM/UB 搬运长度（单位：字节）；不要把它误写成 VF lanes 数。
+- `DataCopyPad` 参数统一使用 `DataCopyExtParams` + `DataCopyPadExtParams<T>`，详见 [api-datacopy.md](../../../ascendc-api-best-practices/references/api-datacopy.md)。
+- `DataCopyPad` 的 padding 只属于 UB staging，不等于 VF mask。进入 VF 后仍要用 `MaskReg` 处理 tail。
+- `SetValue` / `GetValue` 只作为调试辅助，不是生产搬运路径。
+
+## UB/Register 搬运：`Reg::Load*` / `Reg::Store*`
+
+进入 `__simd_vf__` 后，VF body 接收的是 `__ubuf__ T*` 地址。此时使用 `AscendC::Reg::*` load/store，把 UB 数据映射到寄存器对象。
+
+代表签名来自 CANN 9.0.0 `kernel_reg_compute_datacopy_intf.h`：
+
+```cpp
+template <typename T = DefaultType, LoadDist dist = LoadDist::DIST_NORM, typename U>
+__simd_callee__ inline void LoadAlign(U& dstReg, __ubuf__ T* srcAddr);
+
+template <typename T = DefaultType, StoreDist dist = StoreDist::DIST_NORM, typename U>
+__simd_callee__ inline void StoreAlign(__ubuf__ T* dstAddr, U& srcReg, MaskReg& mask);
+
+template <typename T = DefaultType, typename U>
+__simd_callee__ inline void Load(U& dstReg, __ubuf__ T* srcAddr);
+
+template <typename T = DefaultType, typename U>
+__simd_callee__ inline void Store(__ubuf__ T* dstAddr, U& srcReg, uint32_t count);
+```
+
+这里的 `__simd_callee__` 是 SDK RegBase primitive 的声明形态。新算子的 VF 入口仍应写成 `__simd_vf__`，并由 `asc_vf_call` 调用。
+
+典型 VF body：
+
+```cpp
+__simd_vf__ inline void MyRegBaseVf(__ubuf__ float* in, __ubuf__ float* out,
+    uint32_t count, uint16_t loopNum, uint32_t oneRepeatSize)
+{
+    AscendC::Reg::RegTensor<float> xReg;
+    AscendC::Reg::RegTensor<float> yReg;
+    AscendC::Reg::MaskReg mask;
+
+    for (uint16_t i = 0; i < loopNum; ++i) {
+        uint32_t valid = count - static_cast<uint32_t>(i) * oneRepeatSize;
+        if (valid > oneRepeatSize) {
+            valid = oneRepeatSize;
+        }
+
+        mask = AscendC::Reg::UpdateMask<float>(valid);
+        AscendC::Reg::LoadAlign(xReg, in + static_cast<uint32_t>(i) * oneRepeatSize);
+        // ... AscendC::Reg::* compute ...
+        AscendC::Reg::StoreAlign(out + static_cast<uint32_t>(i) * oneRepeatSize, yReg, mask);
+    }
+}
+```
+
+使用规则：
+
+- `LoadAlign` / `StoreAlign` 的对象是 UB address 与 `RegTensor`，不是 GM address。
+- `MaskReg` 控制 VF active lanes；tail mask 必须来自当前 repeat 的有效元素数。
+- `LoadDist` / `StoreDist` 描述寄存器 load/store 分布策略，不是 queue 同步或 MTE 搬运参数。
+- 如果使用 `LoadUnAlign*` / `StoreUnAlign*`，必须说明为什么 aligned 形态不可用，以及 unaligned 预处理对象的生命周期。
+
+## 审查清单
+
+- `CopyIn` / `CopyOut` 是否只负责 GM/UB staging。
+- VF body 是否只接收 `__ubuf__` 地址，不直接访问 GM。
+- 是否用 `Reg::Load*` 把 UB address 转为 `RegTensor`，再用 `Reg::Store*` 写回 UB。
+- `DataCopyPad` padding 与 `MaskReg` tail 是否分别说明，不能互相替代。
+- 设计文档是否把 GM/UB 搬运长度、UB offset、VF repeat size、tail lanes 分开记录。
+
+## 相关文档
+
+- [[regbase_api_reference]]
+- [[compute_api_membase_vs_regbase]]
+- [[regbase_api_whitelist]]
+- [[../dev-experience/regbase_programming_notes]]
+- [[../pitfalls/regbase_vs_membase_confusions]]