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

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

@@ -0,0 +1,142 @@
+---
+title: RegBase API 白名单
+purpose: 作为 RegBase API 的进入门禁，区分普通 kernel-side API 和 VF-function-safe `AscendC::Reg::*` 调用。
+read_when:
+  - 编码或审查前必须确认某个 API family 是否允许。
+  - 主要问题是某个调用属于 kernel shell、UB staging 还是 VF function body。
+not_for:
+  - 性能调优。
+  - 选择现有参考算子。
+keywords:
+  - whitelist
+  - vf function
+  - AscendC::Reg
+  - AscendC::MicroAPI
+  - allowed api
+next_reads:
+  - regbase_api_reference.md
+  - compute_api_membase_vs_regbase.md
+  - ../dev-experience/regbase_programming_notes.md
+  - ../pitfalls/api_misuse.md
+depth: foundation
+topic_type: api
+---
+
+# RegBase API 白名单
+
+本文件是 RegBase direct-invoke 工作的 API 门禁。它把普通 RegBase kernel-side API 与 VF-function-safe API 分开，避免设计和审查把 `LocalTensor` 路径假设混进 `AscendC::Reg::*` reg-compute 语义。开源 kernel 中同一组 VF-safe API 经常写成 `AscendC::MicroAPI::*`；如果某个 API 不在下面的列表中，先按“不可用”处理，直到在安装的 SDK header 或真实参考实现中验证过。
+
+## Header 参考根目录
+
+使用这些 SDK 逻辑根目录做首要验证来源。不要把环境相关绝对路径写进设计或审查结论。
+
+- `<cann-root>/aarch64-linux/asc/include/basic_api/`
+  普通 kernel-side AscendC 接口，例如 `DataCopy`、vector `LocalTensor` compute、barrier、event sync。
+- `<cann-root>/aarch64-linux/asc/include/basic_api/reg_compute/`
+  `AscendC::Reg::*` 公开接口，以及可在 VF function 中调用的 support types。
+- `<cann-root>/aarch64-linux/asc/include/adv_api/`
+  任务相关的高阶 RegBase helper，例如 norm、pad、transpose、select、quantization 等 family。
+- `<cann-root>/aarch64-linux/asc/impl/basic_api/kernel_macros.h`
+  定义 `namespace MicroAPI = Reg;`。很多开源 kernel 因此把同一组 VF-safe API 写成 `AscendC::MicroAPI::*`。
+
+相关文档可能用环境变量或逻辑 include root 作为简写。把它视为同一组 header，不要理解成第二套 API 表面。
+
+## 作用域规则
+
+- 普通 RegBase kernel-side API 和 VF-function API 不能互换，即使名字相似。
+- 设计进入 VF function 后，优先把 `AscendC::Reg::*` 和 `reg_compute/` 下的接口作为 callable surface。
+- 阅读开源代码时，除非本地代码另加 wrapper，否则把 `AscendC::MicroAPI::*` 视为与 `AscendC::Reg::*` 相同的 VF-safe API family。
+- 新算子的 VF 入口通常写成 `__simd_vf__` 并由 `asc_vf_call` 调用；`__simd_callee__` 主要出现在 SDK `reg_compute/` API 声明或内部 VF helper 上。
+- `__simd_vf__` 内可以调用 `reg_compute/` 下声明为 `__simd_callee__` 的 `AscendC::Reg::*` 接口，但不能把任意 VF helper 当成普通可调用工具随意嵌套。
+- 传入 VF helper 的 pointer 参数必须保持在 `__ubuf__` 地址空间。
+- 同一能力如果同时有 kernel-side 与 VF-function-safe 两种形态，编码前必须确认 namespace、参数样式和 mask/control contract。
+
+## 普通 RegBase Kernel-Side API
+
+这些 family 用于普通 RegBase kernel 代码，不是 VF function 的默认白名单。
+
+| Family | 代表 API | VF Function? | 主要 Header Root |
+|---|---|---|---|
+| Vector compute | `Abs`, `Exp`, `Relu`, `Sqrt`, `Rsqrt`, `Reciprocal`, `Ln`, `Log`, `Sigmoid`, `Tanh`, `LeakyRelu`, `Ceil`, `Floor`, `Round` | No | `basic_api/` |
+| Binary compute | `Add`, `Sub`, `Mul`, `Div`, `Max`, `Min`, `And`, `Or`, `Xor`, `Axpy`, `FusedMulAdd`, `AddRelu`, `SubRelu` | No | `basic_api/` |
+| Scalar helpers | `Adds`, `Muls`, `Divs`, `Maxs`, `Mins`, `ShiftLefts`, `ShiftRights` | No | `basic_api/` |
+| Compare and select | `Compare`, `Compares`, `Select` | No | `basic_api/` |
+| Reduction | `ReduceSum`, `WholeReduceSum`, `BlockReduceSum`, `ReduceMax`, `WholeReduceMax`, `BlockReduceMax`, `ReduceMin`, `WholeReduceMin`, `BlockReduceMin`, `ReduceMean`, `ReduceProd`, `ReduceAll`, `ReduceAny` | No | `basic_api/` |
+| Conversion and utility | `Cast`, `ReinterpretCast`, `Duplicate`, `Arange`, `CreateVecIndex`, `Interleave`, `DeInterleave`, `Move` | No | `basic_api/` |
+| Data movement | `DataCopy`, `DataCopyPad`, `DataCopyGather`, `DataCopyUnAlignPre`, `DataCopyUnAlign`, `DataCopyUnAlignPost`, `Copy` | No | `basic_api/` |
+| Sync and event | `PipeBarrier`, `SetFlag`, `WaitFlag`, `CrossCoreSetFlag`, `CrossCoreWaitFlag`, `SyncAll` | No | `basic_api/` |
+
+## VF-Function-Safe API (`AscendC::Reg::*`)
+
+进入 VF function 或 reg-compute helper 路径后，这些 family 是优先 callable surface。权威来源是 `reg_compute/`。
+
+开源 RegBase kernel 经常把同一组 API 写成 `AscendC::MicroAPI::*`。把它看作 alias 风格差异，不要当成第二套白名单。
+
+| Family | 代表 API | VF Function? | 主要 Header Root |
+|---|---|---|---|
+| Unary reg compute | `Abs`, `Relu`, `Exp`, `Sqrt`, `Ln`, `Log`, `Log2`, `Log10`, `Neg`, `Not` | Yes | `basic_api/reg_compute/` |
+| Binary reg compute | `Add`, `Sub`, `Mul`, `Div`, `Max`, `Min`, `And`, `Or`, `Xor`, `MulAddDst`, `Mull` | Yes | `basic_api/reg_compute/` |
+| Scalar reg compute | `Adds`, `Muls`, `Divs`, `Maxs`, `Mins`, `ShiftLefts`, `ShiftRights` | Yes | `basic_api/reg_compute/` |
+| Compare and select | `Compare`, `Compares`, `Select` | Yes | `basic_api/reg_compute/` |
+| Conversion and utility | `Cast`, `Duplicate` | Yes | `basic_api/reg_compute/` |
+| Reg reduction | `Reduce`, `ReduceDataBlock`, `PairReduceElem` | Yes | `basic_api/reg_compute/` |
+| Reg load and store | `LoadAlign`, `StoreAlign`, `LoadUnAlignPre`, `LoadUnAlign`, `StoreUnAlign`, `StoreUnAlignPost`, `Load`, `Store`, `Gather`, `GatherB`, `Scatter` | Yes | `basic_api/reg_compute/` |
+| Mask and copy helpers | `MaskReg`, `CreateMask`, `UpdateMask`, `Pack`, `UnPack`, `Move`, `LocalMemBar` | Yes | `basic_api/reg_compute/` |
+| VF 路径 traits / enums | `LoadDist`, `StoreDist`, `MemType`, `CastTrait`, `CMPMODE`, `RoundMode`, `MaskMergeMode`, `PostLiteral`, `DataCopyMode`, `ReduceType`, `PairReduce` | Yes | `basic_api/reg_compute/` |
+
+> 注：`Reg::Div` 默认 `INTRINSIC` 模式最大 1 ULP 误差（非 IEEE-754 correctly-rounded）。高精度场景传 `DivSpecificMode{precisionMode=true, algo=PRECISION_0ULP_FTZ_FALSE}`（差值补偿算法，0 ULP，仍为 `__simd_callee__` VF-safe）。
+
+## 高阶任务相关 RegBase API
+
+这些 family 存在于 SDK 中，RegBase 工作中可能有用，但不是默认 primitive。使用前必须确认任务适配性、tiling 假设和精确签名。
+
+| Family | 代表 API | VF Function? | 主要 Header Root |
+|---|---|---|---|
+| Norm and mean | `LayerNorm`, `RmsNorm`, `GroupNorm`, `Normalize`, `Mean` | No | `adv_api/` |
+| Pad and broadcast | `Pad`, `Broadcast`, `Brcb` | No | `adv_api/` |
+| Structured select | `SelectWithBytesMask` | No | `adv_api/` |
+| Transpose and layout change | `TransData`, `ConfusionTranspose` | No | `adv_api/` |
+| Quantization | `AscendQuant`, `AscendDequant`, `AscendAntiQuant`, `Quantize`, `Dequantize`, `AntiQuantize` | No | `adv_api/` |
+
+## VF 专项护栏
+
+- 进入 VF function 后，把 `AscendC::Reg::*` 作为默认 API surface；源码使用 `AscendC::MicroAPI::*` 时，按同一 VF-safe family 理解。
+- 不要假设 kernel-side `LocalTensor` API 与 VF-side API 拥有相同签名、mask contract 或地址假设。
+- 代码路径出现 `RegTensor`、`MaskReg`、`LoadDist`、`StoreDist` 时，先检查 VF-capable header。
+- 在 VF helper 内使用 `CreateMask`、`UpdateMask`、`Pack`、`UnPack` 前，重新确认 mask 创建和更新规则。
+- 如果一个 helper 需要再调用另一个 VF helper，暂停并回查设计。新算子的主 VF body 优先保持 `__simd_vf__` + `asc_vf_call` 结构；VF body 内稳定的 callable surface 是 `reg_compute/` 下声明为 `__simd_callee__` 的 `AscendC::Reg::*` API family。
+
+## 非可编译结构示例
+
+以下只表达层级和 API surface，不替代 SDK 签名：
+
+```cpp
+// kernel shell / UB staging: 普通 kernel-side API
+DataCopy(ubIn, gmIn, copyLen);
+
+// VF body: 进入 reg_compute callable surface
+__VEC_SCOPE__ {
+    RegTensor<float> x;
+    MaskReg mask;
+    // 优先使用 AscendC::Reg::*；开源代码中可能写作 AscendC::MicroAPI::*。
+    // 具体参数顺序、模板参数和 mask contract 必须查 reg_compute header。
+}
+```
+
+## 使用护栏
+
+- 编写代码或生成设计前先检查本文件。
+- 白名单检查后，用 [[regbase_api_reference]] 确认 broad family 和心智模型。
+- 需要判断 `LocalTensor` compute 是否应迁移成 `RegTensor` compute 时，用 [[compute_api_membase_vs_regbase]] 做层级对照。
+- 问题属于 barrier、flag、cross-core coordination 时，用 [[regbase_api_sync]]，不要只看 API 可用性。
+- alignment 不确定时优先考虑 `DataCopyPad`；不要假设 `DataCopy` 能吸收 misaligned GM transfer。
+- 如果任务需要未列出的 API，先验证 SDK header family 并更新设计，不要补猜测 API。
+
+## 相关文档
+
+- [[regbase_api_reference]]
+- [[compute_api_membase_vs_regbase]]
+- [[regbase_api_sync]]
+- [[datacopy_best_practices]]
+- [[arithmetic_and_reduce]]
+- [[../pitfalls/precision_guide]]

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

@@ -0,0 +1,24 @@
+# 开发经验索引
+
+该目录沉淀 RegBase 开发过程中的工程经验。需要判断路线、避免重复踩坑、准备构建或解释失败案例时，先读这里。
+
+## 选择表
+
+| 文档 | 用途 | 何时阅读 |
+|---|---|---|
+| [RegBase 构建笔记](./regbase_build_notes.md) | 处理 build/header/路径问题 | 编译前或构建失败时 |
+| [RegBase 性能实践](./regbase_performance_practices.md) | 评估性能瓶颈和优化优先级 | 性能审查或调优 |
+| [RegBase 编程笔记](./regbase_programming_notes.md) | 编码前的写法提醒，覆盖参考实现阅读、数据流、buffer 分域和同步边界 | 开发者开始实现前 |
+| [Tiling 审查笔记](./tiling_review_notes.md) | 设计和审查 tiling packet、tail、dtype route 和 UB 大小 | 设计串讲或 review |
+| [DAV_3510 成功/失败案例](./working_vs_failed_dav_3510_cases.md) | 对照成功和失败路径 | 修复或判断路线时 |
+
+## 使用原则
+
+- 这些文档是工程经验，不替代 API 文档或真实源码。
+- 如果经验来自兼容路径，应在设计中标注适用范围。
+- 经验只能缩短判断路径，不能省略验证。
+
+## 相关文档
+
+- [[../regbase_development_guide]]
+- [[../pitfalls/index]]

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/dev-experience/regbase_build_notes.md

@@ -0,0 +1,49 @@
+---
+title: RegBase 构建笔记
+purpose: 汇总 RegBase 构建阶段常见 header、宏、模板和路径问题。
+read_when:
+  - 编译失败但设计看起来合理。
+  - 新增 RegBase body 或 VF 函数后出现构建错误。
+keywords:
+  - build
+  - header
+  - compile
+next_reads:
+  - regbase_programming_notes.md
+  - ../api/regbase_api_whitelist.md
+  - ../pitfalls/api_misuse.md
+depth: practice
+topic_type: experience
+---
+
+# RegBase 构建笔记
+
+## 1. 先判断失败层级
+
+| 失败位置 | 常见原因 |
+|---|---|
+| Host 编译 | tiling struct、注册宏或 include 路径不匹配 |
+| kernel entry | `TILING_KEY_IS`、模板实例或参数列表不一致 |
+| RegBase header | API 家族不存在、模板参数错误、dtype 不支持 |
+| VF body | `RegTensor` 类型、mask 参数、load/store dist 不匹配 |
+
+## 2. 构建前检查
+
+- RegBase body 所在路径是否与 arch 目录一致，例如 `arch35`。
+- include 是否能找到 RegBase API header。
+- `__VEC_SCOPE__`、`__simd_vf__`、`asc_vf_call` 的位置是否符合工程模板。
+- 模板 dtype 与 tiling route 是否一致。
+- Host 和 kernel 的 tiling data struct 是否一致。
+
+## 3. 常见处理方式
+
+- API 不存在：回到 `regbase_api_whitelist.md` 和 SDK 文档确认，不要改成猜测名称。
+- 模板报错：先缩小到单 dtype route。
+- mask 类型不匹配：检查 `MaskReg` 生成和 API 参数顺序。
+- store 报错：检查 `StoreDist`、输出 dtype 和 UB address 类型。
+
+## 相关文档
+
+- [[regbase_programming_notes]]
+- [[../api/regbase_api_whitelist]]
+- [[../pitfalls/api_misuse]]

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/dev-experience/regbase_performance_practices.md

@@ -0,0 +1,52 @@
+---
+title: RegBase 性能实践
+purpose: 给出 RegBase 性能审查和优化的优先级。
+read_when:
+  - RegBase 算子功能正确但性能不达标。
+  - 需要评估融合链路是否真正减少 UB/GM 往返。
+keywords:
+  - performance
+  - fusion
+  - register
+next_reads:
+  - regbase_programming_notes.md
+  - tiling_review_notes.md
+  - working_vs_failed_dav_3510_cases.md
+depth: practice
+topic_type: experience
+---
+
+# RegBase 性能实践
+
+RegBase 性能收益通常来自减少 UB/GM 往返、保持中间值在 register、减少不必要同步以及让 tail/mask 简洁。
+
+## 1. 优先检查
+
+- 融合链路是否真的减少中间 UB 写回。
+- `RegTensor` 临时变量是否服务于真实数学链。
+- UB buffer 是否过度分配。
+- `CopyIn` / `CopyOut` 是否因为非对齐产生大量碎片 copy。
+- 是否引入了不必要 `PipeBarrier`、`SyncAll` 或 cross-core sync。
+
+## 2. 优化方向
+
+| 问题 | 方向 |
+|---|---|
+| GM 往返多 | 合并 VF chain，减少中间输出 |
+| UB 使用高 | 把短生命周期中间值留在 register |
+| tail 复杂 | 简化 tile 形状或集中 mask 逻辑 |
+| dtype cast 多 | 合并 cast 点，避免来回 cast |
+| 同步过重 | 回到分层同步模型，删除无依据 barrier |
+
+## 3. 不要为了性能牺牲可验证性
+
+- 不要删掉 tail mask。
+- 不要用未验证 API 替换已验证 API。
+- 不要把 Host shape 假设写死进 kernel。
+- 不要为了少一个 buffer 破坏数据 ownership。
+
+## 相关文档
+
+- [[regbase_programming_notes]]
+- [[tiling_review_notes]]
+- [[working_vs_failed_dav_3510_cases]]

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/dev-experience/regbase_programming_notes.md

@@ -0,0 +1,120 @@
+---
+title: RegBase 编程笔记
+purpose: 编写 RegBase 代码前的实用提醒，覆盖参考实现阅读、数据流、buffer 分域、VF 边界、同步边界和伪代码到可编译代码的差异。
+read_when:
+  - 开发者即将根据 DESIGN.md 实现 RegBase 算子。
+  - 需要确认 `__simd_vf__` / `asc_vf_call` 结构。
+  - 需要把 Host/Kernel/UB/VF 分层落到可实现的代码结构。
+keywords:
+  - programming
+  - dataflow
+  - buffer
+  - sync
+  - __simd_vf__
+  - asc_vf_call
+next_reads:
+  - regbase_build_notes.md
+  - ../api/regbase_api_reference.md
+  - ../api/datacopy_best_practices.md
+  - ../api/regbase_api_sync.md
+  - ../reference-ops/open_source_operator_table.md
+depth: practice
+topic_type: experience
+---
+
+# RegBase 编程笔记
+
+## 1. 从真实实现落到工程模板
+
+DESIGN.md 中的 RegBase 伪代码只表达层级、API 家族和数据流。实现时必须按工程模板、真实 API 签名和参考实现调整。
+
+编码前先通过 [[../reference-ops/open_source_operator_table]] 定位候选目录，并确认目录中存在 `op_kernel/arch35/*regbase*`、`*_apt.cpp`、`__VEC_SCOPE__`、`__simd_vf__`、`RegTensor` 或 `AscendC::MicroAPI::*` 等 RegBase 证据。阅读顺序建议固定为：
+
+1. kernel entry：确认 `TILING_KEY_IS(...)`、dtype route 和 kernel 参数列表。
+2. `Init`：确认 GM/UB binding、pipe、queue 或 buffer 分配。
+3. `Process`：确认 tile loop、tail 和 `CopyIn -> Compute -> CopyOut` 顺序。
+4. VF body：确认 `RegTensor`、`MaskReg`、`LoadDist`、`StoreDist` 和 API family。
+
+参考实现只能证明某种结构可行，不能替代当前任务的 shape、dtype、tail 和 API 适配判断。
+
+## 2. 推荐结构
+
+- Kernel outer shell 管理 `Init`、`Process`、`CopyIn`、`Compute`、`CopyOut`。
+- UB `Compute` 层准备 address、count、mask。
+- VF 函数通过 `__simd_vf__` 表达寄存器级 body。
+- UB `Compute` 层通过 `asc_vf_call` 调用 VF 函数。
+- `AscendC::Reg::*` API 在 SDK header 中常声明为 `__simd_callee__`；这是被 VF body 调用的 primitive / helper 形态，不应替代新算子的 `__simd_vf__` 入口。
+
+标准数据流分两层：
+
+```text
+GM input
+  -> CopyIn: DataCopy/DataCopyPad 到 UB tile
+UB input tile
+  -> Compute: 取 UB address，调用 asc_vf_call 或进入 __VEC_SCOPE__
+RegTensor input
+  -> AscendC::Reg::* / AscendC::MicroAPI::* 计算
+RegTensor output
+  -> Store* 回 UB output tile
+UB output tile
+  -> CopyOut: DataCopy/DataCopyPad 回 GM output
+```
+
+`DataCopy` / `DataCopyPad` 属于 GM/UB 搬运，不能写进 `__simd_vf__`。VF 内的 `LoadAlign` / `StoreAlign` 是 UB address 与 `RegTensor` 之间的搬运，具体签名和边界见 [[../api/datacopy_best_practices]]。
+
+## 3. Buffer 分域
+
+RegBase buffer 规划按域写清楚，不按“看起来都是 tensor”混在一起：
+
+| 域 | 常见对象 | 用途 |
+|---|---|---|
+| GM | `GlobalTensor`、workspace、tiling | 输入、输出、全局临时数据 |
+| UB | `TQue`、`TBuf`、`LocalTensor`、raw `__ubuf__` pointer | tile staging、copy、临时 scratch |
+| 寄存器 | `RegTensor<T>`、`MaskReg` | VF 操作数、mask、cast/compare/select 中间值 |
+
+规划顺序：
+
+1. 先确定每个 tile 的输入和输出 UB 大小。
+2. 再确认中间 UB scratch 是否真的需要。
+3. 再列出 VF 内 `RegTensor` 临时变量。
+4. 最后计算总 UB 使用量、对齐方式和 double buffer 开销。
+
+只在一个 VF 链内使用的中间值优先留在 `RegTensor`。需要跨 VF loop、跨 stage 或在 `CopyOut` 前以 tile 形式存在的数据才放 UB。
+
+## 4. VF 内常见对象
+
+- `RegTensor<T>`：输入、输出和中间寄存器，生命周期不跨 VF 作用域或 tile。
+- `MaskReg`：tail、compare 和 select mask，不是同步 primitive。
+- `LoadDist` / `StoreDist`：UB/寄存器之间的 load/store 分布，不是 barrier。
+- `AscendC::Reg::*` 或 `AscendC::MicroAPI::*`：VF-safe 算术和辅助 API。
+- raw UB pointer 在文档或 SDK 声明里常见为 `__ubuf__ T*`，在部分参考实现里也会看到 `__local_mem__ T*`；后者在 CANN 9.0.0 `reg_compute` 公共头中是 `__ubuf__` 的别名。
+
+## 5. 同步边界
+
+同步先按层判断：
+
+- UB pipeline 层：`EnQue` / `DeQue`、`CopyIn -> Compute -> CopyOut` 顺序或必要的 pipe fence 表达 stage handoff。
+- VF 层：只有 VF local scratch 出现真实 producer / consumer 顺序风险时才考虑 `AscendC::Reg::LocalMemBar<src, dst>()`。
+- 高级 pipeline 层：`SetFlag` / `WaitFlag`、`PipeBarrier`、`SyncAll` 或 cross-core flag 只能作为 outer shell 机制，不能写进 `__simd_vf__` 的默认 callable surface。
+
+普通 `LoadAlign -> Add/Mul/Exp -> StoreAlign` 的寄存器链不需要 barrier。`LocalMemBar` 的 `MemType` 组合和使用边界见 [[../api/regbase_api_sync]]。
+
+## 6. 编码检查
+
+- `CopyIn`、`Compute`、`CopyOut` 的 ownership 清楚。
+- VF body 只处理 UB/寄存器，不直接处理 GM。
+- `RegTensor` 不跨 VF 作用域或 tile 保存。
+- mask 生成与当前 tile 有效长度一致。
+- cast 链条和输出 dtype 一致。
+- store 回 UB 后再由 `CopyOut` 写 GM。
+- UB 大小计算包含 scratch、对齐和 double buffer 开销。
+- 同步机制能对应真实层级和生产者 / 消费者关系。
+- 如果 API 参数不确定，先查文档或参考实现，不试错编造。
+
+## 相关文档
+
+- [[regbase_build_notes]]
+- [[../api/regbase_api_reference]]
+- [[../api/datacopy_best_practices]]
+- [[../api/regbase_api_sync]]
+- [[../reference-ops/open_source_operator_table]]

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/dev-experience/tiling_review_notes.md

@@ -0,0 +1,86 @@
+---
+title: Tiling 审查笔记
+purpose: 设计和审查 RegBase tiling 时使用，覆盖 tiling packet、有效长度/对齐长度、tail、dtype route 和 UB 大小。
+read_when:
+  - Host/tiling 还没有把全局 shape 拆成 block、tile 和 tail。
+  - 设计串讲或 review 中需要检查 tiling。
+  - 出现 tail、block split 或 UB 大小问题。
+keywords:
+  - tiling
+  - review
+  - tail
+next_reads:
+  - regbase_programming_notes.md
+  - ../pitfalls/precision_guide.md
+  - ../pitfalls/common_traps.md
+depth: practice
+topic_type: experience
+---
+
+# Tiling 审查笔记
+
+RegBase 的 VF body 只能处理当前 tile 的寄存器通道。Host/tiling 层必须先把全局 shape 拆成可解释的 block、tile 和 tail，并把 kernel 需要的 route 信息传清楚。
+
+## 1. tiling packet 至少包含
+
+- 总元素数或关键维度。
+- 每核处理元素数。
+- 每个 tile 的有效长度和对齐长度。
+- tile 循环次数。
+- tail 元素数。
+- dtype route 或 `TILING_KEY`。
+- UB buffer 大小或推导所需参数。
+
+## 2. 有效长度与对齐长度
+
+| 用途 | 使用有效长度 | 使用对齐长度 |
+|---|---|---|
+| mask 生成 | 是 | 否 |
+| 数学 API count | 是 | 视 API 而定，必须验证 |
+| UB buffer 大小 | 否 | 是 |
+| UB offset | 否 | 通常是 |
+| GM 写回 | 是 | 不能越界 |
+
+## 3. tail 策略
+
+- 每个 tile 都应能得到当前有效长度 `validCount`。
+- VF 内用 `MaskReg` 表示有效通道。
+- store 回 UB 和 GM 写回都不能写出有效范围。
+- 如果 copy 层使用 padding，必须说明 padding 不参与最终输出语义。
+
+## 4. 多 route 场景
+
+- dtype route：fp16、bf16、fp32 可能需要不同 VF chain。
+- shape route：小 shape 可简化 pipeline，大 shape 需要多 tile。
+- alignment route：对齐路径和非对齐路径可以不同，但要保持数学一致。
+
+## 5. 审查必查项
+
+- blockDim 是否来自 shape、device 或 route 推导，不能无依据写死。
+- 每核工作量是否覆盖全部元素且无重叠。
+- tile 有效长度和对齐长度是否区分。
+- tail count 是否传入 kernel 或可由 kernel 推导。
+- UB 总使用量是否包含双缓冲和 scratch。
+- `TILING_KEY` 是否与 dtype route 匹配。
+
+## 6. 常见问题
+
+| 问题 | 影响 |
+|---|---|
+| 用对齐长度参与数学 count | tail 结果错误 |
+| 用有效长度计算 UB offset | 下一 tile 地址错 |
+| 忽略最后一个 block 的剩余量 | 丢数据或越界 |
+| 多 route 使用同一 tiling 字段但语义不同 | 开发者难以实现 |
+| repeat count 超过 API 限制 | 构建失败或运行行为不稳定 |
+
+如果 VF 或普通 vector API 的 repeat count 使用 `uint8_t`，单次 repeat 不能超过 255；当 row count、repeat count 或 tile count 可能超过单次接口限制时，应在 Host tiling 或 kernel loop 中拆分。
+
+## 7. 审查输出建议
+
+问题要指向 DESIGN.md 的具体章节，并说明它会影响 API 可行性、内存规划、多核策略、伪代码可实现性还是精度风险。
+
+## 相关文档
+
+- [[regbase_programming_notes]]
+- [[../pitfalls/precision_guide]]
+- [[../pitfalls/common_traps]]

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/dev-experience/working_vs_failed_dav_3510_cases.md

@@ -0,0 +1,49 @@
+---
+title: DAV_3510 成功/失败案例对照
+purpose: 用 DAV_3510 RegBase 的成功与失败信号帮助判断设计是否走在正确路径上。
+read_when:
+  - 修复中不确定问题来自设计、API、tiling 还是同步。
+  - 需要判断当前实现是否符合 RegBase 主路径。
+keywords:
+  - DAV_3510
+  - success
+  - failure
+next_reads:
+  - regbase_programming_notes.md
+  - ../pitfalls/symptom_to_cause.md
+  - tiling_review_notes.md
+depth: practice
+topic_type: experience
+---
+
+# DAV_3510 成功/失败案例对照
+
+## 成功信号
+
+- Host route、tiling、kernel branch 清楚。
+- `CopyIn -> Compute -> CopyOut` 分层稳定。
+- VF body 明确使用 `RegTensor`、`MaskReg`、`LoadDist`、`StoreDist`。
+- tail mask、dtype cast 和 store 长度一致。
+- API 来自白名单、SDK 文档或真实参考实现。
+
+## 失败信号
+
+- 设计只说“使用 RegBase”，没有分层。
+- `LocalTensor` 计算和 `RegTensor` 计算混在同一层。
+- tail 只在 copy 层处理，VF store 没有 mask。
+- 直接复制参考实现，shape/dtype 不匹配。
+- 为了修复构建问题随意替换 API。
+- 使用 `SyncAll` 或 cross-core flag 解决本地 stage ordering 问题。
+
+## 修复优先级
+
+1. 先确认 route 和 tiling。
+2. 再确认数据流和 buffer ownership。
+3. 再确认 VF API 与 mask。
+4. 最后处理性能和高级同步。
+
+## 相关文档
+
+- [[regbase_programming_notes]]
+- [[../pitfalls/symptom_to_cause]]
+- [[tiling_review_notes]]