cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/tiling-tail-state.md

@@ -0,0 +1,146 @@
+---
+type: Mechanism
+title: Tiling、尾块与跨 tile 状态
+description: 沿 Host tiling、核间分派、循环计数和有效区检查尾块与跨 tile 状态，区分容量变化引入的实验混杂。
+tags: [Tiling, 尾块, 旧状态, 可变计数]
+---
+
+# Tiling、尾块与跨 tile 状态
+
+只在 shape 边界、第二个 tile 或最后一核失败时，分别验证 host tiling、核间所有权、循环状态和尾块有效区。改变 tile 大小会同时改变内存布局、循环次数、归约顺序和流水调度，不能单凭现象改善认定 UB 容量是根因。
+
+若 Host tiling 把同一归约轴切成多个 chunk，还要记录每个 partial 的生成顺序、存储 dtype 和 pairwise/tree 合并拓扑。Host tiling 改变归约顺序时，即使参与元素集合相同，也可能不满足严格 bitwise reduction contract；这时联合查询 [归约算子族](../operators/reduction.md) 与 [累加、归约顺序与消减](accumulation-order.md)，不要把顺序差异误记成漏 partial。
+
+## 逐层核对
+
+1. Host：冻结原始 shape、属性、tiling key、blockDim、每核长度、tile 数和尾块长度。
+2. Kernel 入口：Dump 实际收到的 tiling 字段，确认缓存 key 能区分所有影响代码路径的属性。
+3. 核内循环：记录每轮 offset、有效长度、buffer 状态和参数加载；特别检查 tile 0 与后续 tile。
+4. 输出：按核区间和逻辑有效区验收，物理 padding 不得作为数学输出。
+
+将四类问题分开：通用 shape 约定、动态分支选择、合法 shape 的 tile/tail 切分、跨 tile 参数状态。最小 shape 失败时先确认 shape 合法且 tile 数、有效长度没有出现零或负值；相邻 shape 突变时保存 tiling key 与 kernel 符号；第二行 tile 0 继承上一行末 tile 的模式则检查参数加载和状态重置。
+
+## 调用计数与分批状态
+
+Host 算出的工作量、tiling 字段保存值和调用实参分别记录。若实参确为 uint8_t，256 转换为 0 是表示范围问题；该接口如何解释 0 还要另查。字段范围与接口自身调用上限是两层条件，超限时按当前规则分批，不能只把总量截小。
+
+分批后逐段核对输入地址、有效长度、输出推进、partial 合并、筛选有效数和 mask 状态。使用不同位置的输入指纹比较单次合法调用与分批路径，确认每个合法元素恰好按算法要求处理。归约、排序、转置和 GatherMask 不共用一套 repeat 上限或零值语义，使用 `ascendc-api-knowledge-query` 分别核对调用粒度。
+
+若零长度 tail 没有写目的区，而消费者仍沿用旧长度，就会读到上一轮结果。错误 tiling 修正计算；合法空任务按[Shape 与空输入要求](shape-boundary-contract.md#修复与回归)处理初始化和同步参与，不把零强改为正值。
+
+### 可变计数被消费：后续输出漏写与清零不完整
+
+同一 tile 的前几个输出段正确、后面的段未写，或者新增归约缓存后出现旧值时，检查 API 是否通过引用修改 count/remaining。把三种量分开：跨输出段复用的 `validLen`、当前段可消耗的 `remaining`、当前段的地址 offset。API 推进了剩余量，不代表已经推进地址；地址循环递增，也不代表应该再次扣减 remaining。
+
+在已核对的 950 Reg/SIMD VectorFunction 路径中，`UpdateMask<T>(uint32_t& count)` 会按本轮可处理量更新 count。默认单寄存器配置令 `C=VL字节数/sizeof(T)`：本轮 mask 覆盖前 `min(count,C)` 个元素，随后 count 变为 `max(count-C,0)`。若直接传后续输出还要用的 `aLen`，一个尾段可能将它消耗到零；下一段便形成零 mask 或跳过写入。若随后又手工扣减一次，则可能提前耗尽 mask 或发生无符号下溢，留下未初始化的有效区。[MaskReg 文档](https://gitcode.com/cann/asc-devkit/blob/e5451c7feba11f9e259f4fbc19c4bf82f8c0496c/docs/api/SIMD-API/基础API/Reg矢量计算/寄存器数据类型/MaskReg.md)也包含双寄存器配置；具体产品、dtype 和 regTrait 仍使用 `ascendc-api-knowledge-query` 核对，不把每轮处理量写成跨配置固定常量。
+
+当前 API 确认具有这种副作用后，可采用如下状态分工；这是循环组织示意，load/store 的对齐、mask 和同步条件需按实际代码填写：
+
+```cpp
+const uint32_t validLen = aLen;
+for (uint32_t segment = 0; segment < segmentCount; ++segment) {
+    uint32_t remaining = validLen;
+    for (uint32_t offset = 0; offset < validLen; offset += elementsPerRepeat) {
+        auto mask = AscendC::Reg::UpdateMask<float>(remaining);
+        // 用 mask 处理本 segment 在 offset 处的一轮；不再手工扣减 remaining。
+    }
+}
+```
+
+区分实验不必继续扩大数值输入范围：选择一个完整 repeat、一个短尾段和多个共用长度的输出段，展开每次调用前后的计数与写入区间。可在诊断版本预填合法哨兵，观察哪些有效位置仍保留预填值，再核对真实写入覆盖；若只补回局部 remaining 就让预测区间重新写入，支持计数副作用。算术模型通过却设备结果异常时，同样要核对初始化和写出覆盖，模型不包含这些内存操作。
+
+哨兵保留首先表示未观察到预期值变化，不单独证明 Kernel 或写回未执行：写回同值、读入后原值写回等也可能保留它。需要区分时，让本轮 producer 的输入或生成标识与预填值可区分，再核对对应写入范围及实际执行观察；已有有效写入证据可复用。
+
+修复后错误坐标从少数归约点变成按 segment 重复的整段尾区，应重新审查本次 diff 的计数、清零和写回。它可能是新增实现错误，不能一直用原来的求和树假设解释。具体的 45 个漏写位置与另一处清零不足见 [GRU 修复过程](../cases/thnn-fused-gru-bias-reduction.md#修复过程中的另一种机制可变计数污染后续输出)。
+
+## 区分实验
+
+选择刚好一 tile、加一个元素、少一个元素、多 tile 和尾核五类 shape。若错误总从第二轮相同相对位置开始，优先检查状态重置和参数重载；若只随核区间变化，先检查所有权与尾核长度；若周期等于物理 stride，转向搬运和布局。
+
+## 动态分支边界审计
+
+当两个相邻 shape 的误差、tiling key 或 kernel 符号突然变化时，先从 Host 条件或配置中找出真实边界 `B`，再测 `B-1`、`B`、`B+1`。例如真实边界为 512 时使用 511/512/513；这三个数只是相邻边界模板，不是通用 tile 常量。
+
+每个 shape 用同一张表记录：
+
+| 项目 | 必须保存的观察 |
+|---|---|
+| Host 判定 | 实际参与判断的维度、原始条件文本及 `<`、`<=`、`==` 的命中结果 |
+| 分派身份 | tiling key、kernel 符号、编译分支和产物摘要 |
+| 工作划分 | blockDim、每核区间、tileLen、tileNum、tail 长度和有效元素集合 |
+| Kernel 实收 | 入口实际收到的 shape、属性和 tiling 字段，而不只看 Host 预期值 |
+| 数值边界 | 最后正常 checkpoint、最早异常 checkpoint、错误坐标所属 tile/core |
+
+若 511 与 512 选择不同分支，先分别验证两条分支对自身合法输入的语义；若 Host 在 `B` 选择分支 A，Kernel 却按分支 B 的字段解释，或等号边界存在遗漏/重叠，支持动态分派约定候选。若三个 shape 使用同一分支但只有尾块失配，则降低分派候选，转查有效长度、mask 和尾状态。若允许做诊断性强制分支，执行前写出每条分支在三个 shape 上的预测，并证明实际产物采用了强制结果；强制通过只说明结果依赖该路径，不能证明 Host 判定就是唯一根因，也不能直接作为正式修复。
+
+换 shape 会同时改变数值集合、核数、tile 数和 tail，因此“换 shape 后恢复”不是分派证据。只有相邻输入、实际分支身份、入口字段和首偏离边界共同符合事前预测，才能支持边界条件候选。具体长度阈值、tiling key 名称和分派规则须从当前工程确认。
+
+### 零工作量 producer 与旧值候选
+
+尾块或条件分支后消费者读到上一轮数据时，先单列“本轮 producer 根本没有更新该 region”的候选，再检查地址、generation 和同步。记录实际采用的重载、字段值、目标 region 的写前/写后观察，以及随后 Wait/读取所在的可达路径；没有新写入时，后续读到的可能是旧值或未定义残留，不能直接归因为 Wait 过早。
+
+固定 CANN 9.1 来源给出三类有边界的例子：Atlas A2/A3 的高维 Memory DataCopy 中 `blockCount` 或 `blockLen` 为零是 NOP；Ascend950PR/DT 的 MX `LoadData` 重载（来源页 `Load2DMX.md`）规定量化系数参数 `LoadData2DMxParams` 中 `xStep` 或 `yStep` 为零是 NOP；基础 Memory `TransDataTo5HD` 的 `TransDataTo5HDParams.repeatTimes=0` 不执行转换且不写目的操作数，适用 950PR/DT、Atlas A3、Atlas A2、Atlas 200I/500 A2、Atlas 推理系列 AI Core 和 Atlas 训练系列产品，不适用于 Atlas 推理系列 Vector Core。它们分别适用于各自的 API、产品和通路，不能由字段同名推广到其它 DataCopy、LoadData、转换重载或 profile。
+
+区分实验可在冻结地址、输入、同步对象和其它 tiling 字段后，对零值与最小合法正值各自运行一次，先在 producer 边界确认目标 region 是否被写入。两组的工作量和数学输出约定不同，因而不以最终数值相等作为通过条件；只比较每组在其自身有效区和 oracle 下的结果。若正值路径更新了正确 region 而零值路径没有更新，支持零工作量候选；若两者均更新却消费者仍错，再回查映射、生命周期和 happens-before。
+
+## 多层分段状态：row、head、N-segment 与 K-pass
+
+当首行/首 head/首 N 段/首 K-pass 正确，后续层级才异常时，不要把所有循环都压成一个 `tileId`。为每个 checkpoint 保存完整 epoch：
+
+```text
+(core, row, head, nSegment, kPass, tile, stage)
+```
+
+并分别记录 data 与 scale/parameter 的 GM offset、L1 head offset、L0 起址、LoadData 字段、物理 layout/stride、valid M/N/K，以及该 pass 是初始化还是累加。第一 N 段正常而后续段异常时，优先检查 data offset 与 scale offset 是否都随 `nSegment` 更新；第一 K-pass 正常而后续 pass 异常时，检查 K 起址、长度单位、scale 起址、累加初始化状态和上一 pass 的最后消费者。数据 offset 更新正确并不能证明 scale offset 也正确，两类载体可能有不同 dtype、分形和物理 footprint。
+
+以单 K-pass、单 N 段或单 head 强制运行只能作区分实验。它会改变 L0/L1 占用、MMAD 累加次数、舍入结合顺序和流水回收，因此“单 pass 通过”只支持分段状态/地址候选。只有错误边界随事前预测的 `nSegment`/`kPass` 移动，并在修正一条数据边后其最早分叉同步移动，才可确认相应分段约定。
+
+`K_BASE` 是否必须整除某个单位、`yStep` 的单位、N 段 scale 起址和 head offset 公式都属于精确 LoadData 产品/重载/layout 的强事实；应查询当前 API 页。当前 profile 不支持的 MX 接口公式不可借来解释 910B1，K_BASE、MX 和 head-offset 的具体公式须与当前重载及布局一致。拿不到物理 layout、目标产品或实际采用的生成路径时保持 UNKNOWN。
+
+## UB 与实验混杂
+
+UB 预算必须按物理字节、对齐开销、buffer 个数和生命周期计算。扩大 dtype、改变 double buffer 或调整 tile 会同时改变容量和调度，只能作为有预测的实验。硬件容量、接口返回值和最小对齐属于平台或 API 强事实，不写成跨版本常量。
+
+预算用符号化账本表达：每个存活槽位的 `aligned(elements × sizeof(dtype)) × instances`，再按同一时刻的生命周期求和并加入约定要求的保留空间。不同 TBuf 名称不保证物理独立，ReinterpretCast 或 offset slice 也不产生新容量；反之，double buffer 的实例是否同时存活必须按真实队列/流水约定核对。
+
+升精度实验会同时扩大 UB 占用并可能改变 tileLen、tileNum、分支 key、归约顺序和流水调度。若结果变化，先证明哪一项实际被操纵；不能把“fp32 通过”直接解释为 fp16 算术精度不足。
+
+### 升精度后的 UB 峰值生命周期账本
+
+当候选修复把某段中间计算升精度、增加 Cast 临时量，或升精度后开始编译失败、全零、局部损坏、tileLen/tiling key 改变时，查询本节。不要只把所有声明字节相加，也不要只把改 dtype 的一个 buffer 乘二；应按当前真实分支建立峰值账本：
+
+| 字段 | 核对内容 |
+|---|---|
+| 物理存储 | TBuf/TQue/静态区、alias group、真实分配点与实例数 |
+| 字节 | 元素数、dtype 字节数、当前 API 要求的对齐后大小 |
+| 生命周期 | 首次可能写入、最后一次消费、释放或允许复用的事件 |
+| 并存阶段 | CopyIn、Compute、Cast、CopyOut 及 double-buffer 前后轮是否同时存活 |
+| 运行身份 | shape、tiling key、tileLen、tileNum、blockDim 与实际产物 |
+
+先按当前版本的真实分配器语义计算**保留占用**：每个 `InitBuffer`/静态分配及其实例的对齐后字节都要累计；即使两个张量的数据生命周期不重叠，只要没有地址、内存池或释放语义证明它们复用了同一物理区，就不能从容量账本中折叠。随后再按生命周期计算**并存数据峰值**，用于判断显式 scratch 复用、alias 和提前覆盖是否安全。共享基址的 alias 在两张账本中都只计一次物理区，但只要任一 alias 尚需读取，该区就不能被下一用途覆盖。新旧 tile 的队列实例、升精度临时量和低精度 CopyOut 缓冲在转换阶段可能同时存活，因此并存峰值也不一定等于稳态单 tile 用量。
+
+区分实验应先固定 shape 和分派，分别保存升精度前后的账本与实际 InitBuffer/静态分配证据，再只调整一个生命周期或 tile 参数并预告峰值如何变化。若结果改善同时伴随 tileLen、分支或核数改变，只能说明资源/调度相关，不能确认哪块 buffer 超限。硬件 UB 容量、对齐单位、队列实例语义或某 API 是否隐式分配属于版本/平台强事实；当前权威节点缺失时保持 `UNKNOWN`，不用历史案例常量补齐。
+
+反例：两个大型临时量生命周期不重叠，但各自由不同静态 `InitBuffer` 保留地址；只算活跃数据会误判容量足够。只有分配器约定或实际基址证明它们复用同一物理区时，才可按生命周期折叠容量。反过来，只按“fp16 改 fp32 所以该槽翻倍”计算，又会漏掉 Cast 期间新旧表示与 double-buffer 下一轮输入的并存峰值。UB 容量、安全余量、buffer 数量或对齐常量不作为跨版本事实，必须查询当前版本的官方 API 文档及本地平台说明。
+
+## 平台容量与库预留
+
+存储层次、核类型和跨产品容量差异使用 `knowledge-query` 查询；典型硬件参数不能代替本次运行端的可用容量。这里继续检查当前算子的分配、预留和生命周期，具体 API 的单位与约束仍使用 `ascendc-api-knowledge-query` 查询。
+
+换设备或增加高阶 API 后开始 tile 超预算时，分别记录平台总容量、库内部预留、当前算子的物理分配和活跃数据峰值。Host 与 Kernel 查询值不同时，先比较查询入口、单位、执行形态和预留阶段；多次配置还要确认最终采用的状态。容量、核数与预留入口查[Host 运行时](tiling-tail-state.md#查询容量时区分阶段与用途)，不沿用旧设备常量。
+
+CalcTschNumBlocks 等入口的 AIC/AIV 配置与 blockDim 会改变每核工作量和尾块。检查 Host 计算值是否原样进入 Kernel，并与[实际参与核](multicore-ownership.md#启动核参与核与空核)对照。系统/用户 workspace 的容量与起点另见[workspace 分区](buffer-lifetime-alias.md#系统与用户-workspace-的分区)。
+
+## 收口与回归
+
+正式修复需重新评估 dtype 改变后的 UB 字节预算，并回归边界两侧，而不是把 tile 常量调到当前样例通过。
+
+回归至少覆盖单 tile、两 tile、整除、余 1、最大尾块、动态区间两侧、首行/后续行和不同核所有权。如果修复是参数重载，验证每轮 producer；如果修复是分支边界，验证 Host 与 Kernel 使用同一约定。
+
+当现象落在最后一个有效块或前一 generation 时，可按需打开 [尾块有效区与旧状态：先证明本轮写入](../cases/tail-valid-region-state.md)；它把本页的有效区、零工作量和复用候选组织成可否证对照，不新增 API 事实。
+
+### 查询容量时区分阶段与用途
+
+GetCoreMemSize 的平台容量、ReserveLocalMemory 的预留与 GetRuntimeUBSize 的运行时可用量服务于不同阶段，不能要求它们无条件相等。记录查询位置、单位、执行形态和预留状态，再判断当前物理分配与活跃数据是否超限。具体入口查[平台容量](https://gitcode.com/cann/asc-devkit/blob/e5451c7feba11f9e259f4fbc19c4bf82f8c0496c/docs/api/Utils-API/平台信息获取/PlatformAscendC/GetCoreMemSize.md)和[运行时 UB](https://gitcode.com/cann/asc-devkit/blob/e5451c7feba11f9e259f4fbc19c4bf82f8c0496c/docs/api/SIMD-API/基础API/工具接口/系统资源与变量/GetRuntimeUBSize.md)，当前版本差异使用 `ascendc-api-knowledge-query` 确认。
+
+系统 workspace 与用户 workspace 分别核对容量和起点；总量正确但用户指针偏移不对，仍可能覆盖系统区。资源账本与对照方法见[平台容量与库预留](tiling-tail-state.md#平台容量与库预留)和[workspace 分区](buffer-lifetime-alias.md#系统与用户-workspace-的分区)。核数、启动参数和编译形态属于实际执行身份，应从运行端取得，不能用 Agent 本机代替。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/operators/broadcast-transpose.md

@@ -0,0 +1,64 @@
+---
+type: OperatorRisk
+title: 广播与转置算子族
+description: 按逻辑广播和物理重排分别建立坐标映射，检查 shape、stride、轴置换、padding 与转换链。
+tags: [Broadcast, Transpose, 布局, Stride]
+---
+
+# 广播与转置算子族
+
+## 数学与 reference
+
+Broadcast 改变逻辑索引复用，Transpose 改变坐标到物理地址映射；reference 必须按逻辑 shape 计算。
+
+Broadcast 先写出输入坐标到输出坐标的映射以及广播轴，Transpose 写出轴排列和逆排列；随后才将逻辑坐标映射到 layout/stride。右对齐、维度 1 和非连续输入是逻辑约定，block 数、padding 和搬运 stride 是物理实现，不能互相替代。
+
+## I/O 与实际链路
+
+- 冻结输入/输出 shape、dtype、layout、有效区、padding 和 alias。
+- 从 host tiling、GM 搬入、局部计算、同步到 GM 搬出逐节点记录实际计算链，不以 API 名替代。
+- tiling 分支、多核分区、尾块与特殊值必须进入风险清单。
+
+## 手写轴置换的检索与建模
+
+`tensor_3d_permute`、三维轴置换、轴排列/逆排列、展平索引和手写转置都先路由到本算子说明。先写出输入坐标、输出坐标、轴排列及其逆映射，再分别展平为元素索引；索引单位和物理地址单位不能混用。
+
+算子名称含 `transpose` 不等于实际调用 `AscendC::Transpose`。只有从真实 Kernel 调用链确认该 API 后，才查询对应的版本 API 文档；手写 `GetValue`/`SetValue` 或其他索引实现仍按实际读写链和坐标映射建模。本页不据算子名预判具体题目的根因或修复。
+
+## 敏感 checkpoint
+
+按疑点从输入解码、布局/搬运、消费者前后和最终有效输出中选择少量相关观察，说明观察面、元素映射与参考依据。缺局部 oracle 时先保留原值或检查适用的不变量，不据此排除整段计算。具体见[观察点设计](../../diagnosis/checkpoint-design.md)；仅在已有可比误差且需要解释传播、放大或抵消时，使用[逐层分析](../../diagnosis/progressive-error-analysis.md)。
+
+使用每个轴系数不同的可逆坐标编码，并配对测试无广播、单轴广播、多轴广播、维度 1、非连续输入和尾块。若值来自正确输入坐标但落在错误物理位置，转查 layout/stride；若源坐标本身错误，保留在本算子说明。特定广播指令的输入块数或对齐限制属于版本 API 事实。
+
+### Broadcast shape/stride 双账本
+
+- **何时查**：输出 shape 正确但某一轴重复错、同一源值没有在预期坐标复用，或错误周期随 stride 改变时查询。
+- **查什么**：先按当前算子约定对齐 rank，并为每个输出坐标写出逻辑源坐标；广播轴的逻辑源坐标固定到该轴唯一位置，非广播轴保留输出坐标。再用真实物理 stride 独立计算源元素 offset。把“逻辑上等效为零步长”与 Tensor 实际保存的 stride 分开，不能篡改物理元数据来模拟广播。
+- **怎么证伪**：选择两对输出坐标：一对按约定应共享源坐标，一对不应共享；若两对的源坐标和实际读地址都与 oracle 一致，而首次错误在消费者之后，就降低广播映射候选。
+- **避免混淆**：源坐标错误归广播；源坐标正确但地址错归 layout/stride；地址和值均正确但消费者错则转下游。具体 API 的 rank、axis、临时空间和对齐限制只查询对应版本页，未覆盖组合保持 `UNKNOWN`。
+
+### Permutation 逆映射与交换图
+
+- **何时查**：转置后值集合相同但位置错、转置与广播组合才失败，或连续物化能恢复时查询。
+- **查什么**：同时记录 permutation `p` 和逆排列 `p^-1`，对探针坐标分别计算 `out_coord -> in_coord -> input_offset`。若任务约定允许广播与转置交换，另画两条逻辑等价路径，并在转置后同步重排广播轴；没有该等价约定就不做交换假设。
+- **怎么证伪**：在纯逻辑 reference 上验证 `p^-1(p(x)) = x`，再比较原路径与“先手工广播后转置”或 “先转置后按重排轴广播”的有效区。只有两路使用相互独立的置换实现，且进入消费者前都分别匹配独立 oracle，而消费者后才同向分叉时，才降低 permutation 候选；两路共享同一 Transpose 实现时只能记 `NO_DISCRIMINATION`。
+- **避免混淆**：逆变换通过只证明被采样坐标可逆，可能同时保留相互抵消的两次错误；还要检查单程坐标指纹。连续 staging 会改变容量、tiling 和同步，只是定位实验，不自动证明正式修复。
+
+## 手工物化与 Padding Control
+
+为隔离广播逻辑，按 reference 坐标映射在 host 侧把源值手工展开为稠密逻辑 Tensor，并保持有效区值、dtype 和下游计算不变。手工展开通过而原广播路径失败时，广播的物理实现或布局是候选；两者都失败时，继续检查轴置换或下游消费者，不能仅凭算子名归因。
+
+为隔离物理块，在每个块只填充有效 lane；只有物理缓冲区已经分配这些 padding lane、且当前约定允许诊断代码写入和观测时，才分别使用两组可区分哨兵。有效输出随哨兵变化说明无效区泄漏到搬运或计算；输出不变则降低 padding 候选。padding 是否分配或可写未知时不触碰它，改用有效区/连续物化对照并保持 UNKNOWN。实际块形状和特定广播 API 约束只从 tiling 与对应版本的官方文档读取。
+
+Transpose 后再做一组 view 与连续 staging Tensor 的对照：两者逻辑值和轴映射相同，仅显式物化连续存储。staging 通过而 view 失败时提高连续性、stride 或布局候选；两者同样失败时优先复核排列公式和消费者。手工物化会改变容量、tiling 或执行路径，只用于定位，不能直接当成正式修复证据。
+
+## 小通道转置与转换链
+
+小通道场景可把“装载槽位是否完整”和“输出哪些通道有效”分开检查。历史 C 不超过 16 的 TransDataTo5HD 组合写法，会为未用输入行提供合法的已有行，并在转置后只提取逻辑有效通道；采用前应核对当前重载和真实布局，不能让补齐值进入有效输出。偏移表按输入与输出坐标推导，先用坐标编码核对一整个周期。
+
+FP32→half→转置→Gather(half)→uint8 的组合还可能在转置之前丢失量化边界信息。整数输出相差 1 时，在每次转换前后比较边界两侧输入；按原算法规定的取整方式和时机修复，不能直接加一个 round。布局接口、临时空间、重叠方式与产品支持使用 `ascendc-api-knowledge-query` 核对，有效数与掩码状态见[筛选后的有效区](../mechanisms/data-movement-alignment.md#筛选后的有效区与状态)。
+
+## 版本路由与边界
+
+转置与排布转换的接口资料使用 `ascendc-api-knowledge-query` 获取。本页不代表任一具体实现或 NPU case 已验证。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/operators/convolution.md

@@ -0,0 +1,60 @@
+---
+type: OperatorRisk
+title: Convolution 算子族
+description: 沿窗口与通道坐标、padding、group、dilation 和 K 参与集合，检查卷积布局、累加与输出路径。
+tags: [Convolution, group, dilation, 布局]
+---
+
+# Convolution 算子族
+
+## 数学与 reference
+
+先冻结卷积维数、输入/权重/输出逻辑 shape、stride、dilation、group、padding、bias、dtype 和 layout。reference 必须与当前任务对 padding 值、输出尺寸和累加顺序的约定一致；不要从某个框架默认值推断。
+
+## 实际计算链
+
+按当前疑点展开 Host shape/tiling、输入与权重搬入、layout 转换、im2col 或等价展开、L0A/L0B 准备、Cube/MMAD 累加、后处理及搬出中的相关环节。为所选数据边记录有效区与参考依据，高阶 API 名称不能替代实际链路。
+
+## 敏感 checkpoint
+
+从下列位置按疑点选点，参考与采集前提见[观察点设计](../../diagnosis/checkpoint-design.md)。缺局部 oracle 时可先保留数值或检查适用的不变量，无法判定的部分保留未知，不要求全链采集。
+
+1. padding 后的逻辑输入与边界窗口；
+2. im2col/LoadData 后首个内部矩阵；
+3. 权重布局转换后的首块和通道尾块；
+4. 主累加器在首个 K 块、尾 K 块和合并后；
+5. 后处理前后与最终有效输出区。
+
+## 区分实验
+
+构造无 padding 与有 padding、单通道与通道尾块、单 K 块与多 K 块、单位 stride 与边界 stride 的配对输入。若误差只在空间边界，先比较 padding/im2col；若按通道块周期重复，检查权重布局与尾块；若随 K 增长，检查累加 dtype 和合并顺序；搬入已错时不要先修改 MMAD。
+
+## 空间窗口与通道坐标 oracle
+
+对首错输出坐标 `(n, co, ho, wo)`，先由当前算子约定展开它实际依赖的输入窗口和权重坐标；stride、dilation、group 与 padding 都必须来自本次任务，而不是框架默认值。为输入有效区使用 `encode(n, ci, hi, wi)`，为权重使用不同量级的 `encode(co, ci, kh, kw)`，使 im2col 错位、权重错位和输出通道映射得到不同预测。编码必须在载体 dtype/范围内精确可表示，并在当前有效坐标域内无碰撞。还须证明卷积累加的最坏范围不会溢出，并在实验前用预测表确认各竞争映射会产生不同输出。只比较真实分配且允许观察的有效区；padding poison 还必须是接口语义允许的值。padding 未分配、不可写或 poison 不合法时不放哨兵，改用无 padding/有 padding 的成对 shape 与逻辑边界窗口 oracle。
+
+若只有输出图像四周错误而中心匹配，依次比较逻辑 padding 窗口 oracle（或真实可观察的对应 checkpoint）、首个边界窗口的 im2col 展开和相应 CO1 坐标。关闭 padding 后通过只支持“分叉依赖空间边界”，不能单独区分 padding 值、窗口映射或边界有效区。若误差按输出通道块周期重复，则同时冻结权重块、输出通道映射和通道尾块；数值集合相同但通道坐标错位优先保留布局候选，不先调整累加精度。
+
+### 从输出坐标反解窗口
+
+- **何时查**：首错集中在四周、只在非单位 stride/dilation 出现，或相邻输出点读取了看似正确但错位的输入值时，先查窗口坐标，不先查累加精度。
+- **查什么**：对每个探针输出 `(n, co, ho, wo)` 写出当前任务的 kernel 方向、group 映射和输入坐标等式。在常见的非翻转相关约定下，可用 `hi = ho * stride_h - pad_top + kh * dilation_h`、`wi = wo * stride_w - pad_left + kw * dilation_w` 建账；若任务约定会翻转 kernel、使用不同轴序或非对称 padding，就必须改写等式，不能硬套该示意。账本同时列出窗口内有效坐标与应走 padding 语义的坐标，并把每个贡献绑定到权重坐标。
+- **怎么证伪**：用单一输入坐标和单一权重坐标激活，预测它应影响的全部输出坐标；若 padding 后输入与展开矩阵逐项符合该依赖集合，而主计算后才分叉，就降低窗口/padding 候选。
+- **避免混淆**：关闭 padding 后恢复只能说明错误依赖边界，不能区分窗口公式、padding 值和有效区；具体 LoadData 参数、padding 行为与产品支持仍路由当前版本 API，缺证据时标 `UNKNOWN`。
+
+### Group、Dilation 与通道归属的正交实验
+
+- **何时查**：只有 `group > 1`、`dilation > 1`、某组输出通道或某个膨胀采样相位失败时查询。
+- **查什么**：从任务约定记录每个输出通道所属 group、该 group 可读取的输入通道集合、核内坐标与膨胀后的实际输入坐标；为不同 group、输入通道和核点配置互不碰撞的指纹。
+- **怎么证伪**：固定输出空间坐标，依次只激活同组通道、相邻组通道和一个 dilation 空洞中的坐标。若只有约定内贡献出现、跨组与空洞 control 均为零，且展开结果正确，则降低 group/dilation 映射候选；再增加参与项后才漂移应转向累加或合并。
+- **避免混淆**：按通道块周期错误也可能来自权重 layout、输出通道 tiling 或多核所有权；只有错误值能被 group/窗口坐标预测且首分叉位于展开边，才归到卷积坐标约定。
+
+## K 参与集合与增长实验
+
+卷积共享维由约定决定，通常可由输入通道和核窗口展开为若干贡献。用单块激活、多个完整块激活、尾段单独激活和全零 control 建立参与集合；每组保持输出窗口、权重布局和后处理不变。漏块会让对应唯一贡献消失，低精度累加更常表现为贡献都存在但偏差随参与项增加。这里的 tail 只指约定内逻辑有效 tail，不把物理补齐当贡献。两类现象都可能随共享维增长，只有局部 checkpoint 才能区分。单 K 块通过不能外推多块合并，尾段失败也不能在未验证 padding poison 是否进入计算前宣布是尾 K 参数。
+
+本页用阶段链、窗口 checkpoint、坐标编码、参与集合和预测表组织实验。接口签名、单位和产品支持使用 `ascendc-api-knowledge-query` 查当前原文；普通方法页或 CPU 行为不升级为强事实。Load3D 要核对 `padList`、`padValue`；对使用 `IsResetLoad3dConfig` 的重载，分别确认 `isSetFMatrix`、`isSetPadding` 是否让本次配置生效，或要求调用前另行设置状态。Mmad 与基础 Fixpipe 分别核对类型组合和 L0C→GM/UB/L1 通路。文档分支与当前头文件不一致时，保留两边来源并做最小实验。
+
+## 修复与回归边界
+
+依据具体代码问题、触发条件和致错机制实施修复，再按影响范围回归相关的空间/通道边界、layout、K 尺寸、group 与后处理组合。首次可见分叉或超差不自动等于根因；局部通过而后段失败时，按[逐层分析](../../diagnosis/progressive-error-analysis.md)区分新增差异与上游偏差传播。卷积、LoadData、MMAD 的精确参数与支持范围查询当前版本 API；本页不代表任何具体 Conv 实现已在当前 NPU 验证。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/operators/dynamic-quant.md

@@ -0,0 +1,47 @@
+---
+type: OperatorRisk
+title: 动态量化：统计范围、scale 角色与舍入边界
+description: 沿统计范围、scale 与 offset、浮点映射和输出回写，区分 DynamicQuant/V2 的精度异常。
+tags: [DynamicQuant, 量化, scale, 舍入]
+---
+
+# 动态量化：统计范围、scale 角色与舍入边界
+
+DynamicQuant / DynamicQuantV2 精度异常先沿“分组与可选平滑 → 极值统计 → 量化参数 → 浮点映射 → 舍入/饱和 → 输出与参数回写”定位首次分叉。逐输出检查 y、scale、offset；y 通过不能证明辅助参数正确，辅助参数误差很小也不能证明整数输出不变。
+
+本页提供固定来源支持的算子语义与调查方法。当前任务的合法输入、零范围处理、舍入和特殊值规则仍以其公开需求为准；不要把某个库实现的 epsilon、tiling 常量或输出类型范围复制成通用约定。
+
+## 先确认 scale 和 offset 表示什么
+
+`ops-nn` 的 DynamicQuant 定义每个 token 的对称量化，DynamicQuantV2 还定义非对称量化。若存在平滑系数，统计量和量化应基于算子定义的平滑后输入 u；按组选择平滑系数时，组映射也属于计算链。
+
+| 路径 | 固定来源中的计算关系 | 优先核对 |
+|---|---|---|
+| 对称量化 | s = max(abs(u)) / Q，y = round(u / s) | 返回的 s 是反量化步长；实现内部的乘数 k = 1/s 与 s 角色不同 |
+| 非对称量化 | s = (max(u) − min(u)) / (q_max − q_min)，z = q_max − max(u)/s，y = round(u/s + z) | offset 的符号、单位和加入位置；上下端点是否映射到对应整数端点 |
+
+这里 Q 和 q_min/q_max 来自目标输出约定。来源的 INT8 路径采用 Q=127、q_min=−128、q_max=127；其他格式应读取其自身定义。全零或常量行使 s 的普通公式退化，不能自行决定输出零、加 epsilon 或返回某个固定 scale；先查任务对该输入的规定。
+
+先用局部 oracle 分别比较极值、s、内部 k、z、舍入前浮点值和最终编码。`s = a/Q` 与 `s = 1/(Q/a)` 在实数域等价，FP32 逐步求值未必相同；是否允许差异由输出比较约定决定。变量名 `scale` 无法说明它在某段代码里表示步长还是乘数。
+
+## 从现象选择区分实验
+
+| 观察 | 有区分力的下一步 | 结果边界 |
+|---|---|---|
+| y 大体正确，scale 系统性偏离 | 固定极值和元素分布，逐段核对对外 s 与内部 k；加一组两者不会互相掩盖的极值 | 支持参数角色问题，不能因此排除尾部或其他输出错误 |
+| 非对称路径整体偏移 | 同一行保留最小/最大端点及中间值，检查 z 的单位、符号、舍入和饱和位置 | 端点检查可发现仿射关系错误，不能代替舍入边界回归 |
+| 少量整数差 1，scale 误差很小 | 选择映射后靠近半整数的输入，保持 shape、极值、dtype、tiling 不变；对比除法/倒数、乘法、Cast 前后的实际值 | 小的浮点扰动跨过舍入分界即可改变整数；不能由整数差 1 直接认定 Div 的误差方向 |
+| 最后几行或不同分核后异常 | 将失败行回映到 core、批内行、全局行及三路输出地址，核对每个合法行的计算和写回是否发生 | 先区分行覆盖、统计有效区、输出地址和算术；不要先扩大容差 |
+| padding 或尾轴变化后 scale 改变 | 固定所有有效元素，只改变无效区哨兵与尾轴分块，比较参与极值的元素集合 | 极值被无效区污染与输出尾行漏算是不同候选，需要不同观察点 |
+
+量化边界 probe 应复用正式输入量化与 materializer。想测试浮点映射的某个半整数邻域时，先确认输入经 FP16/BF16 存储后该邻域仍然存在，并且没有顺带改变行极值。若修改除法路径后恢复，还要确认内部参数真实变化及新路径采用；仅在 Host 用 k±1 ULP 重算，只能说明一种候选解释与输出相容。
+
+## API 路径与最终验证
+
+向量除法接口、精度配置以及 Vector/Scalar 交接的同步按实际 profile 查询 API。不能把“向量换标量后样本通过”概括成标量除法在所有输入上正确舍入，也不能为了精度把应由设备完成的量化转到 Host。
+
+原失败恢复后，按实际改动覆盖对称/非对称、参数退化、舍入/饱和边界、行与列尾部，以及可选平滑/分组中实际存在的路径。比较 y、scale、offset 的各自约定与必要联合关系；已有可构造的合法残差优先补最小 probe，再决定是否扩大回归。
+
+## 使用范围
+
+本页提供算法语义与实现分叉；具体工程仍须完成自身的 NPU 回归。半整数邻域的放大关系采用 FP32 数值模型，不代表某条设备除法指令的误差界。

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

@@ -0,0 +1,18 @@
+# 算子与实际计算链
+
+算子说明先固定数学 reference、I/O、dtype、layout、有效区和实际计算链，再路由版本 API。当前覆盖归约与自适应平均池化、广播/转置、排序/归并、Matmul/MMAD、Normalization、Convolution、动态量化与 Softplus 梯度。文中的 checkpoint 只是候选观察点；没有独立 oracle 时不能据此声称定位。
+
+## 资料导航
+
+按当前现象选择排查方法。具体 API 的产品、类型和版本限制使用 `ascendc-api-knowledge-query` 查询，示例代码和类似算子使用 `knowledge-query`；表中的提示帮助选择需要先核对的条件。
+
+| 资料位置 | 何时读 / 解决什么 | 使用提示 |
+| --- | --- | --- |
+| [归约算子族](reduction.md) | 核对参与元素、带索引布局、Atomic 状态及跨核合并；自适应平均池化直接查[小窗口对照](reduction.md#自适应平均池化的小窗口对照)。 | 先列参与元素与 count，再检查累加顺序 |
+| [广播与转置算子族](broadcast-transpose.md) | 核对逻辑广播与物理重排，并检查小通道补齐、有效输出和量化转换链。 | 区分逻辑广播与物理重排 |
+| [排序与归并算子族](sort-merge.md) | 核对有序范围、value/index、有效路与消耗计数、偏移单位、并列规则和 TopK 边界。 | 保留有效长度、并列规则和输出数量 |
+| [Matmul/MMAD 算子族](matmul-mmad.md) | 检查分组与分块、数据/scale 装载、转置、异步写回、HF32 及量化后处理。 | 区分基础指令、高阶接口与实际分块路径 |
+| [Softplus 梯度](softplus-v2-grad.md#按残余症状进入案例) | 按错值、repeat/tail、求值顺序、小量归零或属性复用直达已有案例支路；不代表产品 API 支持。 | 部分修好后按残差继续，不重跑全部候选 |
+| [Norm 算子族](normalization.md) | 核对方差、epsilon 与合并；统计 merge 错查[旧/新状态](normalization.md#统计状态的原地更新时序)，分母近似错查[迭代预算](normalization.md#倒数与开方的迭代预算)。 | 先确认统计输入，再检查分母与仿射输出 |
+| [Convolution 算子族](convolution.md) | 把卷积拆为 padding、im2col/LoadData、group/dilation 通道归属、K 参与集合、Cube/MMAD 累加和后处理；从输出坐标反解逻辑窗口并用单点激活证伪跨组或膨胀映射错误。 | 结合窗口、分组、padding 和搬出路径检查 |
+| [动态量化：统计范围、scale 角色与舍入边界](dynamic-quant.md) | DynamicQuant/V2 沿分组统计、scale 与倒数、offset、浮点映射、Cast/饱和和辅助参数写回定位；用半整数邻域区分小浮点误差如何改变整数输出。 | 分别核对统计范围、scale 角色与量化边界 |

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/operators/matmul-mmad.md

@@ -0,0 +1,131 @@
+---
+type: OperatorRisk
+title: Matmul/MMAD 算子族
+description: 沿矩阵乘与分组计算链，检查组间地址与缓冲复用、装载布局、K 分块参与、累加精度、HF32 模式和后处理。
+tags: [Matmul, MMAD, GMM, 分组地址, 缓冲复用, 累加精度, HF32]
+---
+
+# Matmul/MMAD 算子族
+
+## 数学与 reference
+
+C = A×B + bias；实际链路包含 GM/L1/L0 搬运、布局变换、K 维累加和输出搬出。
+
+冻结 batch、M/N/K、A/B 转置、bias/量化/激活、输入与累加 dtype、输出 layout 和有效区。reference 按实际 K 分块和后处理边界提供局部 oracle；高精度整式只用作数学参考，不能替代逐级累加比较。
+
+## I/O 与实际链路
+
+- 冻结输入/输出 shape、dtype、layout、有效区、padding 和 alias。
+- 从 host tiling、GM 搬入、局部计算、同步到 GM 搬出逐节点记录实际计算链，不以 API 名替代。
+- tiling 分支、多核分区、尾块与特殊值必须进入风险清单。
+
+## Grouped Matmul：先建分组账本，再看数值误差
+
+当普通单组 Matmul 正常，而错误从第二组开始、恰好落在 group 边界、空组会改变后续输出，或 per-token scale 像整体错移时查询本节。不要先把它归成“Cube 精度不足”；先为每组建立一行实际账本：
+
+| 字段 | 必须记录的实际值 |
+|---|---|
+| 逻辑 shape | `group_id, M_g, N_g, K_g`，以及 shape 来自 host tiling、group list 还是固定字段 |
+| A/B/C 视图 | dtype、layout、`transA/transB`、leading dimension、有效区和 padding |
+| 物理区间 | A/B/C 各自的 base、实际 allocation span、末地址；不能只写 `M*K/K*N/M*N` |
+| 分块 | `baseM/baseN/baseK`、M/N/K tile 数、首尾 tile 的真实有效量 |
+| 执行 | group 到 flat task/block 的映射、AIC/AIV 角色、workspace slot/epoch、最终 owner |
+| 后处理 | bias、channel scale、token scale、激活和输出 Cast 的索引公式与 dtype |
+
+把三张 prefix sum 分开计算：`A_base[g]=A0+sum(spanA[h], h<g)`、B 和 C 同理；shape prefix、存储 span prefix 和 task prefix 是三种不同量，不能共用一个 `offset`。对普通行主序 ND 的诊断模型，逻辑坐标可先写成：
+
+```text
+physA(g,i,k) = A_base[g] + (transA ? k*lda+i : i*lda+k)
+physB(g,k,j) = B_base[g] + (transB ? j*ldb+k : k*ldb+j)
+physC(g,i,j) = C_base[g] + i*ldc+j
+```
+
+这只是核对当前实现的坐标账本，不发布任何 API layout 约定。NZ/分形、batch、压缩或带 padding 存储必须换成对应版本的官方文档证明的物理 mapper；此时用逻辑元素数直接累加偏移属于反模式。即使 `M_g=0`，也要逐 tensor 判断该组是否仍拥有 weight/bias/scale 存储，不能统一把 A/B/C span 都清零。
+
+## GMM 的最小局部 oracle
+
+先缩成单 group、小 M/N/K、单个 K-block，并关闭或冻结 bias/量化/激活；用 A 的单行/单 K one-hot 配合 B 的单位基，令一个 `C[i,j]` 只有一个可精确表示的预期贡献。按 `A物理坐标 → Cube输入 → CO1/workspace → epilogue输入 → C物理坐标` 比较同一逻辑元素。该实验只能证明被激活 group、K-block、转置分支和输出坐标；不能证明第二组、尾组、空组、其它 K-block 或量化索引。
+
+然后每次只增加一个维度：第二个非空组、一个空组、M/N 尾块、第二个 K-block、transpose、非紧致 leading dimension、token scale，最后才恢复完整 epilogue。在已确认可反解的观察面，若来源位置相对预期位置的偏移差绝对值恰为前组实际 span，先核对偏移方向与元素/字节单位，再检查 prefix/leading-dimension；它是来源错位线索，不能单独区分错误地址与旧缓冲。若 CO1/workspace 正确而 Vector 后首次错，再查 scale 索引、workspace epoch 和 Cast。随机大 shape 一次通过不能反证这些边界问题。
+
+**组标记与机制区分**：输入编码可逆，不代表经过一般矩阵乘后的输出仍可反解；先确认所选观察面保留编码，必要时使用上面的 one-hot/单位基对照。即使能认出旧值来自哪组，也不能仅凭它判断为何读到了旧值。例如两组 `1×1` 矩阵乘，`B0=B1=1`、`A0=2`，把 `A1` 从 `3` 改成 `5`：错误读取组0的 GM 地址，与源地址正确但 workspace 仍保留组0结果，都可能使第二组输出 `2`。这些小整数只用于说明共享预测，不是实现常量或设备实测。
+
+下一步按缺口核对本轮实际使用的 GM 源地址、搬入完成后的值，以及 workspace 对应的组/轮次和写入、消费完成关系；已有适用观察可复用。只改第二组标记后仍见旧值，只能保留这些候选；需要区分时，再选择候选预测不同的中间观察或固定地址下的缓冲隔离对照，并核对干预是否改变了调度。不要把数值来源、偏移差和新旧混合写成互斥的故障分类。
+
+具体数组长度、offset 公式、分核公式、同步 flag 和量化 API 必须按当前实现与版本核对。使用 `ascendc-api-knowledge-query` 查当前 Matmul/Mmad 接口与样例；可变 `M/N/K` 的 GMM 约定、transpose/NZ span 和 leading-dimension 约束缺少该版本权威依据时保持 `UNKNOWN`。
+
+## 敏感 checkpoint
+
+按当前疑点选择少量相关观察点，说明 reference、CPU 或 NPU 观察面及所用参考或检查性质。缺少可靠局部 oracle 时可先保留原值或检查适用的不变量，无法判定的部分保留未知。选点和对照见[观察点设计](../../diagnosis/checkpoint-design.md)；已有可比误差且需要解释累积、放大或抵消时，再用[逐层分析](../../diagnosis/progressive-error-analysis.md)。
+
+可从 L1 输入、L0A/L0B 准备、首尾 K 块累加器、跨块合并和最终搬出中选能区分候选的位置，无需全链采集。使用非对称 M/N/K 和可逆矩阵模式暴露转置或 layout 错误；用小 K/大 K 和强消减输入区分参数、尾块与累加顺序。checkpoint 已错时先追查其输入与计算，修复位置由根因证据决定。
+
+## K-block 参与集合与分段定位
+
+按当前实现串起 `GM 输入 → A1/B1 → A2/B2 → CO1 → GM 输出` 的相关路径，在所选边界比较对应的逻辑数据；使用 `ascendc-api-knowledge-query` 取得目标版本的矩阵装载与 Matmul/Mmad 原文，再核对具体调用、布局和字段。
+
+- A1/B1：确认输入有效区是否完整进入 L1，并能由坐标编码反解回原逻辑位置。
+- A2/B2：按实际 ZZ/ZN/NZ 分形比较坐标，不把两个不同布局的线性 dump 直接逐元素相减。
+- CO1：用输入控制分别计算各 K-block 的预期贡献，再比较全部 block 同时参与时的结果。
+- GM：确认写回后的逻辑坐标、输出 dtype 和有效区；CO1 局部通过而 GM 失败时，先区分写回新增差异与前段偏差的放大，不能仅凭局部通过排除 Mmad 相关路径。
+
+当 K 被切成多个 block 时，先证明参与项集合，再讨论累加 dtype 或顺序。逐个只激活一个 K-block、其余 block 置零，并增加全部 block 同时激活和全零 control；各组使用非对称、可逆且能在载体 dtype 中精确表示的坐标编码。某一块的预测贡献消失，只能先把边界缩到该块的搬入、布局或参与集合，不能仅凭最终误差宣布 Mmad 精度不足。
+
+分段判断遵循以下顺序：A1/B1 首先异常时查 Nd2Nz 的 shape、stride 和 padding；A1/B1 正常而 A2/B2 异常时查 LoadData 的分形、transpose、repeat 和 stride；A2/B2 正常而 CO1 异常时查 `m/n/k`、C 初值、K-block 参与集合和合法 dtype 组合；CO1 正常而 GM 异常时查 Fixpipe 的 format、`m/n`、stride、量化和输出 dtype。有限数的布局与参与集合通过后再测试特殊值；NaN/Inf 的具体传播必须来自目标算子约定或独立 oracle，本页不定义该语义。
+
+## A/B 布局指纹与后处理隔离
+
+只用随机矩阵容易让 A、B 转置、分形错位和漏 K-block 得到相似的稠密误差。先设计能给竞争候选不同预测的输入：让 A 的单个逻辑行或 K 位置使用 one-hot/basis 模式，让 B 使用 identity 或非对称坐标编码，再交换两侧角色复测。每个编码值必须能在输入 dtype 中精确表示；对称矩阵或重复常量只能作为全零/全通 control，不能排除转置和错位。单位矩阵通过也只证明被激活的路径，不证明其他 K-block、尾块、bias 或输出布局。
+
+需要区分主计算与 epilogue 时，优先在原路径中比较 CO1 与相关后处理边界。关闭 bias、激活、量化、Cast 或写回转换属于实验干预，优先控制一项，并核对 overload、tiling、dtype 与布局的联动；一次关闭多项按组合观察解释。CO1 局部通过、后处理后首次超差时，先用实际 CO1 输入重放可信后处理，区分本段新增差异与上游偏差放大。局部容差通过或局部重放一致不能排除上游原因；后处理若能解释全部变化，应回查 K-block、累加精度或运算顺序。CO1 无法安全观察且没有等价局部边界时保留 `AMBIGUOUS`，不从最终输出反推它正确；关闭后处理后误差变小也不证明主计算正确。
+
+每次比较都记录 `逻辑坐标 → 当前存储级坐标 → 预期贡献`。首个 K-block、共享维后半段、最后完整块和约定允许的 tail 应分别有可区分输入；只有逐级存储边界显示某一贡献首次消失，才进入对应搬入、布局或参与集合候选。one-hot、坐标编码和分块激活用于区分候选；API 字段、布局支持表、对齐值与精度组合以当前版本 API 页为准。
+
+## 装载布局与 scale 配对
+
+换成 fp8/fp4 后出现 NaN、首个 N-segment 正常而后续出错，先分别推导数据与 scale 的地址。逻辑元素数、打包载体和字节数不是同一个单位；fp4 尤其不能把载体 sizeof 当作单个逻辑元素大小。逐个 K-pass、N-segment 记录两类地址与有效范围，使用 `ascendc-api-knowledge-query` 核对所用装载接口的字段单位。
+
+multi-head 只有奇数或偶数 head 异常时，分别比较单 head、双 head 的物理起点、容量和生命周期。数据与 scale 可能有不同的布局与打包方式；每一类都应独立推导偏移，不能因为症状相似就套某个 head-offset 公式。共享区还要检查上一 head 是否已经消费结束，见[多层分段状态](../mechanisms/tiling-tail-state.md#多层分段状态rowheadn-segment-与-k-pass)。
+
+UB→L1 的注册或同步异常，先确认目标产品支持当前接口，再分开核对数据搬运与通信。CANN 9.1 DataCopy_UBToL1_continuous 文档描述的 950PR/950DT SSBuffer 方式使用 SSBuffer 通信，数据经 UB→L1 硬件通道直搬；文档另说明经 Matmul workspace GM 中转并需 REGISTER_MATMUL 的路径。实际采用何种方式须结合 ENABLE_CV_COMM_VIA_SSBUF、执行形态与编译分支核对：配套源码中 SSBuffer 内部开关的推导及直搬分支均涉及 `__MIX_CORE_AIC_RATION__`，用户开关为 true 或 false 都不能单独证明通路。其他产品按对应支持范围与路径查原文，不支持的产品不能靠补注册获得能力。路径切换涉及工作区与同步变化，分别观察；注册成功不等于精度通过。ND2NZ 的补齐长度、零步长、b4 参数和转置连续性也按所用重载核对，保持逻辑有效 K。
+
+## 计算与写回中的常见分叉
+
+| 现象 | 先核对什么 |
+| --- | --- |
+| 改转置参数后整体错位 | 编译期转置能力、运行时请求、Host tiling 与真实布局是否匹配；支持转置不等于每次都转置 |
+| 异步写 UB 后偶发旧值 | 当前 GetTensorC/Iterate 路径是否完成了所需等待，再开始 Vector 消费；同时检查上一轮的回收 |
+| 输出全零或整块未更新 | Iterate 与结果获取是否配合，自管 CO1 路径是否实际搬出；零任务按原空输入语义处理 |
+| half 输入精度超差 | 区分内部累加和最终写回类型；基础 Mmad 的 310p AI Core/910 特定组合提示不能套到所有高阶 Matmul |
+| 只有 M=1、特定 K 或小块失败 | GEMV、K 对齐或相邻 Mmad 依赖是否改变实际路径；先展开调用与地址，不套历史阈值 |
+| CO1 正确、最终输出错位或变值 | Fixpipe 的目的布局、转换/量化与有效范围；特殊值按原输出要求比较 |
+
+使用 `ascendc-api-knowledge-query` 查实际矩阵计算接口的类型组合、异步完成与搬出规则。int8/int4/MX 路径分别核对累加、Bias、模式配置和写回类型，不能从最终 C 类型倒推内部计算。
+
+## HF32 与中间精度
+
+fp32 矩阵乘误差偏大时，可在其他条件不变的情况下关闭当前接口支持的 HF32 开关做对照。误差改善只支持精度路径相关的解释，还需比较局部输入输出、算法和实际生效状态，不能直接认定根因。Host、框架、Kernel 三处的配置要和每次局部参考一起记录；开关无效果时检查配置时机与上层覆盖。
+
+HF32 输入舍入的影响取决于输入分布、消减和实际计算链，不保证误差全局、平滑或随 K 单调增加，局部超差也不能排除 HF32。用局部矩阵模型看，A 为对角矩阵、B 为单位矩阵时，仅一个对角输入发生舍入即可只改变一个输出；这是算术反例，不是设备调用样例。结合实际控制状态与同输入开关对照取证，不用误差形态代替机制验证。
+
+需要用数值对照区分舍入模式时，按当前 API 的定义选取不同模式预测确实分叉的输入和观察点。例如就近偶数与就近远离零只在平局规则上不同，非平局样本的模型吻合不能唯一确认模式；可比较平局样本及其相邻可表示值，并核对后续累加和输出转换是否遮住差异。预舍入对照还需覆盖相关乘加语义，具体按[局部算术模型](../../diagnosis/numerical-modeling.md#局部算术模型)建立，不把 FP64 整式直接充作设备中间参考。
+
+使用 `ascendc-api-knowledge-query` 核对各 HF32 控制入口的枚举取值、关闭能力和执行形态，不能照搬 mode 数字。是否接受降精或改用另一计算路径，由原输出要求决定。
+
+HF32、SetMadType 和 C 接口的 asc_set_fp32_mode 分别确认使能方向和支持条件，不能按相似名称互换。CANN 9.1 SetMadType 中存在 HF32 枚举但标为暂不支持的说明；查询具体控制入口后，再用固定输入与局部观察确认模式真正生效。
+
+C 接口的 asc_mmad_mx 需跟踪 C 清零、初值选择与重复调用是否延续 L0C；asc_set_l0c2gm_config 等搬出配置可能继续执行量化、激活或格式转换。把这些状态放入现有 CO1→输出的观察链，不把最终输出类型当作内部精度。
+
+## GMM 的状态与量化后处理
+
+每组进入计算时核对实际 singleM/N/K。采用 `mList[0]==-1` 和 groupList 前缀的实现，组边界改变后仍用旧 M，可能使跨组行错位；按当前接口定义重建分组范围，不能把这套字段约定推广到所有 GMM。
+
+[GroupedMatmul 官方案例](https://gitcode.com/cann/asc-devkit/blob/e5451c7feba11f9e259f4fbc19c4bf82f8c0496c/docs/guide/算子实践参考/优秀实践/GroupedMatmul算子性能调优案例.md)面向 CANN 9.1.0 资料中的 Atlas A2 per-token 量化路径。整数中间类型、缓冲份数与核配比属于该例的组织方式。当前实现应分别确认 AIC 写完、AIV 开始读、AIV 消费结束和允许复用四个位置；缓冲少本身不证明有竞争，增加份数也不能替代同步。
+
+CO1/workspace 正确但后处理错误时，分别检查 channel scale、token scale 的逻辑索引和 Cast 时机。用两组不同的 scale 哨兵区分广播方向；整数结果过早转低精度后，信息可能在乘 scale 前就丢失。FP32 反量化或有序合并都需要保持原算法、溢出与验收要求；int32 方案仅用于已确认的整数累加路径，不把浮点 GMM 直接改成整数计算。
+
+GMM 更新时分别核对 SetSingleShape 的当前计算范围与 SetOrgShape 的物理组织，组间偏移不能只由同一个 M/N/K 三元组推导。同一对象复用还要确认上一组结果消费完成；官方案例中的 scale、累加类型和核配比仅适用于其自身场景。
+
+## 版本路由与边界
+
+矩阵装载与 Matmul/Mmad 的接口资料使用 `ascendc-api-knowledge-query` 获取。Mmad 参数、矩阵格式和对齐要求应根据所查官方页面并结合当前实现核对；本页不代表任一具体实现或 NPU case 已验证。