SLWChipVerify

SLWChipVerify 是一个轻量级芯片验证 EDA 工具（MVP），支持 Verilog 组合逻辑和时序逻辑验证。

功能

• 读取 JSON 验证规格
• 自动生成 testbench
• examples/simple_cpu_seq_spec.json: 时序逻辑（simple_cpu）示例
• examples/simple_cpu_eventually_spec.json: 时序窗口断言（eventually）示例
• examples/simple_cpu_window_modes_spec.json: 时序窗口断言（always/never/until）示例
• examples/seq_auto_demo.v: 自动时序激励演示 DUT
• examples/seq_auto_demo_spec.json: 自动时序激励演示规格
• examples/seq_random_demo_spec.json: 随机激励+固定种子示例
• examples/github_cpu_validation/projects.json: GitHub 热门 CPU 项目验证清单
• examples/github_cpu_validation/run_github_cpu_validation.py: GitHub 热门 CPU 自动验证脚本
• examples/github_cpu_validation/README.md: GitHub 热门 CPU 示例说明与打包方式

环境要求

• vvp

快速开始

./slwchipverify/one_click_verify.sh

脚本会交互询问：

• Verilog 目录
• 输出目录
• 仿真周期、时钟周期、复位周期

随后自动完成：

• 递归扫描 .v 文件并解析模块结构
• 自动识别或选择顶层模块
• 自动生成 smoke testbench
• 自动调用 iverilog + vvp 仿真
• 自动生成 VCD 波形文件

也可以用非交互模式：

python3 slwchipverify/one_click_verify.py \
  --dir simple_cpu \
  --top simple_cpu \
  --out slwchipverify_auto \
  --cycles 40 \
  --period 10 \
  --reset-cycles 2

批量模式（自动跑所有候选顶层模块）：

python3 slwchipverify/one_click_verify.py \
  --cycles 40 \
  --period 10 \
  --reset-cycles 2 \
  --batch-report slwchipverify/auto_batch/batch_summary.json

也可以直接通过启动脚本透传参数：

./slwchipverify/one_click_verify.sh --dir simple_cpu --batch --out slwchipverify/auto_batch

批量模式输出说明：

• 每个顶层模块会在输出目录下生成独立子目录（包含该模块 TB、仿真可执行文件、日志、VCD）
• 根输出目录下生成 batch_summary.json（或 --batch-report 指定路径）
• 返回码：全部通过返回 0，若任一模块失败返回 1

B) 规格驱动流程（高级）

在 Verilog-Learn 目录下执行：

python3 slwchipverify/slwchipverify.py run \
  -d and-gate/top.v \
  --top top \
  --spec slwchipverify/examples/and_gate_spec.json \
  --report slwchipverify/and_gate_report.json \
  --keep \
  --workdir slwchipverify/build \
  --dump-vcd and_gate_verify.vcd

成功时输出示例：

[SLWChipVerify] PASS: 4/4 cases
[SLWChipVerify] Report written: .../slwchipverify/and_gate_report.json

时序模式示例（使用 simple_cpu/simple_cpu.v）：

python3 slwchipverify/slwchipverify.py run \
  -d simple_cpu/simple_cpu.v \
  --top simple_cpu \
  --spec slwchipverify/examples/simple_cpu_seq_spec.json \
  --report slwchipverify/simple_cpu_seq_report.json

自动时序激励示例（binary_count）：

python3 slwchipverify/slwchipverify.py run \
  -d slwchipverify/examples/seq_auto_demo.v \
  --top seq_auto_demo \
  --spec slwchipverify/examples/seq_auto_demo_spec.json

窗口断言示例（N 周期内 eventually）：

python3 slwchipverify/slwchipverify.py run \
  -d simple_cpu/simple_cpu.v \
  --top simple_cpu \
  --spec slwchipverify/examples/simple_cpu_eventually_spec.json

窗口断言全集示例（always/never/until）：

python3 slwchipverify/slwchipverify.py run \
  -d simple_cpu/simple_cpu.v \
  --top simple_cpu \
  --spec slwchipverify/examples/simple_cpu_window_modes_spec.json

随机激励 + 可复现种子 + CI 报告导出：

python3 slwchipverify/slwchipverify.py run \
  -d slwchipverify/examples/seq_auto_demo.v \
  --top seq_auto_demo \
  --spec slwchipverify/examples/seq_random_demo_spec.json \
  --report slwchipverify/random_report.json \
  --junit slwchipverify/random_junit.xml \
  --csv slwchipverify/random_cases.csv

GitHub 热门 CPU 仓库可用性验证示例：

python3 slwchipverify/examples/github_cpu_validation/run_github_cpu_validation.py

JSON 规格格式

1) 组合逻辑（truth_table）

{ "inputs": ["a", "b"], "outputs": ["f"], "cases": [ { "name": "00", "in": {"a": 0, "b": 0}, "out": {"f": 0} } ] }

说明：

- `inputs` / `outputs` 可以是字符串数组，也可以使用对象指定位宽：
  - `{"name": "data", "width": 8}`
- 值支持：
  - 整数：`15`
  - 常见前缀：`0b1010` / `0x1f` / `0o17`
  - Verilog 字面量：`8'h1f` / `4'b1010`

### 2) 时序逻辑（sequential）

```json
{
  "kind": "sequential",
  "clock": {"name": "clk", "period_ns": 10, "initial": 0},
  "reset": {"name": "rst", "active": 1, "cycles": 2},
  "inputs": [],
  "outputs": [],
  "observes": [
    {"name": "cnt", "expr": "dut.cnt", "width": 4}
  ],
  "max_cycles": 6,
  "auto_stimulus": {
    "enabled": true,
    "start_cycle": 0,
    "mode": "random",
    "seed": 20260419
  },
  "assertions": [
    {"name": "reset0", "cycle": 0, "expect": {"cnt": 0}},
    {"name": "inc3", "cycle": 3, "expect": {"cnt": 2}},
    {
      "name": "eventually_hit_3",
      "cycle": 2,
      "mode": "eventually",
    }
  ]
}

- `clock`: 时钟定义（名称、周期、初值）
- `reset`: 复位定义（名称、有效电平、保持周期）
- `assertions.mode`: `cycle`（默认）/ `eventually` / `always` / `never` / `until`
- `assertions.within`: 窗口模式（eventually/always/never/until）使用，表示窗口宽度（从 `cycle` 起算 N 周期内）
- `assertions.until_expect`: `until` 模式必填，表示终止条件；在终止条件满足前，`expect` 必须持续成立
- `auto_stimulus`: 自动时序激励配置，支持 `binary_count` 和 `random`
- `auto_stimulus.seed`: 随机激励种子，保证可复现

覆盖率统计：

CI 集成报告：

- `--junit`: 导出 JUnit XML
- `--csv`: 导出逐用例 CSV

## GitHub Actions 示例

仓库已提供示例工作流：

- `.github/workflows/slwchipverify-ci.yml`

- 自动运行组合与时序验证
- 直接消费 `--junit` 产物并生成 GitHub Checks 测试结果
- 读取 `--csv` 并写入 Job Summary
- 上传 JSON/JUnit/CSV 报告为构建产物


```bash
./package_slwchipverify_source.sh
脚本会自动生成 ZIP 源码包（默认在 `dist/` 目录），包含：

- `slwchipverify/` 全部源码与示例
- `.github/workflows/slwchipverify-ci.yml`（如果存在）

可直接将 ZIP 解压后上传到 GitHub 仓库，或在本地解压后 `git init` / `git add` / `git commit` 推送。

## 返回码

- `0`: 全部用例通过
- `1`: 有用例失败
- `2`: 工具错误（规格错误、编译失败、仿真错误、超时等）

## 当前限制

- 时序模式当前不包含 UVM、约束随机激励、功能覆盖组等高级能力
- 随机激励当前基于仿真器 `$random(seed)`，用于轻量回归与冒烟验证

后续可扩展到事务级激励、功能覆盖点与协议检查器。