SLWChipVerify/README.md

# 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`

## 快速开始

```bash
./slwchipverify/one_click_verify.sh
```

脚本会交互询问：

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

随后自动完成：

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

也可以用非交互模式：

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

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

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

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

```bash
./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` 目录下执行：

```bash
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
```

成功时输出示例：

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

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

```bash
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`）：

```bash
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）：

```bash
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）：

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

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

```bash
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 仓库可用性验证示例：

```bash
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)`，用于轻量回归与冒烟验证

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