Init Push

2026-04-19 16:14:05 +08:00
commit 5b6bd1ac23
54 changed files with 80296 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,259 @@
+# 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)`，用于轻量回归与冒烟验证
+
+后续可扩展到事务级激励、功能覆盖点与协议检查器。
+```