NutShell Cache 功能验证

对 NutShell 处理器的 Cache 模块（nutcore/mem/Cache.scala）做块级功能验证。 基于 Picker 导出 + Toffee 搭建验证环境。

评审快速入口

本仓库为 UCAgent 赛道提交版本，重点证明两件事：一是 Cache 核心路径、corner case 与故障注入可由 Picker/Toffee 闭环稳定验证；二是 UCAgent 原始产物经过了人工复核、重构和领域逻辑补强，而不是纯 AI 输出。

建议优先阅读：

• PDF 完整报告：docs/NutShell_Cache_参赛验证报告.pdf
• PDF 源文档：docs/参赛验证报告完整版.md
• 总报告：docs/验证报告.md
• 测试计划：docs/test_plan.md
• 覆盖率分析：docs/coverage_report.md
• Bug 与故障注入记录：docs/bug_tracking.md
• AI 缺陷与人工修正对比：docs/ai_human_diff.md

核心结果：

• dcache 功能用例 17 个通过，icache 功能用例 5 个通过。
• 功能覆盖率 8 组 25 个 bin：100%。
• 故障注入 F1-F7：7/7 全部检出。
• 随机 soak：4 万次混合读写/probe，0 一致性不一致。
• raw DUT 行覆盖率 74.4%，排除断言失败体与 L1 集成专属路径后，可达 datapath 行覆盖率 100%。

快速复测（Linux / 容器环境）：

pytest tests/ -q
bash scripts/run_faults.sh

如果在 macOS 上直接运行，预生成的 Picker .so 可能因平台 ABI 不同而无法加载；请在 Linux 或 ucagent-local 容器内运行，或按 rtl/README.md 重新导出 DUT。

DUT 参数

默认 RV64 配置下：

• 4 路组相联，32 KB，128 sets
• cache line 64 字节，8 beats × 64-bit 突发
• TagBits=19 / IndexBits=7 / OffsetBits=6（PAddrBits=32）
• 伪随机替换（LFSR），优先填 invalid way
• icache 只读、无 writeback；dcache 可写、带 dirty 与 coherence
• SimpleBus 接口，状态机 9 态（idle / memRead / memWrite / mmio / wait_resp / release）

目录

src/      验证组件（bundle / env / generator / scoreboard / ref_model / coverage）
tests/    用例（基础路径 / corner case / 故障注入）
docs/     测试计划、覆盖率、bug 记录

运行

以下命令需在 Linux / 容器环境中执行。生成的 dut/、覆盖率 .dat、波形文件等均为中间产物， 已被 .gitignore 排除；评审复现时可按需重新生成。

# 1. 生成 Cache 的 Verilog（NutShell，需 mill + firtool）
cd NutShell && make verilog

# 2. picker 导出 Python DUT
picker export Cache.sv --rw 1 --sname CacheWrapper --tdir ./dut -c

# 3. 功能用例（默认排除 fault/toffee 标记）
pytest tests/ -v

# 4. 故障注入检出（每个独立进程）
bash scripts/run_faults.sh

# 5. 行/分支覆盖率汇总
bash scripts/line_coverage.sh

# 6. toffee-test 标准报告（功能 + 行覆盖率，需 toffee 环境）
bash scripts/toffee_report.sh

验证环境

• DUT 的 SimpleBus 四组通道（in / out_mem / mmio / coh）用 toffee.Bundle 结构化封装（src/cache_bundle.py）。
• 参考模型 + 计分板按内存一致性不变量比对（src/ref_model.py / src/scoreboard.py）。
• 功能覆盖率从总线可观测事件采样（src/coverage_def.py），并经 toffee.funcov 汇入标准报告。
• 故障注入对 RTL 打 patch 生成注入版 DUT（scripts/inject_fault.sh），验证环境检出能力。