Metadata-Version: 2.4
Name: routertl
Version: 3.5.1
Summary: FPGA SDK — simulation, synthesis, linting, and code generation in one pip install. YAML-driven, multi-vendor, batteries included.
Author-email: "Daniel J. Mazure" <dasjimaz@gmail.com>
License: MIT AND LicenseRef-RouteRTL-Proprietary
Project-URL: Homepage, https://www.routertl.dev
Project-URL: Documentation, https://www.routertl.dev/docs
Project-URL: Changelog, https://github.com/djmazure/routertl/blob/main/CHANGELOG.md
Project-URL: Source, https://github.com/djmazure/routertl
Keywords: fpga,vhdl,verilog,simulation,synthesis,cocotb,eda,rtl
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-MIT
License-File: LICENSE-PROPRIETARY
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0
Requires-Dist: rich-click>=1.7.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: docker>=7.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pathspec>=0.11.0
Requires-Dist: tomli>=1.1.0; python_version < "3.11"
Requires-Dist: cocotb>=2.0
Provides-Extra: docs
Requires-Dist: mkdocs<2.0,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings>=1.0; extra == "docs"
Requires-Dist: mkdocstrings-python>=2.0; extra == "docs"
Dynamic: license-file

<p align="center">
  <strong>RouteRTL</strong><br>
  <em>Route every layer — from RTL to bitstream.</em>
</p>

<p align="center">
  <a href="https://www.routertl.com"><img src="https://img.shields.io/badge/web-routertl.com-orange.svg" alt="Website"></a>
  <a href="https://pypi.org/project/routertl/"><img src="https://img.shields.io/pypi/v/routertl.svg" alt="PyPI"></a>
  <a href="LICENSE-MIT"><img src="https://img.shields.io/badge/shell-MIT-green.svg" alt="MIT License"></a>
  <a href="LICENSE-PROPRIETARY"><img src="https://img.shields.io/badge/core-PolyForm%20Shield-blue.svg" alt="PolyForm Shield"></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"></a>
  <a href="https://github.com/cocotb/cocotb"><img src="https://img.shields.io/badge/sim-cocotb%202.0-blueviolet.svg" alt="Cocotb 2.0"></a>
</p>

---

> **I want to...**
>
> | Goal | Link |
> |:-----|:-----|
> | Install the SDK | [Installation Guide](docs/guides/INSTALLATION.md) |
> | Create my first project | [First Steps Tutorial](docs/guides/FIRST_STEPS_TUTORIAL.md) |
> | Write a simulation | [Cocotb Quickstart](docs/guides/COCOTB_QUICKSTART.md) |
> | Use a protocol driver | [Driver Cookbook](docs/guides/DRIVER_COOKBOOK.md) |
> | Understand project.yml | [project.yml Reference](docs/reference/PROJECT_YML_REFERENCE.md) |
> | Fix an error | [Troubleshooting](docs/reference/TROUBLESHOOTING.md) |
> | Browse the API | [API Reference](docs/api/index.md) |

**RouteRTL** (distributed on PyPI as `routertl`) is a command-line SDK for FPGA development. It discovers RTL sources automatically, resolves hierarchy and compilation order, runs simulation with Cocotb, and dispatches synthesis to vendor toolchains — all from a single `project.yml`.

Under the hood it parses VHDL, Verilog, and SystemVerilog source trees, traverses mixed-language designs, dispatches synthesis and implementation to vendor TCL engines (Vivado, Quartus, Radiant, Libero), wraps Cocotb 2.0+ for simulation, and provisions EDA tools headlessly inside Docker. The CLI installs as both `routertl` and the short alias `rr` — both commands are identical.

The project grew out of an internal scaffolding workflow used to accelerate FPGA bring-up across multiple vendor toolchains. Then the AI explosion happened and the scope expanded significantly.

### The Problem

FPGA projects still rely on vendor-specific GUI projects, fragile build scripts, and manual simulation flows that resist automation. Reproducing a build on a colleague's machine — or in CI — often means reverse-engineering tool versions, directory layouts, and undocumented environment variables. RouteRTL replaces all of that with a single `project.yml`: describe the project once, run the entire toolchain from the command line.

## ⚡ 30-Second Demo

Create a working FPGA project and run its first simulation:

```bash
pip install routertl

mkdir demo && cd demo && git init
routertl init --template blinky --vendor xilinx --part xc7z020clg400-1
source .venv/bin/activate

routertl info --forest
```

```
🌲 Design Forest — 1 hierarchy detected

  blinky_top
  └── led_counter

  Sources: 2 files
  Libraries: work
```

```bash
routertl sim test_blinky
```

```
Running simulation: test_blinky
──────────────────────────────────────────────
PASS  test_blinky
```

No manual compilation order. No vendor project files. Just a `project.yml`.

No test for a sub-module? Generate one from the entity:

```bash
routertl testgen edge_counter         # generates Cocotb boilerplate
routertl sim test_edge_counter
```

## 🏆 Field-Tested on Real Codebases

The SDK has been battle-tested against codebases it has never seen before — with zero configuration beyond `rr init`.

**Round 1 — [open-logic](https://github.com/open-logic/open-logic)**: 77 entities, 4 IP areas, flat multi-root library.

<p align="center">
  <img src="https://www.routertl.com/assets/demos/gauntlet_final_state.png" alt="RouteRTL analyzing the open-logic VHDL library — 77 entities, 4 areas, 0 violations" width="720">
</p>

<p align="center"><em>Auto-discovered 4 IP areas · resolved 46 hierarchies · compilation order matches oracle exactly (77/77 files, 0 violations)</em></p>

**Round 2 — [NEORV32](https://github.com/stnolting/neorv32)**: 56 entities, 1 deep monolithic SoC hierarchy, complex generics — the opposite architecture. Same result: 0 violations.

> 🎬 **Interactive demos**: [`gauntlet_demo.html`](docs/assets/demos/gauntlet_demo.html) (open-logic) · [`gauntlet_neorv32_demo.html`](docs/assets/demos/gauntlet_neorv32_demo.html) (NEORV32)

## Core Capabilities

Given a source directory and a `project.yml`, the SDK:

1. **Discovers files** — scans the source tree and picks up VHDL, Verilog, and SystemVerilog (`.vhd`, `.vhdl`, `.v`, `.sv`) files automatically, supporting mixed-language hierarchies.
2. **Resolves hierarchy** — parses entity/module declarations and instantiations to build a design tree.
3. **Resolves dependencies** — figures out which entities depend on which, including package dependencies and cross-library references.
4. **Determines compilation order** — produces a correct build order so simulators and synthesizers don't choke on missing definitions.
5. **Lints out of the box** — `rr lint` runs hierarchy-aware, incremental analysis. Point it at a top-level entity, and dependencies resolve themselves.
6. **Generates simulation boilerplate** — `rr testgen` scaffolds Cocotb testbenches for any entity. `rr sim` runs them on NVC, GHDL, Verilator, Icarus, or QuestaSim — same `project.yml`, same command.
7. **Synthesizes any module in the hierarchy** — not just the top level. Useful for iterating on submodules without waiting for a full build.
8. **Targets any supported vendor** — Vivado, Quartus (Pro and Standard), Radiant, Libero. Switch vendors by changing one word in `project.yml`.
9. **Runs implementation and bitstream generation** — `rr implementation`, `rr bitstream`, with utilization and timing reports via `rr report`.
10. **Provisions EDA tools headlessly** — `rr docker install vivado` automates vendor tool installation inside Docker, including device support and patching.
11. **Runs on Windows via WSL2** — native Linux toolchains, Docker EDA containers, and the full CLI work inside WSL2. No dual-boot required.
12. **Hooks into every build stage** — rarely is an FPGA project just source files presented to the tools. Firmware constants, version ROMs, generated IP, and memory maps often need to be created at build time. RouteRTL lets you declare Python or TCL hooks at every stage — pre-building, pre-synthesis, post-implementation, pre-bitstream — so generated artifacts are always fresh. `expected_outputs` are auto-added to `.gitignore`.

...and more — firmware traceability (Git SHA + dirty-bit in ROM), bus bridge generation, register bank generators (VHDL + C headers + HTML docs), embedded Linux path from `.xsa` to bootable SD card, protocol drivers for verification (UART, SPI, I2C, QSPI, AXI, Avalon, Native Memory), `rr watch` for continuous re-testing, `rr doctor` for toolchain health checks.

## Pre-Commit Quality Gates

Every commit can be gated by a configurable set of checks — declared in `project.yml`, enforced by a Git hook installed with `rr init`. The gates are composable: pick the level of assurance that fits the project.

```yaml
hooks:
  pre_commit:
    enabled: true
    lint: true                        # hierarchy-aware RTL linting
    check_yaml: true                  # project.yml syntax validation
    lint_python: true                 # ruff check on test code
    tests: auto                       # auto-discover all test_*.py
    exclude:
      tests: [test_slow_integration]  # skip heavy tests locally
```

What `tests: auto` does: the hook discovers every `test_*.py` under `simulation.test_dir`, applies exclusions, and runs each one through `rr sim`. A single failing test blocks the commit.

This matters especially in AI-assisted development workflows, where code can change faster than a human can review. The pre-commit gate is the last line of defense before a change enters the repository — linting catches structural regressions, simulation catches functional ones, and YAML validation catches configuration drift.

> **Using AI agents?** The SDK ships structured documentation designed to guide code generators:
> [Cocotb Quickstart](docs/guides/COCOTB_QUICKSTART.md) for test scaffolding patterns,
> [Driver Cookbook](docs/guides/DRIVER_COOKBOOK.md) for protocol driver usage,
> and [project.yml Reference](docs/reference/PROJECT_YML_REFERENCE.md) for configuration schema.
> Point your agent at these before it writes code — the pre-commit gate will catch the rest.

## What's in the Box

Everything below comes with `pip install routertl`.

| Category | What You Get |
|:---------|:-------------|
| **CLI** | `rr` command with 40 commands (120+ incl. subcommands) — sim, build, lint, doctor, docker, deps, bridge-gen, init, watch, and more |
| **Verification** | Cocotb 2.0+ test framework, `Tb` base class, `SignalCollector`, regression reporting with tee logging |
| **Protocol Drivers** | UART (TX+RX), SPI (Master+Slave), I2C, QSPI — zero external dependencies |
| **Bus Drivers** | AXI4-Lite, AXI4, Avalon-MM, Native Memory Master/Slave BFMs, passive monitors, bridge scoreboards |
| **Build System** | Multi-vendor TCL dispatch (Vivado, Quartus Pro/Standard, Radiant, Libero), pre-build hooks, environment injection |
| **Analysis** | Smart linter (hierarchy-aware, incremental), `rr ip auto-discover` (propose `ip.yml` from any source tree), `--forest` tree explorer, `--graph` Mermaid export |
| **Code Generation** | Bus bridge generator (AXI ↔ Avalon ↔ Native Memory), register bank generator (`rr regbank validate/generate/axilite/c-header/html/template`) |
| **DevOps** | Docker EDA provisioner, pre-commit hooks, `.gitignore` auto-sync, workspace health checks |
| **Libraries** | XPM auto-compilation, Unisim stubs, SDK utility units (edge detector, input filter, etc.) |

## Architecture

<p align="center">
  <img src="https://www.routertl.com/assets/fpga_workflow_dark.svg" alt="Architecture — project.yml drives Linting, Simulation, and Synthesis into a reproducible FPGA workflow" width="600">
</p>

## Quick Start

### 1. Install

```bash
pip install routertl
```

> For full platform-specific instructions (Linux, WSL2, macOS, prerequisites),
> see the **[Installation Guide](docs/guides/INSTALLATION.md)**.

### 2. Initialize

```bash
routertl init --name my_project --vendor xilinx --part xc7z020clg400-1
```

This creates the `project.yml`, directory structure, and installs pre-commit hooks. The generated `project.yml` tells the SDK where everything lives — point the paths at your own directory layout and the SDK works out of the box:

```yaml
project:
  name: my_project
  top_module: my_top

paths:
  sources: rtl                      # your RTL sources — auto-discovered
  simulation: tb                    # tb_* RTL testbench wrappers
  constraints: constraints          # vendor constraint files

simulation:
  test_dir: verification/tests      # Cocotb test modules
```

> **Existing repo?** Run `routertl init` inside it, adjust the `paths:` block
> to match your layout, and you're ready — no restructuring needed.

### 3. Develop

```bash
routertl info --forest            # Explore design hierarchy
routertl lint                     # Smart lint (auto-detects hierarchies)
routertl sim test_my_module       # Run simulation with cocotb
routertl watch                    # Re-run tests on file save
routertl synthesis                # Synthesize
routertl implementation           # Place & route
routertl bitstream                # Generate bitstream
routertl report                   # Utilization & timing reports
routertl deps graph               # Visualize dependency tree
```

## Simulation API

The SDK provides a standardized Python API for Cocotb 2.0+ testbenches:

```python
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
```

## Design Exploration

`rr info --forest` reveals your entire design hierarchy with zero configuration:

```console
$ rr info --forest
🌲 Design Forest — 3 hierarchies detected

  zynq_spi_top
  ├── spi_sensor_reader
  │   └── (leaf — SPI master FSM)
  ├── uart_debug_tx
  │   └── (leaf — 8N1 UART transmitter)
  └── edge_counter        [SDK unit]
      └── edge_detector   [SDK unit]

  Sources: 5 files (3 project + 2 SDK)
  Libraries: work, routertl
```

`rr scan-tests` auto-discovers every Cocotb test in your project:

```console
$ rr scan-tests
🔍 Scanning for Cocotb tests in: sim/cocotb/tests

MODULE                              LOCATION                                                COMMAND
----------------------------------------------------------------------------------------------------------------------------------
test_edge_counter                   sim/cocotb/tests/test_edge_counter.py                   routertl sim test_edge_counter
test_spi_sensor                     sim/cocotb/tests/test_spi_sensor.py                     routertl sim test_spi_sensor
test_uart_debug                     sim/cocotb/tests/test_uart_debug.py                     routertl sim test_uart_debug
----------------------------------------------------------------------------------------------------------------------------------
✅ Found 3 tests.
```

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

## Who Is This For?

- **FPGA engineers** who want reproducible, scriptable builds instead of vendor GUI projects
- **Teams** integrating FPGA synthesis, simulation, and linting into CI/CD pipelines
- **Multi-vendor shops** targeting Xilinx, Intel/Altera, Lattice, and Microchip from one project description
- **AI-assisted workflows** — the SDK ships structured docs and pre-commit quality gates designed for code-generating agents

## Prerequisites

| Tool | Required | Notes |
|:-----|:---------|:------|
| Python 3.10+ | ✅ | CLI and simulation framework |
| Git | ✅ | Version control and dependency tracking |
| NVC | Recommended | VHDL simulator for Cocotb 2.0+ (install via [`.deb`](https://github.com/nickg/nvc/releases/latest)) |
| GHDL | Recommended | VHDL analyzer (smart linting, fast analysis) |
| Vivado / Quartus / Radiant / Libero | Optional | Vendor synthesis — or use `rr docker install` for headless provisioning |
| Docker | Optional | For headless EDA tool installation and deterministic environments |
| Verilator | Optional | Verilog/SystemVerilog simulation |
| Icarus Verilog | Optional | Open-source Verilog simulation (`sudo apt install iverilog`) |
| Riviera-PRO / QuestaSim | Optional | Commercial multi-language simulation |

## Documentation

- **[SDK User Guide](docs/reference/SDK_USER_GUIDE.md)** — Configuration, workflows, and command reference
- **[First Steps Tutorial](docs/guides/FIRST_STEPS_TUTORIAL.md)** — 20-minute hands-on walkthrough
- **[Cocotb Quickstart](docs/guides/COCOTB_QUICKSTART.md)** — Write and run simulations
- **[Driver Cookbook](docs/guides/DRIVER_COOKBOOK.md)** — Copy-paste recipes for SPI, UART, and AXI-Lite testing
- **[Existing Project Migration](docs/guides/EXISTING_PROJECT_MIGRATION.md)** — Add RouteRTL to a Vivado/Quartus project
- **[Documentation Index](docs/README.md)** — All docs in one place

## Acknowledgments

RouteRTL stands on the shoulders of outstanding open-source projects:

- **[NVC](https://github.com/nickg/nvc)** by Nick Gasson — The VHDL simulator that powers our Cocotb 2.0+ simulation flow (others also supported).
- **[GHDL](https://github.com/ghdl/ghdl)** — The VHDL analyzer behind the smart linting engine (NVC also possible). GHDL's fast `--std=08` parsing enables incremental, hierarchy-aware linting across entire designs.
- **[Cocotb](https://github.com/cocotb/cocotb)** — The Python testbench framework at the heart of our verification API. Every `@cocotb.test()` in RouteRTL is built on Cocotb's coroutine model.
- **[xpm_vhdl](https://github.com/fransschreuder/xpm_vhdl)** by Frans Schreuder — The VHDL port of Xilinx XPM simulation models that enables vendor-independent simulation of Xilinx primitives like FIFOs and CDCs.
- **[Verilator](https://github.com/verilator/verilator)** — Verilog/SystemVerilog simulation backend.
- **[Icarus Verilog](https://github.com/steveicarus/iverilog)** — Open-source Verilog simulation backend.
- **[Rich](https://github.com/Textualize/rich)** and **[rich-click](https://github.com/ewels/rich-click)** — The CLI presentation layer.
- **[Jinja2](https://github.com/pallets/jinja2)** — Template engine behind code generation.

## Contributing

The best way to contribute is to **use RouteRTL and tell us what breaks** — open an issue, suggest a feature, or just share how you're using it. Run `routertl doctor` and include the output if reporting a bug.

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## Contact

Built and maintained by **Daniel J. Mazure** — ✉️ dasjimaz@gmail.com

## Licensing

RouteRTL uses a **dual-license** model:

| Component | License | You can... |
|:----------|:--------|:-----------|
| CLI, build system, cocotb drivers, hooks, docs | [MIT](LICENSE-MIT) | Use, modify, redistribute — no restrictions |
| Compiled core (`routertl_core/*.so`) | [PolyForm Shield 1.0.0](LICENSE-PROPRIETARY) | Use for any purpose **except** building a competing product |

<details>
<summary><strong>Licensing FAQ</strong></summary>

| 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 or toolchain that substitutes for RouteRTL. Using RouteRTL to build *your own product* (medical devices, radar, telecom, etc.) is **not** competing. |
| Is RouteRTL "open source"? | The CLI and verification framework are OSI-approved open source (MIT). The compiled core is source-available under PolyForm Shield. We describe this model as **open core**. |

</details>

Copyright © 2026 Daniel J. Mazure
