VHDL-FastCheck

VHDL-FastCheck is a toolkit for quickly running VHDL checks and test flows using open source tools:

• GHDL for simulation
• Yosys for synthesis

It provides lightweight Python runners and Makefile helpers to automate simulation and synthesis checks for VHDL projects.

Installation

Clone this repository:

git clone https://github.com/yourusername/vhdl-fastcheck.git
cd vhdl-fastcheck

Create the environment

To download all the necessary dependancies and files to run the scripts, inside the vhdl-fastcheck directory run:

make env

Note: You may need to restart your terminal or source your shell rc file to update your PATH.

Usage

Makefile-based workflow

• Show help:

   make help

  Prints a summary of available Makefile targets and usage instructions.

• Set up the environment:

   make env

  Downloads and installs open source tools (Yosys & GHDL) and sets up your shell environment.

• Run all tests:

   make test TARGET=<path-to-your-vhdl-project>

  • TARGET is the path to the directory containing your VHDL project or exercises.
  • Optionally, set LIB to specify a custom standard cell library for synthesis.

Python-based workflow

python run.py <input-dir>

• <input-dir>: Directory containing compressed archives to analyze.

Workflow

1. Each archive is extracted to a temporary directory.
2. For each extracted directory, make test TARGET=<dir> is run in parallel.
3. All .json files produced by the tests are collected.
4. All JSONs are compacted into a single JSONL file for easy aggregation and analysis.

The resulting JSONL file can be found in the repository root after execution.

Output

• make test (or run_tests.py):

  • For each subdirectory named sim or syn under your target, runs simulation (GHDL) or synthesis (Yosys).
  • Simulation output: Console output from GHDL, including compile logs, testbench results, and pass/fail status for each test. Errors are clearly marked.
  • Synthesis output: Console output from Yosys, including synthesis logs, resource usage, and any warnings or errors. If a standard cell library is used, timing and area reports may be included.
  • At the end, a summary of all test results is printed. Errors are reported with details for debugging.
  • A file named test_results.json is written in the target directory, containing a summary of all results.

• Python runners: Each runner prints detailed logs to the console, including which files are being processed, any dependency analysis, and the results of each simulation or synthesis step. Errors and warnings are clearly indicated.

All outputs are printed to the terminal. For more details, check the logs and error messages printed by each tool.

Example output JSON (test_results.json)

{
	"dir": "~/myproject",
	"tasks": {
		"ex1/sim": {
			"compile": { "ok": true },
			"run": { "ok": true, "result": "PASS" }
		},
		"ex1/syn": {
			"compile": { "ok": true },
			"synth": { "ok": true, "area": 123, "timing": "OK" }
		},
		"ex2/sim": {
			"compile": { "ok": false, "error": "Syntax error" }
		}
	}
}

Each key in tasks is a subdirectory tested. Each value contains the results for that directory, including compile status, run/synth results, and any errors.

Batch Testing Script: run.py

The script run.py automates batch testing of multiple compressed VHDL project directories:

• Extracts all compressed archives (.zip, .tar.gz, etc.) from a specified input directory.
• Runs make test TARGET=<dir> in parallel for each extracted directory.
• Collects all .json result files generated by the tests.
• Compacts all JSON results into a single JSONL file in the repo root: results-<input-dir>.jsonl.

To run batch analysis, use:

python3 run.py /path/to/the/root/dir/

This will:

• Extract each archive in /path/to/the/root/dir/ to a temporary directory
• Run all tests for each extracted project
• Collect the results into a single file named results-archives.jsonl in the repository root

After completion, check the terminal output for logs and see the results-archives.jsonl file for a summary of all test results.

Example: Analysis Directory Structure

When running analysis (e.g., with python3 run.py <input-dir> or make test TARGET=<dir>), your input directory should be organized as follows:

<input-dir>/
├── ex1/
│   ├── sim/
│   │   ├── tb_example1.vhd
│   │   └── ...
│   └── syn/
│       ├── top_example1.vhd
│       └── ...
├── ex2/
│   ├── sim/
│   │   └── tb_example2.vhd
│   └── syn/
│       └── top_example2.vhd
└── ...

• Each subdirectory (e.g., ex1, ex2) represents a separate VHDL project or exercise.
• Each project should contain sim/ (for simulation testbenches) and/or syn/ (for synthesis sources).
• Place your VHDL files in the appropriate subfolders.

This structure is required for the automation scripts to correctly find and process your VHDL files.

Repository layout

• src/ — Python runners and helpers
• utils/ — Make helpers for Yosys and other tooling