cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/buffer-lifetime-alias.md

@@ -0,0 +1,133 @@
+---
+type: Mechanism
+title: Buffer 生命周期、绑定与别名
+description: 从物理内存、逻辑 Tensor 绑定、区域与轮次追踪，区分别名覆盖、生命周期和流水依赖问题。
+tags: [Buffer, 别名, 生命周期, workspace]
+---
+
+# Buffer 生命周期、绑定与别名
+
+当某个中间量稳定等于另一个张量、跨 tile 继承旧值或修改 buffer 数量后现象变化时，分别检查物理内存所有权、逻辑 Tensor 绑定、生命周期和流水依赖。相同地址不必然是错误，错误绑定也不必然越界。
+
+## 所有权账本
+
+为每个 TBuf/TQue/LocalTensor 记录分配字节数、获取 offset、元素 dtype、有效区、生产者、消费者、首次写、最后读和释放/复用点。对 ReinterpretCast、切片和偏移 Tensor 记录共享的物理基址，不能把类型不同误写成独立分配。
+
+再按当前版本 API 的真实单位计算每次读写的字节区间，分别标出 logical valid、padding 和 allocation capacity。独立 buffer 对照若同时改变 OOB 落点、alignment 或有效 lane，只能记为混杂实验，不能把结果单独归因于 alias 或生命周期。
+
+同时建立“逻辑角色—物理槽位”表：变量名、预加载目标、VF 实参位置、VF 写回槽位和 CopyOut 源槽位必须能够串成同一条数据流。输出恰好等于某个中间量时，先用错值反解核对槽位；源码注释与实际 producer 冲突时，以地址和值证据为准。
+
+### TPosition 是逻辑位置
+
+Ascend C 用 `TPosition` 表达张量的逻辑用途，再映射到物理存储。常用映射如下，依据 CANN 9.0.0 的通用说明；带产品条件的位置继续按原文解释。[TPosition 定义][buffer-source-5]、[逻辑位置与物理存储映射][buffer-source-11]
+
+| 逻辑位置 | 对应物理存储 | 语义 |
+| --- | --- | --- |
+| `VECIN` / `VECCALC` / `VECOUT` | UB | 矢量输入、临时计算和输出；三种名字不代表三块独立硬件存储 |
+| `A1` / `B1` | L1 | 左、右矩阵的数据分块 |
+| `A2` / `B2` | L0A / L0B | 送入 Cube 的左、右矩阵分块 |
+| `CO1` | L0C | Cube 输出和累加结果 |
+
+例如，输入队列和输出队列都可能占用 UB，但具体缓冲区是否重叠由分配和复用方式决定。`LocalTensor` 的逻辑位置也不能单独说明 layout、dtype 或当前内容是否就绪。需要确认分配与队列用法时，使用 `ascendc-api-knowledge-query` 查当前 Buffer、Tensor 与队列接口。
+
+[buffer-source-5]: https://gitcode.com/cann/asc-devkit/blob/c8c1b9df6bb9cd61c09751c7ef414b89e06af274/docs/api/context/TPosition.md
+[buffer-source-11]: https://gitcode.com/cann/asc-devkit/blob/c8c1b9df6bb9cd61c09751c7ef414b89e06af274/docs/api/context/通用说明和约束.md
+
+### region 身份不由变量名决定
+
+把同步和生命周期账本中的对象写成 `(物理根/基址, offset, 有效范围, generation)`，而不是只写 buffer 变量名或 index 文本。下列情况需要得到不同的审计结论：
+
+- 同名 index 在后续分支或流水重新赋值后，可能已选择另一个物理 slot；应分别记录重绑定前后的值域。
+- 同一根 buffer 即使 index 名称相同，写入与读取的 offset 或有效范围不同，也应视为不同 region；要展开本轮的地址范围再核对。
+- 不同表达式不能直接判为不同 region。只有在当前 dtype、符号和循环取值域下证明映射相同，或运行时地址观测一致，才可合并；例如非负整型范围内 `idx & 3` 与 `idx % 4` 可指向同一模 4 region。
+
+复合 alias、宏展开、指针转换或无法取得实际循环范围时，既不能断言同一 region，也不能断言错配，应标为 `UNKNOWN` 并补充基址、offset、有效范围和 epoch 探针。该约束能避免把“同步已配对”误解为 “当前消费者读取的区域已准备好”。
+
+## VF 跨文件端到端账本
+
+遇到无类型区分力的 VF 裸指针时，不在调用点或定义点单独停下。对每条 dtype/分支路径分别追踪：
+
+```text
+调用实参位置/物理地址
+  -> VF 形参位置/语义角色/读写方向
+  -> 进入的 UB 槽位
+  -> 本次调用后的最后写者
+  -> 下一 VF 或 Cast 的读取槽位
+  -> CopyOut 的最终源槽位
+```
+
+表中至少记录 `R/W/RW`、进入前 producer、退出后 last-writer 和最终消费者。类型相同只能说明调用可编译，变量名相似也不能证明按位置绑定正确；某个 LocalTensor 名称保持不变时，其物理槽位仍可能已被另一 VF、Cast 或复用写覆盖。FP32 与 FP16/BF16 若走不同 Cast 或 CopyOut 路径，应拆成独立账本，不能用一条已闭合路径代替其他 dtype。
+
+### 用数值指纹反解槽位
+
+为候选输入和中间槽位选择符号、数量级或位模式明显不同的探针值，先计算“若实参交换”“若搬出中间槽”“若读取旧 tile”各自应得到的输出，再比较 actual 与候选值的类别、位模式和逐元素关系。actual 稳定逐位等于某个中间量，比“误差很大”更能支持错槽位候选；只在容差内接近则仍可能来自舍入或公式近似。若候选槽位在所选输入上数值相同，该实验没有区分力，应更换输入而不是报告反证。
+
+### 静态 `0 finding` 的边界
+
+静态审计未报告问题，只能说明当前规则对当前输入文件没有命中。调用与 VF 定义未同时提供、宏或模板展开不可见、alias/offset 过于复杂、名称 token 缺少语义，都会留下漏报面。因此 `0 finding` 不能证明实参顺序、读写方向、last-writer、有效 lane 或 CopyOut 源正确；发现 VF 后仍须完成人工账本。反过来，静态 finding 也只是候选，必须用可区分输入和单变量修改确认，不能直接写成根因。
+
+#### 跨文件 VF 的漏报审计
+
+当编译通过、全域稳定错值像参数置换或错误 CopyOut，但只对入口文件运行静态审计得到 `0 finding` 时，查询本节。先确认审计输入是否同时覆盖调用点、VF 定义、本地 include、目标 dtype/宏分支和实际生成源码；再检查工具是否能解析当前位置参数、模板展开、alias/offset、last-writer 与最终搬出槽。“加载了多个文件”也不等于这些语义均被追踪。
+
+人工账本至少选一条实际执行路径，从调用实参地址一直连到最终 CopyOut；对另一个 dtype 或 Cast 路径建立独立 control。随后用可区分哨兵让各槽位位模式不同，一次只交换一个实参或搬出源，并预先计算 actual 应匹配哪个指纹。若修改后的目标产物按预测改变，才支持错位/错槽候选；工具后来出现 finding 仍只是附加线索。
+
+无法获得展开后源码、实际分支或产物采用证据时，把静态覆盖范围和结论写成 `UNKNOWN`。反例：仅把调用文件交给工具时为零命中，加入 VF 定义后出现候选，这不表示前一次证明源码正确，也不表示工具对所有跨文件调用都无效；它只暴露了那次输入和规则的覆盖边界。宏生成的调用即使文件齐全仍可能漏报，因此不能把“零告警”当成阴性实验。
+
+## 时间维度：生命周期与旧 tile
+
+把“绑定了错误槽位”和“同一槽位在错误时间被读取”分开。为每次写入附加 `epoch=(row, tile, stage)`，再核对消费者读取的 epoch 是否属于当前轮。第一行正常、后续行的 tile 0 像上一行最后一个 tile，支持参数未刷新或状态沿用候选；所有 row 都稳定等于另一中间量，则优先检查语义绑定和 VF/CopyOut 接力。两种机制可以同时存在，先修全域错槽位后可能才显出旧 tile 边界。
+
+用每轮不同哨兵能确认读取的是哪个 epoch；哨兵必须进入真实 producer 路径，不能只改未被当前分支消费的临时变量。`blockDim=1` 仍可能让一个核处理多行和多 tile，因此单核失败不排除生命周期或旧状态，只削弱纯核间竞争解释。
+
+当同一 slot 的旧 generation 与发布/回收路径同时可疑时，按需查看 [同步诊断：保护区域、条件路径与缓冲回收](../cases/sync-dataflow-handshake.md)；先分开验证 region、路径闭合和最后消费者，不把生命周期现象直接归为一条同步 API。
+
+### Queue/Double Buffer 的槽位时间线
+
+当实现使用 TQue 或 Double Buffer 时，不能把变量名、Queue `depth` 和物理实例数视为同一个量。先从当前版本 API 页取得 `depth`、`InitBuffer(num)`、EnQue/DeQue/FreeTensor 的强事实，再为每个实际 slot 建立状态账本：
+
+```text
+epoch i: FREE -> Alloc -> producer写 -> EnQue -> DeQue -> consumer最后读 -> Free
+epoch i+1: 只允许在另一个空闲slot上重叠，或在slot i完成回收后复用
+```
+
+账本至少记录 `(row,tile,stage)`、LocalTensor 基址、Queue/slot、producer 完成证据、交接点、最后 consumer 和 Free 点。Double Buffer 的价值来自相邻 epoch 可在不同实例上流水重叠；它不允许 producer 覆盖仍由上一 epoch 消费的同一物理区。提前 Free、漏 Free、EnQue/DeQue 交接了不同地址，或下一轮 Alloc 比最后消费更早，均是可证伪候选，不因输出稳定而自动排除。
+
+验证时分别做两种单变量 control：一是固定 tile/shape 仅把 `num=2` 改为 `num=1`，记录实际实例与事件时间线如何改变；二是保持实例数，仅延后目标 Tensor 的 Free 或增加 checkpoint，验证最早分叉是否按预测移动。前者同时改变并行调度，单独通过只能支持“slot/时序相关”；后者若 checkpoint 本身改变调度也仍是混杂证据。拿不到实际 slot 地址、生成同步或最后消费者时，结论写 UNKNOWN。
+
+资源预算继续使用两本账：`InitBuffer` 等真实分配形成的**保留占用**，以及各 epoch/alias 的 **并存数据峰值**。队列 `depth` 不能直接乘进物理保留占用；只有 `InitBuffer(num)`、静态分配或真实地址证据才能确定物理实例数。反过来，两个实例已保留也不表示数据生命周期必然同时活跃。
+
+## 资源申请与共享容量
+
+| 现象 | 需要展开的关系 |
+| --- | --- |
+| 前几轮正常，后续申请失败或读到旧值 | 本轮是否归还了前一轮占用的槽位；Alloc/EnQue/DeQue/Free 是否交接同一区域；新分配区是否已写满有效输入 |
+| 只在后续 stage 或非零偏移出现 NaN/Inf | 各 stage 对同一 slot 的元素数、字节数和对齐后跨度是否一致；首槽 offset 为零可能掩盖大小错配 |
+| 混用多个队列与手动事件后异常 | 分别记录队列和 TPipe 事件的申请、释放及同时存活数量，再查当前资源限制；不能先假定统一池或统一上限 |
+
+实际分配的补齐、偏移、队列 depth、绑定和支持通路使用 `ascendc-api-knowledge-query` 查所用 Buffer 接口。未写满的输入应补齐有效写入；归约临时区的初值由具体操作决定，不能一律清零。
+
+### 系统与用户 workspace 的分区
+
+直调与框架入口的初始化责任可能不同。使用 Matmul 等高阶接口时，分别列出系统区、用户区的容量和半开地址范围，核对传给 Kernel 的指针如何到达实际读写点；把整个 workspace 头指针当用户区，会与系统状态重叠。概念边界见[Host 资源口径](tiling-tail-state.md#查询容量时区分阶段与用途)；所需初始化、取址和编译选项使用 `ascendc-api-knowledge-query` 查当前调用，不能假定直调自动完成框架步骤。
+
+容量足够也不保证复用安全；给各区写入不同的合法诊断标记，追踪首次覆盖发生在哪个调用。跨 stage 的字节常量应来自同一布局推导，修复时同步更新全部分支和消费者。
+
+## 最小实验
+
+1. 输出实际基址、offset 和 buffer 标识，确认源码符号与物理存储的对应关系。
+2. 只将一个可疑中间量换到独立临时区（独立 buffer）；预测若别名是原因，最早分叉点应随之移动或消失。
+3. 对多 tile 循环在每轮写入不同哨兵，确认参数或中间量是在本轮产生，而非沿用上一轮状态。
+4. 在复用边界前后保存数据；添加同步只能作为区分实验，并需证明它覆盖了正确 producer-consumer 边。
+
+对绑定候选还应逐项核对 `LocalTensor<T> = buffer.Get<T>()` 与真正写入该 buffer 的预加载路径。用 NumPy 或 CPU 模型通过只能说明其覆盖的数学语义合理，不能证明真实 Kernel 绑定正确。`blockDim=1` 只能削弱纯核间解释；如果单核仍负责多行或多 tile，生命周期和状态残留仍然可能存在。
+
+## 阴性结果
+
+独立 buffer 未改善时，先确认改动被采用、该存活区间内物理存储确实独立，以及局部观察覆盖候选的必要预测。有效观察与预测矛盾，才排除被检验的具体别名解释；一次替换不能排除其他 buffer、跨轮复用或并存缺陷。最终输出未变时，先看相关局部值是否已恢复，再决定是否转查计算参数、搬运地址或其他依赖。扩大 buffer 后通过也只说明布局变化影响现象，可能同时改变流水调度或越界落点；形成正式修复前仍需绑定和生命周期证据。
+
+正式修复要同步修正所有 dtype 分支和调用点，并回归独立 buffer、原复用布局、首尾 tile、跨行和 CopyOut。诊断阶段扩大 buffer 或关闭复用产生的通过结果，不能直接作为生产补丁。
+
+## 事实边界
+
+VF 调用模型、接口支持和同步语义必须查询当前版本 API 文档，缺少权威来源时保持 `UNKNOWN`。查询 CANN 9.0.0 的 TQue、depth、实例数与事件语义时，使用 `ascendc-api-knowledge-query` 选择对应版本与接口。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/cast-rounding.md

@@ -0,0 +1,76 @@
+---
+type: Mechanism
+title: Cast、舍入与中间精度
+description: 通过转换前后位模式和局部对照，区分舍入、整数表示丢失、过早降精度与存储覆盖。
+tags: [Cast, 舍入, 中间精度, 整数表示]
+---
+
+# Cast、舍入与中间精度
+
+阶梯状误差、半 ULP 差异或只在 dtype 边界失败，可以提高 Cast 候选优先级，但不能直接确认 RoundMode。先保存 Cast 前后的值和位模式，确认首次信息损失是否确实发生在该边。
+
+## 区分实验
+
+1. 固定 Cast 输入位模式，只切换目标版本和精确 dtype 组合明确支持的舍入模式。
+2. 样本同时包含正负非整数、tie 两侧、范围边界、正负零和当前接口允许的特殊值。
+3. 对每种模式事先计算预测位模式，并确认构建产物采用了修改后的调用。
+4. 增加一个完整 repeat 与一个 tail，防止把 mask 或有效长度错误误判为舍入差异。
+
+先列出整条计算链的显式和隐式 Cast，标记第一次缩窄位置。最终输出改成 FP32 但上游仍发生缩窄时，结果不会恢复；相反，中间 dtype 扩大后局部边界移动，才支持过早降精度候选。整数或索引进入低精度浮点前，要用位模式和可表示边界验证信息损失，不能假设“先转更宽浮点再转窄”会恢复已经不可表示的整数。
+
+## 整数进入 FP16 的可表示性探针
+
+不要写成“所有大于 2048 的整数都不能由 FP16 精确表示”。FP16 的有效二进制精度为 11 位：绝对值不超过 2048 的整数都可精确表示；超过后表示间距随指数增大，因此仍有部分整数可表示。例如 2048、2050 和 4096 可精确表示，而 2049、4097 不可精确表示。负值按相同间距规律检查，不用单个正边界外推全部输入域。
+
+用实际业务索引的最小值、最大值和边界邻点做 `integer -> FP16 -> wider/integer oracle` 往返探针，同时保存输入整数、FP16 位模式、回读值和首次碰撞的两个整数。若约定要求逐个整数精确，地址、计数或索引运算应保留整数表示，不能靠容差掩盖碰撞。
+
+`integer -> FP32 -> FP16` 仍受最终 FP16 间距限制，不能绕过窄化；而较大整数在 FP32 中也可能先丢失低位，所以“先转 FP32”不是通用修复。具体 Cast 重载、舍入模式和 dtype 组合是否受当前产品支持必须查询对应版本 API 页；缺少权威证据时保持 UNKNOWN。
+
+## int32 转 FP32：同为四字节也可能丢失整数低位
+
+FP32 有 24 位有效二进制精度：绝对值不超过 `2^24` 的整数都可精确表示，超过后只有部分整数可表示。在最近偶数舍入的数值模型中，`16777217 → 16777216`，但 `16777218` 仍可精确表示；负数按相同间距检查。同为四字节、转换后范围没有溢出，或模式名称含 `NONE`，都不能证明信息无损。
+
+当索引、计数或离散标签在转换后碰撞时，给实际业务范围加入相邻整数、`2^24` 两侧和正负对照，记录整数原值、浮点位模式及回读值。只在转换之后增大 dtype 无法恢复低位；若当前任务要求逐个整数精确，保留整数链作为对照，并核对实际调用支持的模式。这里的数值模型不替代目标 API 的运行结果。
+
+需要一条已限定 profile 的输入、位模式和触发/control 例子时，按需查看 [整数进入浮点链：相邻整数碰撞](../cases/integer-float-collision.md)；它不外推当前任务的 Cast 重载或业务范围。
+
+## 宽化 Cast：数值误差还是存储覆盖
+
+若 FP16/BF16→FP32 后反而出现整段错值，或只有复用同一缓冲时失败，同时检查数值转换与目的区覆盖。`ReinterpretCast` 或另取一个不同 dtype 的 Tensor 视图不等于新分配；对连续有效的 `n` 个元素，源、目的所需字节数分别由 `n * sizeof(src_dtype)` 和 `n * sizeof(dst_dtype)` 计算，mask/repeat 路径还要展开各次真实读写区间。总容量足够与源数据在消费前未被覆盖是两个不同条件。
+
+固定 Cast 文档提醒较短 dtype 转较长 dtype 时地址重叠可能导致错误；它不能被简化为所有重载、产品和输入范围均必然失败。先按当前 API 的地址重叠规则核对，再只将目的 Tensor 改为独立且容量足够的区域，保持源位模式、count/mask、stride 和 RoundMode 不变，比较 Cast 前后首个分叉。若独立目的区消除了错值且地址账本支持覆盖，提高存储候选；若仍失败，按当前支持重载及 Cast 前后位模式继续检查转换链和上游。改变布局同时改变了 tiling、对齐或调度时仍需排除混杂。
+
+若目标写入已经覆盖尚未读取的源数据，调用之后增加 barrier 或更换 RoundMode 都不能恢复它。具体片内读写先后不从这张地址账本推断；生命周期与 alias 的其它分叉见 [Buffer 生命周期、绑定与别名](buffer-lifetime-alias.md)。
+
+## 比例偏差与舍入配置
+
+整数转 half 后出现固定倍率偏差时，先确认实际走普通 Cast 还是反量化路径，并记录当前 scale；不要按历史倍率直接修正。跨产品移植后 float→half 的误差方向改变，则分别核对重载、支持的 RoundMode 和真实配置，用正负半整数附近的样本比较转换前后值。接口被拒或枚举存在但组合不支持时，使用 `ascendc-api-knowledge-query` 查类型转换规则，不能用 ReinterpretCast 代替数值转换。
+
+### 量化中间精度与参考结果
+
+AscendQuant 的 float→int8 路径可能在内部先把输入、scale、offset 转成 half，具体过程使用 `ascendc-api-knowledge-query` 查所用量化重载。若比原 CPU 参考误差大，可以建立含 half 中间量的模型来找首次分叉；这个模型用于解释实现，不自动替代任务的验收基准。只有算子定义证明原基准有误时才更正，否则应修复计算路径。
+
+“入口先量化到低精度 → 高精度求值 → 转回输出类型”也是一条待核对的数值路径，不自动代表项目要求或不可避免的误差下界。它与 golden 超差只说明两条路径存在差异，不能据此宣布口径错误或排除实现问题；按已确认定义构造独立局部参考，再检查实际路径的剩余偏差。
+
+量化输出集中在最大值附近时，分别检查 scale 的解码值、量化前数值和实际饱和模式；不要直接调整 scale 的取整方向。动态统计、scale 与倒数混用等问题见[动态量化](../operators/dynamic-quant.md)，MX/E8M0 另见[精度模式](precision-mode-approximation.md#mxe8m0-边界)。
+
+## 模式名称与 SIMT 转换
+
+模式名称不是无损或实际生效的证明。CANN 9.1 Memory Cast 将有精度损失时的 CAST_NONE 解释为 CAST_RINT；当前 dtype、产品和重载是否允许仍须查询。AscendQuant 的部分可配置舍入路径还存在不支持的 roundMode 回退默认模式且不报错的说明；配置写进源码但结果不随之变化时，先核对组合表，再用 tie 两侧和边界值比较实际位模式，不直接判为编译器忽略配置。
+
+SIMT 转换按精确函数查询，不把 Tensor Cast 的 RoundMode 表或 FP8 的特殊值规则套到 half、BF16、整数转换。对 half2、bfloat16x2 等打包类型，先展开真实分量并对齐输入输出位置，再比较每个分量的舍入、饱和和异常值；只有打包路径失败时，同时保留布局与数值两类候选。
+
+## 判断规则
+
+- Cast 前匹配、Cast 后稳定匹配另一已支持模式，才支持 RoundMode 候选。
+- 仅范围外分叉优先检查溢出、饱和和转换约束。
+- 扩大中间 dtype 有效、修改某项最终 Cast 设置无效时，可提升过早降精度候选的优先级；先核对各改动的实际范围与采用，不能据此排除最终转换另有问题。
+- Cast 前已经分叉，只能说明更早已有可见差异，不能据此排除 Cast 自身另有错误或锁定上游根因。用已确认转换语义分别重放实际与可信参考输入，区分本段未解释的偏差及已有差异的放大或隐藏。
+
+跨 FP16、BF16、FP32 或整数的 A/B 测试同时改变了表示范围、尾数和可能的实现路径，只能用于缩小范围。RoundMode 名称、枚举值、默认行为和 dtype 支持必须查询当前版本的精确重载；旧案例中的固定模式配对只作为待验证主题。
+
+若小增量只在最终升宽前丢失，按需查看 [FP16 升精度：在首次信息损失前改变位置](../cases/fp16-promotion-boundary.md) 的首次窄化对照；仍以当前逐操作约定决定能否调整提升位置。
+
+枚举值存在不代表某个重载、dtype 组合和产品支持它；编译通过也不能替代输出位模式验证。
+
+Cast 的源目的重叠约束使用 `ascendc-api-knowledge-query` 查目标产品与具体重载，涉及版本差异时再查当前头文件或做最小实验。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/complex-operator-boundary.md

@@ -0,0 +1,48 @@
+---
+type: Mechanism
+title: Matmul、卷积、Norm 与复合算子边界
+description: 将复合算子拆为可观察的数据边，沿反向依赖与局部 oracle 缩小首个分叉，检查机制遮蔽与残差。
+tags: [融合算子, 计算链, 局部对照, 首个分叉]
+---
+
+# Matmul、卷积、Norm 与复合算子边界
+
+复合算子应先拆成可观察的数据边，不直接从最终误差猜测某个高阶 API。至少区分输入布局与搬入、主计算、累加/归约、缩放或量化、激活、搬出以及多核合并。
+
+## 局部 oracle
+
+为每条边建立与实际 layout、dtype 和有效区一致的局部 oracle。Matmul/MMAD 要记录 M/N/K、转置、ND/NZ 布局、输入与累加 dtype、HF32/量化配置；Norm 要分离统计量、归一化和仿射；卷积要分离 im2col/LoadData、Cube 累加和后处理。
+
+## 定位顺序
+
+1. 确认输入搬入后的逻辑矩阵或向量与 oracle 一致。
+2. 检查主计算输出的首次分叉，避免被后处理饱和或 Cast 掩盖。
+3. 对归约或 K 轴使用长度边界和强消减输入。
+4. 对随路量化、ReLU、bias 和输出布局，优先逐项关闭或替换；无法分离的变化按组合干预解释。
+
+## 反向依赖切片与首分叉四问
+
+- **何时查**：最终输出同时可能由搬运、主计算、partial 合并和 epilogue 解释，或全量 dump 成本过高时，从首错输出坐标反向切片。
+- **查什么**：只保留能到达该输出坐标的 producer、tile/core、partial 和后处理边，逐边记录 `producer -> consumer`、逻辑坐标、dtype/layout、有效区、owner 与局部 oracle。对 fan-in 边必须验证完整贡献集合，不能用一个正确 partial 代表整个合并。
+- **怎么证伪**：根据相邻点的有效比较继续定位：上游匹配/下游分叉时保留该边候选；两者都错则继续向上游；两者都匹配则向下游。不可比的点标 `AMBIGUOUS`；观察虽改变执行条件、但本轮比较仍有效时，保留本轮 PASS/FAIL，并限制对原程序的推断。受控地用 oracle 替换该边输入时，先确认替换生效、被检验关系仍成立，且必要预测有区分力；下游观察与该预测矛盾时，只排除相应的单因解释。
+- **避免混淆**：“最早被观察到”不等于“最早产生”，时间顺序也不等于数据依赖顺序。边界跨越 layout、Cast 和同步三种变化时仍太宽；先增加能区分候选的 checkpoint。首分叉落到广播、排序、卷积或 MMAD 后，转相应算子/API 页，不把本页升级为万能根因。
+
+## 机制依赖与遮蔽
+
+同一最终误差可以同时包含搬运、布局、累加、参数、同步和后处理缺陷。先修复或绕过最早分叉后，必须重新建立边界；后面的机制可能此前被全零、NaN 或错误槽位遮蔽。局部 oracle 只证明它覆盖的数据边，不把前一 checkpoint 正常外推到未观察的内部阶段。
+
+## 何时停止展开
+
+全链路 dump 不是目标。只要相邻两个可比 checkpoint 已形成“上游与局部 oracle 一致、下游首次偏离”，且保留下来的候选对下一项单变量实验给出不同预测，就停止继续向无关阶段展开，转入该数据边对应的机制页。若相邻点仍同时跨越布局转换、dtype 转换和同步，则边界还不够窄；优先增加一个能减少竞争候选的观察点，而不是把所有内部张量都导出。
+
+停止展开前确认两点对应同一逻辑数据、有效区及明确的 dtype/layout，采集完整，并有适用的独立 oracle。下游不可比时将该点记为 `AMBIGUOUS`；上游通过不能证明两个点之间所有隐藏阶段都正确。观察改变 UB、同步或 tiling 时，说明与原程序的差别；本轮比较有效仍保留其结果，需要向原程序推断时再核对未插桩基线。选点、状态与成本控制沿用[观察点设计](../../diagnosis/checkpoint-design.md)。
+
+## 绕过后的残差线程
+
+对最早分叉做有效实验或受控绕过后，重新计算整个误差拓扑。只有有效实验兑现了该解释的区分性预测，才能称第一条解释已获支持；单纯绕过只提供边界观察。原症状按预测消失而出现互不重叠的新坏点时，可能是此前被遮蔽的第二缺陷；保留已支持解释和证据边界，为新残差建立独立线程，不用新形态反向否定已经兑现的预测。若旧坏点仍有可信残差，先判断是原线程未完全解释、正式修复不完整，还是补丁引入回归，再决定是否拆线程。
+
+每个线程记录自己的首错边界、假设、实验、修复范围和回归集合。只有后续证据支持同一因果链，且合并不会丢失任一原始边界、Parent、实验和验证状态时才合并线程；最终报告必须分别说明已解决、未解决和未验证的机制。线索拆分与合并的通用判据见[假设与实验](../../diagnosis/hypothesis-experiment.md)。本页方法不携带任何固定 API、阈值或生产根因；强事实继续查询对应版本的官方文档。
+
+优先路由到独立算子说明：Reduce、Broadcast/Transpose、Matmul/MMAD、Normalization 和 Convolution 分别保存数学约定与 checkpoint。本页用于复合链拆分和多机制线程管理，不替代算子公式或版本 API。
+
+高阶 API 的 tiling、workspace、支持 dtype 和产品限制必须查询当前版本的官方文档。生产算子中的用法只能证明一种已观察模式，不能自动成为所有 shape、版本或产品的接口约定。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/data-movement-alignment.md

@@ -0,0 +1,104 @@
+---
+type: Mechanism
+title: 搬运、对齐与有效区
+description: 分开核对逻辑长度、物理容量、搬运长度、mask 与有效区，区分对齐、Stride、Padding 和布局问题。
+tags: [DataCopy, 对齐, Stride, 有效区]
+---
+
+# 搬运、对齐与有效区
+
+当错误首次出现在 GM 与片上存储之间、行尾或非对齐 shape 时，先冻结五个互不等价的量：逻辑元素数、物理分配字节数、单次搬运长度、计算 mask 覆盖长度和最终有效输出区。任何一个量经过向上对齐，都不能自动替代另外四个量。
+
+仅非对齐 shape 失败会提高尾块相关候选，仍需沿长度边界核对实际搬运与计算路径；尾部可能采用不同的 Cast、累加 dtype 或求值顺序，不能据此排除数值路径。搬入后的相关有效数据已正确时，继续找首次出错的计算或写回节点。
+
+## 建立数据边约定
+
+对每条可疑边记录：producer、源物理位置和 offset、API 精确重载、每个参数的单位、目的位置和 offset、consumer、有效元素区间。将 stride 写成地址公式，并分别计算第 0、1、末块的实际地址；不要只比较参数名。
+
+再为同一条边建立三单位账本：逻辑元素 offset/count；对于字节寻址且没有打包/压缩/格式转换的表示，再用 `sizeof(dtype)` 换算字节地址/count；接口字段名、实参值及该精确重载声明的单位。bit-packed 或格式转换路径按实际 packing、data block 与 layout 约定换算，缺少定义时保持 UNKNOWN。物理 block count/形状、有效区和 padding 另列，不能用块数替换元素数或字节数。接口单位和支持能力属于版本强事实；应路由到当前版本的数据搬运/布局 API 页，不从旧案例或参数名称猜测。
+
+若尾块只留下前一 generation 的图样，按需查看 [尾块有效区与旧状态：先证明本轮写入](../cases/tail-valid-region-state.md)，先验证本轮 producer 是否覆盖消费者的有效 region，再判断搬运、mask 或同步。
+
+少量抽样一致只说明这些元素在本次观察下相符，不能直接排除整条输入或搬运路径。要排除与失败输出有关的搬入问题，先对应它实际依赖的元素、轮次和状态，再核对这些依赖是否被正确传入；可结合有针对性的采集与已核实的源码、有效区和映射，不要求全量 dump。依赖尚未覆盖时保留输入侧候选，也可继续检查计算或写回。
+
+## 可证伪实验
+
+1. 使用共享前缀相同的对齐与非对齐 shape，只改变有效长度，并确认 tiling key、核数和分支可比。
+2. 在搬运前、搬运后、首次消费后三处保存同一逻辑元素及其物理 offset。
+3. 将错误索引按行、data block、repeat 和核区间重排，检查周期是否与某个 stride 或 padding 一致。
+4. 若改换重载，先按目标版本重新计算参数单位和目标缓冲区容量，再比较结果。
+
+## 布局、Stride 与 Padding 分流
+
+把逻辑 layout 和物理搬运分开：ND/NZ/分块布局决定坐标如何落到物理位置，搬运 API 决定这些物理区间如何复制。对 reshape/transpose 后的 Tensor 先判断是否连续，再把元素 stride、字节 stride 和接口参数单位分别写入表中。错误周期等于一行或一个通道块时，用可逆坐标编码区分轴映射错误与纯搬运长度错误。
+
+对 transpose/reshape view，先由轴映射推导每一轴的元素 stride，再换算字节地址；不能因逻辑 shape 相同就假设物理连续。构造一组配对诊断：原 view 与按同一逻辑值显式物化的连续 staging Tensor，分别在消费者前后比较值和地址。只有 staging 通过时，才提高非连续访问、stride 或搬运参数候选。staging 同时可能改变对齐、buffer 占用、tiling 和同步路径，必须记录这些差异，不能把该 control 直接升级为正式修复。
+
+### 多行批量搬运与逐行搬运对照
+
+当 `blockCount>1` 的批量搬运只有第二行以后错误，而逐行调用看似正常时，查询本节。先为逻辑行 `r` 写出同一对照目标：
+
+```text
+src_head(r), valid_bytes(r), src_physical_pitch
+dst_head(r), dst_physical_pitch, valid_elements(r), padding/dummy 区
+```
+
+批量路径用一次调用的 `blockLen + src/dst stride` 推导这些地址；逐行路径用每次 Tensor offset 推导。只有两条路径的第 0、1、末行逻辑坐标、物理起址、valid 区和目标 buffer 容量完全相同，才是地址语义上的 control。批量搬运减少调用次数是性能候选，不是正确性证明；逐行搬运还会改变 DMA 提交次数、EnQue/DeQue 节奏和 Double Buffer 重叠，因而“逐行通过”可能同时掩盖 stride、padding 或流水回收问题。
+
+先做三个有预测的实验：把 `blockCount` 从多行缩到 1 但保持相同行 pitch；保留批量调用而只让 stride 表达连续行；给每行首尾写入可逆 `(row,col)` 编码并比较第一个错行。若错误边界随 `blockCount`/stride 预测移动，支持批量地址约定候选；若只随 Queue/slot 节奏变化，转查生命周期与同步。缺少精确重载单位、UB 物理行宽或每行有效长度时结论为 UNKNOWN。
+
+### Padding 位置、物理 pitch 与归约集合
+
+在 CANN 9.1 Ascend950PR/DT 的 GM→UB `DataCopyPad` 入口中，Normal 会让每个非对齐数据块补齐，而 Compact 将数据块合并后只在整块末尾补齐；Compact 下 `dstStride`、`leftPadding` 和 `rightPadding` 不生效。这是该产品、方向和重载的布局事实，不能推广到 A2/A3 或其它搬运通路。
+
+因此多行数据进入消费者时必须同时写出 `row_head(r)` 的**物理 pitch**和本行的**逻辑有效元素数**。CANN 9.1 Memory `ReduceSum` 的 count 入口需按产品解释：在支持 `isSetMask` 的产品上，默认 true 时由 `count` 指定参与元素数，false 时由调用前设置的 mask 决定；在本节的 Ascend950PR/DT 上，`isSetMask` 不生效，仍按 `count` 归约。其他产品的参数支持与其他重载分别查对应 API。count 不替代行首寻址，也不自动把 Normal 的逐行 padding 或 Compact 的末尾 padding 变成有效输入。
+
+比较 Normal 与 Compact 的实验先按各自合法布局解码同一 logical region，再比较逻辑元素和相应的归约结果；raw UB 字节或物理 pitch 不同本身不是失败。需要观察 padding 时，使用当前 API 已定义的 `paddingValue` 或明确配置的 SetPadValue；未由当前条件定义的 dummy 不写预期值。随后只改变 mode，保持逻辑输入和消费者约定不变：若错误随解码后的 row head 或有效 count 预测移动，支持布局/集合候选；若逻辑 region 在搬运后已正确，转查后续计算、别名或同步。
+
+### 共享 L1/L0 的多阶段边约定
+
+GM→L1、L1→L0、Cube/Vector 消费和写回之间共享同一片 L1/L0 时，每阶段单独“shape 正确”仍不足。建立阶段表，逐边记录逻辑 shape、dtype、物理 format、C0/分形、起始 offset、head-to-head stride、有效尾块、producer/consumer 和存活区间。下一阶段的源约定必须与上一阶段实际写出的物理布局一致；不能让前一阶段按 ND/NZ 的一种 stride 写入，后一阶段却用另一种 shape 或转置标志解释同一地址。
+
+对共享 buffer 同时检查两条轴：空间上，第 0、1、末分形地址是否按同一 layout 公式闭合；时间上，下一 stage 或下一 head/tile 是否在最后消费者之前覆盖该区。独立 staging 通过时，只能提高 layout、stride 或 alias 候选，因为 staging 同时改变地址、容量与调度。LoadData 的 C0、字段单位和产品支持必须转查版本 API 页；如果只能取得逻辑 shape 而拿不到物理 format/stride，保持 UNKNOWN。
+
+Padding 只属于物理存储时，后续计算 mask、Reduce count 和最终比较必须排除无效 lane。不要看到尾部脏值就直接扩大 padding；先在搬入后、计算前、搬出前比较同一有效元素。GlobalTensor 标量写、LocalTensor 标量写和 DMA 搬运的可见性路径不同，若地址和值正确但消费者看到旧值，转查同步或 Cache 可见性，而不是继续调整 `blockLen`。
+
+DataCopy/DataCopyPad 为 DMA 对齐形成的 padding/dummy 与 Conv/Load3D 的逻辑空间 padding 必须分账：前者描述物理传输与无效 lane，后者参与窗口坐标和数学边界。DMA padding 值即使恰为 0，也不能据此改变卷积 padList；Conv padValue 即使已设置，也不能证明 GM↔UB 尾块 dummy 已初始化。
+
+## 筛选后的有效区与状态
+
+GatherMask 后的物理 Tensor 容量不等于本轮筛选结果长度。记录返回的有效数（如当前接口的 rsvdCnt），只把有效元素交给搬出、统计与下一次计算；尾部随机值只有被消费时才影响结果。自定义掩码编码不匹配 dtype、多 repeat 读取范围重叠，也会表现为选出的元素或数量不对；使用 `ascendc-api-knowledge-query` 核对掩码规则，再展开实际读取位置。
+
+若第一轮正确、后续轮次异常，同时检查掩码模式与输入复用：当前 GatherMask 是否改变了后续计算依赖的模式，DropOut 是否修改了随后还要使用的 mask。分别保存调用前后状态与掩码内容，在确需的段落设置/恢复模式，或为可变输入保留正确副本。DropOut 的保留位、缩放位置与 dtype 仍按原算法核对。
+
+Gather/Scatter 的 offset 先换算为真实字节地址，再检查边界与目标位置是否重复。重复 Scatter 位置涉及写入所有权，不能只靠调整偏移单位修复，另见[索引与地址归属](index-address-ownership.md)。逐行与多行搬运的容量、单位及对齐问题继续使用上方的成对地址实验。
+
+## 跨架构迁移时重画数据通路
+
+存储和计算单元的角色可以复用；**具体连接通路、编程能力与资源规模**需要保留架构条件。下面是 2201 → 3510 迁移中对读代码有直接影响的差异，依据 CANN 9.1.0 的迁移指南，属于选摘而非完整支持矩阵。[2201 到 3510 架构变更][movement-source-7]
+
+| 项目 | 2201 | 3510 |
+| --- | --- | --- |
+| Vector 计算方式 | Membase | Regbase，支持 SIMD Reg、SIMT 及混合编程 |
+| GM → L0A/L0B | 存在直接通路 | 该直接通路移除，需经 L1 中转 |
+| UB → L1 | 没有该直接通路，通常经 GM 中转 | 新增直接通路 |
+| L0C → UB | 没有该直接通路，通常经 GM 中转 | 新增单向直接通路 |
+| L1 → GM | 存在直接通路 | 该直接通路移除；调试搬出同样受影响 |
+
+迁移时先把数据流重新画通，再核对搬运、转换与同步的 API 条件。上述表格只比较 2201 和 3510，不用于判断其他架构；某条通路存在也不代表任意 dtype、layout 或搬运接口均可用。
+
+[movement-source-7]: https://gitcode.com/cann/asc-devkit/blob/e5451c7feba11f9e259f4fbc19c4bf82f8c0496c/docs/guide/跨代迁移兼容性指南/3510架构迁移指导/2201到3510架构变更.md
+
+## 结论边界
+
+- 非对齐 shape 失败只说明路径依赖 shape；它不证明接口不支持非对齐。
+- 尾部出现旧值可能来自 CopyOut 长度、计算 mask、目标容量或同步，不能只归因于 padding。
+- 结合[msSanitizer](https://gitcode.com/Ascend/mssanitizer)的访存告警核对实际访问，仍需证明逻辑 offset 与有效区是否正确。
+- 在已核对的有效范围内，搬运后值正确而首次消费后错误时，可降低对应搬运候选，转向计算 mask、别名或同步消费边；范围外的依赖仍需单独检查。
+- 布局转换前后逻辑坐标一致而物理地址不同是正常现象；只有实际坐标映射与约定不符才构成缺陷。
+
+确认根因前，不把“扩大 buffer”“全部按 32B 处理”作为通用修复；这类改动可能掩盖越界并把无效 padding 纳入计算或验收。
+
+## 事实边界
+
+DataCopy/LoadData 的地址单位、padding 行为、C0 与产品支持必须以当前版本 API 文档为准；先确认这些条件，再使用多行批量/逐行对照与逐阶段布局账本。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/golden-host-contract.md

@@ -0,0 +1,84 @@
+---
+type: Mechanism
+title: Golden、Host 属性与构建采用
+description: 核对比较约定、参考来源、Host 属性与实际构建采用，区分 golden 不一致、缓存复用与现场伪差异。
+tags: [golden, Host, 比较约定, 构建采用]
+---
+
+# Golden、Host 属性与构建采用
+
+精度调试首先验证比较双方是否对应同一计算定义与比较规则。冻结输入字节、shape/layout、dtype、属性、数学公式、特殊值规则、有效区和容差；golden 生成脚本、随机种子及依赖版本也属于证据。
+
+归约还要记录实际参考路径：框架默认 `sum`、pairwise/tree、按 repeat 分组和显式逐元素循环即使作用于同一集合，也可能产生不同浮点结果。`sequential` 需要说明累加 dtype、索引顺序和中间舍入位置；记录这些用于复现与解释，不自动给所有算子增加内部树必须相同的要求。
+
+框架 reference 对 shape、stride、CPU SIMD 或线程分派敏感时，仅固定 Python 脚本和 dtype 不够。原矩阵求和后取列，与先抽取该列再求和，可能走不同结合树；应保留原布局或用已核对的逐操作模型建立局部对照。具体例子与适用边界见[框架参考的分层归约](accumulation-order.md#框架参考的分层归约与主尾列分派)。需求未规定结合树却观察到 oracle 对其敏感时，如实记录需求与实现的差异，不自行放宽原 evaluator。
+
+## 比较模型随输出语义选择
+
+当用户问“该用哪种误差标准”时，先查输出承担的公开语义，再查 dtype。非计算搬运或索引通常先验证坐标和值是否保持；整数算术通常先查精确数值与溢出约定；浮点计算需要冻结公式、逐步 dtype、求值顺序和项目阈值；量化路径还要冻结 scale、zero-point、舍入、饱和、量化轴及最终输出类型；随机输出则先查分布和重复性约定。它们是不同 evaluator 家族，不能互换。
+
+判定比较模型是否可用时，至少回答四个问题：它来自哪项项目要求；它是否覆盖当前输出的有效区和特殊值；故意破坏该要求时 evaluator 是否会失败；阈值是否在看见本次结果前已经确定。任一项未知，模型只可用于探索，不能支撑最终 PASS。高精度 reference、位级比较或统计检验本身都没有天然更高的证据等级，关键是它是否忠实于当前公开约定。
+
+## 三个常见伪差异
+
+- Golden 忠实度：参考实现使用不同公式、累加 dtype、归约顺序或边界语义。
+- Host 约定：属性未进入 tiling/cache key，旧 tiling 或旧二进制被复用。
+- 构建采用：修改了未参与构建的文件、产物未更新或运行加载了另一目录下的二进制。
+
+## Oracle 来源、降级与独立性
+
+没有可直接使用的项目 golden，或需要为中间 checkpoint 构造局部 oracle 时，按证据目的逐级寻找：
+
+1. 项目验收明确指定的 reference 与 evaluator；它定义最终通过口径。
+2. 与目标实现独立、语义相同的现成实现或可证明数学性质；先核对公式、边界与 dtype。
+3. 由较小基本算子组合出的 reference；逐步保留量化、Cast、layout、有效区和求值顺序。
+4. 自建 CPU 算术链、不变量或手算小例；适合筛选候选和局部边界，除非另有约定依据，否则不自动升级为最终验收 oracle。
+
+“降级”表示可用证据范围变窄，不表示后一个来源必然数值更差。每次降级都记录共享依赖：若 golden 和 kernel 复用了同一个索引公式、常量表、生成器或 helper，两者一致可能只是共同错误。用手算小例、第二个独立实现、守恒/对称等性质和故意违反要求的敏感性反测来校准。高精度整式只证明数学参考；若目标约定包含逐步低精度舍入、特殊值或固定顺序，它不能直接判定每个实现 checkpoint。算子 reference 的通用降级分层与无 golden 时的独立依据见[算子建模](../../diagnosis/operator-modeling.md)与[Checkpoint 设计](../../diagnosis/checkpoint-design.md)；本节保留该阶梯在 golden/Host 约定场景的应用。
+
+## 稳定式与逐步 oracle
+
+稳定重写或移位指数在实数域可以等价，却未必与约定的有限精度求值链等价。构造 oracle 时保留实际的中间 dtype、Cast 和舍入点；例如实现按“移位 → 指数 → 缩放”执行，就分别记录每一步的量化结果，而不以未舍入的理想移位指数值直接替代。再用能使中间类别、舍入格点或最终输出分叉的输入比较原链、重写链与项目 oracle。
+
+高精度表达式适合说明数学目标，但不能自动裁决逐步低精度约定。若项目 golden 已定义该顺序，先复用它；若没有，局部逐步 oracle 只能支撑候选和实验，最终验收仍需回到项目比较模型。
+
+## 派生 probe 的输入保真
+
+为解释疑点而自建 CPU/probe 时，优先复用正式 materializer、dtype 量化、序列化和 oracle；先证明 probe 与正式 harness 在同一输入上使用相同字节/位模式、有效区和比较口径。没有复用输入链的手工脚本只能作为探索证据，不能单独推翻 Kernel 或 golden；若两者不一致，先定位输入、量化、layout 或 evaluator 的分叉，再解释计算结果。
+
+## Host 属性、缓存身份和采用的四向实验
+
+当错误依赖同一进程中的调用历史，尤其是同 shape、同输入但不同标量属性的第二次调用像第一次时，先做四向实验，不先修改 Kernel：
+
+| 实验 | 固定项 | 主要回答的问题 |
+|---|---|---|
+| 新进程单独执行 A；另一个新进程单独执行 B | 输入、shape、环境和产物 | 单次属性传递及 Kernel 路径是否本来就错误 |
+| 新进程执行 A→B | 同上，仅改变调用顺序 | B 是否受到首次 A 的历史影响 |
+| 新进程执行 B→A | 同上 | 历史影响能否随首次属性反转 |
+| 在第二次调用只改变 shape | 属性 A/B 和公共输入语义 | shape 是否改变缓存身份、分支或 tiling；这是对照，不是单独结论 |
+
+每次保存 Host 实参、实际进入 tiling/Kernel 的属性、tiling key、kernel 符号、blockDim、二进制身份和 fresh 输出。若 A→B 的第二次像 A、B→A 的第二次像 B，而新进程单独 A/B 都正确，支持“首次调用状态污染后续调用”的缓存身份候选；若新进程第一次就错，优先查属性传递、tiling 或 Kernel；若属性已经到达但分支未随之变化，转查动态分派；若行为只随重建产物变化且不随顺序反转，转查构建采用。
+
+换 shape 后恢复不能单独证明缓存键遗漏，因为 shape 还可能改变 kernel、tiling、核数和 tail。四向实验只收窄候选，最终仍要定位实际声明或数据流，并证明修正后的属性身份进入真实运行路径。不要把清空宽泛用户缓存目录作为默认实验；先识别项目内真实产物、缓存对象和加载路径。固定阈值、框架专名或缓存实现断言不作为通用约定；历史材料一律不作为 API 强事实来源。
+
+## 通信上下文的身份与生命周期
+
+通信配置中出现确定性或缓冲字段，不证明当前初始化和真实路径已采用它。Host 的 internal 头文件只提供声明线索，不能当作公开支持矩阵，也不能用新版声明补齐旧版的 Host 接口规则；分别核对实际链接版本、初始化和运行状态。
+
+跨卡直调中，同一缓冲或上下文被不同通信域意外复用，会表现为内容互相覆盖、建链异常或释放阶段崩溃。核对 HcclChannelAcquire 与 HcclEngineCtx 的 engine、ctxTag、通信域及实际初始化是否对应；描述符先按当前接口初始化，再填写并检查真正下发的字段。配置数字和标签限制使用 `knowledge-query` 查 Host 通信原文，不跨版本照搬枚举。
+
+释放时区分用户申请的内存与库管理的内置缓冲、引擎上下文；按当前组件的生命周期结束通信域，再处理设备重置，不能把库内存当作用户 aclrtMalloc 内存直接释放。若只在第二次建链或先后运行两个通信域时失败，沿上面的 A→B/B→A 方法比较对象身份与残留状态。
+
+通信域级与进程级确定性配置应和链接版本、执行形态一起记录。只看到字段被设置，不代表实际通信路径已经采用它；数值顺序的对照见[跨卡归约](../operators/reduction.md#跨卡归约对照)，通道就绪和远端完成见[通信缓冲所有权](multicore-ownership.md#跨卡通信的缓冲所有权)。
+
+## 验证方法
+
+先用小输入手算或第二个独立 oracle 交叉验证 golden，再保存产物哈希、构建日志和加载路径。对影响 Kernel 语义的每个 Host 属性做成对实验，确认 tiling 字段和产物随属性变化。仅当相同输入与约定下 actual 首次分叉，才进入设备侧机制定位。
+
+Golden-only 自比较只验证 golden 生成链自身的一致性，不能替代 actual-vs-golden。用例清单中的 required、optional 或 invalid 标签也不能代替执行事实：只有对应 shape/dtype/输入实际物化、进入目标入口并按冻结 return-code/evaluator 记录后，才计入该类覆盖。
+
+Oracle 需要逐层忠实于当前验收：数学公式、求值顺序、中间 dtype、特殊值、padding 有效区和输出 Cast 都应可追溯。高精度解析解、框架表达式和逐操作硬件模型用途不同；来源名称不能替代实际行为验证。对极值域或分支边界，使用第二个独立实现或逐点实验交叉检查。
+
+先按算子公开约定选择验收模型，再冻结 evaluator 实现和阈值来源。整数精确比较、浮点容差、量化误差、随机分布检验和非计算类位级一致不是可互换模板；若项目约定未说明，保持 `UNKNOWN` 并补充独立依据，不能从 dtype 名称推导固定行业阈值。特殊值是否相等也必须由同一 evaluator 明确定义。
+
+放宽容差、重新生成 golden 或清空缓存只能作为诊断动作；除非新约定有独立依据，否则不能把失败改写成通过。修复与回归按[工作流阶段 4—5](../../../SKILL.md#六阶段调试流程)推进。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/index-address-ownership.md

@@ -0,0 +1,57 @@
+---
+type: Mechanism
+title: 索引、Offset 与地址归属
+description: 将逻辑坐标、元素 offset、字节地址和核所有权分层，用错值指纹与区间对照验证寻址候选。
+tags: [索引, Offset, 地址, 所有权]
+---
+
+# 索引、Offset 与地址归属
+
+稳定错位、输出等于相邻位置、Gather/Scatter 局部异常或多维展平后周期性错误，应先把逻辑坐标、元素 offset、字节地址、搬运块参数和核所有权分层。数值正确但落在错误位置属于寻址问题，不属于舍入。
+
+## 地址账本
+
+对每条读写边记录逻辑坐标、规范化后的 index、展平公式、元素 offset、`sizeof(dtype)`、物理基址、字节地址、有效区和所属核。分别代入首元素、跨行点、边界前后、最后元素和一个非法索引；包含负索引语义时，必须先按当前算子约定规范化，再进入无符号地址计算。
+
+## 支持与反证
+
+- 在保留可逆编码的观察面反解出固定错位，且预测地址与错误值一致，支持索引候选。
+- 搬运后逻辑值和地址都正确、首次计算后才分叉，应降低寻址候选。
+- 周期等于行 stride 或 data block 时，需同时核对 [搬运、对齐与有效区](data-movement-alignment.md)。
+- 只在核边界重叠或遗漏时，转查 [多核分区、所有权与核间协同](multicore-ownership.md)。
+
+## 区分实验
+
+用 `value = f(n,c,h,w)` 的可逆编码填充输入，选择能够区分相邻轴和相邻核的系数。对同一坐标同时计算 reference offset 和 Kernel offset，单独固定一个 index 或一个核执行。Gather/Scatter 还要区分 index 生成错误、index 规范化错误和最终地址换算错误；一次只替换其中一层。
+
+系数应由实际 shape 选择，使每个轴的取值区间不碰撞，例如先按最内轴基数递推，再构造 `value = n*K_n + c*K_c + h*K_h + w`；不要复制某个案例的固定常量。编码值必须在载体 dtype 中精确可表示，否则改用整数旁路记录或缩小探针域，避免把编码碰撞误判为地址碰撞。
+
+反解前确认选定观察面仍保留编码且映射可逆。输入编码无碰撞、可精确表示，不代表经过 MatMul 或归约后的输出仍能直接解码：一般乘加会混合多个输入。可在搬运后的输入面读码；需要观察最终输出时，按合法 shape 选用单位矩阵、one-hot 等控制，并核对实际公式、缩放或附加项是否保留编码，或按当前算术计算各候选的输出指纹后比较。矩阵乘对照见[Matmul / MMAD](../operators/matmul-mmad.md)。
+
+在已确认可反解的观察面，对 ND 布局先从值解出逻辑坐标，再独立计算连续元素 offset。对 blocked 布局，仍用打包前的逻辑坐标编码值，并用该次 tiling/layout 给出的实际块形状另算外层块坐标和块内坐标；块形状未知时保持 UNKNOWN，不预设固定通道块。样本应成对跨越行边界和块边界，并比较不同块中的同一块内坐标。值能解出正确逻辑坐标但地址错误时优先查物理映射；值本身解出错误轴时优先查轴排列或索引公式。
+
+### 错值反解与 delta 指纹
+
+- **何时查**：错误输出稳定地等于另一个合法位置、每行错位量固定，或错误呈轴周期而数值本身仍像输入指纹时查询。
+- **查什么**：先从 actual 值反解其真实来源坐标 `q`，再与目标坐标 `p` 同时计算 `delta_coord = q - p`、逻辑元素 offset 差和字节地址差；对当前实际存在的行、块、核等边界分别取成对样本，不存在的轴记为 N/A，不能只看一个首错点。
+- **怎么证伪**：若反解值没有唯一来源，先区分输入码碰撞与观察面已经混合编码，再换编码、观察面或比较候选输出；未命中输入码本身不能反证寻址问题。可反解且来源坐标正确、读写地址也与 reference 一致，或 delta 随数值内容而非 shape/stride 改变时，降低寻址候选并转计算链。
+- **避免混淆**：固定元素 delta 可能来自轴置换，固定字节 delta 可能来自基址/单位；delta 与 owner、核数或分区边界联动时才提高所有权候选。周期形态本身不能裁决，API offset 单位仍以当前版本页为准。
+
+### 半开区间所有权证明
+
+- **何时查**：单核正常、多核出现重叠/空洞，尾核异常，或 Gather/Scatter 多次写同一目标时查询。
+- **查什么**：把每个 producer 的逻辑输出集合和物理写集合都表示成半开区间或显式索引集；记录 `owner`、`begin`、`end`、有效数量、base offset 和允许的冲突/合并规则。验证所有合法输出的覆盖次数，不用“每核平均长度”替代真实尾区间。
+- **怎么证伪**：强制单核、两核并成相邻区间、交换核编号，并用每核独立指纹；若集合并集恰好覆盖有效区、互斥约定下交集为空、交换 owner 后错误不随边界移动，就降低所有权候选。
+- **避免混淆**：逻辑区间正确但物理地址重叠属于地址换算；物理区间正确但结果偶发变化转同步/生命周期；约定允许重复 index 时不能把交集直接判成踩踏，应转受控合并或原子语义说明。通用的核参与集合、空洞和尾核分区证明继续路由 [多核分区、所有权与核间协同](multicore-ownership.md)，本节只保留 index/地址到 owner 的桥接。
+
+## Production 模式：索引散写与原子所有权
+
+生产实现中可观察到一种候选模式：运行时 index 先做约定范围过滤，再由多个核或多次更新写向同一目标位置；冲突地址通过受控的原子区间合并。诊断时只采用三项审计动作：在无符号地址换算前验证负值/上界，证明相同 index 是否允许碰撞，以及记录原子模式开启、每次散写和恢复普通写的完整生命周期。具体同步方向、原子 API 和产品支持仍查询官方 API 文档。
+
+区分实验应同时包含非法 index、两个更新命中同一地址、互不冲突的 control 和多核重复运行。若普通写只在碰撞时丢更新，支持所有权/合并候选；若单次单核也写到相邻行，先修正三段 offset 公式。浮点原子顺序可能改变舍入分布，但“每次不同”仍不能越过地址、初始化和可见性证据直接归因于顺序。
+
+## 修复与回归
+
+修正最早错误的坐标或单位换算，不用扩大 buffer 掩盖越界。回归覆盖首尾位置、跨行、跨块、负索引或非法索引约定、不同 dtype 字节宽度和多核边界。API 参数单位和合法范围须在官方 API 文档中核对当前 CANN 的相关差异。
+
+先按[分块与索引](../../diagnosis/operator-modeling.md#3-看懂分块与索引)把当前代码的执行位置对应到数据。仅在实际使用 SIMT 时补充线程索引与共享数据分析；具体 API 语义不清时，使用 `ascendc-api-knowledge-query` 核对。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/index.md

@@ -0,0 +1,32 @@
+# 精度异常机制
+
+本区域沉淀可跨算子复用的精度异常机制，包括触发现象、成立条件和区分实验。初筛时，根据计算链上的 Cast、归约、索引、搬运、同步、缓冲复用或尾块等敏感点查阅；取得中间观察后，再聚焦首次分叉及其上游依赖，不要求先找到异常边界才能使用这些经验。
+
+机制页说明常见现象、成立条件和检查方法。API 签名、支持类型、硬件容量与同步范围查询当前 CANN 的官方文档和平台说明。
+
+症状相似只能提供线索；用对照实验确认原因，修复后回放失败输入并做必要回归。
+
+## 按症状打开案例
+
+尾块或条件分支后读到旧值时，先查 [尾块有效区与旧状态](../cases/tail-valid-region-state.md)；单块正确、合并 partial 后失配时，查 [Partial 统计合并](../cases/partial-statistics-merge.md)。融合参数失敏或临时区疑似覆盖时，查 [FusedRmsNormGeluResidual](../cases/fused-rmsnorm-gelu-residual.md)；错值像中间量、极值或属性沿用时，查 [SoftplusV2Grad](../cases/softplus-v2-grad-family.md)。整数索引/计数进入浮点后才相等时查 [相邻整数碰撞](../cases/integer-float-collision.md)；小增量在最终升到 FP32 前已消失时查 [FP16 升精度位置](../cases/fp16-promotion-boundary.md)。事件配对但多轮、条件或多输出异常时，查 [同步诊断](../cases/sync-dataflow-handshake.md)。案例只提供调查分叉，不能替代机制页或当前 API 证据。
+
+## 资料导航
+
+按当前现象选择排查方法。具体 API 的产品、类型和版本限制使用 `ascendc-api-knowledge-query` 查询；表中的提示帮助选择需要先核对的条件。
+
+| 资料位置 | 何时读 / 解决什么 | 使用提示 |
+| --- | --- | --- |
+| [搬运、对齐与有效区](data-movement-alignment.md) | 用物理行距、有效范围和地址对照检查搬运；筛选后继续核对有效数、mask 状态与输入复用。 | 区分有效长度、物理容量与搬运范围 |
+| [Buffer 生命周期、绑定与别名](buffer-lifetime-alias.md) | 检查绑定、跨 tile 生命周期、队列与事件资源、共享容量和系统/用户 workspace 分区。 | 核对每轮读写区域、绑定与生命周期 |
+| [流水同步与数据可见性](pipeline-sync-visibility.md) | 检查实际读写流水、数据就绪与缓冲回收，并区分缓存可见性与观察扰动。 | 先区分核内流水依赖与核间通知 |
+| [Cast、舍入与中间精度](cast-rounding.md) | 定位转换前后首次信息损失、整数碰撞、覆盖与比例偏差，区分量化中间模型和原验收基准。 | 明确每一步的 dtype、舍入和转换位置 |
+| [累加、归约顺序与消减](accumulation-order.md) | 区分累加树、跨块与主尾列分派；Log/Atanh 近零失配可直接查[逐步对照](accumulation-order.md#atanh-近零的逐步对照)。 | 先找首次丢失信息的位置，不把局部 chunk 规律当完整 reference |
+| [NaN、Inf、溢出与次正规数](special-values.md) | 按首次类别分叉定位；另有[未选支路污染](special-values.md#未选分支也可能污染结果)与[有限/Inf 边界](special-values.md#有限与-inf-分类边界)示例。 | 特殊值处理按任务语义与当前接口核对 |
+| [Tiling、尾块与跨 tile 状态](tiling-tail-state.md) | 核对 Host/Kernel 分派、调用计数、可变参数消耗、分批覆盖、零工作量、跨 tile 状态及平台容量预留。 | 后续输出段漏写时，区分有效长度、剩余计数与地址推进 |
+| [Golden、Host 属性与构建采用](golden-host-contract.md) | 按原输出要求检查参考实现、Host 属性、缓存、构建采用和通信上下文生命周期。 | 参考实现、Host 配置和实际构建分别核对 |
+| [Matmul、卷积、Norm 与复合算子边界](complex-operator-boundary.md) | 把复合算子拆成布局搬入、主计算、归约、后处理和搬出边界；用反向依赖切片与 fan-in 完整贡献表锁定最早分叉，并判断绕过后残差应留在线内还是分线。 | 分阶段建立可解释的中间结果对照 |
+| [Shape、Rank 与边界维度约定](shape-boundary-contract.md) | 区分 rank-0、空维、维度 1、shape、tiling、broadcast 与动态分派，用 B-1/B/B+1、等价 reshape 和不等号审计核对 Host 与 Kernel 的边界语义。 | 区分空维、维度 1 与 rank-0 |
+| [索引、Offset 与地址归属](index-address-ownership.md) | 把逻辑坐标、元素 offset、字节地址和半开所有权分层，用错值反解 delta、相邻合法位置与跨边界样本区分 ND/blocked 映射错误。 | 按实际布局、打包方式和地址单位推导 |
+| [精度模式、近似路径与 Fallback](precision-mode-approximation.md) | 分离 API 近似、过早降精度、Cast 时机和下游放大，并用 dtype×tiling 二维对照识别升精度实验的路径混杂。 | 升精度时同时检查是否改变了执行路径 |
+| [算法公式、常量与参数槽位](algorithm-parameter-contract.md) | 核对重结合、槽位和原始谓词；一条后端修好后查[跨实现小量放大](algorithm-parameter-contract.md#跨实现的小量放大对照)。 | 核对实际分派，各路径分别保留验证结果 |
+| [多核分区、所有权与核间协同](multicore-ownership.md) | 核对核与 rank 的任务归属、等待覆盖、通知轮次、通信缓冲和远端完成。 | 核对参与核、读写区间和每轮 workspace 状态 |