nutshell-cache-verification/docs/fault_injection.md

故障注入与 Bug 追踪

工具

scripts/inject_bug.py 会从 rtl/Cache.v 生成可复现 RTL mutant：

python3 scripts/inject_bug.py --bug mask_merge --output faults/Cache_mask_merge_bug.v
python3 scripts/inject_bug.py --bug mmio_decode --output faults/Cache_mmio_decode_bug.v
python3 scripts/inject_bug.py --bug read_data_lsb --output faults/Cache_read_data_lsb_bug.v

生成的 mutant 是验证环境自检材料，不建议纳入正常回归。

一键审计：

make fault-audit-all

设计的故障

Bug ID	注入点	预期影响	主要检出用例	状态
B1 mask_merge	hit write data bus 忽略 byte mask	部分写覆盖未选中字节	test_mask_and_conflict_directed, test_smoke	已实际编译 mutant 并检出
B2 mmio_decode	禁用第二个 MMIO decode 窗口	0x4000_0000-0x7fff_ffff 地址被错误缓存	test_mmio_second_window_is_uncached	已实际编译 mutant 并检出
B3 read_data_lsb	读响应 bit0 翻转	任意读数据与 oracle 不一致	test_smoke, test_mmio_second_window_is_uncached	已实际编译 mutant 并检出
B4 memory fault	后端内存周期性读损坏/丢写/强制 mask	验证 Scoreboard 对数据错误敏感	test_faulty_memory_policy_is_deterministic, test_scoreboard_catches_corrupt_read	已单元验证

审计证据

• 汇总：reports/fault_audit_summary.md
• mask_merge：reports/fault_mask_merge_audit.md
• mmio_decode：reports/fault_mmio_decode_audit.md
• read_data_lsb：reports/fault_read_data_lsb_audit.md

Bug 记录

日期	类型	现象	处理
2026-06-28	环境/协议	DUT 的 WRITERSP rdata 保持上一次写数据，Scoreboard 期望 0	按 SimpleBus 语义将写响应 rdata 视为 don't-care，在 agent/scoreboard 中只比较命令
2026-06-28	工具链	macOS 上 Picker 生成 wrapper 可能链接到 Python 3.14，Python 3.11 import 失败	增加 scripts/patch_picker_makefiles.py 并通过 CMAKE_ARGS 固定 Python 3.11

建议的 mutant 审计流程

1. 运行 make regression 确认 golden RTL 通过。
2. 生成目标 mutant。
3. 临时用 mutant 替换 Picker 输入并运行对应 directed test。
4. 期望 pytest/Toffee 报告 mismatch；记录首个失败 transaction。
5. 重新 make gen_dut && make test-hw 恢复 golden DUT。