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

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

@@ -0,0 +1,38 @@
+# RegBase API 索引
+
+该子树是 RegBase 直接调用工作的 API 入口，用于组织 API 家族、VF 边界、数据搬运和同步。这里不是 SDK 全量手册；它用于缩小检查范围，然后回到 SDK header、官方文档或真实参考实现确认最终签名。
+
+## 使用规则
+
+- 当问题主要是 API family、VF 边界、数据搬运或同步时，先读本索引。
+- 针对一个子问题，先按 `purpose`、`read_when`、`keywords` 选最小文档集合，最多展开 5 篇叶子文档。
+- 如果 5 篇 API 文档仍不能关闭问题，把问题拆成 API、数据流、精度或同步子问题；不要一次加载整个子树。
+- API 名、模板参数、枚举名、namespace 和代码标识保持英文原样；中文只解释语义。
+
+## 路由表
+
+| 文件 | 用途 | 何时阅读 | 不适用场景 | 关键词 |
+|---|---|---|---|---|
+| [RegBase API 白名单](./regbase_api_whitelist.md) | 验证 API 是否属于可用家族，以及普通 kernel API 与 VF-safe API 的边界 | 编码或审查前必须确认某个 API family 是否允许 | 性能调优 | whitelist, VF, Reg, MicroAPI |
+| [RegBase API 参考](./regbase_api_reference.md) | API 可用性缩小后，提供核心类型、作用域、代表 family 和数据搬运 family 的签名地图 | 需要做 family-level 调用提醒 | 替代 SDK header 做穷尽签名验证 | signatures, RegTensor, LoadDist |
+| [MemBase 与 RegBase 计算 API 对照](./compute_api_membase_vs_regbase.md) | 对比 `LocalTensor` compute 与 `RegTensor` compute 的对象、入口和 API 形态 | 迁移 MemBase 计算链或审查 API 层级混用 | 只判断 GM/UB copy 对齐 | MemBase, LocalTensor, RegTensor |
+| [RegBase API 同步](./regbase_api_sync.md) | 说明 VF 内部 `LocalMemBar` 的声明、`MemType` 组合和真实使用边界 | 问题涉及 VF 内同步、本地 scratch 复用或错误 barrier | 顶层方案路线选择 | sync, LocalMemBar |
+| [RegBase DataCopy 分层](./datacopy_best_practices.md) | 区分 GM/UB staging 与 UB/Register VF 搬运 | 设计 `CopyIn -> Compute -> CopyOut` 或审查 `DataCopyPad` / `Reg::LoadAlign` 层级 | 纯 MemBase 算子实现 | DataCopyPad, LoadAlign, StoreAlign |
+| [Pipeline 与 Buffer](./pipeline_and_buffer.md) | 解释 `TQue` / `TBuf` / queue handoff 作为兼容材料时的含义和限制 | 需要比较 queue-based fallback 或 UB pipeline | 默认 RegBase shell 语义 | pipeline, TQue, buffer |
+| [算术与归约](./arithmetic_and_reduce.md) | 选择 scalar、broadcast、reduce、compare 等 API family，并记录 repeat/alignment 限制 | 数学已经明确，但 helper family 不清楚 | 构建或打包问题 | arithmetic, reduce, repeat |
+
+## 常见路径
+
+- API 可用性、VF-function 边界、签名提醒：[[regbase_api_whitelist]] + [[regbase_api_reference]]
+- MemBase 与 RegBase 计算 API 对照：[[compute_api_membase_vs_regbase]]
+- GM/UB staging 与 UB/Register 搬运分层：[[datacopy_best_practices]]
+- buffering 和 queue 兼容说明：[[pipeline_and_buffer]] + [[regbase_api_sync]]
+- scalar、broadcast、reduce、compare 约束：[[arithmetic_and_reduce]]
+- 精度和 cast 策略：[[../pitfalls/precision_guide]]；Cast / Truncate 签名：[[regbase_api_reference]]
+
+## 相关文档
+
+- [[../regbase_development_guide]]
+- [[../pitfalls/index]]
+- [[../dev-experience/index]]
+- [[../reference-ops/open_source_operator_table]]

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

@@ -0,0 +1,105 @@
+---
+title: Pipeline 与 Buffer
+purpose: 把 queue buffering 与 handoff 作为兼容材料解释清楚，用于和 RegBase 主路径对照。
+read_when:
+  - 需要解释或比较 MemBase-like queued pipeline。
+  - fallback 路径仍使用 `TQue` / `TBuf` 语义，需要明确限制。
+not_for:
+  - 默认 RegBase shell 语义。
+  - VF compute-body 设计。
+keywords:
+  - pipeline
+  - buffer
+  - TQue
+  - compatibility
+next_reads:
+  - datacopy_best_practices.md
+  - regbase_api_sync.md
+  - ../pitfalls/regbase_vs_membase_confusions.md
+depth: intermediate
+topic_type: api
+---
+
+# Pipeline 与 Buffer
+
+本卡片把 UB buffering 与 queue-style handoff 作为 RegBase direct-invoke 的兼容材料记录。需要对比 MemBase-style pipeline 与 RegBase-authoritative path，或记录 fallback 实现时使用。
+
+## Buffer 选择
+
+记录 compatibility path 时：
+
+- 当 buffer 同时参与 movement 和 compute handoff，使用 `TQue`。
+- 当 buffer 只是该兼容路径中的 vector computation scratch space，使用 `TBuf`。
+
+不要因为看到 `TQue`、`TBuf` 或 `LocalTensor` 就判定不是 RegBase；关键要看 compute core 是否进入 VF / register compute。反过来，也不要让 queue pipeline 成为 RegBase 设计的中心而遮住 VF body。
+
+## Queue Depth 与 Double Buffer
+
+不要把 queue depth 和 double buffering 混为一谈：
+
+- `TQue<..., depth>` 控制 queue abstraction。
+- `InitBuffer(que, num, size)` 控制 provision 的 physical buffer 数量。
+- `num = 2` 才是为该 queue 开启 double buffering 的关键。
+
+实践中，对比或 fallback 到 queued model 时，template depth 保持小而清晰，让 `InitBuffer` 的 count 表达真实 buffer 数量。
+
+## Pipeline Sync Model
+
+兼容路径中的典型流程是：
+
+1. allocate a queue buffer
+2. copy into it
+3. `EnQue` it
+4. `DeQue` it in the next stage
+5. compute
+6. enqueue the output
+7. `DeQue` the output when it is ready to leave UB
+
+这个模型保证 movement 和 compute 可以安全 overlap。它是 UB pipeline 层的 stage handoff，不是 VF lane control，也不是跨核同步。
+
+## `PipeBarrier` 何时使用
+
+只有在兼容路径里需要粗粒度 fence，或正在诊断 sync defect 时才使用 barrier。
+
+- 适合调试 bug 是否由 ordering 引起。
+- 不适合作为默认性能策略。
+- 不是 proper queue handoff 的替代品。
+
+## Batch Movement Pattern
+
+row-oriented 工作中常见模式：
+
+- batch copy 多行进入 UB。
+- 在 UB 内逐行处理。
+- batch copy 结果回 GM。
+
+这通常比 queue-based fallback 中每行发一次 copy call 更好。
+
+## 非可编译结构示例
+
+```cpp
+// queued compatibility path 的层级示意：
+auto tile = inQue.AllocTensor<T>();
+// DataCopy(tile, gmIn, copyLen);
+inQue.EnQue(tile);
+
+auto ready = inQue.DeQue<T>();
+// compute on ready, or pass UB address into VF body if this is RegBase-compatible shell
+outQue.EnQue(ready);
+```
+
+设计记录要说明：queue 数量、`InitBuffer` 的 `num` 与 `size`、是否 double buffer、`CopyIn -> Compute -> CopyOut` ownership 如何转移，以及 VF body 从哪个 UB address load。
+
+## 常见错误
+
+- 把 `AllocTensor` 当成也会等待数据 ready。
+- 以为 `depth` 本身开启 double buffering。
+- movement path 需要 queue 语义，却误用 `TBuf`。
+- 用 barrier 串行化 pipeline，而 queue handoff 原本可以保持 stage overlap。
+
+## 相关文档
+
+- [[regbase_api_sync]]
+- [[datacopy_best_practices]]
+- [[arithmetic_and_reduce]]
+- [[../pitfalls/precision_guide]]

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

@@ -0,0 +1,303 @@
+---
+title: RegBase API 参考
+purpose: API 可用性和 VF 边界已缩小后，提供 RegBase 核心类型、作用域、调用 family 和数据搬运 family 的紧凑签名地图。
+read_when:
+  - 已确认任务进入 RegBase，需要家族级签名概览。
+  - 需要在查 header 前映射名称、作用域和调用家族。
+not_for:
+  - 替代 SDK header 做穷尽签名验证。
+  - 顶层路线选择。
+keywords:
+  - api reference
+  - signatures
+  - RegTensor
+  - LoadDist
+next_reads:
+  - regbase_api_whitelist.md
+  - compute_api_membase_vs_regbase.md
+  - arithmetic_and_reduce.md
+  - ../dev-experience/regbase_programming_notes.md
+depth: foundation
+topic_type: api
+---
+
+# Ascend C RegBase API 参考
+
+本文件是直接调用工作中的 RegBase 签名地图。它用于建立方向感；最终可用性、参数顺序、模板参数和 dtype 限制仍必须回到白名单、SDK header 和真实参考实现验证。
+
+## 范围
+
+- 覆盖 `DAV_3510` RegBase 优先的直接调用工作中常见的 kernel 侧 API。
+- 区分普通 kernel 侧 API 与 VF 函数安全的 `AscendC::Reg::*` API。
+- 说明开源 kernel 经常把同一组 VF-safe surface 写成 `AscendC::MicroAPI::*`，因为 `MicroAPI` 是 `Reg` 的 SDK alias。
+- 把 MemBase 兼容作为上下文，不把 `LocalTensor` / `TQue` workflow 当作 RegBase API 的来源。
+- 聚焦设计和实现审查中最常出现的 core types 与 call families。
+
+## 核心类型和作用域标记
+
+| 名称 | 定义 / 用途 | 关键边界 |
+|---|---|---|
+| `RegTensor<T>` | 寄存器级 tensor storage，用于 VF 内部操作数和中间值 | 生命周期应局限在 VF body 或 reg-compute helper 内 |
+| `MaskReg` | vector operation 的 mask register | 控制 active lanes、tail、compare/select，不是同步 primitive |
+| `__VEC_SCOPE__ { ... }` | RegBase compute scope | 表明进入 VF / register compute 语义 |
+| `LoadDist` / `StoreDist` | UB 与 register object 之间的 distributed load/store 策略 | 描述 load/store distribution，不是 barrier |
+| `CastTrait` | cast 行为控制，包含 `RegLayout`、`SatMode`、`MaskMergeMode`、`RoundMode` 等 | 用于 dtype route 和 cast 语义 |
+| `MemType` | `LocalMemBar` 的本地 memory 访问类别 | 区分 `VEC_STORE`、`VEC_LOAD`、`SCALAR_STORE`、`SCALAR_LOAD` 等本地访问顺序 |
+
+重要 header 位置：
+
+- CANN 9.0.0 中，VF 函数安全的可调用家族位于 `<cann-root>/aarch64-linux/asc/include/basic_api/reg_compute/`。
+- 普通 kernel 侧可调用家族位于 `<cann-root>/aarch64-linux/asc/include/basic_api/`。
+- 高阶 helper 位于 `<cann-root>/aarch64-linux/asc/include/adv_api/`。
+- 很多真实 kernel include `kernel_operator.h` 并写 `AscendC::MicroAPI::*`；alias 在 `<cann-root>/aarch64-linux/asc/impl/basic_api/kernel_macros.h` 中定义。
+- 不同 SDK 包可能暴露不同逻辑 include root；结论应以当前 SDK 实际 header 为准，不要只按旧路径字符串判断 API 是否存在。
+
+## 计算 API 家族
+
+常见 RegBase compute call 包括：
+
+- unary math：`Abs`、`Exp`、`Relu`、`Sqrt`、`Ln`、`Log`
+- binary math：`Add`、`Sub`、`Mul`、`Div`、`Max`、`Min`
+- scalar helpers：`Adds`、`Muls`
+- compare / select：`Compare`、`Compares`、`Select`
+- type conversion / packing：`Cast`、`Pack`、`UnPack`
+- VF 归约 helper：`Reduce`、`ReduceDataBlock`、`PairReduceElem`、`WelfordUpdate` / `WelfordFinalize`（A5 新增，一步 mean+var）
+- 寄存器内重排：`Sort`、`Interleave` / `DeInterleave`
+
+使用顺序是：先查 [[regbase_api_whitelist]]，再用本文件确认大类调用家族。特别要通过白名单判断当前路径需要普通 kernel 侧 API，还是 VF 函数安全的 `AscendC::Reg::*` API；源码中后者可能写作 `AscendC::MicroAPI::*`。
+
+## Reg Compute 代表签名
+
+以下签名来自 CANN 9.0.0 `basic_api/reg_compute/` header，用于提示参数形态。它们不是穷尽清单；写代码前仍要回到当前 SDK header 检查 dtype、模板默认值和平台条件。
+
+这里的 `__simd_callee__` 是 SDK header 里 RegBase primitive / helper 的声明宏，不是新算子 VF 入口的推荐写法。编写算子时，外层 `Compute` 通常通过 `asc_vf_call<...>` 调用一个 `__simd_vf__` 函数；该 `__simd_vf__` 函数内部再调用下面这些 `AscendC::Reg::*` API。只有在拆内部 VF helper 时，才会看到类似 SDK 参考实现里的 `__simd_callee__` helper。
+
+典型层级：
+
+```cpp
+__simd_vf__ inline void MyOpVf(__ubuf__ float* in, __ubuf__ float* out, uint32_t count)
+{
+    AscendC::Reg::RegTensor<float> xReg;
+    AscendC::Reg::MaskReg mask = AscendC::Reg::UpdateMask<float>(count);
+    AscendC::Reg::LoadAlign(xReg, in);
+    // AscendC::Reg::* API 在 SDK header 中声明为 __simd_callee__。
+    AscendC::Reg::StoreAlign(out, xReg, mask);
+}
+```
+
+### `UpdateMask` 的计数副作用
+
+当前 SDK 的 RegBase header 将 `UpdateMask<T>` 声明为
+`UpdateMask(uint32_t&)`；实现通过 post-update 语义把传入计数推进到本次
+VF slice 之后的剩余数量。写 VF tail 循环前必须以当前 SDK header 和实现为准
+核对支持的 dtype、`RegTrait` 与更新行为，不能把它当作只读的 mask 工厂。
+
+一个进度变量只能有一个推进者。下面的写法由 `UpdateMask` 独自推进
+`remaining`，索引用不变的 `offset`/循环步长计算：
+
+```cpp
+uint32_t remaining = cols;
+for (uint32_t offset = 0; offset < cols; offset += VEC_LEN) {
+    MaskReg mask = AscendC::Reg::UpdateMask<float>(remaining);
+    // 使用 offset 和 mask 访问当前 slice；不要再修改 remaining。
+    ComputeSlice(in + offset, out + offset, mask);
+}
+```
+
+也可以让 `UpdateMask` 只推进独立的 `active`，而由外层使用调用前保存的
+`step` 推进 `remaining` 和索引：
+
+```cpp
+uint32_t remaining = cols;
+for (uint32_t offset = 0; offset < cols;) {
+    uint32_t step = Min(remaining, VEC_LEN);
+    uint32_t active = step;
+    MaskReg mask = AscendC::Reg::UpdateMask<float>(active);
+    ComputeSlice(in + offset, out + offset, mask);
+    offset += step;
+    remaining -= step;
+}
+```
+
+以下模式是错误的 double-decrement：`UpdateMask(remaining)` 已经推进了
+`remaining`，循环体再次按 `VEC_LEN` 递减会跳过 tail/slice，不能用一次精度
+通过掩盖该错误：
+
+```cpp
+MaskReg mask = AscendC::Reg::UpdateMask<float>(remaining);
+remaining -= VEC_LEN;  // 错误：同一个进度变量有两个推进者
+```
+
+`MaskReg` 只描述本次向量操作的有效 lane，不提供 GM/UB 或跨核同步；同步仍
+由 Kernel/流水层按对应事实源闭合。
+
+### 二元 / 标量
+
+来源：`kernel_reg_compute_vec_binary_intf.h`、`kernel_reg_compute_vec_binary_scalar_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);
+
+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);
+```
+
+### 比较 / 选择
+
+来源：`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);
+```
+
+### 转换 / 归约
+
+来源：`kernel_reg_compute_vec_vconv_intf.h`、`kernel_reg_compute_vec_reduce_intf.h`。
+
+```cpp
+template <typename T = DefaultType, typename U = DefaultType,
+          const CastTrait& trait = castTrait, typename S, typename V>
+__simd_callee__ inline void Cast(S& dstReg, V& srcReg, MaskReg& mask);
+
+template <typename T = DefaultType, RoundMode roundMode = RoundMode::CAST_NONE,
+          MaskMergeMode mode = MaskMergeMode::ZEROING, typename S>
+__simd_callee__ inline void Truncate(S& dstReg, S& srcReg, MaskReg& mask);
+
+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);
+```
+
+### 本地 memory barrier
+
+来源：`kernel_reg_compute_membar_intf.h`。
+
+```cpp
+template <MemType src, MemType dst>
+__simd_callee__ inline void LocalMemBar();
+```
+
+`LocalMemBar` 是 VF 内部本地 memory 顺序接口，常见于 `RegTensor -> local scratch -> RegTensor` 或非对齐 VF load/store 辅助状态复用场景。它不是 queue handoff、event flag 或跨核同步。使用规则见 [[regbase_api_sync]]。
+
+## 数据搬运 API 家族
+
+RegBase 直接调用路径也会用到少量 VF 侧 UB/寄存器数据搬运家族：
+
+- `LoadDist`
+- `StoreDist`
+- `LoadAlign` / `StoreAlign`
+- `LoadUnAlignPre` / `LoadUnAlign`
+- `StoreUnAlign` / `StoreUnAlignPost`
+- `Load` / `Store`
+- `Gather` / `GatherB` / `Scatter`
+- 地址与掩码：`AddrReg`（`CreateAddrReg`，供带偏移的 Load/Store 使用）、mask 搬入/搬出（`LoadAlign(MaskReg&, …)` / `StoreAlign(MaskReg&)` / `MaskGenWithRegTensor` / `Move`）
+
+来源：`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, DataCopyMode dataMode, typename U>
+__simd_callee__ inline void LoadAlign(U& dstReg, __ubuf__ T* srcAddr,
+                                      uint32_t dataBlockStride, MaskReg& mask);
+
+template <typename T = DefaultType, DataCopyMode dataMode, typename U>
+__simd_callee__ inline void StoreAlign(__ubuf__ T* dstAddr, U& srcReg,
+                                       uint32_t dataBlockStride, 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);
+
+template <typename T = DefaultType, typename U>
+__simd_callee__ inline void Store(__ubuf__ T* dstAddr, U& srcReg, uint32_t count);
+
+template <typename T0 = DefaultType, typename T1, typename T2 = DefaultType, typename T3, typename T4>
+__simd_callee__ inline void Gather(T3& dstReg, __ubuf__ T1* baseAddr, T4& index, MaskReg& mask);
+
+template <typename T = DefaultType, typename U = DefaultType, typename S, typename V>
+__simd_callee__ inline void Scatter(__ubuf__ T* baseAddr, S& srcReg, V& index, MaskReg& mask);
+```
+
+GM/UB 搬运细节优先查 [[datacopy_best_practices]]，不要把 kernel 侧 `DataCopyPad` 与 VF 侧 UB/寄存器 load/store 混成同一层。
+
+## 系统变量与 SPR
+
+- 核 / 块号：`GetBlockIdx`、`GetBlockNum`、`GetCoreNum`
+- 溢出模式控制：`GetCtrlSpr` / `SetCtrlSpr`（SPR 为全局状态，修改后必须恢复；数值范围可控的算子关闭溢检测可提速）
+
+## 非可编译结构示例
+
+以下片段只说明层级，不保证参数顺序或模板签名：
+
+```cpp
+// UB staging 已经准备好 inAddr/outAddr。
+__VEC_SCOPE__ {
+    RegTensor<float> vin;
+    RegTensor<float> vout;
+    MaskReg mask;
+
+    // load: UB address -> RegTensor，LoadDist 决定分布策略。
+    // AscendC::Reg::LoadAlign<float, LoadDist::DIST_NORM>(vin, inAddr);
+
+    // compute: 使用 AscendC::Reg::* 或源码中的 AscendC::MicroAPI::*。
+    // AscendC::Reg::Abs(vout, vin, mask);
+
+    // store: RegTensor -> UB address，StoreDist 决定写回策略。
+    // AscendC::Reg::StoreAlign<float, StoreDist::DIST_NORM>(outAddr, vout, mask);
+}
+```
+
+在 DESIGN.md 中，不能只写“调用 RegBase API”。至少写出：输入寄存器、输出寄存器、mask 来源、load/store 策略和文档依据。
+
+## 决策规则
+
+1. 先检查 [[regbase_api_whitelist]]。
+2. 用本文件确认 broad RegBase call family 和正确心智模型。
+3. 问题涉及 VF 内部本地 memory 顺序、readiness、stall 或 cross-core coordination 时，读 [[regbase_api_sync]]。
+4. 任务可能改变 precision 或 cast timing 时，读 [[../pitfalls/precision_guide]]。
+5. 如果任务实际依赖 MemBase-only workflow，把它视为 scope change，不要强行套 RegBase 语义。
+
+## 相关文档
+
+- [[regbase_api_whitelist]]
+- [[compute_api_membase_vs_regbase]]
+- [[regbase_api_sync]]
+- [[datacopy_best_practices]]
+- [[pipeline_and_buffer]]
+- [[arithmetic_and_reduce]]
+- [[../pitfalls/precision_guide]]

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

@@ -0,0 +1,173 @@
+---
+title: RegBase API 同步
+purpose: 说明 RegBase/VF 内部真实可用的同步接口 `LocalMemBar`，包括声明位置、`MemType` 组合和使用边界。
+read_when:
+  - 需要判断 VF body 内是否需要同步或 memory barrier。
+  - 代码中出现 `LocalMemBar`、`MemType`、非对齐 VF load/store 或本地 scratch 复用。
+  - 审查中发现把 kernel-side 同步 API 写进 RegBase/VF 内部链路。
+not_for:
+  - 顶层算子分类。
+  - 纯构建失败。
+keywords:
+  - sync
+  - LocalMemBar
+  - MemType
+  - VF
+next_reads:
+  - ../dev-experience/regbase_programming_notes.md
+  - ../pitfalls/symptom_to_cause.md
+  - regbase_api_whitelist.md
+  - datacopy_best_practices.md
+depth: foundation
+topic_type: api
+---
+
+# RegBase API 同步
+
+本卡片只记录 RegBase/VF 内部的同步接口。CANN 9.0.0 公开的 RegBase VF 内同步入口是 `AscendC::Reg::LocalMemBar<src, dst>()`；它是 local memory barrier，用于约束 VF 侧本地 load/store 与 scalar load/store 的顺序。
+
+`SetFlag`、`WaitFlag`、`PipeBarrier`、`SyncAll`、`CrossCoreSetFlag`、`CrossCoreWaitFlag` 不是 `reg_compute/` 里的 VF 内同步接口。它们只能作为 kernel shell、pipeline 或跨核协同的上下文边界理解，不能写进 `__simd_vf__` 的默认 callable surface。
+
+## 1. 结论
+
+- 普通连续 `RegTensor` 计算不需要默认插入同步。
+- `MaskReg` 只控制 active lanes，不是同步 primitive。
+- `LoadDist` / `StoreDist` 只描述 UB 与 register 之间的 load/store 分布策略，不是 barrier。
+- `LocalMemBar` 只在 VF 内部存在本地 memory access 顺序风险时使用，例如 store 到本地 scratch 后马上 load 回来。
+- 内部实现会调用 `mem_bar(...)`，但 `mem_bar` 不是本 skill 推荐给新算子的公开接口；新代码优先使用 `LocalMemBar`。
+
+## 2. VF 内同步接口定义
+
+来源：CANN 9.0.0 `basic_api/reg_compute/kernel_reg_compute_membar_intf.h`。
+
+```cpp
+namespace AscendC {
+namespace Reg {
+
+template <MemType src, MemType dst>
+__simd_callee__ inline void LocalMemBar();
+
+} // namespace Reg
+} // namespace AscendC
+```
+
+`MemType` 定义在 `kernel_reg_compute_utils.h`：
+
+```cpp
+enum class MemType {
+    VEC_STORE,
+    VEC_LOAD,
+    SCALAR_STORE,
+    SCALAR_LOAD,
+    VEC_ALL,
+    SCALAR_ALL
+};
+```
+
+`kernel_reg_compute_membar_intf_impl.h` 中 `LocalMemBar()` 会转调 `LocalMemBarImpl<src, dst>()`。`dav_c310` / `dav_l311` 等平台实现再把 `MemType` 组合映射到内部 `mem_bar(...)` 指令码。
+
+真实代码中同一接口也可能写成 `AscendC::MicroAPI::LocalMemBar`，因为 `kernel_macros.h` 中定义了 `namespace MicroAPI = Reg;`。
+
+## 3. 支持的 MemType 组合
+
+当前 header / impl 通过 `static_assert` 或分支限定组合。CANN 9.0.0 中可见组合如下：
+
+| 公开组合 | 内部 barrier 码 | 适用顺序 |
+|---|---|---|
+| `LocalMemBar<MemType::VEC_STORE, MemType::VEC_LOAD>()` | `VST_VLD` | VF store 到本地地址后，后续 VF load 读取同一类本地数据 |
+| `LocalMemBar<MemType::VEC_LOAD, MemType::VEC_STORE>()` | `VLD_VST` | VF load 后，后续 VF store 对相关本地地址有顺序依赖 |
+| `LocalMemBar<MemType::VEC_STORE, MemType::VEC_STORE>()` | `VST_VST` | 多次 VF store 之间需要固定本地写入顺序 |
+| `LocalMemBar<MemType::VEC_STORE, MemType::SCALAR_LOAD>()` | `VST_LD` | VF store 后，scalar load 读取相关本地数据 |
+| `LocalMemBar<MemType::VEC_STORE, MemType::SCALAR_STORE>()` | `VST_ST` | VF store 与后续 scalar store 存在顺序依赖 |
+| `LocalMemBar<MemType::VEC_LOAD, MemType::SCALAR_STORE>()` | `VLD_ST` | VF load 后，scalar store 需要按序发生 |
+| `LocalMemBar<MemType::SCALAR_STORE, MemType::VEC_LOAD>()` | `ST_VLD` | scalar store 后，VF load 读取相关本地数据 |
+| `LocalMemBar<MemType::SCALAR_STORE, MemType::VEC_STORE>()` | `ST_VST` | scalar store 与后续 VF store 需要固定顺序 |
+| `LocalMemBar<MemType::SCALAR_LOAD, MemType::VEC_STORE>()` | `LD_VST` | scalar load 与后续 VF store 需要固定顺序 |
+| `LocalMemBar<MemType::VEC_ALL, MemType::VEC_ALL>()` | `VV_ALL` | VF load/store 全量本地顺序 |
+| `LocalMemBar<MemType::VEC_ALL, MemType::SCALAR_ALL>()` | `VS_ALL` | VF 访问到 scalar 访问的全量本地顺序 |
+| `LocalMemBar<MemType::SCALAR_ALL, MemType::VEC_ALL>()` | `SV_ALL` | scalar 访问到 VF 访问的全量本地顺序 |
+
+写代码前仍以当前 SDK header 的 `LocalMemBarImpl` 约束为准。不要猜 `SCALAR_LOAD -> VEC_LOAD`、`VEC_LOAD -> VEC_LOAD` 等未列出的组合。
+
+## 4. 真实参考中的使用形态
+
+CANN 9.0.0 参考实现中，`LocalMemBar` 常见于 RegBase reduce、softmax、norm、gather-mask 等实现。最常见形态是：
+
+```cpp
+Reg::LocalMemBar<Reg::MemType::VEC_STORE, Reg::MemType::VEC_LOAD>();
+```
+
+这类代码通常先用 VF store 把中间值落到本地 scratch / UB，再用 VF load 或后续 reg-compute 阶段重新读取。barrier 保护的是这个本地 memory 生产者 / 消费者关系，不是 GM 到 UB 的 MTE 搬运，也不是 `CopyIn -> Compute -> CopyOut` 的 queue 交接。
+
+也能看到少量 `VEC_STORE -> SCALAR_LOAD`、`VEC_STORE -> VEC_STORE` 等组合，通常由普通 vector / reg-compute 实现内部使用。除非设计中能指出明确的本地 memory 读写关系，否则不要为了“保险”添加这些组合。
+
+## 5. 何时使用
+
+只有存在本地 memory 复用或访问类别切换时才考虑 `LocalMemBar`。常见场景：
+
+- VF store 把中间结果写入 UB / local scratch，随后又通过 VF load 读回做二阶段归约。
+- `LoadUnAlignPre` / `LoadUnAlign` / `StoreUnAlign` / `StoreUnAlignPost` 这类非对齐搬运辅助状态之间需要固定访问顺序。
+- VF scatter / gather 更新本地表后，后续 VF 或 scalar 路径立刻读取同一片本地数据。
+- reduce、prefix、sort、softmax、norm 等算法复用同一 scratch 区，存在 `store -> load` 或 `load -> store` 顺序风险。
+
+不需要 `LocalMemBar` 的常见场景：
+
+- `Add -> Mul -> Exp` 这类全部停留在 `RegTensor` 上的寄存器计算链。
+- 单次 `LoadAlign -> compute -> StoreAlign`，中间没有本地 scratch 复用。
+- tail 控制、select 控制或 compare 结果传递；这些应靠 `MaskReg` 表达。
+- `CopyIn` 和 `Compute` 之间的 UB buffer ownership；这属于 kernel shell 的 queue / stage ordering。
+
+## 6. 非可编译结构示例
+
+```cpp
+__simd_vf__ inline void ReduceLikeVf(__ubuf__ float* scratch, uint32_t count)
+{
+    using namespace AscendC::Reg;
+
+    RegTensor<float> tmp;
+    RegTensor<float> acc;
+    MaskReg mask = UpdateMask<float>(count);
+
+    // 第一阶段：RegTensor -> 本地 scratch。
+    StoreAlign<float, StoreDist::DIST_NORM_B32>(scratch, tmp, mask);
+
+    // 本地 scratch 被重新作为 VF load 输入时，插入本地 memory barrier。
+    LocalMemBar<MemType::VEC_STORE, MemType::VEC_LOAD>();
+
+    // 第二阶段：本地 scratch -> RegTensor。
+    LoadAlign<float, LoadDist::DIST_NORM>(acc, scratch);
+}
+```
+
+具体使用时，`scratch` 的地址空间、load/store API 名称和模板参数必须以当前 SDK header 与参考实现为准。
+
+## 7. 不是 VF 内同步接口的内容
+
+这些 API 真实存在，但不属于 `reg_compute/` VF 内同步接口：
+
+| API / 机制 | 所在层级 | 为什么不能当作 VF 内同步 |
+|---|---|---|
+| `SetFlag` / `WaitFlag` | kernel-side event | 用于 pipe / event 协调，不在 `AscendC::Reg::*` callable surface |
+| `PipeBarrier<PIPE_*>` | kernel-side pipe fence | 约束 pipe，不表达 RegTensor / VF local scratch 顺序 |
+| `SyncAll` | kernel-side stronger sync | 用于更大范围同步，不是 VF body 内 local memory barrier |
+| `CrossCoreSetFlag` / `CrossCoreWaitFlag` | 跨核同步 | 解决跨 core 生产者 / 消费者，不解决 VF local scratch 顺序 |
+| `MaskReg` / `CreateMask` / `UpdateMask` | VF lane 控制 | 只控制 active lanes，不产生 memory ordering |
+
+不要因为 RegBase kernel 的外壳用了 `TQue`、`DataCopyPad` 或事件 flag，就把这些 API 放进 `__simd_vf__` 的可调用面。
+
+## 8. 审查检查项
+
+- VF 内同步是否只使用 `LocalMemBar`。
+- 每个 `LocalMemBar<src, dst>` 是否能对应真实的本地 memory 生产者和消费者。
+- `MemType` 方向是否匹配：例如 store 后 load 应写 `VEC_STORE -> VEC_LOAD`。
+- 是否把内部实现细节 `mem_bar(...)` 当作新算子首选公开 API。
+- 是否把 `MaskReg`、`LoadDist`、`StoreDist` 误写成同步接口。
+- 是否在 `__simd_vf__` 里混入 kernel-side `SetFlag`、`WaitFlag`、`PipeBarrier`、`SyncAll` 或 `CrossCore*`。
+- 如果只是普通寄存器计算链，是否删除了无依据的 barrier。
+
+## 相关文档
+
+- [[../regbase_development_guide]]
+- [[../dev-experience/regbase_programming_notes]]
+- [[datacopy_best_practices]]
+- [[pipeline_and_buffer]]