FallenSigh
8fdf944555
- sync_rtl/common/: skid_buffer, pipeline_reg, defines (valid/ready) - sync_rtl/mod_add/: modular adder example with Verilator C++ TB - test_framework/: Python-driven Verilator compile/sim/compare pipeline - test_framework/modules/mod_add/: 50-vector test plan, full鏈路 PASS - .trellis/spec/: RTL and test_framework conventions documented
67 lines
2.4 KiB
Markdown
67 lines
2.4 KiB
Markdown
# Test Framework Structure
|
|
|
|
## Directory Layout
|
|
|
|
```
|
|
test_framework/
|
|
├── run_all.py # CLI entry: --module, --case, --list, --quick
|
|
├── config.json # Verilator path, clock period, timeouts
|
|
├── lib/
|
|
│ ├── test_runner.py # Discovery, compile, run, compare pipeline
|
|
│ ├── sim_controller.py # Verilator compiles/run wrapper
|
|
│ ├── vector_gen.py # Base class for vector generators
|
|
│ ├── result_checker.py # Hex-file comparison
|
|
│ └── reporter.py # Terminal + HTML output
|
|
├── modules/
|
|
│ └── <module>/
|
|
│ ├── test_plan.json # Module test definition
|
|
│ ├── gen_vectors.py # Vector generator (subclass of VectorGenerator)
|
|
│ └── vectors/ # Generated hex files (auto-cleaned)
|
|
└── reports/
|
|
├── latest/
|
|
└── history/
|
|
```
|
|
|
|
## test_plan.json Schema
|
|
|
|
```json
|
|
{
|
|
"module": "<name>",
|
|
"rtl_top": "sync_rtl/<path>/<top>.v",
|
|
"rtl_deps": ["sync_rtl/common/<dep>.v"],
|
|
"tb_cpp": "sync_rtl/<path>/TB/tb_<top>.cpp",
|
|
"simulator": "verilator",
|
|
"timeout_s": 30,
|
|
"cases": [{
|
|
"id": "<case_id>",
|
|
"description": "<what this tests>",
|
|
"params": {},
|
|
"num_vectors": 50,
|
|
"tolerance": "bit_exact"
|
|
}]
|
|
}
|
|
```
|
|
|
|
- `rtl_top`: top module basename (without .v) is used as Verilator `--top-module`
|
|
- `rtl_deps`: listed before `rtl_top` in Verilator command line
|
|
- `tolerance`: "bit_exact" uses result_checker.py; otherwise delegates to gen_vectors.compare_results()
|
|
|
|
## Vector Generator Contract
|
|
|
|
Each module's `gen_vectors.py` must:
|
|
1. Subclass `VectorGenerator` from `test_framework.lib.vector_gen`
|
|
2. Implement `generate_one(params) -> dict` returning `{"input": {...}, "expected": {...}}`
|
|
3. Override `write_hex_file(vectors, filepath)` for input format
|
|
4. Override `write_expected_file(vectors, filepath)` for expected format
|
|
|
|
The framework auto-discovers the generator class by scanning for subclasses of VectorGenerator.
|
|
|
|
## Adding a New Module
|
|
|
|
1. Create `test_framework/modules/<name>/test_plan.json`
|
|
2. Create `test_framework/modules/<name>/gen_vectors.py`
|
|
3. Create `sync_rtl/<name>/<name>_sync.v` (RTL)
|
|
4. Create `sync_rtl/<name>/TB/tb_<name>.cpp` (Verilator C++ TB)
|
|
5. Run `python3 test_framework/run_all.py --list` to verify discovery
|
|
6. Run `python3 test_framework/run_all.py --module <name>` to test
|