Initializing SDK Environment...

Reference Designs

Every template provides a complete, working project — RTL sources, cocotb tests, and a project.yml file ready for immediate linting, simulation, and synthesis.


# List all available templates
rr init --list-templates

# Scaffold a project from a template (rr init works in the current directory)
mkdir my_project && cd my_project
rr init --template edge_counter --name my_project

File names keep the template's names; rr init rewrites the entity names, project.yml, and the cocotb test tops to match your --name.

Available Templates

edge_counter — Minimal Edge Counter

A minimal 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.


mkdir my_edge && cd my_edge
rr init --template edge_counter --name my_edge
rr sim run

What you get:

File	Purpose
`src/edge_counter_top.vhd`	Wraps `edge_counter` — counts rising edges
`sim/cocotb/tests/test_edge_counter.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.


mkdir my_counter && cd my_counter
rr init --template counter --name my_counter
rr sim run

What you get:

File	Purpose
`src/counter_top.vhd`	Cycle counter writing milestones to `fifo_xpm_sync`
`sim/cocotb/tests/test_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.


mkdir my_axi && cd my_axi
rr init --template axi --name my_axi
rr sim run

What you get:

File	Purpose
`src/axi_regbank.vhd`	AXI-Lite register bank (port stubs)
`sim/cocotb/tests/test_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.


mkdir my_uart && cd my_uart
rr init --template uart_loopback --name my_uart
rr sim run

What you get:

File	Purpose
`src/demo_uart_top.vhd`	UART TX wired to RX (loopback)
`sim/cocotb/tests/test_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.


mkdir my_sensor && cd my_sensor
rr init --template zynq_spi --name my_sensor
rr sim run

What you get:

File	Purpose
`src/spi_sensor_reader.vhd`	SPI master (8-bit cmd, 8-bit response)
`src/uart_debug_tx.vhd`	UART TX at 115200 baud (8N1)
`src/zynq_spi_top.vhd`	Top-level: SPI + UART + edge counter
`sim/cocotb/tests/test_zynq_spi.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.


mkdir my_pf && cd my_pf
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
mkdir <project_name> && cd <project_name>
rr init --template <name> --name <project_name>

# 2. Verify environment
rr doctor

# 3. Explore the design hierarchy
rr hierarchy --forest

# 4. Run simulations
rr sim run

# 5. Lint
rr linting

# 6. Synthesize
rr synth run

Loading docs...

Reference Designs

Every template provides a complete, working project — RTL sources, cocotb tests, and a project.yml file ready for immediate linting, simulation, and synthesis.


# List all available templates
rr init --list-templates

# Scaffold a project from a template (rr init works in the current directory)
mkdir my_project && cd my_project
rr init --template edge_counter --name my_project

File names keep the template's names; rr init rewrites the entity names, project.yml, and the cocotb test tops to match your --name.

Available Templates

edge_counter — Minimal Edge Counter

A minimal 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.


mkdir my_edge && cd my_edge
rr init --template edge_counter --name my_edge
rr sim run

What you get:

File	Purpose
`src/edge_counter_top.vhd`	Wraps `edge_counter` — counts rising edges
`sim/cocotb/tests/test_edge_counter.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.


mkdir my_counter && cd my_counter
rr init --template counter --name my_counter
rr sim run

What you get:

File	Purpose
`src/counter_top.vhd`	Cycle counter writing milestones to `fifo_xpm_sync`
`sim/cocotb/tests/test_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.


mkdir my_axi && cd my_axi
rr init --template axi --name my_axi
rr sim run

What you get:

File	Purpose
`src/axi_regbank.vhd`	AXI-Lite register bank (port stubs)
`sim/cocotb/tests/test_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.


mkdir my_uart && cd my_uart
rr init --template uart_loopback --name my_uart
rr sim run

What you get:

File	Purpose
`src/demo_uart_top.vhd`	UART TX wired to RX (loopback)
`sim/cocotb/tests/test_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.


mkdir my_sensor && cd my_sensor
rr init --template zynq_spi --name my_sensor
rr sim run

What you get:

File	Purpose
`src/spi_sensor_reader.vhd`	SPI master (8-bit cmd, 8-bit response)
`src/uart_debug_tx.vhd`	UART TX at 115200 baud (8N1)
`src/zynq_spi_top.vhd`	Top-level: SPI + UART + edge counter
`sim/cocotb/tests/test_zynq_spi.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.


mkdir my_pf && cd my_pf
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
mkdir <project_name> && cd <project_name>
rr init --template <name> --name <project_name>

# 2. Verify environment
rr doctor

# 3. Explore the design hierarchy
rr hierarchy --forest

# 4. Run simulations
rr sim run

# 5. Lint
rr linting

# 6. Synthesize
rr synth run