NutShell Cache Verification with UCAgent

This repository is the competition workspace for automated and human-in-the-loop verification of the NutShell Cache using Picker, Toffee, toffee-test, and UCAgent.

Current Status

• Baseline DUT and Toffee environment imported from XS-MLVP/Example-NutShellCache.
• UCAgent-assisted development records are documented; model/API settings are not required to run tests.
• Directed, CRV, fault-injection, and RTL coverage-target tests are included under tests/.
• Verification documentation and human-collaboration records are included under docs/.

Quick Start

In the configured UCAgent / Picker / Toffee verification environment:

cd /workspace/nutshell-cache-verify
make gen_dut
make test
make crv-convergence
make rtl-cov-sweep
make mutation

Current verification result: 34 pytest/toffee-test cases pass, followed by aggregate functional coverage generation under reports/. Latest measured coverage is 100.0% Python functional coverage (60/60 bins) and 84.0% merged RTL selector-sweep coverage (1227/1454). The single VCache_coverage.dat left by a plain pytest run is only a last-test diagnostic artifact, so official RTL evidence comes from the merged sweep. Latest RTL mutation campaign result is 6/6 killed. Latest CRV convergence analysis reports 100.0% CRV intent coverage (26/26 bins), with all 10 fixed seeds independently closing the same-set generator target subset. Run coverage commands serially because they use Verilator’s VCache_coverage.dat artifact.

The first command uses Picker to export rtl/Cache.v into a Python-drivable DUT package. The second command runs the Toffee/toffee-test based regression. The third command preserves and merges per-selector Verilator coverage data.

Repository Layout

rtl/        Cache RTL under verification
src/env/    Toffee agents and environment wiring
src/ref/    Reference cache model
tests/      pytest/toffee-test testcases
docs/       Test plan, coverage plan, bug tracking, AI-human collaboration records
reports/    Generated verification reports and coverage artifacts
skills/     UCAgent skill for repeatable Cache verification workflow
scripts/    Local helper scripts

Verification Goal

The high-score target is not only to pass smoke tests, but to build a reusable verification environment that covers:

• load/store hit paths
• miss detection and refill
• dirty victim writeback
• replacement pressure on same set
• MMIO bypass/path separation
• partial write mask behavior
• back-to-back and non-blocking requests
• scoreboard/reference-model consistency
• functional coverage closure
• fault-injection based verification-environment validation

License

Apache License 2.0.

Advanced Verification Commands

make test       # pytest + functional coverage + RTL coverage
make crv-convergence  # seed-to-coverage report for constrained-random traffic
make mutation   # inject and restore RTL mutations, expected to be killed by directed tests
make rtl-cov    # collect Verilator coverage from VCache_coverage.dat
make rtl-cov-sweep  # run selected tests one-by-one and merge RTL coverage