已合并
feat(knowledge): 新增 MMAD 与矢量/掩码接口边界值输入验收 Runbook #181
bianque创建于 10 天前
feat(knowledge): 新增 MMAD 与矢量/掩码接口边界值输入验收 Runbook #181
已合并
共 4 个文件变更+237-0
| @@ -214,3 +214,6 @@ | |||
| 214 | - [分核 partial 的初始化、参与者集合与最终归并](inter_core_reduction_contract.md)：用普通 UnsortedSegmentSum 的 int64 两阶段实现说明分片布局、空核和初始化顺序；按源码观察给出采用检查，不冒充修复轨迹或设备归因结果。 | 214 | - [分核 partial 的初始化、参与者集合与最终归并](inter_core_reduction_contract.md)：用普通 UnsortedSegmentSum 的 int64 两阶段实现说明分片布局、空核和初始化顺序；按源码观察给出采用检查，不冒充修复轨迹或设备归因结果。 |
| 215 | - [直接 DFT 的向量化轴、FP32 入口与缓冲预算](rfft_dft_vectorization_axes_and_buffer_budget.md)：从两份完整实现比较按输入位置归约与按频率 Lane 累加的依赖，并核对真实 FP32 入口、对齐长度和 InitBuffer 请求边界。 | 215 | - [直接 DFT 的向量化轴、FP32 入口与缓冲预算](rfft_dft_vectorization_axes_and_buffer_budget.md)：从两份完整实现比较按输入位置归约与按频率 Lane 累加的依赖，并核对真实 FP32 入口、对齐长度和 InitBuffer 请求边界。 |
| 216 | - [重复索引更新的目标行所有权](target_row_ownership_for_duplicate_indices.md)：在 dense 唯一 AIV 编号前提下，用目标行取模归属保证同一目标的更新由同一 owner 按输入顺序处理。 | 216 | - [重复索引更新的目标行所有权](target_row_ownership_for_duplicate_indices.md)：在 dense 唯一 AIV 编号前提下，用目标行取模归属保证同一目标的更新由同一 owner 按输入顺序处理。 |
| 217 | + | ||
| 218 | +- [Mmad 与 MmadMx 边界值输入验收与失败归类](mmad_boundary_value_input_acceptance.md)：Mmad/MmadMx 在 inf、nan、dtype 极值、零维与量化类型入参下的期望输出口径不同：两族加法阶段的正负 inf 相加结果相反，量化类型会在入参侧折叠 inf/nan。本卡给出按接口族与饱和模式分列的判定步骤、双 oracle 校验法与四类失败归因顺序；来源限定 Mmad 为 950/A3/A2、MmadMx 为 950。 | ||
| 219 | +- [Memory/Reg 矢量接口边界值输入验收（含原子操作与掩码）](vector_interface_boundary_value_acceptance.md)：Memory 与 Reg 矢量接口、原子操作、Mask 四份边界值来源的平台范围与表列口径各不相同：Memory/Reg 与原子按「INF/NAN 模式 / 饱和模式」双列，Mask 则只给 isSetMask 支持矩阵。本卡给出逐族取期望的判定步骤、按产品、模式和具体接口表取期望的校验法、Normal 连续/逐比特与 Counter 模式的区分，以及「先小数组后真实 shape」的验收顺序。 | ||
| @@ -0,0 +1,91 @@ | |||
| 1 | +--- | ||
| 2 | +type: Runbook | ||
| 3 | +title: Mmad 与 MmadMx 边界值输入验收与失败归类 | ||
| 4 | +description: Mmad/MmadMx 在 inf、nan、dtype 极值、零维与量化类型入参下的期望输出口径不同：两族加法阶段的正负 inf 相加结果相反，量化类型会在入参侧折叠 inf/nan。本卡给出按接口族与饱和模式分列的判定步骤、双 oracle 校验法与四类失败归因顺序；来源限定 Mmad 为 950/A3/A2、MmadMx 为 950。 | ||
| 5 | +tags: | ||
| 6 | +- task.testing | ||
| 7 | +- topic.precision | ||
| 8 | +- topic.programming_model.execution_unit.cube | ||
| 9 | +status: stable | ||
| 10 | +sources: | ||
| 11 | +- resource: cann-docs-raw/asc-devkit/docs/zh/api/appendix/mmad_interface_boundary_value_summary.md | ||
| 12 | + role: primary | ||
| 13 | +- resource: cann-docs-raw/asc-devkit/docs/zh/api/appendix/mmad_mx_interface_boundary_value_summary.md | ||
| 14 | + role: primary | ||
| 15 | +created_at: '2026-10-28T08:00:00Z' | ||
| 16 | +updated_at: '2026-10-28T08:00:00Z' | ||
| 17 | +platforms: | ||
| 18 | +- '950' | ||
| 19 | +- a3 | ||
| 20 | +- a2 | ||
| 21 | +--- | ||
| 22 | + | ||
| 23 | +# Mmad 与 MmadMx 边界值输入验收与失败归类 | ||
| 24 | + | ||
| 25 | +## 适用范围 | ||
| 26 | + | ||
| 27 | +- **接口族与平台不是同一集合**：`Mmad` 边界值汇总声明对 Ascend 950PR&950DT、Atlas A3、Atlas A2 生效；`MmadMx` 汇总只声明 Ascend 950PR&950DT。把 MmadMx 的条目用到 A2/A3，或反过来，都是越界推断。 | ||
| 28 | +- 适用任务：为 MMAD 类矩阵乘接口补特殊值用例、判定一次边界值失败是"输入越界/模式没开对"还是"实现缺陷"。 | ||
| 29 | +- **本卡来源只有两份 appendix 汇总**（见 `sources`）。接口约束、地址对齐、尺寸语义来自相邻接口卡，正文中按链接逐条标注，不并入本卡断言；对齐类条款不在本卡来源范围内。 | ||
| 30 | + | ||
| 31 | +## 第一个变量是"饱和模式"，不是"接口" | ||
| 32 | + | ||
| 33 | +两份汇总的表列口径并不相同，混读会直接算错期望值： | ||
| 34 | + | ||
| 35 | +- **Mmad 汇总只给 INF/NAN 模式（非饱和模式）一张表**，表注写明"INF/NAN 模式（非饱和模式）下……"。该表**没有**饱和模式列，饱和模式的输出不能从这张表推。 | ||
| 36 | +- **MmadMx 汇总同时给两张**：INF/NAN 模式边界值表，以及独立的「饱和模式边界值汇总」段落（先饱和再按数值计算）。 | ||
| 37 | +- 饱和开关属于控制寄存器/接口配置，不在本卡表格内；取值与默认值见 [SetSaturationFlag](../../apis/simd_api/basic_api/special_register_access/set_saturation_flag_isasi.md) 与 [Mmad](../../apis/simd_api/basic_api/cube_compute_isasi/mmad_compute/mmad.md) 的「特殊值/边界值约束说明」。验收时必须先记录本次用例跑的是哪种模式。 | ||
| 38 | + | ||
| 39 | +## 两族最容易互套错的一条：加法阶段的正负 inf | ||
| 40 | + | ||
| 41 | +| 场景（加法阶段） | Mmad 期望 dst | MmadMx 期望 dst | | ||
| 42 | +|---|---|---| | ||
| 43 | +| A=+inf，B=-inf | **nan** | **-inf** | | ||
| 44 | +| A=-inf，B=+inf | **nan** | **+inf** | | ||
| 45 | + | ||
| 46 | +两族在乘法阶段的口径一致（inf×非零→±inf、inf×0→nan、含 nan→nan、溢出按正负给 ±inf），**差异只在加法阶段**。因此跨接口复用期望值时，乘法点可以复用，加法点必须逐族重取。MmadMx 的这条与 IEEE 754 的"inf + (−inf) = nan"也不一致，不能用 IEEE 754 反推。 | ||
| 47 | + | ||
| 48 | +## 量化类型：inf/nan 在"入参侧"就被折叠 | ||
| 49 | + | ||
| 50 | +MmadMx 支持的低精度量化类型没有完整的 inf/nan 表示，边界值会先被换成有限数值，再去计算： | ||
| 51 | + | ||
| 52 | +- `fp4x2_e1m2_t` / `fp4x2_e2m1_t` 无 ±inf/nan 定义：+inf → `1.75` / `6`，−inf → `-1.75` / `-6`，nan → `0.0`。 | ||
| 53 | +- `fp8_e4m3fn_t` 只有 nan 定义、无 ±inf 定义：+inf / −inf 都被转换为 nan。 | ||
| 54 | + | ||
| 55 | +验收含义：如果用例在**入参侧**注入 inf 并期望输出 ±inf，量化类型下该期望本来就错——注入点先折叠，实际参与运算的是有限值。这类用例应按"入参折叠后"重新计算期望，而不是记为失败。 | ||
| 56 | + | ||
| 57 | +## 来源内部存在张力的一处：nan 输入 | ||
| 58 | + | ||
| 59 | +MmadMx 汇总的边界值表给出"nan 输入 → nan 输出"，但同一份来源的「边界值说明」又写"MmadMx 计算应避免 nan 输入，否则可能会产生执行报错"。二者不能同时当作无条件结论。验收取更严口径：**nan 输入不写成"必须正常输出 nan"的正向用例**；确需覆盖时按"允许报错"单独登记，并记录报错信息，不计入功能失败。 | ||
| 60 | + | ||
| 61 | +## 判定步骤（按序执行） | ||
| 62 | + | ||
| 63 | +1. **先判是不是 NOP**：按 [Mmad](../../apis/simd_api/basic_api/cube_compute_isasi/mmad_compute/mmad.md) 与 [MmadMx](../../apis/simd_api/basic_api/cube_compute_isasi/mmad_compute/mmad_mx.md) 的约束说明，M、K、N 任一为 0 时指令不执行（空操作）。K=0/N=0 用例的期望是"输出保持原值/不被改写"，不是"输出 0"；若 dst 被清零，先查是不是用例自己的预置或清零步骤造成的。 | ||
| 64 | +2. **再判模式**：确认饱和开关的实际状态，并与所用表列对齐。用 Mmad 表去核对饱和模式结果，或用 MmadMx 饱和段去核对 INF/NAN 模式结果，都会得到假失败。 | ||
| 65 | +3. **再判量化折叠**：确认 A/B 的实际 dtype。若为 `fp4x2_*` 或 `fp8_e4m3fn_t`，先把注入的 inf/nan 按上节折叠，再重算期望。 | ||
| 66 | +4. **再判尺寸/分形边界**：M/K/N 非 16 的倍数时，无效数据会占满分形空间但不参与计算（见 [Mmad](../../apis/simd_api/basic_api/cube_compute_isasi/mmad_compute/mmad.md) 约束说明）。期望值只按有效形状算；把无效区数值纳入比对会产生假失败。 | ||
| 67 | +5. **最后才判实现缺陷**：以上四项都排除后，才把"逐元素与表列期望不符"记为实现问题，并附上模式、dtype、M/K/N、注入点和期望来源条目。 | ||
| 68 | + | ||
| 69 | +## 验证方式 | ||
| 70 | + | ||
| 71 | +- **双 oracle**：期望值有两条独立来源——IEEE 754 与来源表列。两者冲突时以**表列为准**并按族记录（加法阶段正负 inf 即典型冲突点）。两族都一致的点，才可用 IEEE 754 批量生成期望。 | ||
| 72 | +- **单元素优先**：先在最小形状（能覆盖一个 16×16 分形的最低维度）上单点注入特殊值，确认该点行为后再放大。放大后若失败，差异必然来自 shape/分形/循环边界而非特殊值语义。 | ||
| 73 | +- **一模式一跑**：非饱和与饱和模式各跑一轮同一用例集，两轮结果分开归档；不要把两轮混在同一份通过率里。 | ||
| 74 | +- **对齐前置不在本卡**：地址对齐（dst L0C 1024B、A/B 512B、bias 64B）与 K 方向对齐开关 `kDirectionAlign`（仅 float 相关，`ceil(K/8)*8` 或 `ceil(K/16)*16`）见 [Mmad](../../apis/simd_api/basic_api/cube_compute_isasi/mmad_compute/mmad.md) 与 [K方向对齐约束](../../apis/simd_api/basic_api/cube_compute_isasi/mmad_compute_key_features/k_direction_alignment_constraint.md)。本卡只判定"边界值输入"，不判定对齐违规。 | ||
| 75 | + | ||
| 76 | +## 与相邻卡的分工 | ||
| 77 | + | ||
| 78 | +- 原文镜像：[Mmad 接口边界值汇总](../../apis/appendix/mmad_interface_boundary_value_summary.md)、[MmadMx 接口边界值汇总](../../apis/appendix/mmad_mx_interface_boundary_value_summary.md)（type=API，逐表原文）。本卡是判定流程与失败归因，不复制全部行。 | ||
| 79 | +- 尺寸/对齐/同步等接口约束在 [Mmad](../../apis/simd_api/basic_api/cube_compute_isasi/mmad_compute/mmad.md)、[MmadMx](../../apis/simd_api/basic_api/cube_compute_isasi/mmad_compute/mmad_mx.md) 与 [K方向对齐约束](../../apis/simd_api/basic_api/cube_compute_isasi/mmad_compute_key_features/k_direction_alignment_constraint.md)；本卡不重复其参数表。 | ||
| 80 | +- 饱和开关语义见 [SetSaturationFlag](../../apis/simd_api/basic_api/special_register_access/set_saturation_flag_isasi.md)；本卡只用它区分模式，不展开各 `SaturationMode` 的适用范围。 | ||
| 81 | +- 用例构造侧限制：[TTK 取值域仅整张量语义，单元素NaN/Inf注入用例壳不物化](ttk_value_range_no_single_element_nan_inf_injection.md) 说明单元素注入在 TTK 下不物化。本卡的"单元素优先"需走 `manual_input_binaries` 或 C++ ST。 | ||
| 82 | +- 参考值生成本身会溢出：[case_gen 极端量级分布产 overflow/underflow 参考值](case_gen_extreme_magnitude_distributions_overflow_refs.md) 是 golden 侧问题；本卡是接口侧期望口径。 | ||
| 83 | +- 实现侧 inf 传播陷阱（算法引入 inf−inf）见 [Two-Product split 遇 inf 产 NaN 破坏 inf 传播](../precision/two_product_split_inf_nan_pollution.md)，与本卡的接口期望判定互补。 | ||
| 84 | + | ||
| 85 | +## 失效边界 | ||
| 86 | + | ||
| 87 | +- 本卡所有期望值来自固定提交中的两份 appendix 汇总，**本卡未做硬件实测**；表值是**文档值**，不是实测上限。 | ||
| 88 | +- Mmad 的饱和模式输出**不在本卡来源内**（该汇总只给 INF/NAN 模式表）：饱和模式验收必须回到接口卡与 `SetSaturationFlag`，不能引用本卡表格。 | ||
| 89 | +- 上述例外（inf×0、inf+(−inf)）与"溢出按正负取 ±inf"是该两份汇总的声明；接口若另有备注，以接口卡为准。 | ||
| 90 | +- 平台范围按族限定：Mmad 为 950/A3/A2，MmadMx 仅 950。MmadMx 条目不可外推到 A2/A3。 | ||
| 91 | +- 本卡不覆盖 dtype 转换（Cast）过程中的边界值行为，也不覆盖 Fixpipe 搬出阶段的量化饱和。 | ||
| @@ -0,0 +1,115 @@ | |||
| 1 | +--- | ||
| 2 | +type: Runbook | ||
| 3 | +title: Memory/Reg 矢量接口边界值输入验收（含原子操作与掩码） | ||
| 4 | +description: Memory 与 Reg 矢量接口、原子操作、Mask 四份边界值来源的平台范围与表列口径各不相同：Memory/Reg 与原子按「INF/NAN 模式 / 饱和模式」双列，Mask 则只给 isSetMask 支持矩阵。本卡给出逐族取期望的判定步骤、按产品、模式和具体接口表取期望的校验法、Normal 连续/逐比特与 Counter 模式的区分，以及「先小数组后真实 shape」的验收顺序。 | ||
| 5 | +tags: | ||
| 6 | +- task.testing | ||
| 7 | +- topic.implementation.masking | ||
| 8 | +- topic.alignment | ||
| 9 | +- topic.precision | ||
| 10 | +status: stable | ||
| 11 | +sources: | ||
| 12 | +- resource: cann-docs-raw/asc-devkit/docs/zh/api/appendix/memory_vector_compute_interface_boundary_value_summary.md | ||
| 13 | + role: primary | ||
| 14 | +- resource: cann-docs-raw/asc-devkit/docs/zh/api/appendix/reg_vector_compute_interface_boundary_value_summary.md | ||
| 15 | + role: primary | ||
| 16 | +- resource: cann-docs-raw/asc-devkit/docs/zh/api/appendix/atomic_operations_interface_boundary_value_summary.md | ||
| 17 | + role: supporting | ||
| 18 | +- resource: cann-docs-raw/asc-devkit/docs/zh/api/appendix/Mask_interface_summary.md | ||
| 19 | + role: supporting | ||
| 20 | +created_at: '2026-10-28T08:00:00Z' | ||
| 21 | +updated_at: '2026-10-28T08:00:00Z' | ||
| 22 | +platforms: | ||
| 23 | +- '950' | ||
| 24 | +- a3 | ||
| 25 | +- a2 | ||
| 26 | +--- | ||
| 27 | + | ||
| 28 | +# Memory/Reg 矢量接口边界值输入验收（含原子操作与掩码） | ||
| 29 | + | ||
| 30 | +## 适用范围 | ||
| 31 | + | ||
| 32 | +四份来源的平台声明不是同一个集合，**不能把任一份的行套到另一份的平台上**： | ||
| 33 | + | ||
| 34 | +| 来源 | 声明生效平台 | 覆盖内容 | | ||
| 35 | +|---|---|---| | ||
| 36 | +| Memory 矢量边界值汇总 | Atlas A3、Atlas A2 | 各类 Memory 矢量接口的双模式边界值表，另含一张"输出 inf/nan 场景总结" | | ||
| 37 | +| Reg 矢量边界值汇总 | Ascend 950PR&950DT | 各类 Reg 矢量接口的双模式边界值表，**无**汇总场景表，直接按接口族分节 | | ||
| 38 | +| 原子操作边界值汇总 | Atlas A3、Atlas A2 | SetAtomicAdd / SetAtomicMax / SetAtomicMin 三张双模式表 | | ||
| 39 | +| Mask 接口汇总 | Atlas A3、Atlas A2 | 各接口 `isSetMask` 模板参数支持情况矩阵 | | ||
| 40 | + | ||
| 41 | +本卡判定"边界值输入下的期望输出与验收顺序"；精度档位、denormal、ulp 与软仿差异另有专卡（见分工）。**source 未涉及 denormal/subnormal**，本卡不写该口径。 | ||
| 42 | + | ||
| 43 | +## 第一步：先确定跑的是哪种模式 | ||
| 44 | + | ||
| 45 | +Memory 矢量、Reg 矢量、原子操作三份来源都按同一套二分给出结果，但列名和覆盖程度不同： | ||
| 46 | + | ||
| 47 | +- **INF/NAN 模式（非饱和模式）**：计算结果为 inf / -inf / nan 时按原样输出；**输出为整数时**，有限的超范围数值按目标类型位数截断、保留低位。 | ||
| 48 | +- **饱和模式**：inf 和 -inf 被饱和为 MAX 和 MIN 输出，nan 被饱和为 0 输出；输出为整数时，超范围有限值被饱和为目标类型的最大值/最小值。 | ||
| 49 | +- 饱和模式按数据类型分类设置（`SaturationMode::FLOAT` / `INT` / `CAST` / `FLOAT8` 等），各模式影响的类型与默认开关不同，见 [SetSaturationFlag](../../apis/simd_api/basic_api/special_register_access/set_saturation_flag_isasi.md)。Memory 与 Reg 汇总对此只写"按数据类型分类设置，请参考该接口"；原子操作汇总则直接给出 INF/NAN 与饱和两列。 | ||
| 50 | +- 来源明确声明：**绝大部分场景下 INF/NAN 模式输出与 IEEE 754 一致，不一致会在对应接口处备注**。该说明须在对应来源和接口范围内使用，不为其他族提供统一 oracle。 | ||
| 51 | + | ||
| 52 | +## 第二步：oracle 用三步法，不要单靠 IEEE 754 | ||
| 53 | + | ||
| 54 | +1. **先定位产品、接口族、dtype 与模式的来源条目**。仅当对应来源明确声明时，才用 IEEE 754 生成非饱和浮点期望；不能对所有 Reg 接口设置统一默认。 | ||
| 55 | +2. **核对该族的汇总表与具体接口表**。Memory 汇总有一张"浮点数计算输出 inf/nan 的场景"表，列出的例外包括：`exp(-inf)=0`；`inf * 0 = nan`；`inf + (-inf) = nan`；非 nan 且非 0 的值除以 0（如 Div / Sqrt / Reciprocal 一类）得到 inf；`ln(0.0) = -inf`、`ln(-0.0) = -inf`；`rsqrt(0.0) = inf`、`rsqrt(-0.0) = -inf`；`(-inf) - (-inf) = nan`。另注：nan 不区分正负，inf 区分正负。 | ||
| 56 | +3. **再逐接口查备注**：来源把"与 IEEE 754 不一致"的披露责任放在具体接口条目上。只按 1、2 两步批量套，遇到有备注的接口会得到假失败。 | ||
| 57 | + | ||
| 58 | +注意 Reg 汇总**没有**这张汇总例外表——它的例外只能在各接口族的表内逐条看到。把 Memory 的例外表当成两族共用，会漏掉 Reg 侧接口级差异。 | ||
| 59 | + | ||
| 60 | +## 第三步：把"掩码"拆成三层再判 | ||
| 61 | + | ||
| 62 | +**(a) 接口形态**：`isSetMask` 的支持矩阵按「Tensor 前 n 个数计算」与「Tensor 高维切分计算」两种形态分列，同一接口在两种形态下可能一个是"有 isSetMask"、另一个是"无 isSetMask"。表中 `-` 表示**不存在该类型接口**，既不是"不支持"也不是"未声明"。该矩阵只对 Atlas A3/A2 声明。 | ||
| 63 | + | ||
| 64 | +**(b) 设置方式**：分为接口内已设置 Mask（内部调用 SetMaskCount / SetVectorMask / SetMaskNorm / ResetMask）、由模板参数控制（`isSetMask=true` 接口内设置；`false` 由调用方在接口外设置）、以及接口不支持或无需设置 Mask 三类。逐接口归属见 [Mask 接口汇总](../../apis/appendix/mask_interface_summary.md)。 | ||
| 65 | + | ||
| 66 | +**(c) 两个易错点**： | ||
| 67 | +- **"有 isSetMask 但不起作用"**：Compare 与 Select 的高维切分形态即属此类。这类接口不能靠外部 `SetVectorMask` 改变参与计算的元素；Select 要在外部设掩码，须改用不传 mask 参数的重载。 | ||
| 68 | +- **全 1 与全 0 不对称**：`ResetMask` 把 mask 恢复为默认值**全 1**，语义是"每次迭代内所有元素都参与运算"（见 [ResetMask](../../apis/simd_api/basic_api/memory_vector_compute/mask_operations/reset_mask.md)）。全 0 掩码的专门行为在四份来源中**均无条款**，本卡不给出期望值，需按目标接口文档另行确认。 | ||
| 69 | + | ||
| 70 | +## 第四步：区分"元素数"与"逐比特" | ||
| 71 | + | ||
| 72 | +这不是同一个参数的两种叫法，而是**先选模式、再选含义**： | ||
| 73 | + | ||
| 74 | +- **Counter 模式**（[SetMaskCount](../../apis/simd_api/basic_api/memory_vector_compute/mask_operations/set_mask_count.md)）：mask 表示**整个矢量计算参与计算的元素个数**；此模式不需要开发者感知迭代次数、也不需要处理非对齐尾块，迭代次数由 Vector 单元自动推断。 | ||
| 75 | +- **Normal 模式**（[SetMaskNorm](../../apis/simd_api/basic_api/memory_vector_compute/mask_operations/set_mask_norm.md)）：系统默认模式，支持开发者配置迭代次数。该模式下 mask 有**两种含义**（[SetVectorMask](../../apis/simd_api/basic_api/memory_vector_compute/mask_operations/set_vector_mask.md)）： | ||
| 76 | + - **连续模式**：前面连续多少个元素参与计算。取值范围随操作数位宽变化：16 位 `[0,128]`、32 位 `[0,64]`、64 位 `[0,32]`。 | ||
| 77 | + - **逐比特模式**：按位控制，bit=1 参与。16 位时 maskHigh/maskLow ∈ `[0,2^64-1]` 且不同时为 0；32 位时 maskHigh=0、maskLow ∈ `[0,2^64-1]`；64 位时 maskHigh=0、maskLow ∈ `[0,2^32-1]`。 | ||
| 78 | + | ||
| 79 | +验收含义：**来源推荐使用 Counter 模式处理长度非对齐与尾块**（把元素总数直接传入，由硬件推断迭代），并非所有接口的强制要求。手动管理须先确认目标重载允许 `isSetMask=false`，计算后恢复 Normal 模式。若实现选了 Normal 模式，尾块边界就变成实现责任，必须单独构造尾块用例。 | ||
| 80 | + | ||
| 81 | +## 第五步：原子操作先预置 dst 再判定 | ||
| 82 | + | ||
| 83 | +- 三张表分别对应 SetAtomicAdd / SetAtomicMax / SetAtomicMin，各给 INF/NAN 模式与饱和模式两列；表注写明**INF/NAN 模式列结果与 IEEE 754 理论结果一致**。 | ||
| 84 | +- 饱和模式的折叠是：inf → MAX、-inf → MIN、nan → 0，其中 MAX/MIN 是该数据类型的最大值/最小值（表中 half 为 `65504.0` / `-65504.0`；例如 `-inf + inf` 在非饱和模式为 nan、在饱和模式为 `0.0`）。 | ||
| 85 | +- **来源三张表的 src/dst 数据类型全部是 half**。因此本卡可断言的边界值口径仅限 half；float、整数等类型不在来源范围，不得据此外推。 | ||
| 86 | +- 原子语义是"新值与 dst 已有值合成"，所以用例**必须先把 dst 预置成已知边界值并在执行后读回**；否则"预置写错"与"原子计算错"在同一次失败里无法区分。跨块累加还要固定块划分，保证每次读回的 dst 只受一个累加序列影响。 | ||
| 87 | + | ||
| 88 | +## 验收顺序（先小后大，逐级锁定变量） | ||
| 89 | + | ||
| 90 | +1. **最小 shape + 全有限已知值**：锁定 strides、offset、起始地址与读写范围。 | ||
| 91 | +2. **最小 shape + 单点特殊值，非饱和模式**：按对应族、dtype、模式和具体接口表取期望（第二步），不能将 Memory 汇总表套到 Reg。此级只应有"表格口径"这一类期望。 | ||
| 92 | +3. **同用例开饱和模式重跑**：期望改为 ±MAX / 0 折叠，结果与第 2 级分开归档，不合并通过率。 | ||
| 93 | +4. **放大到真实 shape**：此时失败应归因到 shape/分形/循环，而非特殊值语义；尾块按 Counter 模式或显式尾块路径单独覆盖。 | ||
| 94 | +5. **跨块原子累加**：预置 dst → 执行 → 读回，仅改变块划分重复一轮，确认结果与块顺序无关（或与来源声明的顺序要求一致）。 | ||
| 95 | +6. **掩码矩阵抽检**：全 1（ResetMask 默认）、连续 n、逐比特组合各一条；对"有 isSetMask 但不起作用"的接口单独登记，不记为失败。 | ||
| 96 | + | ||
| 97 | +## 与相邻卡的分工 | ||
| 98 | + | ||
| 99 | +- 原文镜像：[Memory 矢量边界值汇总](../../apis/appendix/memory_vector_compute_interface_boundary_value_summary.md)、[Reg 矢量边界值汇总](../../apis/appendix/reg_vector_compute_interface_boundary_value_summary.md)、[原子操作边界值汇总](../../apis/appendix/atomic_operations_interface_boundary_value_summary.md)、[Mask 接口汇总](../../apis/appendix/mask_interface_summary.md)（type=API，逐表原文）。本卡是判定流程，不复制数据表。 | ||
| 100 | +- [Reg 矢量接口硬件精度与软仿精度差异](../precision/reg_vector_hardware_vs_soft_simulation_precision.md)：那张卡解**精度档位 / denormal / ulp / 软仿路径**；本卡解**特殊值输入下的输出口径**。前者的 denormal 结论不能替代本卡的 inf/nan 判定，反之亦然。 | ||
| 101 | +- 掩码 API 语义在 [SetVectorMask](../../apis/simd_api/basic_api/memory_vector_compute/mask_operations/set_vector_mask.md)、[SetMaskCount](../../apis/simd_api/basic_api/memory_vector_compute/mask_operations/set_mask_count.md)、[SetMaskNorm](../../apis/simd_api/basic_api/memory_vector_compute/mask_operations/set_mask_norm.md)、[ResetMask](../../apis/simd_api/basic_api/memory_vector_compute/mask_operations/reset_mask.md)；本卡只用它们解释 mask 含义，不重复参数表。 | ||
| 102 | +- 饱和开关的取值、默认值与数据类型归类见 [SetSaturationFlag](../../apis/simd_api/basic_api/special_register_access/set_saturation_flag_isasi.md)；原子接口本身见 [SetAtomicAdd](../../apis/simd_api/basic_api/atomic_operations/set_atomic_add.md)、[SetAtomicMax](../../apis/simd_api/basic_api/atomic_operations/set_atomic_max_isasi.md)、[SetAtomicMin](../../apis/simd_api/basic_api/atomic_operations/set_atomic_min_isasi.md)。 | ||
| 103 | +- 尾块与对齐的搬运侧口径：[完整块与安全尾块分开选搬运路径](aligned_tile_copy_safe_tail.md)；本卡的尾块判据是 Counter 模式的元素数语义，两者互补。 | ||
| 104 | +- 单元素特殊值注入的框架限制：[TTK 取值域仅整张量语义](ttk_value_range_no_single_element_nan_inf_injection.md) 说明该注入在 TTK 下不物化；本卡第 2 级需改用 `manual_input_binaries` 或 C++ ST。 | ||
| 105 | +- 掩码参数掩盖真实错误码：[aclnn ST 掩盖 execute 错误码](aclnn_st_masks_execute_error_code_probe.md)；本卡判期望值，那张卡判错误码可见性。 | ||
| 106 | +- 大累加项数的精度越阈：[fp16 大累加项数跨实现 MERE 越阈边界](../precision/fp16_large_term_accumulation_cross_golden_boundary.md)；本卡只判边界值输出，不判跨实现精度阈值。 | ||
| 107 | + | ||
| 108 | +## 失效边界 | ||
| 109 | + | ||
| 110 | +- 本卡所有期望值来自固定提交中的四份 appendix 汇总，**本卡未做硬件实测**；表值是**文档值**。 | ||
| 111 | +- 平台范围按来源逐族限定（Memory、原子、Mask 为 A3/A2；Reg 为 950）。跨族搬用条目即越界。 | ||
| 112 | +- **denormal / subnormal 与地址对齐在四份来源中均无条款**：本卡不写这两类口径。对齐类问题应查接口卡；尾块口径来自 `SetMaskCount` 的 Counter 模式说明，不是来自边界值汇总。 | ||
| 113 | +- 原子表仅覆盖 half；float 与整数类型的边界值期望不在本卡来源内。 | ||
| 114 | +- 全 0 掩码无来源条款，本卡不给期望值。 | ||
| 115 | +- 饱和模式的默认开关因 `SaturationMode` 与数据类型而异，若用例未显式设置，实际模式可能与假设不同；每次判定都要先记录实际开关状态。 | ||
| @@ -28,6 +28,34 @@ SIMT 理论值的单位是“单个 Vector Core 每 cycle 元素数”，且只 | |||
| 28 | - 导航：按 `knowledge_ingest.py sync-indexes` 同步各级 `index.md`。 | 28 | - 导航：按 `knowledge_ingest.py sync-indexes` 同步各级 `index.md`。 |
| 29 | - 检查：`bash check.sh`（全库 Lint、索引同步、检索门禁、单测、Ruff、Shell 语法）。 | 29 | - 检查：`bash check.sh`（全库 Lint、索引同步、检索门禁、单测、Ruff、Shell 语法）。 |
| 30 | 30 | ||
| 31 | +## [15:40] knowledge | 新增 Mmad 与 MmadMx 边界值输入验收与失败归类 | ||
| 32 | + | ||
| 33 | +### Summary | ||
| 34 | + | ||
| 35 | +Mmad/MmadMx 在 inf、nan、dtype 极值、零维与量化类型入参下的期望输出口径不同：两族加法阶段的正负 inf 相加结果相反，量化类型会在入参侧折叠 inf/nan。本卡给出按接口族与饱和模式分列的判定步骤、双 oracle 校验法与四类失败归因顺序；来源限定 Mmad 为 950/A3/A2、MmadMx 为 950。 | ||
| 36 | + | ||
| 37 | +### Details | ||
| 38 | + | ||
| 39 | +- 处理决定：create。写卡前已检索同主题，确认无重复入口。 | ||
| 40 | +- 路径：`knowledge/ops/ascendc/runbooks/validations/mmad_boundary_value_input_acceptance.md`（Runbook）。 | ||
| 41 | +- 来源：`resource: cann-docs-raw/asc-devkit/docs/zh/api/appendix/mmad_interface_boundary_value_summary.md`；`role: primary`；`resource: cann-docs-raw/asc-devkit/docs/zh/api/appendix/mmad_mx_interface_boundary_value_summary.md`；`role: primary` | ||
| 42 | +- 导航：按 `knowledge_ingest.py sync-indexes` 同步各级 `index.md`。 | ||
| 43 | +- 检查：`bash check.sh`（全库 Lint、索引同步、检索门禁、单测、Ruff、Shell 语法）。 | ||
| 44 | + | ||
| 45 | +## [15:40] knowledge | 新增 Memory/Reg 矢量接口边界值输入验收（含原子操作与掩码） | ||
| 46 | + | ||
| 47 | +### Summary | ||
| 48 | + | ||
| 49 | +Memory 与 Reg 矢量接口、原子操作、Mask 四份边界值来源的平台范围与表列口径各不相同：Memory/Reg 与原子按「INF/NAN 模式 / 饱和模式」双列，Mask 则只给 isSetMask 支持矩阵。本卡给出逐族取期望的判定步骤、按产品、模式和具体接口表取期望的校验法、Normal 连续/逐比特与 Counter 模式的区分，以及「先小数组后真实 shape」的验收顺序。 | ||
| 50 | + | ||
| 51 | +### Details | ||
| 52 | + | ||
| 53 | +- 处理决定：create。写卡前已检索同主题，确认无重复入口。 | ||
| 54 | +- 路径：`knowledge/ops/ascendc/runbooks/validations/vector_interface_boundary_value_acceptance.md`（Runbook）。 | ||
| 55 | +- 来源：`resource: cann-docs-raw/asc-devkit/docs/zh/api/appendix/memory_vector_compute_interface_boundary_value_summary.md`；`role: primary`；`resource: cann-docs-raw/asc-devkit/docs/zh/api/appendix/reg_vector_compute_interface_boundary_value_summary.md`；`role: primary`；`resource: cann-docs-raw/asc-devkit/docs/zh/api/appendix/atomic_operations_interface_boundary_value_summary.md`；`role: supporting`；`resource: cann-docs-raw/asc-devkit/docs/zh/api/appendix/Mask_interface_summary.md`；`role: supporting` | ||
| 56 | +- 导航：按 `knowledge_ingest.py sync-indexes` 同步各级 `index.md`。 | ||
| 57 | +- 检查：`bash check.sh`（全库 Lint、索引同步、检索门禁、单测、Ruff、Shell 语法）。 | ||
| 58 | + | ||
| 31 | ## [14:38] validate | 完成 PR143 检视修订与最新目标的提交前验证 | 59 | ## [14:38] validate | 完成 PR143 检视修订与最新目标的提交前验证 |
| 32 | 60 | ||
| 33 | ### Summary | 61 | ### Summary |