rtl_buddy
rtl_buddy is a Python CLI for Verilog and SystemVerilog RTL design and verification. It drives the tools your project already uses from YAML configuration, with a consistent interface for humans, CI, and AI agents.
It covers simulation and randomized regressions, filelist generation, synthesis, place-and-route, power analysis, formal property verification, mutation testing, waveform viewing, hierarchy rendering, AXI profiling, and spec traceability.
To see what each of those produces before installing anything, take the Tour: every command on it ran unchanged against the project template, and every table and image is that run's real output.
uv run rb test basic
uv run rb test smoke --repeat 20
uv run rb regression
uv run rb regression --coverage-merge
uv run rb synth -c synth/sandbox/synth.yaml
uv run rb fpv -c fpv/sandbox/fpv.yaml
uv run rb wave basic
uv run rb axi-profile run basic
uv run rb tool-check
Why rtl_buddy
- Run one test or a full regression from YAML instead of ad hoc shell scripts.
- Keep simulator invocation, seeds, logs, and result handling consistent across runs.
- Define filelists once in project models.
- Add sweep and preprocessing hooks without rewriting the main flow.
- Export JSONL logs and JSON results for CI and agent workflows.
Features
- Tests and regressions (
rb test,rb randtest,rb regression): one CLI across Verilator, Icarus Verilog, and VCS, with new-seed, repeat, and replay support. cocotb tests run through the same flow. - Configuration: suites, regressions, platforms, builders, and models in YAML.
rb filelistgenerates simulator-ready filelists frommodels.yaml. - Elaboration (
rb elab,rb elab-regression): parse, type-check, and elaboratemodels.yamlfilelists with pyslang, without building a simulator. - Synthesis (
rb synth): Yosys fromsynth.yaml, with optional Liberty mapping, effort levels, synthesis regressions, and the yosys-slang frontend. OpenROAD is an alternative backend. - Place-and-route (
rb pnr): OpenROAD flow from the post-synthesis netlist to routed DEF, netlist, SDC, and timing/DRC reports. - Power analysis (
rb power,rb power-regression): OpenROADreport_powerwith static, synthetic, or SAIF/VCD activity.rb saifconverts FST/VCD to SAIF. - Formal verification (
rb fpv,rb fpv-regression): SymbiYosys proofs with pinned solvers.rb wave-fpvopens a failed proof's counterexample. - Mutation testing (
rb mut): scores a verification suite by mutating a design and checking whether an FPV proof or simulation oracle kills each mutant. Uses the optional rtl-buddy-xeno engine. - Waveforms (
rb wave): opens Surfer with live signal values annotated in your editor over WCP. - Hierarchy (
rb hier,rb hier-query): module hierarchy diagrams and queries through rtl-buddy-view, with optional clock-domain annotations. - AXI profiling (
rb axi-profile): discover AXI bundles, emit a bind-style monitor, turn a test's FST intoaxi-perf.jsonand per-transaction Parquet, and open a marimo notebook. - Coordination hub (
rb hub): a broker between the rtl-buddy-view SPA, Surfer, and editor adapters. Serves graph (/gph), coverage (/cov), and physical-metrics (/phy) panes. - Physical metrics (
rb phys): per-module gate count and area, per-instance power, and a run listing from the merged synthesis and power model. - Spec traceability (
rb spec): tracespecs.yamlitems to models and tests. - Tool check (
rb tool-check): reports whichrbsubcommands are ready and which are blocked on missing or out-of-version tools. - Coverage: collect, merge, summarize, and export Verilator coverage.
- Hooks: sweep generation and test preprocessing scripts.
- Verible (
rb verible): lint, syntax, format, and preprocessor commands, plusverible.filelistgeneration. - Output for humans and machines: Rich console output, and JSONL logs plus JSON results with
--machine.
Installation
rtl_buddy is on PyPI. It needs Python 3.11 or newer and uv:
uv add rtl_buddy
External tools depend on the commands you use. rb test needs a simulator, rb synth needs the rtl-buddy/yosys fork, rb pnr and rb power need OpenROAD, rb fpv needs SymbiYosys and an SMT solver, rb hier needs rtl-buddy-view, and rb wave needs the rtl-buddy/surfer fork. The installation page has the full feature-to-tool matrix.
To develop rtl_buddy itself, install the dev group:
uv sync --group dev
npm ci # documentation builds only
uv run ruff check
uv run ruff format --check
uv run pytest
Quick start
The rtl-buddy project template is a ready-to-run project with example designs, tests, and rtl_buddy integration. In a project:
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
See the Quick Start guide.
Artefacts go under artefacts/{sanitized_test_name}/. A single run writes test.log, test.err, test.randseed, and coverage.dat there. Repeated runs write to artefacts/{sanitized_test_name}/run-0001/ and so on, and the three top-level test.* files are symlinks to the latest run.
Documentation
Full documentation: rtl-buddy.github.io/rtl_buddy. Start with the Tour for real output of every workflow, then Installation and the Quick Start. Each version also publishes <version>/llms.txt and <version>/agent/catalog.json for agents. Offline, use rb docs list and rb docs show.
Known limitations are on the known issues page.
1 maintainer
Metadata
1 maintainer
Release files for rtl-buddy 6.83.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| rtl_buddy-6.83.0.tar.gz | 1.3 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| rtl_buddy-6.83.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.8 MB
Release files / rtl_buddy-6.83.0.tar.gz
| Download URL | rtl_buddy-6.83.0.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
53215a428200c22d692431e23b6eddb0d3da9b12b7e635769de0bb0b5d9bd79a
|
|
BLAKE2b-256 checksum How to use checksums |
9e7d461c87c324710bf48839e5866cb348f901c353d74a7fdb76f57d27c42f94
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logRelease files / rtl_buddy-6.83.0-py3-none-any.whl
| Download URL | rtl_buddy-6.83.0-py3-none-any.whl |
|---|---|
| Size | 1.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e9d963eae542c58b6e4fc6997804aac6d02978e3e2bcb1d5e1fd8ac3911cf1db
|
|
BLAKE2b-256 checksum How to use checksums |
4ec773a683b5bec9a13341e2d0acfc1708f9d6650c8e66168cc8d89dbd017998
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency log
