RAPID RTL

RAPID RTL is an advanced FPGA system design environment engineered for high-efficiency hardware development. It provides a robust, multi-vendor workflow that streamlines project generation, simulation, and verification.

Owner: Daniel J. Mazure

🚀 Key Features

• Multi-Vendor Support: Seamlessly switch between Xilinx Vivado, Lattice Radiant, and Altera Quartus workflows.
• Automated Project Generation: Create reproducible projects from a single source of truth (project.yml or file_list.mk) using TCL automation.
• Advanced Register Bank System:
  • Define registers in human-readable YAML.
  • Automatically generate VHDL packages, Python constants, and C headers.
  • Built-in versioning and consistency checks.
• Smart Dependency Management:
  • Automatic handling of external IP and VHDL libraries.
  • Intelligent project.yml integration.
• Modern Simulation Environment:
  • Cocotb integration for Python-based testbenches.
  • Combined VHDL/Verilog Support: Test mixed-language designs seamlessly.
  • Multiple Backends: Support for GHDL, NVC (VHDL), and Verilator (Verilog/SystemVerilog).
• Containerized Workflow: Docker support for both full vendor suites (Vivado) and lightweight open-source simulation tools.

📂 Repository Structure

rapidrtl/
├── tcl/               # TCL scripts for Vivado and Radiant project automation
├── tools/             # Helper utilities
│   ├── regbank-utils/ # Scripts for register bank generation (YAML -> HDL/Python/C)
│   ├── docker/        # Vendor-specific Docker scripts (Vivado)
│   ├── oss-docker/    # Lightweight OSS simulation Docker (Verilator, GHDL, NVC)
│   └── sh/            # Shell scripts for linting, parsing, and maintenance
├── sim/               # Simulation environment
│   ├── cocotb/        # Cocotb testbenches and launchers
│   └── wrappers/      # Simulation wrappers
├── src/               # RTL source files
│   ├── pkg/           # VHDL packages (system_regbank_pkg.vhd, etc.)
│   └── regbank/       # Generated register bank artifacts
├── Makefile           # Master Makefile for all project operations
└── file_list.mk       # Master list of source files

🛠️ Prerequisites

To use the full capabilities of RAPID RTL, you will need:

• FPGA Tools:
  • Xilinx Vivado (2024.1 or later)
  • Lattice Radiant (2024.2 or later)
• Simulation:
  • GHDL or NVC (for VHDL)
  • Verilator (v5.0 or later, for Verilog/SystemVerilog)
• Software:
  • Python 3.10+
  • Docker (highly recommended)
  • Git LFS (for large binary artifacts)

🚦 Getting Started

0. Install Git Hooks (Optional)

Install pre-commit hooks to ensure unit tests pass before committing:

make install-hooks

1. Project Configuration

1. Source Files: Edit file_list.mk to add your VHDL/Verilog source files.
2. Environment:
   • Multi-vendor settings are controlled via tcl/environment.tcl.
   • Project generation options are in tcl/xilinx/project_options_system.tcl or equivalent Lattice scripts.
3. Registers: Define your memory map in tools/regbank-utils/regbank_schema.yml.

2. Build Commands

Rapid RTL uses a comprehensive Makefile to manage the flow.

Project Creation:

make project VENDOR=xilinx   # Create a Vivado project
make project VENDOR=lattice  # Create a Radiant project

Synthesis & Implementation:

make synthesis      # Run synthesis
make implementation # Run implementation
make bitstream      # Generate bitstream

Register Bank:

make parse_regbank  # Validate YAML and generate VHDL packages

3. Simulation (Cocotb)

Setup: Initialize the simulation environment (downloads dependencies like cocotbext-i2c, cocotbext-uart):

make -C sim bootstrap

Run Tests:

The SDK uses the cocotb_tools.runner for orchestration. To run a test, set the PYTHONPATH to include the SDK root and run your Python test script:

# Run a specific VHDL test with GHDL
export SIM=ghdl
python3 sim/cocotb/tests/units/test_edge_detector.py

# Run a Verilog test with Verilator
export SIM=verilator
python3 sim/cocotb/tests/units/test_verilog_counter.py

Note: The SIM environment variable defaults to ghdl if not specified.

🐳 Docker Support

Vendor Environment (Vivado)

Full vendor suite for synthesis and implementation.

make docker-build  # Build the project Docker image
make docker-shell  # Start the container

OSS Simulation Environment

Lightweight environment for fast simulations (GHDL, NVC, Verilator).

cd tools/oss-docker
docker-compose up -d
docker-compose exec rapidrtl-oss bash

📚 Documentation

For detailed documentation, see the docs/ folder:

• Documentation Index - Central hub for all documentation
• Analysis Report - Technical pros/cons and improvement suggestions
• Cocotb Simulation Guide - Running simulations with GHDL/NVC
• Backend Development Guide - Adding new simulator backends

Tool Documentation

📜 License

MIT License. See Makefile header for details.