Metadata-Version: 2.4
Name: routertl
Version: 3.1.0
Summary: The full-vertical FPGA SDK. Define once in YAML. Simulate, synthesize, and ship — across Xilinx, Intel, and Lattice — from one terminal.
Author-email: "Daniel J. Mazure" <dasjimaz@gmail.com>
License: MIT AND LicenseRef-RouteRTL-Proprietary
Project-URL: Homepage, https://github.com/djmazure/routertl
Project-URL: Documentation, https://djmazure.github.io/routertl/
Project-URL: Repository, https://github.com/djmazure/routertl
Project-URL: Changelog, https://github.com/djmazure/routertl/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/djmazure/routertl/issues
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
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.</em>
</p>

<p align="center">
  <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>
  <a href="https://pypi.org/project/routertl/"><img src="https://img.shields.io/pypi/v/routertl.svg" alt="PyPI"></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** is the open-source FPGA SDK that routes your design from RTL to a bootable Linux image — with one YAML, one CLI, and zero vendor lock-in.

```bash
# From zero to simulating in 60 seconds
pip install routertl
mkdir my_soc && cd my_soc && git init
routertl init --template blinky --name my_soc --vendor xilinx --part xc7z020clg400-1
source .venv/bin/activate
routertl sim test_edge_counter
```

## Why RouteRTL?

Every FPGA engineer knows the pain: **you don't just design hardware — you babysit toolchains.** Vivado TCL scripts, Quartus QSF files, GHDL compilation orders, hand-crafted Makefiles, register bank boilerplate, device-tree fragments, C header files, and the ever-growing gap between the bitstream and the software that drives it.

**RouteRTL is the only FPGA SDK that covers the full vertical** — RTL verification, multi-vendor synthesis, register bank generation, and embedded Linux boot — in a single, YAML-driven, CLI-first framework.

## Architecture

```mermaid
graph TB
    subgraph top ["🎯 One YAML → Everything"]
        YAML["project.yml"]
    end

    subgraph verify ["🧪 Verify"]
        SIM["Cocotb Simulations"]
        LINT["Smart Linting"]
        WATCH["Watch Mode"]
        BRIDGEGEN["Bridge RTL Generator"]
    end

    subgraph build ["🔨 Build"]
        VIVADO["Vivado"]
        QUARTUS["Quartus"]
        RADIANT["Radiant"]
    end

    subgraph ship ["🐧 Ship"]
        DTBO["Device Tree Overlays"]
        CHEADERS["C UIO Headers"]
        PYDRV["Python Drivers"]
        BOOT["BOOT.bin / SD Card"]
    end

    YAML --> SIM
    YAML --> LINT
    YAML --> VIVADO
    YAML --> QUARTUS
    YAML --> RADIANT
    YAML --> DTBO
    YAML --> CHEADERS

    SIM --> WATCH
    VIVADO --> DTBO
    DTBO --> BOOT

    style YAML fill:#2d5016,stroke:#4a8c2a,color:#fff
    style SIM fill:#1a5c3a,stroke:#2da36b,color:#fff
    style LINT fill:#1a5c3a,stroke:#2da36b,color:#fff
    style WATCH fill:#1a5c3a,stroke:#2da36b,color:#fff
    style BRIDGEGEN fill:#1a5c3a,stroke:#2da36b,color:#fff
    style VIVADO fill:#5c1a3a,stroke:#a32d6d,color:#fff
    style QUARTUS fill:#5c1a3a,stroke:#a32d6d,color:#fff
    style RADIANT fill:#5c1a3a,stroke:#a32d6d,color:#fff
    style DTBO fill:#3a5c1a,stroke:#6ba32d,color:#fff
    style CHEADERS fill:#3a5c1a,stroke:#6ba32d,color:#fff
    style PYDRV fill:#3a5c1a,stroke:#6ba32d,color:#fff
    style BOOT fill:#3a5c1a,stroke:#6ba32d,color:#fff
```

## Features

| # | Feature | Description |
|:-:|:--------|:------------|
| 1 | **YAML → Bitstream → Linux** | One config drives synthesis, simulation, register banks, device trees, C headers, Python drivers, and SD card assembly. |
| 2 | **Multi-Vendor, Zero Lock-in** | Same `project.yml` targets Xilinx, Intel/Altera, and Lattice. Switch vendors by changing one line. |
| 3 | **RTL Bridge Generator** | Describe a bus bridge in YAML → get synthesizable VHDL/SystemVerilog with AXI4/Avalon/Native support. |
| 4 | **Smart Linting** | Automatic hierarchy detection via forest analysis. Lint a 50-file design by naming the top — dependencies resolve themselves. |
| 5 | **Verification Culture** | Pre-commit hooks gate on simulation. `routertl diff` shows which tests to re-run. `routertl watch` re-runs them on save. |
| 6 | **Docker Environments** | `sim`, `vivado`, `quartus`, `radiant`, `questa`, `riviera`, `buildroot` — fully deterministic, one-command setup. |
| 7 | **41+ CLI Commands** | `routertl sim`, `routertl schematic`, `routertl report`, `routertl doctor`, `routertl linux build`, shell completion, plugin system. |
| 8 | **Embedded Linux Pipeline** | From `.xsa` to bootable SD card: BSP generation, U-Boot cross-compile, kernel build, device tree overlays, memory map cross-checking. |

> **Not using embedded Linux?** RouteRTL is equally useful for bare-metal
> designs — use `routertl synthesis` for bitstream generation and the full
> simulation/linting/CI pipeline without the `linux` commands.

## 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 your `project.yml`, `Makefile`, directory structure, and installs pre-commit hooks.

### 3. Develop

```bash
routertl sim test_my_module      # Run simulation
routertl lint                     # Smart lint (auto-detects hierarchies)
routertl watch                    # Re-run tests on file save
routertl synth list               # Synthesis validation status board
routertl synthesis                # Build bitstream
routertl schematic                # Open schematic viewer
routertl linux build              # Build embedded Linux image
```

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

Native protocol drivers included: **UART**, **SPI**, **I2C**, **AXI4-Lite**.

## Design Exploration

One command reveals your entire design hierarchy:

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

## Prerequisites

| Tool | Required | Notes |
|:-----|:---------|:------|
| Python 3.10+ | ✅ | CLI and simulation framework |
| Make, Git | ✅ | Build system |
| NVC | ✅ | Recommended VHDL simulator for Cocotb 2.0+ (install via [`.deb`](https://github.com/nickg/nvc/releases/latest)) |
| GHDL | ✅ | VHDL analyzer (smart linting) |
| Vivado / Quartus / Radiant | Optional | Vendor synthesis tools |
| Docker | Optional | For deterministic environments |
| Verilator | Optional | Verilog/SystemVerilog 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. NVC's excellent VHDL-2008 support and VPI implementation make modern Python-driven verification possible.
- **[GHDL](https://github.com/ghdl/ghdl)** — The VHDL analyzer behind our smart linting engine. 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.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute.

## 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 © 2024-2026 Daniel J. Mazure
