NutShell Cache 自动化验证工程

面向赛题“基于 UCAgent 完成果壳（NutShell）Cache 自动化验证”的完整验证工程：用 Picker 将 rtl/Cache.v 导出为 Python 可驱动 DUT，用 Toffee 搭建结构化验证环境，并人工补强 CRV、Scoreboard、Functional Coverage 与故障注入方案。

提交仓库：https://www.gitlink.org.cn/wangyue111/nutshell-cache-verification

自动/AI 评审入口：AUTOMATED_REVIEW.md · reports/ai_review_scorecard.json

评委先看这 30 秒

评审关注点	本仓库直接证据
Cache 核心路径是否覆盖	tests/test_directed.py, tests/test_coverage_stress.py, tests/test_random_crv.py 覆盖 read/write、miss refill、partial mask、同组替换、MMIO uncached、flush/refill、coherence probe。
是否真能跑 RTL	make regression 实机通过：纯 Python 模型测试 5 passed，Picker/Verilator 生成 DUT 后 Toffee 硬件仿真 12 passed。
是否有覆盖率闭环	reports/model_coverage.md：Functional Coverage 100.00%；reports/rtl_coverage_summary.md：line/toggle/branch/expr 均有量化数据。
是否能检出复杂故障	make fault-audit-all：mask_merge、mmio_decode、read_data_lsb 三类 RTL mutant 均被杀死。
是否体现人工协同	docs/ai_collaboration.md 记录 AI 生成片段、人工发现盲区、协议修正、CRV/Scoreboard/coverage 重构。

实机演示

下面不是概念图，是本机实际执行 make regression、make report、make fault-audit-all 后生成的终端摘要：

验证闭环架构

评分点对齐

需要什么硬件？

不需要 FPGA、开发板或 GPU。赛题验证主要是软件仿真：

用途	最低配置	推荐配置
模型/生成器/Scoreboard 单元测试	2 核 CPU，4 GB RAM，2 GB 磁盘	4 核 CPU，8 GB RAM
Picker + Verilator 硬件仿真	4 核 CPU，8 GB RAM，10 GB 磁盘	8+ 核 CPU，16 GB RAM，20 GB 磁盘
长随机回归/多种故障注入	4 核 CPU，16 GB RAM	16+ 核 CPU，32 GB RAM

软件依赖：Python 3.10/3.11、C/C++ 编译器、CMake、SWIG、Verilator、Picker、Toffee、toffee-test、pytest。macOS Apple Silicon 和 Linux x86_64 都可运行。

快速运行

make env-check      # 检查 Picker/Verilator/Toffee 环境
make gen_dut        # Picker 导出并编译 Python DUT 包 Cache/
make test-model     # 纯 Python CRV/oracle/scoreboard 测试
make test-hw        # Toffee + Picker 硬件仿真测试
make regression     # model + gen_dut + hardware 全流程
make report         # 生成 reports/model_coverage.{json,md}
make rtl-coverage   # 生成 Verilator RTL line/toggle/branch/expr coverage
make fault-audit BUG=mask_merge  # 构建单个 mutant，确认测试能检出，再恢复 golden DUT
make fault-audit-all  # 跑完 mask/mmio/read-data 三类 mutant audit

Makefile 默认优先选择 Python 3.11；如机器上存在多个 Python，可显式指定：

make env-check PYTHON=/path/to/python3.11
make regression PYTHON=/path/to/python3.11

当前已验证环境示例：Python 3.11.15、Picker 0.9.0-master、Verilator 5.048、SWIG 4.4.1、toffee-test 0.3.1。

目录结构

rtl/Cache.v                         # NutShell Cache RTL
src/env/                            # Toffee Bundle/Agent/Env/SimpleBus RAM
src/generator/crv.py                # 人工定制 CRV 激励与场景库
src/ref/cache_oracle.py             # 可执行参考模型与故障内存
src/ref/ref_cache.py                # Toffee driver_hook 参考模型适配
src/scoreboard/scoreboard.py        # Scoreboard 与失配诊断
src/funcov/cache_coverage.py        # Functional Coverage 采样/导出
tests/                              # smoke/direct/random/model 回归
scripts/                            # 环境检查、报告生成、RTL mutant 注入
skills/nutshell-cache-verifier/     # repo-local Agent Skill
docs/                               # 测试计划、覆盖率计划、故障注入、AI协同和评分映射
reports/                            # 覆盖率与验证报告
THIRD_PARTY_NOTICES.md              # DUT/工具链第三方来源与许可证说明

人工定制亮点

• 约束细化：同组冲突、脏替换、部分写掩码、MMIO 双窗口、连续读写 hazard、热点 index 随机场景。
• 结构化环境：将 Bundle、Agent、Env、Oracle、Scoreboard、Coverage 分层，便于 UCAgent 继续扩展。
• 故障注入：scripts/inject_bug.py 可生成掩码合并错误、MMIO decode 错误、读数据 bit 翻转等 RTL mutant。
• 覆盖率闭环：CacheCoverage.REQUIRED 定义命令、地址空间、mask、word offset、读写转移、冲突深度等必达 bin。
• 协议级修正：SimpleBus WRITERSP.rdata 按 don’t-care 处理，避免 AI 生成代码中常见的假失败。

关键报告

• 测试计划：docs/test_plan.md
• 覆盖率计划：docs/coverage_plan.md
• 故障注入：docs/fault_injection.md
• AI 协同记录：docs/ai_collaboration.md
• 评审标准映射：docs/evaluation_mapping.md
• 第三方许可证说明：THIRD_PARTY_NOTICES.md
• 验证报告：reports/verification_report.md
• 模型覆盖率：reports/model_coverage.md
• RTL 覆盖率：reports/rtl_coverage_summary.md

常见问题

• WRITERSP rdata 不一致：SimpleBus 写响应的 rdata 为 don’t-care，本环境在 agent/scoreboard 层只比较有效的响应命令。
• macOS 多 Python 版本：scripts/patch_picker_makefiles.py 会给 Picker 生成的 Makefile 增加 CMAKE_ARGS，避免 wrapper 链到错误的 Python ABI。
• 没有服务器 sudo：仍可在用户目录编译安装 Picker/Toffee；Verilator/CMake/SWIG 若系统缺失，建议用已有包管理器或容器。
• 打包提交：优先使用 GitLink 仓库或 git archive 导出源码；不要直接压缩本地工作目录，避免带入 Cache/、波形、coverage .dat、.pytest_cache/ 等生成物。