NutShell Cache 自动化验证（基于 UCAgent）

仓库地址：

• GitLink（主）：https://www.gitlink.org.cn/putaoptg/UCagent-test
• GitHub（镜像）：https://github.com/ghptg0711/UCagent-test

Overview

本项目基于 UCAgent（AI 驱动验证智能体）完成对开源 RISC-V 处理器 NutShell 中 Cache 子系统的自动化功能验证。

验证闭环采用 Picker / Toffee 框架搭建，核心验证组件与 DUT 适配层解耦，支持在纯 Python 环境下运行单元回归，也可在 WSL2 环境下对接真实 NutShell Cache DUT 进行端到端验证。

验证平台包含以下关键能力：

• 参考模型（Reference Model）：位级精确的 Cache 行为模型，支持读写命中/缺失、替换、脏回写、部分写掩码合并等语义。
• 激励生成器（Generator）：提供定向用例与约束随机（CRV）流，覆盖替换、RAW 冒险、行边界、部分写、跨偏移、非缓存访问等场景。
• 计分板（Scoreboard）：逐事务比对 DUT 与参考模型响应，检测数据错配、事务序错乱等故障。
• 覆盖率收集器（Coverage）：功能覆盖率建模，含命中/缺失、脏/干净替换、延迟档位、同 set 访问等 bins。
• 故障注入（Faults）：注入读数据位翻转、写掩码丢弃、脏回写破坏、响应序交换等故障，验证计分板检出能力。
• 真实 DUT 适配器（Real DUT Adapter）：通过 Picker 生成的 Python 绑定对接 Verilator 编译的真实 NutShell Cache DUT。

Quick Start

# 环境要求：Python 3.10+, WSL2 (Ubuntu), Verilator 5.032
python -m venv .venv
source .venv/bin/activate
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e . -r requirements-dev.txt

# 检查 Git 对象、gitlink、嵌套仓库和漏提交文件
python tools/check_repo_health.py

# 运行测试
python -m pytest tests/ -v --asyncio-mode=auto

# 运行核心回归
PYTHONPATH=src python -m cache_vip.regression

# WSL2 全量验证：预编译 DUT 需要 Python 3.14
bash run_wsl_tests.sh

run_wsl_tests.sh 默认使用清华 PyPI 镜像；可通过 PIP_INDEX_URL 覆盖。xspcomm 源码固定为官方提交 23ba5c4，优先从 GitLink 国内镜像获取，构建结果缓存在 ~/.cache/nutshell-cache-verification/。缺少 CMake、SWIG 或 Python 开发头文件时， 安装脚本会使用当前 Ubuntu APT 源补齐依赖。 仓库中 rtl/generated_real/_UT_RealNutShellCache.so 使用 Python 3.13+ C API，并由 Python 3.14 环境生成；真实 DUT 验证请使用 Python 3.14。 该历史证据二进制还使用了 Picker 模板原有的 -march=native，不能保证跨 CPU 直接运行。标准 GitHub-hosted CI 只执行可移植的 core 与 DUT contract 测试；真实 DUT job 仅能在带 real-dut 标签、CPU 兼容且已安装 Picker 的 self-hosted runner 上手工触发。新的 DUT 构建模板默认使用通用 x86-64 指令集。

Project Structure

.
├── src/cache_vip/        # 验证组件
│   ├── reference_model.py    # 参考模型
│   ├── generator.py          # 激励生成器
│   ├── scoreboard.py         # 计分板
│   ├── coverage.py           # 覆盖率收集器
│   ├── faults.py             # 故障注入
│   ├── regression.py         # 回归入口
│   ├── toffee_adapter.py     # Toffee 适配层
│   ├── real_dut_adapter.py   # 真实 DUT 适配器
│   ├── memory_agent.py       # 内存代理
│   └── transactions.py       # 事务定义
├── tests/                # 测试用例（Mock DUT + real DUT smoke）
├── docs/                 # 文档（方案设计、验收计划、验证报告等）
├── reports/              # 验证报告（回归摘要、覆盖率、缺陷跟踪）
├── configs/              # 信号映射配置（signal_map*.yaml）
├── scripts/              # Verilator 构建、仿真和覆盖率脚本
└── rtl/                  # RTL 和 Picker 生成产物
    ├── dut_gen/          # 预编译 Verilog RTL
    └── generated_real/   # Picker 生成的 Python DUT 封装

注意：NutShell Cache RTL 以预编译 Verilog 形式引入（非 Chisel/Scala 源码）。 原始源码来自 NutShell 项目的 Cache 子系统，通过 Chisel 编译为 Verilog 后提交， 以确保验证环境的可复现性。 本地可选的 NutShell/ 源码仓库不会作为顶层 gitlink 提交；其来源与固定提交记录在 third_party_sources.json，仓库健康检查会在该目录存在时验证提交、工作区和对象完整性。

Verification Results

指标	结果
Core Reference Model 功能覆盖率	**100%**（19/19 bins）
故障检出	5/5 全部检出
单元测试	详见 CI 与本地 pytest 日志
CRV 回归	多 seed 约束随机回归，详见 reports/core_regression_summary.md
Real DUT 功能覆盖率	待兼容 self-hosted runner 实测，不以 core 覆盖率替代

详细验证数据见 reports/coverage_summary.md 与 reports/core_regression_summary.md。

CI

项目通过 GitHub Actions 持续集成（见 .github/workflows/verification.yml）：

• unit-tests：在标准 Ubuntu Runner 上运行单元测试与核心回归，不依赖 WSL2。
• dut-contract-tests：验证 independent expected/actual、Scoreboard 和 Adapter actual 保真。
• real-dut-tests：仅在手工触发且存在兼容的 self-hosted Picker runner 时运行；其结果 不由前两个 job 替代。

License

本项目遵循 Apache License 2.0。