05 · 故障注入、第一处差异与修复回归

让失败可解释，再谈排障经验

本章在同一 FIFO 工程中加入一个确定性故障：读数据的最低位被翻转。它通过编译宏 COURSE_BUG 控制，正常源码与故障源码不需要手工来回编辑，分别保存在 local/sa 与 local-bug/sa-bug 构建中。这个案例由本站构造，不是客户事故。目标是证明检查器能捕获错误，并把第一处日志差异映射到波形中的具体更新。

配置示例：只在故障构建定义宏

正常读操作把 mem[rp] 送到 dout，故障分支额外异或 8 位常量 1。输入 3 的二进制最低位因此从 1 变成 0，实际输出为 2；这是可以手算的根因。故障不改变指针、count 或握手，因此最终事务数仍然可能正确。这正好说明只比较完成数量不足以证明功能通过。

原工程的受控教学故障。flow.py compile --bug 才启用，正常构建不受影响。

`ifdef COURSE_BUG
  dout <= mem[rp] ^ 8'h01;
`else
  dout <= mem[rp];
`endif

操作步骤：从本地失败到目标设备复现

先用本地模拟器验证诊断路径，预期失败本身就是实验的一部分。工具返回非零时不要马上修脚本使其吞掉退出码；应读取 run.log 中首个 COURSE_MISMATCH。设备侧使用相同宏和输入，只把执行位置切换到 SA；若需要失败现场，使用 wave 模式保留会话与原始 trace，再进行第四章的离线导出。

1. 编译独立故障版本

   预期与判定：build/local-bug 与正常 build/local 分开，避免污染已通过的基线。

2. 运行 bug01 并保留非零退出

   预期与判定：首条差异应为 seq=0 expected=3 actual=2 cycle=13。

3. 按需要在 SA 故障构建复现

   预期与判定：使用 sa-bug 和 wave 模式，功能失败时 runner 仍非零；从 run.json 找 trace_path。

4. 回到正常构建做回归

   预期与判定：复用相同输入运行 fix01，64 笔逐笔通过且与 golden 一致。

在解压后的 palladium-course 工程根目录执行。标为硬件步骤的命令需在已配置的授权 Linux 环境验证。

python3 flow.py compile local --bug
python3 flow.py run local --bug --id bug01 --vcd
# 上一条应非零退出；阅读 runs/bug01/run.log
python3 flow.py run local --id fix01
python3 flow.py compare runs/golden/transactions.csv runs/fix01/transactions.csv

# 以下两条需要目标 Palladium 环境
python3 flow.py compile sa --bug
python3 flow.py run sa --bug --id bug-wave --mode wave

预期输出：错误必须由独立检查器发现

下面是本站软件故障变体的实际诊断值。COURSE_DONE 仍可能显示 sent 与 received 都为 64，但 mismatches 非零，不能被计为通过。wave 模式会允许 Tcl 完成采集后退出，再由调度器依据结果判失败；因此“采集成功”与“功能失败”可以同时成立。两个状态都应保留，不应把非零退出码强行改成零。

首条差异及 64 个错误由软件自测复现；SA 波形分支是待设备验证的操作流程。

COURSE_MISMATCH seq=0 expected=3 actual=2 cycle=13
COURSE_DONE sent=64 received=64 mismatches=64 cycles=121 full_stall=32
# 普通模式：Testbench 报 COURSE_FAIL，进程非零
# wave 模式：采集后调度器报 COURSE_RESULT，仍非零

# 正常构建回归：
COMPARE_PASS: 64 ordered transactions match

从第一处差异反推根因

先看 seq=0 的输入是否确实为 3、是否被接受，再看该次读出前 empty 是否为 0。若输入与握手都正确而 dout 变为 2，继续核对读数据通路，不要先修改 Scoreboard 的期望公式。本例故障在输出更新处；真实项目还可能涉及存储读延迟、参数、字节序和复位。保持输入不变逐项排除，比从最后一次超时追查更直接。

常见排障误区与校验失败

失败用例应足够小且输入明确。更换随机种子、减少事务数、关闭检查器或修改期望值都可能让表面错误消失，却不能证明原问题被修复。本站调度器会重新校验 CSV，并保留独立运行标识；整理问题时同时提交构建身份、第一处差异和相关波形窗口，而不只发送一张没有时间或版本标识的截图。

典型故障：把检查器改成接受错误值

当检查器暴露差异时，应先证明规格与参考模型正确，再修改设计。下面的案例说明如何避免循环论证：如果期望值直接从 DUT 输出计算，或为了消除失败把 3 改成 2，那么测试已经失去独立性。正常版通过与故障版失败必须同时成立，才能证明该检查至少能覆盖本类错误。

完成检查

• 故障版第一笔错误可复现且非零退出
• 日志、CSV 与波形使用同一个运行和构建身份
• 正常版回归通过，检查器与黄金期望未被改写

延伸阅读与来源

本文为黄河电子原创教学说明。产品命令与支持范围请以实际安装版本的官方文档为准。

• Getting Started with TBA on Palladium · WXE 24.05

  第 21–22 页：分割后的参数与访问问题说明为何需要跨环境比对；本章 XOR 故障及日志为原创。 页码为本次查阅版本的印刷页码；公开链接通向厂商入口，受限原手册不在本站分发。

• Running and Debugging Designs on Palladium · WXE 24.05

  第 49–53 页：SA 调试与运行状态。 页码为本次查阅版本的印刷页码；公开链接通向厂商入口，受限原手册不在本站分发。

继续阅读