Reference Designs
Every template is a complete, working project — RTL sources, cocotb tests, and
project.yml ready to lint, simulate, and synthesize out of the box.
# List all available templates
rr init --list-templates
# Scaffold a new project from a template
rr init --template sensor_hub --name my_project
Available Templates
blinky — Minimal Edge Counter
The simplest possible RouteRTL project. Wraps the SDK's edge_counter unit
and verifies it with a single cocotb test.
Best for: First contact with RouteRTL, verifying your environment works.
rr init --template blinky --name my_blinky
cd my_blinky && rr sim
What you get:
| File | Purpose |
|---|---|
src/my_blinky_top.vhd | Wraps edge_counter — counts rising edges |
sim/cocotb/tests/test_my_blinky.py | Drives 10 edges, verifies count output |
project.yml | Xilinx Zynq-7020 config |
Concepts demonstrated: Unit instantiation, single cocotb test, basic project.yml.
counter — External Dependencies
Intermediate project showing how to pull in external libraries. Uses a synchronous FIFO from the Xilinx XPM VHDL library.
Best for: Learning the dependency system and working with third-party libraries.
rr init --template counter --name my_counter
cd my_counter && rr sim
What you get:
| File | Purpose |
|---|---|
src/my_counter_top.vhd | Cycle counter writing milestones to fifo_xpm_sync |
sim/cocotb/tests/test_my_counter.py | Reads FIFO milestones and verifies values |
libs/xpm_vhdl/ | Auto-cloned Xilinx XPM VHDL library |
Concepts demonstrated: Git-cloned dependencies, FIFO integration, generic parameters.
axi — AXI-Lite Protocol Verification
Protocol-level verification using the SDK's bus functional model drivers. Four tests exercise AXI-Lite read/write from Python.
Best for: Learning BFM-driven testing and protocol verification.
rr init --template axi --name my_axi
cd my_axi && rr sim
What you get:
| File | Purpose |
|---|---|
src/my_axi_regbank.vhd | AXI-Lite register bank (port stubs) |
sim/cocotb/tests/test_my_axi_regbank.py | 4 protocol tests: write/read, sequential, byte strobes, overwrite |
Concepts demonstrated: TbEnv setup, AxiLiteMaster/AxiLiteSlave drivers, protocol-level testing.
uart_loopback — Package Manager Integration
Demonstrates the RouteRTL package manager with real open-source IP from the Open Logic project.
Best for: Learning rr pkg add and integrating third-party IP cores.
rr init --template uart_loopback --name my_uart
cd my_uart && rr sim
What you get:
| File | Purpose |
|---|---|
src/demo_my_uart_top.vhd | UART TX wired to RX (loopback) |
sim/cocotb/tests/test_my_uart_loopback.py | Sends bytes and verifies echo |
project.yml | Includes packages section with open-logic/olo_intf_uart |
Concepts demonstrated: Package manager (rr pkg add), third-party IP integration, serial protocol testing.
zynq_spi — Production SPI Sensor Design
Real-world Zynq-7020 sensor acquisition pattern with SPI master reading a sensor and UART transmitting the results for debug.
Best for: Seeing a production-grade multi-module design with mixed protocols.
rr init --template zynq_spi --name my_sensor
cd my_sensor && rr sim
What you get:
| File | Purpose |
|---|---|
src/my_sensor_spi_sensor_reader.vhd | SPI master (8-bit cmd, 8-bit response) |
src/my_sensor_uart_debug_tx.vhd | UART TX at 115200 baud (8N1) |
src/my_sensor_spi_top.vhd | Top-level: SPI + UART + edge counter |
sim/cocotb/tests/test_my_sensor.py | SPI slave driver + UART verifier |
Concepts demonstrated: Multiple RTL modules, mixed-protocol design, production-grade testbench.
polarfire — Microchip Libero SoC
Minimal example targeting a Microchip PolarFire FPGA. Shows how project.yml
adapts to non-Xilinx vendors.
Best for: Getting started with Microchip/Libero projects.
rr init --template polarfire --name my_pf
What you get:
| File | Purpose |
|---|---|
src/units/edge_detector.vhd | SDK edge detector unit |
constraints/timing.sdc | Timing constraints |
project.yml | Microchip MPF100T-FCG484 config, Libero 2025.2 |
Concepts demonstrated: Vendor-specific configuration, SDC constraints.
What Every Template Creates
Regardless of which template you choose, rr init also scaffolds:
| File | Purpose |
|---|---|
project.yml | Main project configuration |
Makefile | SDK integration wrapper |
pyproject.toml | Python config with ruff linter settings |
.gitignore | Build artifact exclusions |
VERSION | Project version tracking |
Workflow After Scaffolding
# 1. Scaffold
rr init --template <name> --name <project_name>
# 2. Verify environment
rr doctor
# 3. Explore the design hierarchy
rr hier --forest
# 4. Run simulations
rr sim
# 5. Lint
rr lint
# 6. Synthesize
rr synth run