rtl-buddy 4.0.0

Python CLI for Verilog and SystemVerilog RTL testing, randomized regressions, coverage, and simulator workflow automation.

rtl_buddy

rtl_buddy is a Python CLI for running Verilog and SystemVerilog RTL tests, randomized regressions, filelist generation, Verilator/VCS simulator workflows, Yosys synthesis flows, coverage, and adjacent verification automation. It is designed to work well for both humans and AI agents.

It is built to sit on top of the tools your project already uses, while giving you a cleaner, more repeatable interface for day-to-day verification work. The primary supported simulation flows are Verilator and VCS-based compile, simulation, test, regression, as well as Yosys-based synthesis. Basic Verible command integration exists, while broader first-class Verible and PeakRDL workflows are on the roadmap.

Typical commands look like:

uv run rb test basic
uv run rb test smoke --repeat 20
uv run rb regression
uv run rb regression --coverage-merge

Why rtl_buddy

rtl_buddy gives RTL projects a lightweight control plane for common verification tasks:

• Run a single test or a full regression from YAML config instead of ad hoc shell scripts
• Keep simulator invocation, seeds, logs, and result handling consistent across runs
• Manage filelists easily with project model definitions
• Add sweep generation, preprocessing, and postprocessing hooks without rewriting the main flow
• Export machine-readable logs that work well in CI and AI-agent-driven workflows

Features

• Test and regression commands: run one test, many tests, or whole suites with a consistent CLI
• Randomized testing support: create new seeds, repeat runs, and replay previous randomized iterations
• Structured config model: describe suites, regressions, platforms, builders, and models in readable YAML
• Filelist generation: build simulator-ready filelists from models.yaml
• Synthesis flows: run Yosys synthesis from synth.yaml, including optional Liberty-mapped runs and synthesis regressions
• Coverage workflows: collect, merge, summarize, and export Verilator coverage
• Hookable execution flow: plug in your own sweep generation, test preprocessing, and postprocessing scripts
• Verible integration: invoke lint, syntax, formatting, and preprocessing commands through the same project config
• Rich outputs for humans: displays pretty formatted for easy reading
• Structured logging for machines: emits JSONL logs for interpretation by CI systems, automation, and coding agents
• Cross-project reuse: keep one tool interface while adapting it to different RTL repo layouts and builder setups

Installation

rtl_buddy is available on PyPI and installed into your project environment with uv:

uv add rtl_buddy

For local development in this repo, install the composite dev group:

uv sync --group dev
uv run ruff check
uv run ruff format --check
uv run pytest

Prerequisites:

• Python 3.11+
• uv

Beyond Python and uv, every other dependency is feature-dependent: which external tools you need depends on which rb commands you use. For example, rb test needs a simulator (Verilator / VCS), rb synth needs the rtl-buddy/yosys fork, rb wave needs the rtl-buddy/surfer fork.

See the installation page for the full feature-to-dependency matrix, including integration types (Integrated tool vs Pluggable vs Pluggable — curated) and install commands.

Documentation

Full documentation is at rtl-buddy.github.io/rtl_buddy.

Quick Start

The fastest way to get started is the rtl-buddy project template — a ready-to-run RTL project with example designs, tests, and full rtl_buddy integration.

Once you have a project set up, the basic commands are:

uv run rb test basic      # run a single test
uv run rb regression      # run the full regression
uv run rb synth -c synth/sandbox/synth.yaml

For full usage, see the Quick Start guide.

Runtime artefacts are stored under artefacts/{sanitized_test_name}/. Single runs write files such as test.log, test.err, test.randseed, and coverage.dat there directly, while repeated runs use nested directories such as artefacts/{sanitized_test_name}/run-0001/. The suite root always keeps test.log, test.err, and test.randseed symlinked to the latest run for convenience.

Known Issues

See the known issues page.