NutShell Cache 验证（nutshell-uc）

用 UCAgent + toffee + picker 对 NutShell（果壳）处理器的 Cache 做功能验证。UCAgent 生成验证原型，再在其上做人工定制与补全。

被验证对象（DUT）

NCache 取自 NutShell 的 Cache.scala elaborate 产物（NCache_RTL/NCache.v 与 NCache/NCache.v），4 路组相联、写回、meta/data SRAM 片内内联。对外端口：

端口	方向	作用
io_in	上游 SimpleBus	CPU/上级发来的读写请求与响应
io_out_mem	下游主存	缺失时 refill、脏行写回
io_mmio	下游	MMIO 直通，不进 Cache
io_flush / io_empty	控制/状态	flush 触发与流水线空标志
io_out_coh	一致性	探听接口，本验证 tie-off

主存在 io_out_mem 上，是 refill/写回能否闭环的关键，因此挂了行为化主存 Mock，而不是把 meta/data SRAM 当外置端口。

工具链

• picker 把 Verilog 通过 verilator（5.008）导出成可在 Python 里驱动的 DUT（_UT_NCache.so + libUT_NCache.py），make init_NCache 重新生成。
• toffee / toffee-test 提供 Bundle、Agent、功能覆盖组与 pytest 集成。
• UCAgent 读 RTL 与规格，分阶段生成 Bundle、Mock、参考模型、覆盖定义与用例骨架。

验证架构

• unity_test/tests/NCache_bundle_defs.py — 8 个 Bundle（Req/Resp、MemReq/MemResp、MMIO 收发、Coherence 收发），把 DUT 扁平信号封装成握手接口。
• unity_test/tests/NCache_api.py — env fixture 与驱动层：send_request / wait_resp / read / write / Step / reset，以及内存/寄存器预置。
• unity_test/tests/NCache_mock_basic.py — 三个行为 Mock：MockMemory（主存 refill/写回、可预置数据、带统计）、MockMMIO（寄存器读写）、MockCoherence（一致性 tie-off）。
• unity_test/tests/NCache_function_coverage_def.py — 功能覆盖组（funcov），覆盖点绑定到用例。

测试计划

unity_test/NCache_functions_and_checks.md 定义 11 个功能组（FG） / 30 个功能点（FC） / 84 个检查点（CK），覆盖：读写命中/缺失、4 路及同组替换、脏行写回（触发/时序/完整性）、写后读前递、flush、MMIO 隔离、访问粒度 1/2/4/8B、请求/响应握手与背压、参考模型与主存 Mock 自检。

当前状态

$ python3 -m pytest tests/ -q
55 passed

• 55 个用例全部通过，稳定无 flaky。其中读写命中/缺失、4 路与同组替换、脏行写回、写后读前递、握手/背压、MMIO 隔离、地址边界七类行为用例（test_NCache_{boundary,flush,forward,handshake,mmio}.py）都做真实事务并对数据/状态断言，不是只检查返回类型。
• 补全骨架用例时定位并修复了验证环境（testbench）自身的问题，均记录在 unity_test/NCache_bug_analysis.md：
  • MockMemory 主存 Mock 的 SimpleBus 协议原本是错的——只认 cmd=0/1、只回单拍，而 DUT 的 refill 走突发读（cmd=2，末拍 cmd=6）、写回走突发写（cmd=3/7）。协议不匹配时每次缺失都在 s3 阶段死等。已重写为临界字优先的 8 拍突发协议 + 握手门控 + 写回应答，refill/writeback 闭环才真正跑通。
  • SRAM 复位需约 128 拍（metaArray 逐 set 清零），复位后须轮询 req_ready 再驱动；下游 io_out_mem/io_mmio 的 ready 须每拍驱动；多 Mock 共享 session 级 DUT 回调需活跃实例门控以免累积死锁。
• 未改动任何 NCache RTL，问题全在验证环境侧。
• 唯一与 DUT 相关的是已知设计约束：io_flush[1]（整行 flush）在本 DCache 实例会触发 RTL 断言（NutShell 里整行 flush 仅允许 icache），故 flush 用例只驱动 io_flush bit0（冲刷 stage2）。
• 功能覆盖：27 个新检查点（CK）已绑定并在真实事务中被采样；行覆盖率的数值化 HTML 报告需 UCAgent 推进到覆盖门禁阶段（见后续）。

诚实说明：这是 UCAgent 生成原型 + 人工深度定制的结果——框架由 UCAgent 生成，用例的驱动时序与 Mock 协议由人工核对 DUT 逐拍行为后补全/修正。

复现

需要 Linux（或 WSL2）、python3、verilator ≥ 5.008、picker、toffee/toffee-test。

# 1. 重新生成 DUT（picker + verilator）
cd NCache && make        # 或在 UCAgent 工作区 make init_NCache

# 2. 运行验证
cd unity_test && python3 -m pytest tests/ -q

目录

NCache/          picker 导出的 DUT（NCache.v + 驱动封装 + Makefile）
NCache_RTL/      被验证的 Cache RTL 源
unity_test/      验证代码（Bundle/驱动/Mock/覆盖定义/用例）与分析文档
uc_test_report/  toffee 测试报告
Guide_Doc/       UCAgent 各阶段规格模板

后续

1. 推进到行覆盖门禁，产出 code_coverage.json 与数值化 HTML 覆盖报告。
2. 补充受 io_flush[1] RTL 断言限制而暂未覆盖的整行 flush 路径（或按 icache 配置单独验证）。
3. Path B：从 NutShell master 用 mill 写 Cache elaboration driver 重新 elaborate，替换 NCache.v 复跑，与仓库现有 DUT 对照。