Metadata-Version: 2.4
Name: routertl
Version: 3.7.0
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>Your entire FPGA workflow — from RTL to bitstream — in one pip install.</em>
</p>

<p align="center">
  <a href="https://www.routertl.dev"><img src="https://img.shields.io/badge/web-routertl.dev-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>

---

**RouteRTL** is a command-line FPGA SDK. Describe your design once in `project.yml`, then simulate, lint, synthesize, and package — all from the terminal. No vendor GUIs, no fragile build scripts, no "works on my machine."

```bash
pip install routertl
```

## ⚡ Three Commands to "Wow"

```bash
rr init --template blinky -y          # scaffold a working project
rr info --forest                      # see your design hierarchy
rr sim test_blinky                    # run simulation — done
```

```
🌲 Design Forest — 1 hierarchy detected

  blinky_top
  └── led_counter

  Sources: 2 files · Libraries: work
```

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

## 📦 2,000+ IP Blocks — One Command Away

```bash
rr pkg search fifo                    # browse the IP catalog
rr pkg add open-logic/olo_base_fifo   # install with dependency resolution
rr pkg list                           # see what's installed
```

Pre-packaged from open-logic, NEORV32, CVA6, NOEL-V, GRLIB, and more. Dependencies auto-resolved, pinned by commit SHA in a lock file. Think `pip` for FPGA IP.

## What You Get

| | |
|:--|:--|
| **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 — `rr lint` just works |
| **Code Generation** | Bus bridges (AXI ↔ Avalon ↔ Native), register banks (VHDL + C headers + HTML docs) |
| **Pre-Commit Gates** | Lint + simulate + YAML check on every commit — configured in `project.yml` |
| **Docker EDA Provisioning** | `rr docker install vivado` — headless vendor tool setup, same environment everywhere |
| **IP Package Manager** | 2,000+ blocks, dependency graphs, lock files, `rr pkg search/add/update` |

## 🏆 Battle-Tested

The SDK has been validated against codebases it has never seen before — zero configuration beyond `rr init`:

- **[open-logic](https://github.com/open-logic/open-logic)** — 77 entities, 4 IP areas, flat multi-root library → 77/77 files, 0 violations
- **[NEORV32](https://github.com/stnolting/neorv32)** — 56 entities, deep monolithic SoC, complex generics → 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)

## The Full CLI

```bash
rr info --forest              # design hierarchy
rr lint                       # smart lint
rr sim test_my_module         # simulate
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 docker install vivado      # headless EDA provisioning
rr doctor                     # toolchain health check
```

Both `routertl` and `rr` work — same commands, your pick.

## Quick Start

### 1. Install

```bash
pip install routertl
```

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

### 2. Initialize

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

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

> **Existing repo?** Run `rr init` inside it, adjust the `paths:` block to match your layout — no restructuring needed.

### 3. Develop

```bash
rr info --forest              # explore what was discovered
rr sim test_my_module         # run simulation
rr synth run my_top           # synthesize when ready
```

## Simulation API

```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: 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`
- **AI-assisted workflows** — structured docs and pre-commit gates designed for code-generating agents

## Documentation

> **I want to...**
>
> | Goal | Link |
> |:-----|:-----|
> | 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) |
> | Migrate an existing project | [Existing Project Migration](docs/guides/EXISTING_PROJECT_MIGRATION.md) |
> | Fix an error | [Troubleshooting](docs/reference/TROUBLESHOOTING.md) |
> | Browse all docs | [Documentation Index](docs/README.md) |

## 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+ ([`.deb`](https://github.com/nickg/nvc/releases/latest)) |
| GHDL | Recommended | VHDL analyzer (fast linting) |
| Vendor tools | Optional | Vivado / Quartus / Radiant / Libero — or `rr docker install` |

## Acknowledgments

RouteRTL stands on the shoulders of outstanding open-source projects:
[NVC](https://github.com/nickg/nvc) · [GHDL](https://github.com/ghdl/ghdl) · [Cocotb](https://github.com/cocotb/cocotb) · [xpm_vhdl](https://github.com/fransschreuder/xpm_vhdl) · [Verilator](https://github.com/verilator/verilator) · [Icarus Verilog](https://github.com/steveicarus/iverilog) · [Rich](https://github.com/Textualize/rich) · [Jinja2](https://github.com/pallets/jinja2)

## Contributing

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

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

## Contact

Built and maintained by **Daniel J. Mazure** — [routertl.dev](https://www.routertl.dev)

## 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 that substitutes for RouteRTL. Using RouteRTL to build *your own product* is **not** competing. |

</details>

Copyright © 2026 Daniel J. Mazure
