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

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/scenario-extension-guide.md

@@ -0,0 +1,84 @@
+# Blaze 定制扩展场景接入指导
+
+本文只用于新增或维护 `/ascendc-blaze-best-practice` 自身的定制扩展场景，不属于普通算子任务的 Step 1--4 阅读路径。运行普通算子任务时不要读取本文。
+
+## 1. 最小接入单元
+
+新增场景只提交一个高内聚单元：
+
+```text
+references/scenarios/<scenario-id>/
+  <scenario-id>-design.md
+  <scenario-id>-development.md
+  <optional focused references>
+references/scenarios/index.md 中一个注册项
+```
+
+当前只支持唯一命中一个定制场景，不支持多个场景组合。除非能证明通用合同无法表达，新增场景不得修改 Step 2、Step 3 或 Step 4 的流程骨架；与现有场景的准入条件可能同时满足时必须收窄边界，否则让 Step 3 输出多命中 `unsupported`。
+
+## 2. 先定义需求语义边界
+
+1. 使用稳定、唯一、kebab-case 的 `scenario_id`，不包含版本、芯片快照或 Blaze 组装方案名称。
+2. 定义支持范围，且在同一范围中明确排除的语义；只引用 Step 3 需求合同中可观察的语义，不引用 Blaze 源码文件名、Asset、候选优劣或设备结果。
+3. 定义全部准入条件；每项都必须能由精确需求合同判断，并且不能与现有场景同时满足。
+4. 证明它不是 Basic、Batch、Grouped、Quantized、MX、layout、transpose 或 shape 等纯 MatMul 维度；详细不支持边界和用户恢复路径写入场景设计指导。
+
+## 3. 编写场景设计指导
+
+场景设计指导必须声明：
+
+```text
+scope and exclusions
+required Step 3 contracts
+required Blaze source facts from the Investigation report
+whether matmul_base_analysis or another common analysis is consumed
+how each prerequisite is checked
+one generic Step 2 supplement-question format
+dependency Skill loading gates
+design decisions and evidence boundaries
+consumed/preserved/replaced/added contracts
+interface, Kernel, resource, data, synchronization and validation outputs
+customization authorization
+unsupported boundary and return targets
+```
+
+Step 2 不读取注册表或任何场景文档。场景不能通过修改 Step 2、要求固定场景 bundle 或令 Step 2 感知场景 ID 来获得调查事实。发现前提缺失时，设计指导只允许提出一次无场景名的补充问题：问题须描述需求语义、待确认的 Blaze 源码关系、影响 requirement IDs 和有限源码读取前沿。
+
+场景是否消费 Step 3 的 Blaze 官方库分析由自己定义。若不消费 `matmul_base_analysis`，不得把它列为必需输入。设计指导只能在 Step 3 的 DESIGN 冻结前读取，不能把开发动作塞入 DESIGN，也不能把选择留给 Step 4。
+
+## 4. 编写场景开发指导
+
+开发指导是 Step 3 在 DESIGN 冻结后编译项目 PLAN 的方法输入，必须提供：
+
+```text
+plan inputs and implementation_route=blaze_custom condition
+required readings and dependency loading rules
+ordered action rules and prerequisites
+target file rules and implementation constraints
+build/Tiling/Launcher/data/Golden wiring rules
+validation checkpoints and deliverables
+cleanup and rollback
+```
+
+开发指导只定义可实例化的方法和条件分支，不写某个项目的固定 Blaze 组装方案、dtype、shape、slot、ratio、文件清单或验证次数。Step 3 必须把激活要求展开到 PLAN 的 `scenario_guidance_compliance`、`reading_manifest`、`ordered_actions`、checkpoint 和交付件；Step 4 不直接解释开发指导。
+
+## 5. 注册合同
+
+在 [场景索引](index.md) 增加唯一一行：
+
+1. 填写稳定且唯一的场景 ID、支持范围、全部准入条件、设计指导链接和开发指导链接。
+2. 支持范围必须同时说明支持语义和明确排除的语义；准入条件只使用 Step 3 需求合同可判断的信息。
+3. 依赖 Skill、调查前提、合同依赖、定制范围、不支持边界、维护规则和验证要求只写入场景设计/开发指导，不写入索引。
+4. 不新增 JSON、marker、schema、场景 bundle、预匹配、支持状态或路线状态字段，也不维护第二份目录表。
+
+## 6. 接入验证
+
+至少验证：
+
+- 索引行的场景 ID 唯一，支持范围和准入条件非空，设计/开发链接均可访问；
+- 正例唯一命中，范围外语义不命中；与每个已启用场景的重叠用例产生明确 `unsupported`；
+- Step 2 不读取注册表、设计指导、开发指导或依赖 Skill；
+- Step 3 仅在官方 Blaze 方案存在 `native_gaps` 时读取注册表，并按 `design -> DESIGN -> development -> PLAN` 顺序加载；
+- 场景源码前提缺失时只产生一次无场景名补充调查，不生成可执行 PLAN；
+- Asset、官方源码和未注册 custom 层未被授权；
+- Markdown 链接、Skill 校验和 `git diff --check` 通过。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/weight-dequant-prologue-fusion/layout-variant-boundary.md

@@ -0,0 +1,76 @@
+# Layout 支持范围与不支持边界专题
+
+本文是本场景的 Layout/变体边界专题。Step 3 用它设计支持域和拒绝域；DESIGN 冻结后，Step 3 用它编译 PLAN 的边界验证。本文不提供固定 Layout recipe。
+
+## 1. 输入与输出合同
+
+输入：`matmul_base_analysis`、Investigation 中已闭合的 Layout Pattern 事实、当前 Prologue/BlockMmad witness。输出：
+
+```text
+supported_layout_contract
+unsupported_boundary_contract
+layout_validation_additions
+```
+
+## 2. 当前支持范围
+
+DESIGN 必须基于 Investigation 确认的源码事实冻结支持范围。当前参考支持域（以 Asset 为结构起点，实际由 Investigation 确认）：
+
+| 维度 | 支持 | Layout Pattern | 说明 |
+|---|---|---|---|
+| A Layout | ND | `NDExtLayoutPtn` | transA=false |
+| A Layout | DN | `DNExtLayoutPtn` | transA=true |
+| A Layout | NZ | `NZLayoutPtn` | 分形变体 |
+| B Layout | ND | `NDExtLayoutPtn` | transB=false |
+| B Layout | DN | `DNExtLayoutPtn` | transB=true |
+| C Layout | ND（行主序） | `NDExtLayoutPtn` | 输出 |
+| transB | true / false | — | 影响分形轴（N 或 K）和 AIV 切分方向 |
+| hasOffset | true / false | — | 影响 VF 分支和 UB 布局 |
+| hasBias | true / false | — | 影响 BT 路径和 L1 空间 |
+
+## 3. 当前不支持边界
+
+以下变体当前不支持，DESIGN 必须记录不支持原因和恢复路径：
+
+| 变体 | 支持状态 | 条件/原因 | 恢复路径 |
+|---|---|---|---|
+| int8 weight | 已验证（产线+skill） | 默认支持 | — |
+| fp8_e4m3fn / fp8_e5m2 weight | 已验证 | Cast 链（fp8→float→bf16/half）经编译+精度验证通过 | 见 [VF 反量化链路专题](prologue-vf-dequant-design.md) §3.1 |
+| pergroup 量化 | 不支持 | 当前只支持 perchannel（scale/offset 按 N 维广播） | 需扩展 Prologue 循环结构和 Tiling |
+| StreamK / Full-load | 不支持 | Tiling 仅提供 SWAT 流式路径 | 需新增 Scheduler 和 Tiling Engine |
+| Weight-Quant + Vector Epilogue 后融合 | 不支持 | Epilogue 固定为 void（直写 GM） | 需在 Kernel 中扩展 Epilogue 模板参数 |
+
+## 4. 互斥性声明
+
+本场景与 `elementwise-broadcast-epilogue-fusion` 场景互斥：
+
+| 对比维度 | 本场景（weight-dequant-prologue） | elementwise-broadcast-epilogue |
+|---|---|---|
+| 数据流方向 | V+C（AIV 先反量化 → AIC 后 MMAD） | C+V（AIC 先 MMAD → AIV 后处理） |
+| Vector 位置 | MMAD 之前（Prologue） | MMAD 之后（Epilogue） |
+| 自定义层 | BlockMmad(替换) + Kernel(替换) + Prologue(新增) | Epilogue(新增) |
+| 同时命中 | 不可能：同一需求不能既是"先 Vector 后 MatMul"又是"先 MatMul 后 Vector" | 同左 |
+
+如果需求同时包含 V+C prologue 和 C+V epilogue，则两个场景都不唯一命中，Step 3 输出 `unsupported`。
+
+## 5. 与纯 Quantized MatMul 的区分
+
+本场景不属纯 Quantized MatMul（A8W8/MX）范畴。区分依据：
+
+| 对比维度 | 纯 Quantized MatMul | 本场景（weight-dequant-prologue） |
+|---|---|---|
+| 量化路径 | Blaze 原生 scale 路径（A8W8/MX） | AIV 侧反量化 prologue |
+| B 输入 | Blaze 支持的低比特格式 | int8 权重，需 device 侧反量化 |
+| Blaze 覆盖 | `Blaze::Gemm` 原生支持 | Blaze 无此入口（native_gap） |
+| 路线 | blaze_native | blaze_custom |
+
+## 6. 验证门禁
+
+- 支持范围内的每种 Layout/transpose/hasOffset/hasBias 组合均有验证用例；
+- 不支持边界有明确的拒绝条件和错误信息；
+- transB=true 和 transB=false 的分形轴对齐约束分别验证；
+- NZ A Layout 的分形变体路径闭合；
+- 与 elementwise 场景的互斥性通过跨场景用例验证；
+- 官方源码区与 Blaze Asset 原文件保持零改动。
+
+具体 Layout Pattern、dtype 和 shape 组合来自 DESIGN/PLAN 和当前 Investigation，不由本文固定。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/weight-dequant-prologue-fusion/pitfalls-and-diagnosis.md

@@ -0,0 +1,124 @@
+# 常见陷阱与精度诊断专题
+
+本文是本场景的验证方法与诊断专题。Step 3 用它设计验证合同并编译 PLAN；Step 4 以 PLAN 初始验证基线为起点，按实际失败证据读取本文并执行诊断。本文不提供固定 case 数或固定阈值。
+
+## 1. 基线合同
+
+每个项目在 DESIGN/PLAN 中冻结：
+
+```text
+logical_inputs_and_seed
+physical_conversion_and_packing
+formula_and_dtype_order
+shape/layout/transpose/hasOffset/hasBias partitions
+actual blockShape and Tiling
+CPU golden
+atol/rtol/nonfinite gate
+required negative/positive comparisons
+repeat policy
+```
+
+阈值由需求和数值合同决定；必须全元素通过且拒绝非有限值。Golden 必须使用与 VF 指令行为一致的计算精度（如 PyTorch bf16 运算），不得使用 C++ fp32 模拟替代。
+
+## 2. 隔离模式
+
+所有模式使用同一逻辑输入、物理转换、Tiling 记录和 Golden，只改变 DESIGN 声明的隔离变量：
+
+| 模式 | 隔离目标 | 必须记录 |
+|---|---|---|
+| A-only-MMAD | AIC 侧 MMAD（使用预反量化 B_dequant 作为输入） | 真实 GM 分支/等价路径、C Golden、MMAD 证据 |
+| Dequant-only | AIV 侧反量化（零 MMAD，验证 VF Cast 链） | 零 C 生成方式、B_dequant 输出、V Golden |
+| Full | 完整 V+C（AIV 反量化 + AIC MMAD） | 全公式、CV 同步、reuse、final drain、重复回归 |
+
+未激活的模式必须在 DESIGN 说明 N/A 依据。A-only 不证明 VF Cast 链；Dequant-only 不证明 MMAD；单独通过模式不替代 Full。
+
+## 3. 最早失败域
+
+| 最早失败 | 责任域 | 优先核对 |
+|---|---|---|
+| Dequant-only 失败 | AIV Prologue | Cast 链 dtype 顺序、CastTrait 声明、UB 布局、scale/offset 加载 |
+| Dequant-only 通过且 A-only 失败 | AIC BlockMmad | B_dequant layout 一致性、L1 布局、K 循环、L0C/Fixpipe |
+| 前两项通过且 Full 失败 | V+C 协作 | CV 同步时序、flag 预置/残留、L1 buffer 覆盖、final drain |
+| 特定 transB/hasOffset/hasBias 组合失败 | 边界条件 | 分形轴对齐、UB 空间约束、bias 类型一致性 |
+
+结论必须附首错位置和对应 source/device evidence。
+
+## 4. 常见陷阱诊断线索
+
+以下陷阱来自历史开发经验，作为诊断线索而非根因结论。每个陷阱必须在当前 Investigation/DESIGN 上下文中重新验证：
+
+| # | 陷阱 | 症状 | 诊断方向 |
+|---|---|---|---|
+| 1 | CastTrait 用 `constexpr` 而非 `static constexpr` | VF 函数内 CastTrait 作为 NTTP 时编译失败 | 检查 CastTrait 声明形式与源码一致 |
+| 2 | `biasGmPtr` 用 `CType*` 而非 `BiasType*` | `CopyGM2L1` 类型检查失败 | 检查 GM/L1/BT 三处 bias 类型一致 |
+| 3 | `biasL1Offset_` 用 `sizeof(CType)` 而非 `sizeof(BiasType)` | L1 bias 空间不足 | 检查 Tiling `biasElemBytes` 与 `sizeof(BiasType)` 一致 |
+| 4 | transB=true 时 N 方向尾轮切分 | `CeilDiv` 不保证 16 对齐，破坏分形边界 | 检查 Tiling 中 transB=true 时禁止 N 方向尾轮切分 |
+| 5 | Mask 类型与操作数类型不匹配 | 设备挂死或输出错乱 | Cast 用源类型 mask；Add/Mul/StoreAlign 用操作数类型 mask（见 [VF 反量化链路专题](prologue-vf-dequant-design.md) §5.2） |
+| 6 | StoreAlign 的 dataBlockStride 是 16 的倍数 | AIV Vec 性能下降 48%~62%（bank 冲突） | 将 outerAxisSize 从 `kUbLen`/`nUbLen` 改为 `+1`（见 [UB 布局专题](prologue-ub-layout-design.md) §6） |
+| 7 | UB→L1 用 Te::Copy 而非 copy_ubuf_to_cbuf（bank padding 后） | layout stride 无法描述 +1 padding，L1 数据错位 | 改用 copy_ubuf_to_cbuf 显式指定 srcGap=1 |
+
+陷阱的诊断结论必须通过单变量负/正对照确认，不得仅凭症状推断根因。
+
+## 5. Golden 合同
+
+CPU Golden 必须与设备使用相同的公式和 dtype 顺序。Cast 链因 B dtype 不同而异，Golden 必须匹配：
+
+```text
+# int8: int8 → half → bf16 (两步)
+B_dequant = (Cast<int8→half→bf16>(B) + offset_bf16) * scale_bf16
+
+# fp8_e4m3fn: fp8 → float → bf16 (两步)
+B_dequant = (Cast<fp8→float→bf16>(B) + offset_bf16) * scale_bf16
+
+# fp8_e4m3fn: fp8 → float32 → bfloat16 (匹配设备 Cast 链路)
+B_dequant = (Cast<fp8→float→bf16>(B) + offset_bf16) * scale_bf16
+
+# 所有 dtype 的 MatMul 部分:
+C = A_bf16 → fp32 @ B_dequant → fp32 → bf16
+```
+
+关键约束：
+1. Golden 的反量化必须使用与 VF 指令行为一致的计算精度（如 PyTorch bf16 运算），不得使用 fp32 模拟；
+2. MatMul 累加使用 fp32（与 L0C 累加一致），最终输出转回 bf16；
+3. offset 缺省时 Golden 跳过 Add（与 `if constexpr` 编译期分支一致）；
+4. Golden 由 PLAN 指定的 host/Python 逻辑生成；C++ Launcher 只执行设备 Kernel，不现场计算 Golden。
+
+PyTorch Golden 代码片段参考：
+
+```python
+# int8: int8 → float16 → bfloat16 (两步 Cast, 匹配设备链路)
+B_half = B.to(torch.float16)
+B_bf16 = B_half.to(torch.bfloat16)
+
+# fp8_e4m3fn: fp8 → float32 → bfloat16 (匹配设备 Cast 链路)
+B_f = B.to(torch.float32)
+B_bf16 = B_f.to(torch.bfloat16)
+
+# 反量化 (Add offset → Mul scale, bf16 精度)
+B_dequant = (B_bf16 + offset_bf16) * scale_bf16
+
+# MatMul (fp32 累加 → bf16 输出)
+C = A_bf16.to(torch.float32) @ B_dequant.to(torch.float32)
+C_bf16 = C.to(torch.bfloat16)
+```
+
+## 6. 单变量负向/正向
+
+对每个候选根因建立：
+
+```text
+baseline_id
+changed_variable
+negative_reproduction
+positive_recovery
+affected_boundary_cases
+full_repeat_result
+```
+
+只移除一个变量（CastTrait 声明、bias 类型、L1 offset、尾轮切分等）；不能把多个改动一起作为根因。只有负向稳定失败、正向稳定恢复、相关边界和清理后 Full 都通过，才能将结论写成 `device_verified`；否则为 `unverified`。
+
+## 7. 清理与交付门禁
+
+交付前必须删除 PLAN 和 `execution_record` 中记录的诊断注入、故障开关、Dump 和临时输出；清理后重新构建，并执行 DESIGN 声明范围内的隔离模式、边界、transB/hasOffset/hasBias 组合和 Full 重复回归。
+
+最终记录：实际输入/shape/dtype/layout、Tiling/blockShape、错误统计、非有限值、source/device evidence、支持/未验证范围和清理状态。只有清理后 required checkpoints 全部通过，PLAN 才能标记交付完成。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/weight-dequant-prologue-fusion/prologue-ub-layout-design.md

@@ -0,0 +1,135 @@
+# Prologue UB 布局与空间约束专题
+
+本文是本场景 Prologue 层的 UB 内存规划专题。Step 3 用它设计 Prologue delta 中的 UB 布局合同；DESIGN 冻结后，Step 3 用它编译对应 PLAN action；Step 4 只有在 PLAN 将本文绑定到当前 action 时才读取。本文不选择 Blaze 组装方案，也不提供固定 UB recipe。
+
+## 1. 输入与输出合同
+
+输入：`matmul_base_analysis`、Investigation 中已闭合的 UB 容量事实、反量化公式合同和当前 Tiling 参数。输出：
+
+```text
+ub_layout_contract
+ub_space_constraint
+ub_lifecycle_contract
+ub_validation_additions
+```
+
+每个结论必须引用当前候选组装方案评估、witness 和 evidence IDs。
+
+## 2. UB ping-pong 布局合同
+
+Prologue 在 AIV 侧使用 UB 进行反量化。DESIGN 必须冻结 UB 的双 buffer ping-pong 布局：
+
+| 对象 | 必填合同 |
+|---|---|
+| bIn | 输入 B 的低比特 dtype（int8, 1B）、每个 buffer 的 N×K 元素数、ping-pong 双 buffer |
+| bOut | 反量化后 B_dequant 的 dtype（bf16, 2B）、每个 buffer 的 N×K 元素数、ping-pong 双 buffer |
+| scale | perchannel scale 的 dtype、shape `(N,)`、每个 half 各一份的加载策略 |
+| offset（可选） | perchannel offset 的 dtype、shape `(N,)`、每个 half 各一份的加载策略 |
+
+DESIGN 必须回答：
+
+1. 每个 half 内 bIn/bOut/scale/offset 的排列顺序和字节范围；
+2. scale/offset 的加载时机（首轮 K-L1 迭代加载，后续迭代复用）；
+3. ping-pong buffer 的切换时机和与 K-L1 迭代的对应关系；
+4. 每个 buffer 内低比特输入和 bf16/fp16 输出的共存约束。
+
+## 3. UB 空间约束合同
+
+DESIGN 必须冻结 UB 空间约束公式。公式必须按当前 B dtype 参数化，不得硬编码 int8 系数：
+
+```text
+2 * (weightElemBytes + dequantBElemBytes) * kUbSize * nUbSize + 2 * dequantBElemBytes * nUbSize * (1 + hasOffset) <= UB_SIZE
+```
+
+其中：
+- `weightElemBytes = sizeof(BType)`：B 权重输入字节数（int8/fp8=1B）
+- `dequantBElemBytes = sizeof(DequantBType)`：B_dequant 字节数（bf16/fp16=2B，= scale/offset 字节数）
+- `2 * (weightElemBytes + dequantBElemBytes)`：bIn 和 bOut 各 2 个 buffer 的每元素字节数
+- `2 * dequantBElemBytes`：scale 的 2 个 buffer；offset 同理（仅 hasOffset=true 时计入）
+- `kUbSize`：单 AIV 单 buffer 的 K 方向元素数
+- `nUbSize`：单 AIV 单 buffer 的 N 方向元素数
+
+int8/fp8 时系数 = `2×(1+2)=6`。
+
+PLAN 必须验证当前 Tiling 参数满足此约束。约束不满足时调整 kUbSize/nUbSize 或返回 Step 3 重新选择 Tiling 合法值。
+
+## 4. UB 生命周期合同
+
+DESIGN 必须冻结每个 UB 区域的生命周期：
+
+| 区域 | 生产者 | 消费者 | 生命周期 |
+|---|---|---|---|
+| bIn[buf] | GM→UB DataCopy | VF 反量化 | 从 DataCopy 完成到 VF 消费完成 |
+| bOut[buf] | VF 反量化写入 | UB→L1 DataCopy | 从 VF 写入完成到 L1 搬运完成 |
+| scale[buf] | GM→UB DataCopy | VF Mul | 从加载到该 half 最后一次 K-L1 迭代 |
+| offset[buf] | GM→UB DataCopy | VF Add | 从加载到该 half 最后一次 K-L1 迭代 |
+
+ping-pong buffer 的覆盖前等待通过 HardEvent 同步保证。DESIGN 必须确认同步事件配对闭合，不得依赖 UB 隐式时序。
+
+## 5. 验证门禁
+
+- UB 空间约束公式在当前 Tiling 参数下满足；
+- ping-pong buffer 的切换与 K-L1 迭代对齐，无数据竞争；
+- scale/offset 的加载时机正确（仅首轮加载，后续复用）；
+- hasOffset=false 时 UB 布局正确排除 offset 区域；
+- UB 区域的字节边界和对齐满足 DataCopy 要求；
+- 官方源码区与 Blaze Asset 原文件保持零改动。
+
+具体 kUbSize、nUbSize、hasOffset 和 UB_SIZE 来自 DESIGN/PLAN 和当前环境事实，不由本文固定。
+
+## 6. UB Bank 冲突优化
+
+### 6.1 Bank 冲突原理
+
+UB 共 16 个 bank，每 32 字节为一个 DataBlock，bank 索引 = `DataBlock索引 % 16`。`StoreAlign<T, DATA_BLOCK_COPY>` 一次写 256 字节 = 8 个 DataBlock。当 `dataBlockStride % 16 == 0` 时，8 个 DataBlock 全映射到同一 bank，需 8 个 cycle 完成而非 1 个 cycle，导致 StoreAlign 吞吐降为 1/8。
+
+### 6.2 修复方法
+
+将 `dataBlockStride`（即 VF 函数的 `outerAxisSize`）从外轴元素数改为**外轴元素数 + 1**，使 8 个 DataBlock 分布到不同 bank：
+
+```text
+outerAxisSize = (transB ? nUbLen : kUbLen) + 1
+```
+
+### 6.3 Padding 方向
+
+padding 加在外轴方向：
+
+| transB | 分形格式 | 外轴 | padding 方向 | outerAxisSize |
+|---|---|---|---|---|
+| false | NZ | K | K+1 | kUbLen + 1 |
+| true | ZN | N | N+1 | nUbLen + 1 |
+
+### 6.4 UB Buffer 大小调整
+
+`bOutOneBuffer_` 必须包含 padding 空间：
+
+- transB=false: `(kUbSize + 1) * nUbSize * sizeof(DequantBType)`
+- transB=true: `kUbSize * (nUbSize + 1) * sizeof(DequantBType)`
+
+`bInOneBuffer_` 不需要 padding（bIn 是低比特输入，不通过 StoreAlign 写出）。
+
+### 6.5 UB→L1 搬运改用 copy_ubuf_to_cbuf
+
+padding 后，UB 中数据的物理 stride 与 NZ/ZN layout 描述的 stride 不一致（layout 的 stride 是 16 对齐的，无法描述 +1）。因此不能用 `Te::Copy(CopyUB2L1)`（它从 layout 自动计算 srcGap），必须用底层 `copy_ubuf_to_cbuf` 显式指定参数：
+
+```text
+copy_ubuf_to_cbuf(dst, src, sid, nBurst, lenBurst, srcGap, dstGap)
+  dst:      L1 目标地址
+  src:      UB 源地址
+  sid:      stream id, 固定为 0
+  nBurst:   外轴 burst 数（外轴 16-group 数）
+  lenBurst: 每个 burst 的 DataBlock 数（内轴连续 DataBlock 数, 32B/个）
+  srcGap:   相邻 burst 间在 UB 中跳过的 DataBlock 数（bank conflict padding = 1）
+  dstGap:   相邻 burst 间在 L1 中跳过的 DataBlock 数（L1 对齐 padding）
+```
+
+NZ（transB=false，外轴=N, 内轴=K）：
+- `nBurst = CeilDiv(nUbLen, 16)`，`lenBurst = kUbLen`，`srcGap = 1`，`dstGap = CeilAlign(curKL1, 16) - kUbLen`
+
+ZN（transB=true，外轴=K, 内轴=N）：
+- `nBurst = CeilDiv(kUbLen, 16)`，`lenBurst = nUbLen`，`srcGap = 1`，`dstGap = CeilAlign(curN, 16) - nUbLen`
+
+### 6.6 性能影响
+
+bank 冲突修复后，AIV Vec 时间降低 48%~62%（StoreAlign 写入吞吐提升 8 倍）。整体 Task Duration 的改善取决于 AIC MAC 是否为瓶颈——当 AIC MAC 占主导时整体改善有限，小 shape 或 AIV 成为瓶颈时效果更显著。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/weight-dequant-prologue-fusion/prologue-vf-dequant-design.md

@@ -0,0 +1,213 @@
+# VF 反量化链路专题
+
+本文是本场景 Prologue 层的 VF 反量化链路专题。Step 3 用它设计 Prologue delta 中的 VF Cast 合同；DESIGN 冻结后，Step 3 用它编译对应 PLAN action；Step 4 只有在 PLAN 将本文绑定到当前 action 时才读取。本文不选择 Blaze 组装方案，也不提供固定 VF recipe。
+
+## 1. 输入与输出合同
+
+输入：`matmul_base_analysis`、Investigation 中已闭合的 VF/Cast API 事实、反量化公式合同和当前 dtype 约束。输出：
+
+```text
+vf_dequant_contract
+cast_chain_contract
+vf_validation_additions
+```
+
+每个结论必须引用当前候选组装方案评估、witness 和 evidence IDs。历史 `source_observed`/`device_verified` 只有在 Investigation、Blaze 组装方案、构建和测试范围一致时才能复用；否则标记 `unverified`。
+
+## 2. 反量化公式合同
+
+DESIGN 必须冻结以下反量化语义：
+
+```text
+B_dequant[i,j] = (B[i,j] + offset[j]) * scale[j]
+```
+
+| 对象           | 必填合同                                                                       |
+| -------------- | ------------------------------------------------------------------------------ |
+| B 输入         | 低比特 dtype（int8/fp8）、逻辑/物理 shape、layout、perchannel 量化模式         |
+| Cast 中间值    | 每步 Cast 的输入/输出 dtype、精度语义、执行域；按 BType 分支选择中间寄存器类型 |
+| scale          | dtype（bf16/fp16）、shape`(N,)`、perchannel 加载方式、广播映射               |
+| offset         | dtype、shape`(N,)`、可选语义、缺省为 0 的条件                                |
+| B_dequant 输出 | dtype（bf16/fp16）、写入 L1 的 layout 和生命周期                               |
+
+offset 存在时先 Add 后 Mul；offset 缺省时跳过 Add 分支。公式顺序、dtype 转换链和舍入行为必须与 CPU Golden 完全一致。
+
+## 3. Cast 链合同
+
+VF 反量化在 AIV 侧执行，使用 `__simd_vf__` 执行域。DESIGN 必须按当前 B 输入 dtype 和目标 B_dequant dtype 冻结 Cast 链。下表汇总当前已验证的 cast 链路（CANN 9.1.0 / dav-3510）：
+
+| B dtype → B_dequant dtype | Cast 步骤                   | 中间寄存器类型         | 验证状态         |
+| -------------------------- | --------------------------- | ---------------------- | ---------------- |
+| int8 → bf16               | 两步：int8→half→bf16      | RegTensor<half>  | ✅ 编译+精度通过 |
+| int8 → fp16               | 一步：int8→half            | —                     | ✅ 编译+精度通过 |
+| fp8_e4m3fn → bf16         | 两步：fp8_e4m3→float→bf16 | RegTensor<float> | ✅ 编译+精度通过 |
+| fp8_e4m3fn → fp16         | 两步：fp8_e4m3→float→half | RegTensor<float> | ✅ 编译+精度通过 |
+| fp8_e5m2 → bf16           | 两步：fp8_e5m2→float→bf16 | RegTensor<float> | ✅ 编译+精度通过 |
+| fp8_e5m2 → fp16           | 两步：fp8_e5m2→float→half | RegTensor<float> | 编译通过，同链路 |
+
+### 3.1 Cast 链路实践参考
+
+以下为各 dtype 的实际实现方式，供 Investigation 和 DESIGN 参考。**这些不是固定 recipe**——具体 API 参数（CastTrait/LoadDist/StoreDist）应从当前 CANN 源码确认。
+
+#### int8（8bit→16bit）
+
+- LoadDist：`DIST_UNPACK_B8`（每字节展开为 16-bit slot `[byte, 0]`）
+- Cast 链：int8→half 直接（目标 fp16）；int8→half→bf16 两步（目标 bf16，硬件不支持 int8→bf16 直转）
+- 注意点：当目标为 bf16 时，int8 需经 half 中转
+
+#### fp8_e4m3fn / fp8_e5m2（8bit→32bit→16bit，拆合模式）
+
+`DIST_UNPACK_B8` 将每个 fp8 字节展开为 16-bit slot `[byte, 0]`。由于 fp8→float 是 8bit→32bit 转换，需要用两种 RegLayout 分别提取偶数和奇数 lane 的 fp8 值到两个 float 寄存器，再经 float→bf16 的两种 RegLayout 分拆到两个 bf16 寄存器，最后用 `Or` 合并为一个密集 bf16 寄存器。
+
+**CastTrait 配置：**
+
+| CastTrait                    | RegLayout | SatMode     | MaskMergeMode | RoundMode      | 用途                           |
+| ---------------------------- | --------- | ----------- | ------------- | -------------- | ------------------------------ |
+| `castTraitFp8ToFP32_ZERO`  | `ZERO`  | `UNKNOWN` | `ZEROING`   | `UNKNOWN`    | fp8→float, 提取偶数 lane      |
+| `castTraitFp8ToFP32_TWO`   | `TWO`   | `UNKNOWN` | `ZEROING`   | `UNKNOWN`    | fp8→float, 提取奇数 lane      |
+| `castTraitFP32ToBF16_ZERO` | `ZERO`  | `NO_SAT`  | `ZEROING`   | `CAST_RINT` | float→bf16, even 16-bit slots |
+| `castTraitFP32ToBF16_ONE`  | `ONE`   | `NO_SAT`  | `ZEROING`   | `CAST_RINT` | float→bf16, odd 16-bit slots  |
+
+**Mask 类型规则：** mask 类型必须与 Cast 的**源操作数类型**一致。fp8→float Cast 用 `CreateMask<uint8_t>`；float→bf16 Cast 用 `CreateMask<float>`；Or/Add/Mul/StoreAlign 用 `CreateMask<DequantBType>`。
+
+```cpp
+MaskReg maskAll = CreateMask<uint8_t, MaskPattern::ALL>();      // fp8→float Cast 用
+MaskReg maskFp32 = CreateMask<float, MaskPattern::ALL>();       // float→bf16 Cast 用
+MaskReg maskBf16 = CreateMask<DequantBType, MaskPattern::ALL>(); // Or/Add/Mul/StoreAlign 用
+
+**`Or` 的 `bfloat16_t` 限制：** `Or` 的 `static_assert` 不包含 `bfloat16_t`，需 `reinterpret_cast` 为 `RegTensor<uint16_t>&` 调用。
+
+**VF 函数完整调用序列：**
+
+```cpp
+// 寄存器声明
+RegTensor<BType> regBIn;
+RegTensor<float> regFp32A, regFp32B;      // 偶数/奇数 lane 的 float 中间值
+RegTensor<DequantBType> regBf16A, regBf16B; // even/odd 16-bit slots 的 bf16
+RegTensor<DequantBType> regBOut;           // 合并后的密集 bf16
+RegTensor<DequantBType> regScale, regOffset;
+MaskReg maskAll = CreateMask<uint8_t, MaskPattern::ALL>();   // fp8→float Cast 用
+MaskReg maskFp32 = CreateMask<float, MaskPattern::ALL>();    // float→bf16 Cast 用
+MaskReg maskBf16 = CreateMask<DequantBType, MaskPattern::ALL>(); // Or/Add/Mul/Store 用
+
+// CastTrait 声明（static constexpr，作为 NTTP 传入 Cast）
+static constexpr CastTrait castTraitFp8ToFP32_ZERO = {
+    RegLayout::ZERO, SatMode::UNKNOWN, MaskMergeMode::ZEROING, RoundMode::UNKNOWN};
+static constexpr CastTrait castTraitFp8ToFP32_TWO = {
+    RegLayout::TWO, SatMode::UNKNOWN, MaskMergeMode::ZEROING, RoundMode::UNKNOWN};
+static constexpr CastTrait castTraitFP32ToBF16_ZERO = {
+    RegLayout::ZERO, SatMode::NO_SAT, MaskMergeMode::ZEROING, RoundMode::CAST_RINT};
+static constexpr CastTrait castTraitFP32ToBF16_ONE = {
+    RegLayout::ONE, SatMode::NO_SAT, MaskMergeMode::ZEROING, RoundMode::CAST_RINT};
+
+// 每个 K-N tile 的 VF 计算循环体：
+// 1. 加载 scale/offset（按 transB 选 LoadDist）
+LoadAlign<DequantBType, LOAD_TRAIT_SCALE>(regScale, scalePhyAddr + vfNOffset);
+if constexpr (HasOffset) {
+    LoadAlign<DequantBType, LOAD_TRAIT_SCALE>(regOffset, offsetPhyAddr + vfNOffset);
+}
+
+// 2. 加载 fp8 权重（DIST_UNPACK_B8: 每字节 → [byte, 0] 16-bit slot）
+LoadAlign<BType, LoadDist::DIST_UNPACK_B8>(regBIn, bInPhyAddr + ...);
+
+// 3. fp8→float 拆分（两路：偶数 lane + 奇数 lane）
+Cast<float, BType, castTraitFp8ToFP32_ZERO>(regFp32A, regBIn, maskAll);  // 偶数 → 64 float
+Cast<float, BType, castTraitFp8ToFP32_TWO>(regFp32B, regBIn, maskAll);   // 奇数 → 64 float
+
+// 4. float→bf16 分拆（两路：even slots + odd slots）
+Cast<DequantBType, float, castTraitFP32ToBF16_ZERO>(regBf16A, regFp32A, maskFp32);
+Cast<DequantBType, float, castTraitFP32ToBF16_ONE>(regBf16B, regFp32B, maskFp32);
+
+// 5. Or 合并为密集 bf16（需 reinterpret_cast 为 uint16_t）
+Or<uint16_t, MaskMergeMode::ZEROING>(
+    (RegTensor<uint16_t>&)regBOut,
+    (RegTensor<uint16_t>&)regBf16A,
+    (RegTensor<uint16_t>&)regBf16B, maskBf16);
+
+// 6. 反量化：Add(offset) → Mul(scale)
+if constexpr (HasOffset) {
+    Add(regBOut, regBOut, regOffset, maskBf16);
+}
+Mul(regBOut, regBOut, regScale, maskBf16);
+
+// 7. 写回 UB（NZ/ZN strided，outerAxisSize 含 +1 bank conflict padding）
+StoreAlign<DequantBType, DataCopyMode::DATA_BLOCK_COPY>(
+    bOutPhyAddr + outerAxisSize * innerOffset + BLOCK_CUBE * outerIdx,
+    regBOut, outerAxisSize, maskBf16);
+```
+
+> **数据流图：**
+>
+> ```
+> UB fp8 bytes
+>   → LoadAlign<DIST_UNPACK_B8> → regBIn: [b0, 0, b1, 0, b2, 0, ...] (128 fp8 in 16-bit slots)
+>   → Cast<float, ZERO>  → regFp32A: [b0→f32, _, b2→f32, _, ...]  (偶数 lane, 64 float)
+>   → Cast<float, TWO>   → regFp32B: [b1→f32, _, b3→f32, _, ...]  (奇数 lane, 64 float)
+>   → Cast<bf16, ZERO>   → regBf16A: [b0→bf16, 0, b2→bf16, 0, ...]  (even 16-bit slots)
+>   → Cast<bf16, ONE>    → regBf16B: [0, b1→bf16, 0, b3→bf16, ...]  (odd 16-bit slots)
+>   → Or<uint16_t>       → regBOut:  [b0→bf16, b1→bf16, b2→bf16, ...]  (dense 128 bf16)
+>   → [Add offset] → [Mul scale]
+>   → StoreAlign<DATA_BLOCK_COPY> → UB (NZ/ZN strided)
+> ```
+
+### 3.2 扩展新 dtype 的合同
+
+扩展新 dtype 时，DESIGN 必须为每步 Cast 记录：
+
+```text
+cast_step_id
+input_dtype
+output_dtype
+casttrait_configuration （从 asc-devkit API 文档确认，编译+精度验证）
+loaddist                 （从 asc-devkit LoadAlign 文档确认，编译+精度验证）
+storedist                （从 asc-devkit StoreAlign 文档确认，编译+精度验证）
+source_ref
+observed_limitation
+```
+
+Investigation 必须确认所需 Cast dtype 组合在当前 CANN 版本中受支持（查阅 asc-devkit `Cast.md` 数据类型组合表）。CastTrait 不可用或签名不闭合时，标记 blocking 并返回 Step 2 补充调查。
+
+## 4. CastTrait 声明形式约束
+
+CastTrait 作为 NTTP（非类型模板参数）传入 VF 函数时，必须使用 `static constexpr` 声明，不得使用 `constexpr`。理由：`constexpr` 变量作为 NTTP 在某些编译上下文中无法推导，导致编译失败。
+
+DESIGN 必须记录当前 Investigation 确认的 CastTrait 声明形式和 source_ref。PLAN 的 VF 实现动作必须验证复制后的 CastTrait 声明与源码一致。
+
+## 5. VF 调用结构合同
+
+VF 反量化使用三层结构：VF 函数定义（`__simd_vf__` 执行域）→ 参数打包 struct → 调用点（`asc_vf_call`）。DESIGN 必须冻结：
+
+| 层              | 必填合同                                                              |
+| --------------- | --------------------------------------------------------------------- |
+| VF 函数         | 执行域修饰符、模板参数（BType/DequantBType）、参数列表、Cast 调用顺序 |
+| 参数打包 struct | 字段名/类型、UB 地址指针（`__ubuf__`）、迭代计数、offset 存在性分支 |
+| 调用点          | `asc_vf_call` 的参数传递、VF 函数绑定、执行域约束                   |
+
+VF 函数内的 Cast 分支通过 `if constexpr` 按 BType 在编译期选择，不产生运行时分支开销。不同 BType 使用不同的中间寄存器类型（int8 走 half，fp8 走 float）。hasOffset 为 false 时编译期排除 Add 路径。
+
+Cast 指令的饱和模式通过 CastTrait 的 SatMode 字段和 SetCtrlSpr 指令控制。`SetCtrlSpr` 必须在 `__simd_vf__` 外调用。具体配置策略由 Investigation 从 asc-devkit `Cast.md` 确认。
+
+### 5.1 scale/offset LoadDist 参考
+
+scale/offset 始终为 `DequantBType`（bf16/fp16），其 LoadDist 仅取决于 transB 和量化模式：
+
+| transB | 量化模式 | LoadDist | 依据 |
+|---|---|---|---|
+| true (Nk) | perchannel | `DIST_BRC_B16` | 广播单个 b16 到所有 slot |
+| true (Nk) | pertensor | `Duplicate`（标量广播） | 单值广播 |
+| false (Kn) | perchannel | `DIST_NORM` | 正常加载 |
+| false (Kn) | pertensor | `Duplicate` | 单值广播 |
+
+切换 B weight dtype 不影响 scale/offset 的 LoadDist。
+
+## 6. 验证门禁
+
+- Cast 链每步的 dtype 转换顺序与 CPU Golden 完全一致；
+- CastTrait、LoadDist、StoreDist 的配置经编译+精度验证确认正确；
+- Golden 必须使用与 VF 指令行为一致的计算精度（如 PyTorch bf16 运算）；
+- hasOffset 和 hasBias 的组合均需覆盖；
+- 各 dtype 边界值（int8: -128/127, fp8 最值）的反量化结果在 Golden 容差内；
+- CastTrait 声明形式（`static constexpr`）与 Investigation 确认的源码一致；
+- 官方源码区与 Blaze Asset 原文件保持零改动。
+
+具体 dtype、shape 和重复次数来自 DESIGN/PLAN，不由本文固定。