Simulator Backends & CI/CD Strategy

This document outlines the supported simulator backends in RouteRTL, their licensing implications, and strategies for CI/CD integration.

1. Supported Simulators

RouteRTL uses Cocotb as its testbench framework, which supports various simulators via standard interfaces (VPI, VHPI, FLI).

2. Adding a New Backend

To add support for a new simulator (e.g., Riviera-PRO), implement a backend class in sim/cocotb/engine/backends/ (relative to SDK root).

Implementation Pattern

1. Backend Class: Create riviera_backend.py inheriting from SimulatorBackend.
2. Compilation: Implement compile() using the vendor's tools (e.g., vlib, vcom).
3. Elaboration/Run: Implement simulate() to invoke the simulator with Cocotb's VPI hooks.
4. Auto-Detection: Update sim_engine.py to detect the simulator executable and register the backend.

# Example Pattern
class RivieraBackend(SimulatorBackend):
    def compile(self):
        self.exec("vlib", "work")
        self.exec("vcom", "-work", "work", *self.sources)

    def simulate(self):
        # Cocotb requires specific VPI lib arguments
        self.exec("vsim", "-c", "-do", "run -all", ...)

3. CI/CD Strategy

Open Source Simulators (GHDL, NVC, Icarus Verilog)

• Default Choice: These should be the default for all CI pipelines.
• Installation: We recommend installing NVC via the upstream .deb package (v1.19.3+) to avoid building from source. See the NVC Releases page.
• Docker Integration: Use standard images (e.g., ghdl/ghdl:bullseye-mcode) in Bitbucket/GitLab/GitHub runners.
• Cost: Free.

Commercial Simulators (Riviera-PRO, Questa, Vivado)

• Licensing: These require a valid license (floating or node-locked).
• Constraint: Cannot run on standard shared runner infrastructure (GitHub Actions, Bitbucket Pipelines) without connecting to a license server.
• Strategy:
  • Conditional Execution: Only run these tests if the environment variable ALDEC_LICENSE_FILE (or equivalent) is present.
  • Self-Hosted Runners: Use self-hosted runners that have VPN/LAN access to your license server.
  • Manual Trigger: Configure CI to skip these tests by default and run them only on manual triggers or specific protected branches.

4. Recommendations for RouteRTL Users

• Primary Workflow: Develop and verify locally using GHDL, NVC, Verilator, or Icarus Verilog.
• Release Validation: If you have a commercial license (e.g., Vivado WebPACK or Enterprise), validating critical IP blocks on the commercial simulator before tape-out is recommended to catch backend-specific bugs.
• CI/CD: Stick to GHDL/NVC/Icarus/Verilator for pull requests to ensure fast, free feedback loops.