NutShell Cache 验证项目

项目简介

本仓库面向 NutShell Cache 模块搭建了一套基于 Python、pytest、Toffee 和 Picker 的验证环境。

最终提交版本以人工重构和人工审查后的 Toffee 验证环境为准，UCAgent/Codex 的输出主要作为原型生成、思路探索和对比审查材料。项目中保留了 AI 协作记录、UCAgent 输出审查、覆盖率分析和 bug injection 实验记录。

评审快速入口

推荐运行：

make reproduce

等价脚本入口：

bash scripts/reproduce.sh

该命令会在需要时生成 Picker DUT，运行主回归，并生成 Toffee report。

环境依赖

Picker
Verilator
Python 3.10
pytest
toffee-test

常用命令

make gen_dut      # 使用 Picker 生成 Python DUT
make test         # 运行主回归
make report       # 运行主回归并生成 Toffee report
make reproduce    # 评审用一键复现入口
make random       # seed 可控的随机 smoke，可通过 RANDOM_SEED/RANDOM_ITERS 配置
make mutant_demo  # 可选：运行 RTL mutant demo，默认 MUTANT=dirty_writeback
make check_submission
make clean        # 删除 report、波形和仿真数据输出

目录结构

rtl/        被验证的 Cache RTL
src/env/    Toffee 环境、agent、coverage、memory model、timeline
src/ref/    Cache 参考模型和后端行为检查
test/       定向、随机、MMIO、blocking、flush 和 bug 场景测试
reports/    已保存的 Toffee 和代码覆盖率报告
docs/       英文版 AI 协作、生成代码快照、覆盖率分析、提交检查文档
docs_zh/    中文版文档索引和审查说明
scripts/    复现和辅助脚本

当前结果

24/24 testcases passed
Functional coverage: 100.0%
Coverage: 7/7 groups, 24/24 points, 72/72 bins
Line coverage: 94.26%

正式验证报告：

CACHE_VERIFICATION_REPORT.pdf

已保存的 Toffee/line coverage 报告：

reports/report-20260603094655/report-20260603094655.html

文档索引

docs_zh/REVIEWER_GUIDE.md：评审快速导航，包含运行命令、预期结果和推荐阅读顺序。
docs_zh/VERIFICATION_PLAN.md：功能点到 testcase、checker、coverage 的映射和最终验证范围。
docs_zh/GAP_ANALYSIS.md：验证边界说明和未纳入结论范围的 rationale。
docs_zh/AI_COLLABORATION.md：AI 协作过程记录，说明 UCAgent/Codex 输出如何被人工审查、修正或舍弃。
docs_zh/AI_REVIEW_MATRIX.md：表格化记录 AI 生成了什么、人工发现了什么问题、如何发现、如何修正以及最终证据。
docs_zh/UCAGENT_OUTPUT_REVIEW.md：UCAgent 输出审查记录，包含 model bypass、mock、手写 trace 等风险点。
docs_zh/ai_collaboration_records/：UCAgent/Codex 生成代码快照的中文说明。实际快照位于 docs/ai_collaboration_records/generated_code_snapshots/，只作为过程证据，最终可运行代码仍以 src/、test/、scripts/ 为准。
docs_zh/CRV_STRATEGY.md：受约束随机策略，包含 seed、迭代次数、合法地址约束和 checker 边界。
docs_zh/COVERAGE_ANALYSIS.md：功能覆盖率和代码覆盖率分析。
docs_zh/BUG_TRACKING.md：高风险 bug 场景、checker 覆盖情况和 AI 输出风险记录。
docs_zh/BUG_INJECTION_RESULT.md：RTL mutant 实验记录，说明验证环境可以抓到字节掩码和 dirty writeback 地址错位类 RTL bug。
docs_zh/SUBMISSION_CHECKLIST.md：对齐比赛评审维度的提交检查清单。

英文版同名文档位于 docs/ 目录。

可选 bug injection 复现入口：

make mutant_demo MUTANT=dirty_writeback
make mutant_demo MUTANT=wmask

说明

波形文件和仿真数据文件没有放入提交仓库，可以通过回归重新生成。

最终验证结论来自人工重构后的 Toffee 环境、主回归结果、保存的 Toffee report 和已记录的 bug injection 实验，不直接采用未经审查的 UCAgent 自动生成代码作为最终验证依据。

License

本项目使用 Apache License 2.0，详见 LICENSE。