routertl 5.0.0

RouteRTL
The FPGA build system that reads your HDL and figures it out.

---

python3 -m venv .venv
source .venv/bin/activate
pip install routertl

PEP 668 note: the venv step above is not optional on Ubuntu 24.04+, Debian 12+, or any externally-managed Python — a bare pip install routertl there fails with error: externally-managed-environment. Creating and activating the venv first sidesteps it entirely. If you want a global CLI instead of a per-project venv, pipx install routertl also works. Do not reach for pip install --break-system-packages — it installs into the OS-managed Python and can break system packages.

Python 3.14: cocotb 2.1+ supports 3.10–3.14, so rr sim is available on the same interpreters as the rest of the CLI. Install with pip install 'cocotb>=2.1' if it is missing from the environment.

Optional service features are available as routertl[mcp], routertl[docker], and routertl[web]; the core install omits those stacks.

RouteRTL is a command-line FPGA SDK with a built-in IP package manager. Install a UART core, an AXI interconnect, or a full RISC-V SoC — dependencies are resolved automatically from the source code, so you never maintain file lists or compile order by hand, and a build that passes on one machine passes on every machine.

Viewing waveforms? RouteRTL projects open directly in RouteWave, the companion waveform viewer. Run rr routewave to inspect VCD/FST captures from rr sim without leaving the SDK workflow.

Install an IP, See It Work

rr init --non-interactive --no-venv
rr pkg add open-logic/olo_intf_uart
rr lint olo_intf_uart

  + open-logic/olo_intf_uart ^4.4.1
  Resolving 1 package(s) from https://registry.routertl.dev
    open-logic/olo_intf_uart: ^4.4.1 -> 4.4.1
  Written ip.lock (1 packages)

  Lint passed  (ghdl)

RouteRTL cloned the package, resolved 8 transitive VHDL dependencies, compiled them in the correct library order, and linted — all from one command.

rr hierarchy --forest

  olo_intf_uart  (olo_intf_uart.vhd, 8 files)
  |-- olo_base_strobe_gen
  |   +-- [1 pkgs: olo_base_pkg_math]
  |-- olo_intf_sync
  |   +-- [1 pkgs: olo_base_pkg_attribute]
  +-- [3 pkgs: olo_base_pkg_logic, olo_base_pkg_math, olo_base_pkg_string]

IP Registry. Cross-Language Dependency Resolution.

rr pkg search ethernet                           # browse the catalog
rr pkg add fpganinja/taxi::taxi_eth_mac_1g       # Verilog — single module from a repo
rr pkg add open-logic/olo_base_fifo_async        # VHDL — library deps auto-resolved
rr pkg add openhwgroup/cva6                      # SystemVerilog — full RISC-V SoC

The registry detects licenses (MIT, GPL, CERN-OHL) and classifies each package as permissive, weak, or strong copyleft. Every package is scanned with role computation — tops, components, and primitives classified automatically.

When you install a package, RouteRTL:

1. Queries the registry for dependency metadata
2. Resolves missing libraries and modules to their provider packages
3. Auto-installs transitive dependencies
4. Compiles everything in the correct order
5. Lints and reports results

Pre-packaged from open-logic, fpganinja (Corundum, Taxi Ethernet/AXI/PCIe), OpenHW Group (CVA6/CORE-V), PULP Platform (AXI, common cells), Analog Devices, VUnit, Enclustra, NEORV32, and more. Pinned by commit SHA in a lock file.

What You Get

Three-Register Architecture	rr pkg (IPs), rr rules (design rules with exact-part + IP-version scoping), rr ref (reference designs — buildable projects with version-pinned IP deps). Overview →
IP Package Manager	Growing registry with license detection, cross-language dependency graphs, lock files, R1–R9 description quality pipeline (validator + scanner self-heal + submit gate + CI gate + weekly drift guard), rr pkg search/add/update
Auto-Discovery	Point at a source tree — VHDL, Verilog, SystemVerilog hierarchy resolved automatically
Multi-Vendor Synthesis	Vivado, Quartus (Pro/Standard), Radiant, Libero — change one word in project.yml
Cocotb 2.0+ Simulation	rr sim, rr testgen, rr watch — NVC, GHDL, Verilator, Icarus, QuestaSim
Protocol Drivers	UART, SPI, I2C, QSPI, AXI4-Lite, AXI4, Avalon-MM — included, zero extra deps
Smart Linting	Hierarchy-aware, incremental, multi-pass — rr lint needs no per-file setup
Code Generation	Bus bridges (AXI/Avalon/Native), register banks (VHDL + C headers + HTML docs)
Pre-Commit Gates	Lint + simulate + YAML check on every commit
Docker EDA Provisioning	rr docker install vivado — headless vendor tool setup, same environment everywhere

Validated on Real Codebases

Validated against real-world codebases with zero configuration beyond rr init:

• open-logic — 69 IPs, flat multi-root VHDL library. All files resolved, 0 violations.
• NEORV32 — 56 entities, deep monolithic SoC, complex generics. 0 violations.

The CLI

rr init                       # scaffold a project
rr hierarchy --forest         # design hierarchy
rr lint                       # smart lint (GHDL + Verilator)
rr sim test_my_module         # simulate (cocotb 2.1+)
rr testgen edge_counter       # generate test boilerplate
rr watch                      # re-run on save
rr synth run my_top           # synthesize
rr implementation             # place & route
rr bitstream                  # generate bitstream
rr report                     # utilization & timing
rr deps graph                 # dependency visualization
rr pkg search / add / update  # IP package manager
rr rules check                # match design rules to current toolchain
rr ref list / install         # scaffold from a reference design
rr migrate                    # import existing Vivado or vw projects
rr docker install vivado      # headless EDA provisioning
rr doctor                     # toolchain health check

Both routertl and rr work as entry points.

Quick Start

1. Install

python3 -m venv .venv
source .venv/bin/activate
pip install routertl

For platform-specific instructions (Linux, WSL2, macOS), see the Installation Guide.

2. Initialize

rr init --name my_project --vendor xilinx --part xc7z020clg400-1

Creates project.yml, directory structure, virtual environment, and pre-commit hooks.

Existing project? rr migrate imports Vivado projects and conventional-layout vw.toml workspaces (Quartus support coming soon). Or run rr init inside an existing repo and adjust the paths: block.

3. Add IP and Build

rr pkg add open-logic/olo_base_fifo_sync  # install with deps
rr lint                                    # verify everything compiles
rr sim test_my_module                      # run simulation
rr synth run my_top                        # synthesize

Simulation API

from routertl.sim import Tb, run_simulation, UartSource, SignalCollector

@cocotb.test()
async def test_my_module(dut):
    tb = Tb(dut)
    await tb.start_clock()
    await tb.reset()
    # Your test logic here

Native protocol drivers included: AXI4-Lite, AXI4, Avalon-MM, Native Memory, UART, SPI, I2C — with passive monitors and bridge scoreboards.

Who Is This For?

• FPGA engineers who want reproducible, scriptable builds instead of vendor GUI projects
• Teams integrating FPGA into CI/CD pipelines
• Multi-vendor shops targeting Xilinx, Intel/Altera, Lattice, and Microchip from one project.yml

Documentation

I want to...

Goal	Link
Create my first project	First Steps Tutorial
Write a simulation	Cocotb Quickstart
Use a protocol driver	Driver Cookbook
Understand project.yml	project.yml Reference
Migrate an existing project	Existing Project Migration
Fix an error	Troubleshooting
Browse all docs	Documentation Index

Prerequisites

Tool	Required	Notes
Python 3.10+	Yes	CLI and simulation framework
Git	Yes	Version control and dependency tracking
NVC	Recommended	VHDL simulator for Cocotb 2.0+ (.deb)
GHDL	Recommended	VHDL analyzer (fast linting)
Vendor tools	Optional	Vivado / Quartus / Radiant / Libero — or rr docker install

Acknowledgments

RouteRTL builds on the work of several outstanding open-source projects. We gratefully acknowledge:

Project	Role in RouteRTL
NVC	Primary VHDL simulator for Cocotb 2.0+ simulation
GHDL	VHDL analysis, linting, and secondary simulation backend
Cocotb	Python-based verification framework powering rr sim
Verilator	Verilog/SystemVerilog simulation and linting backend
Icarus Verilog	Lightweight Verilog simulation backend
xpm_vhdl	Open-source VHDL implementation of Xilinx XPM macros
Rich	Terminal formatting for CLI output
Jinja2	Template engine for code generation

RouteRTL would not be possible without these projects and their maintainers.

Contributing

The best way to contribute is to use RouteRTL and tell us what breaks. To report a bug, suggest a feature, or share how you're using it, email support@routertl.dev. Include the output of rr doctor when reporting issues.

See CONTRIBUTING.md for details.

Contact

Built and maintained by Daniel J. Mazure — routertl.dev · support@routertl.dev

Licensing

RouteRTL uses a dual-license model:

Component	License	You can...
CLI, build system, cocotb drivers, hooks, docs	MIT	Use, modify, redistribute — attribution only
Compiled core (routertl_core/*.so)	PolyForm Shield 1.0.0	Use for any purpose except building a competing product

Licensing FAQ

Question	Answer
Can I use RouteRTL commercially?	Yes — use it to build, simulate, and ship your FPGA products without restriction.
Can I modify the CLI or build system?	Yes — they're MIT-licensed. Fork, extend, contribute PRs — all welcome.
Can I decompile the .so modules?	No — that violates the PolyForm Shield license.
Can I redistribute the PyPI wheel?	Yes — as-is, per standard PyPI terms.
What counts as "competing"?	Building and distributing an FPGA SDK that substitutes for RouteRTL. Using RouteRTL to build your own product is not competing.

Copyright 2026 Daniel J. Mazure