RapidRTL SDK User Guide

Welcome to the RapidRTL SDK! This framework provides a unified build system, simulation engine, and verification tools for FPGA development.

The SDK is designed to be a lightweight dependency for your hardware projects, typically included as a Git Submodule.

# In your project root
git submodule add git@bitbucket.org:dasjimaz/rapidrtl.git vendor/rapidrtl
git submodule update --init --recursive

[!TIP] This architecture separates your proprietary RTL code and testbenches from the shared SDK build infrastructure.

2. Project Setup

Option A: Automatic Initialization

Use the included helper script to scaffold a new project:

python3 vendor/rapidrtl/tools/project-manager/init_project.py --name "my_project" --vendor xilinx

The script will interactively prompt for:

• Top module name
• FPGA part number
• Source directory (default: src)
• Simulation directory (default: sim)
• Constraints directory (default: xdc)

For non-interactive mode, provide all arguments:

python3 vendor/rapidrtl/tools/project-manager/init_project.py \
    --name "my_project" \
    --vendor xilinx \
    --part "xc7z020clg400-1" \
    --src-dir hw/rtl \
    --sim-dir hw/sim

Option B: Manual Setup

1. Create project.yml: This is the heart of your project configuration.
2. Create Makefile: Include the SDK master makefile.

Minimal Makefile

ROOT_DIR := $(shell pwd)
include vendor/rapidrtl/tools/Common.mk

The project.yml file is the "single source of truth" for your project.

project:
  name: my_sniffer_project
  top_module: uart_sniffer      # Synthesis top-level
  top_sim: tb_uart_sniffer      # Simulation top-level

hardware:
  vendor: xilinx                # xilinx, lattice, or altera
  part: "xc7z020clg400-1"
  platform: my_custom_board

# Automatically find sources in src/ and vendor/rapidrtl/src
auto_sources: true

features:
  regbank: true                 # Enable automated register bank generation

simulation:
  test_dir: sim/cocotb/tests    # Custom location for tests

# Custom directory paths (for non-standard project structures)
paths:
  sources: hw/rtl               # Default: src
  simulation: hw/sim            # Default: sim
  constraints: hw/constraints   # Default: xdc

# Tool-specific tweaks
vendor_overrides:
  xilinx:
    enable_pblocks: true
  lattice:
    synthesis_tool: lse

# Quality control for Hooks
hooks:
  pre_commit:
    enabled: true
    lint: true
    check_yaml: true
    tests:
      - tb_uart_sniffer

dependencies:
  xpm_vhdl:
    url: https://github.com/Xilinx/XilinxPowerAndPerformance.git
    fallback_url: https://github.com/another-mirror/xpm_vhdl.git
    path: libs/xpm_vhdl
    library: xpm

[!TIP] The paths: section allows you to use a non-standard directory structure. If omitted, defaults (src, sim, xdc) are used.

4. Quality Control

The SDK provides robust tools to ensure code quality and consistency.

Git Hooks

The SDK provides a pre-configured git hook that runs linting and tests automatically before every commit.

To Install:

make install-hooks

This copies the hook script to .git/hooks/pre-commit.

Smart Linting

The SDK uses a "Smart Linter" that automatically detects hierarchy roots (forest detection) to optimize the linting process.

Usage:

# Auto-detect hierarchies and lint everything (default)
make linting

# Target a specific top-level module (resolves dependencies automatically)
make linting TOP=my_module

How it works:

1. Forest Detection: The linter scans your source files to identify independent hierarchies.
2. Dependency Resolution: For each hierarchy (or the specified TOP), it calculates the exact dependency tree.
3. Targeted Linting: It runs the linter only on the relevant files for that hierarchy, reducing noise and false positives.

5. Dependency Management

The SDK includes a dependency manager (tools/project-manager/manage_dependencies.py) to handle external libraries automatically.

Configuration: Define dependencies in your project.yml:

dependencies:
  library_name:
    url: https://git.example.com/repo.git
    path: libs/local_path  # Where to clone it
    library: lib_name      # VHDL library name

Usage: Dependencies are automatically checked and cloned when you run implementation or simulation commands. You can also trigger it manually:

make update-config

6. Development Workflow

• Run Simulation:

  • Single test: Set SIM (optional) and run the python script:

    export SIM=ghdl
    python3 sim/cocotb/tests/test_my_feature.py
    

  • Regression (All tests): Auto-discover and run all test_*.py files:

    make simulation
    

    Configured via simulation.test_dir in project.yml.

• Build Bitstream: make bitstream
• Clean: make clean
• Update SDK: make update-sdk
  • Pulls the latest version of the RapidRTL submodule and displays the new commit hash.
• Update Source Lists:
  • make update-src: Scans src/ for new RTL files and appends them to project.yml.
  • make update-sim: Scans sim/ for new testbenches (tb_*.vhd) and appends them to project.yml.
  • make update-xdc: Scans xdc/ for new constraint files (*.xdc) and appends them to project.yml.
  • make update-xdc: Scans xdc/ for new constraint files (*.xdc) and appends them to project.yml.
  • make update-tcl: Scans tcl/ for new Tcl scripts and hooks.
  • make update-all: Runs all updates.
• View Project Sources: make sources
  • Displays a categorized list of all files currently tracked by the build system.
• View Hierarchy: make hierarchy TOP=module_name
  • Displays the dependency tree for the specified module.
• Waveform Viewing:
  • make waves TOP=tb_name: Opens the waveform for a previous simulation.
  • make sim-waves MODULE=tb_name: Runs simulation and immediately opens the waveform.
  • Simulations generate waveforms by default. To disable: make simulation WAVES=0.
• RTL Schematics: make schematic TOP=module_name
  • Generates an SVG schematic of the specified module (using Yosys/Netlistsvg) in schematics/.
• Non-Project Mode Synthesis: make npm-synthesis TOP=module_name
  • Runs Vivado synthesis for the specified module without a full project file.
  • Automatically resolves dependencies using dependency_resolver.py.
  • Outputs a .dcp checkpoint to dcp/<module>/.
  • Ideal for quick iteration on sub-modules or IP packaging.

7. Directory Structure

Recommended structure for your project:

my-project/
├── project.yml
├── Makefile
├── src/                # Your RTL (VHDL/Verilog) code
├── sim/
│   └── cocotb/tests/   # Your Python tests
├── xdc/                # Constraints
└── vendor/
    └── rapidrtl/       # The SDK

8. Build System Variables

The RapidRTL build system populates several variables from your project.yml. These are available in your Makefile after including Common.mk:

You can inspect the current values of these variables at any time by running:

make sources

9. How to Remove the SDK (Submodule)

If you need to un-track the SDK from your repository, use the provided make target:

make remove-sdk

(This de-initializes the submodule and removes the vendor/rapidrtl directory)

Re-Initialize Project

If you need to wipe all generated artifacts (Makefile, project.yml, build folders) and start fresh:

make reinit-project

WARNING: This deletes your project.yml. Use with caution.

10. Register Bank & Versioning

The SDK handles register bank creation split into two parts: Static Schema and Dynamic Build Info.

How It Works

1. Static Schema: You define project_regbank.yml. This dictates the memory map.
   • Generated to: src/pkg/system_regbank_pkg.vhd (Address constants, Types).
   • Status: Always Created (if YAML exists).
2. Dynamic Build Info: The SDK calculates version, git hash, and build date at build time.
   • Generated to: src/pkg/rom_info_pkg.vhd (Constants: C_GIT_HASH, C_BUILD_DATE).
   • Status: Always Updated on every make synthesis.

[!NOTE] The SDK does NOT modify your project_regbank.yml. It injects build values directly into the VHDL via rom_info_pkg.

Managing Registers

You can add or remove registers interactively using Make targets:

# Interactive wizard to add a new register
make add-register

# Remove a specific register by name
make remove-register NAME=my_reg

Manual Generation

While generation happens automatically during build, you can verify your schema manually:

# Generate VHDL packages from YAML
make parse_regbank

# Generate ROM info package (Git hash, Build date)
make rom_info

11. Regression Testing

To ensure your project remains compatible with SDK updates, we recommend running the Integration Test suite.

Should I add this to Pre-Commit? No. The full integration test (which runs make synthesis) is too heavy (minutes) for a pre-commit hook.

Recommendation:

• Pre-Commit: Run make lint (fast).
• CI / Nightly: Run python3 vendor/rapidrtl/tools/project-manager/tests/test_client_integration.py (comprehensive).

12. Test Generation Tools

The SDK includes cocotb-testgen, a tool to automatically generate Cocotb test stubs from your VHDL sources.

Usage:

Option A: Make Target (Recommended)

make testgen

(Creates stubs in sim/cocotb/tests for sources in src/)

Option B: Manual Execution

python3 vendor/rapidrtl/tools/cocotb-testgen/gen_cocotb_structure.py \
    --src src \
    --out sim/cocotb/tests

(Use this for custom paths or source directories)

See tools/cocotb-testgen/README.md for full documentation.

13. VUnit: Native VHDL Testbenches

Usage

# Run all VUnit tests
make vunit

# List available tests
make vunit-list

# Run with waveform viewer
make vunit-gui

See sim/vunit/README.md for full documentation on writing testbenches, adding DUT sources, and using the check library.

14. Docker Development Environment

The SDK includes pre-configured Docker environments for consistent, reproducible builds across different machines.

Available Environments

Usage

# Build the container image
make docker-build

# Start an interactive shell (your project is mounted inside)
make docker-shell

# Run a specific command inside the container
make docker-run CMD="make simulation"

# Use Vivado environment instead of OSS
make docker-shell DOCKER_ENV=vivado

[!TIP] The container mounts your project directory. Changes inside the container are reflected on your host filesystem.

15. Advanced Tools

The SDK includes specialized tools for power users in tools/.

ILA Generator (tools/ila-gen)

Automates the creation of Xilinx Integrated Logic Analyzers (ILA).

• Input: YAML configuration defining signals to probe.
• Output: VHDL/Verilog instantiation snippet + TCL debug setup.
• Usage: python3 vendor/rapidrtl/tools/ila-gen/gen_ila.py config.yaml

Report Analyzer (tools/report-analyzer)

Scripts to parse and filter verbose Vivado reports.

• filter_control_sets.py: Analyzes control set reduction issues.
• utilization_filter.py: Extracts hierarchical utilization for specific modules.

See tools/report-analyzer/README.md for details.

See tools/docker/README.md for detailed Docker documentation.