RouteRTL SDK Developer Guide

This document is intended for developers and maintainers of the RouteRTL SDK itself. If you are a user of the SDK looking to build an FPGA project, please see the main README.md and SDK User Guide.

🏗️ Philosophy

RouteRTL is designed as a framework, not just a collection of scripts. It strictly separates "User Project" concerns from "SDK Infrastructure" concerns.

• SDK (Vendor): Located in vendor/routertl/. Contains generic build scripts, verification engines, and reusable IP.
• Client Project: The root repository. Contains the actual RTL, constraints, and project-specific config.

As an SDK developer, your goal is to ensure the SDK layer remains generic, robust, and properly abstracted.

📂 Repository Structure (Deep Dive)

The SDK uses a functional organization:

vendor/routertl/
├── tcl/               # TCL scripts for Vendor Tools
│   ├── xilinx/        # Vivado project generation, synthesis, impl scripts
│   ├── lattice/       # Radiant project generation scripts
│   └── altera/        # Quartus scripts (experimental)
├── tools/             # Python & Shell utilities
│   ├── project-manager/ # The core: init_project, dependency_resolver, smart_linter
│   ├── regbank-utils/   # YAML → VHDL/C/Python register generation
│   ├── cocotb-testgen/  # Auto-generates test stubs from VHDL entities
│   ├── docker/          # Unified Docker images (sim, vivado, quartus, etc.)
│   └── sh/              # Miscellaneous shell helpers
├── sim/               # Simulation Engine
│   ├── cocotb/        # The Python testbench runner
│   │   ├── engine/    # Core simulation logic
│   │   ├── docs/      # Backend development docs
│   │   └── tests/     # Regression tests for the simulation engine
│   └── wrappers/      # HDL wrappers for simulation
├── src/               # SDK-provided RTL
│   ├── pkg/           # Common VHDL packages (axi_pkg, etc.)
│   └── units/         # Generic IP blocks (FIFOs, CDCs, etc.)
└── docs/              # Documentation

🛠️ Setting Up Your Dev Environment

As an SDK contributor, you should install the pre-commit hooks to ensure you don't break the core logic.

1. Install Git Hooks

The hooks will run unit tests for the project-manager and smart_linter before every commit.

make install-hooks

2. Run Internal Tests

To verify the project-manager logic (dependency resolution, proper YAML parsing):

make regression

To verify the simulation engine itself (internal regression):

make sim-regression

🔌 Adding Support for New Tools

1. Adding a New Simulator Backend

All simulation backends (GHDL, NVC, Verilator, Icarus) are plugins in sim/cocotb/engine/backends/. To add a new backend (e.g., Questa, Xcelium), refer to sim/cocotb/docs/BACKEND_DEVELOPMENT.md.

2. Adding a New Vendor Flow

Vendor flows are controlled via Common.mk and the tcl/ directory.

1. Create TCL Scripts: Add a new folder tcl/<new_vendor>/ with scripts for project generation and synthesis.
2. Update Makefile:
   • Add detection logic in tools/Common.mk.
   • Create a target to invoke the new TCL scripts (e.g., make project VENDOR=<new_vendor>).
3. Update init_project.py: Allow the new vendor in the --vendor argument list.

🧰 Internal Tool Documentation

Detailed documentation for specific internal tools:

🚀 Release Process

1. Update Version: Bump the version in VERSION file.
2. Changelog: precise entries in CHANGELOG.md.
3. Tag: Git tag the commit (git tag -a v1.x.x -m "Release v1.x.x").
4. Push: Push to the main repository.

Note: When you push changes to the SDK, client projects must run make update-sdk to pull the new commit.