Frequently Asked Questions

1. How is RouteRTL different from FuSoC?

FuSoC is a package manager and build dispatcher — you curate .core files with CAPI2 descriptors, pick a backend, and get a build. It excels at composing reusable IP libraries via its VLNV naming convention and provider system.

RouteRTL is an integrated development platform. You write one project.yml and get automatic source discovery, dependency resolution, hierarchy-aware linting, cocotb simulation with protocol drivers, code generation, multi-vendor synthesis, and bitstream output — without maintaining manual file lists or per-core descriptors.

In short: FuSoC gives you flexibility and modularity; RouteRTL gives you an opinionated, end-to-end workflow from RTL to bitstream.

2. What FPGA vendors are supported?

• Xilinx / AMD — Vivado (+ Vitis HLS, embedded Linux via .xsa)
• Intel / Altera — Quartus Pro, Standard, and Lite editions
• Lattice — Radiant
• Microchip — Libero SoC
• Open-source — Yosys + nextpnr

Switching vendors is a one-line change in project.yml. Constraints, IP, and vendor-specific options are handled per-target in the targets/ directory.

3. Do I need to manually list my source files?

No. RouteRTL parses your VHDL, Verilog, and SystemVerilog sources, detects entity/module declarations, resolves the dependency graph via post-order DFS, and compiles in the correct order automatically.

It also auto-detects custom libraries from library clauses and use statements — no manual libraries.json needed for standard projects.

This has been validated against real-world designs with 77+ entities at 100% accuracy.

4. Can I add RouteRTL to an existing Vivado or Quartus project?

Yes. See the Existing Project Migration guide.

RouteRTL wraps vendor TCL natively — your existing constraints (.xdc, .sdc), IP cores, and project settings carry over. You don't need to start from scratch or rewrite your build flow.

5. What simulators does RouteRTL support?

• Open-source: NVC, GHDL, Verilator, Icarus Verilog
• Commercial: QuestaSim, Riviera-PRO

Cocotb 2.0+ is natively integrated. RouteRTL ships with built-in protocol drivers for:

• AXI4, AXI4-Lite, Avalon-MM, Native Memory
• UART (TX/RX), SPI (Master/Slave), I2C, QSPI

Waveform output is configurable per backend (FST, VCD, GHW, WLF).

See the Simulator Backends reference for details.

6. Is RouteRTL open source?

Dual-licensed:

• MIT — CLI, build system, cocotb drivers, hooks, documentation, examples. Use, fork, and modify freely.
• PolyForm Shield 1.0 — Compiled core (parser, dependency resolver, linter engine). Free to use for any purpose except building a competing product.

This means you can use RouteRTL commercially in your own FPGA projects without restriction. The Shield license only prevents someone from repackaging the core as a rival SDK.

7. How do I install it?

pip install routertl

Python 3.10+ required. Then verify your vendor toolchain:

rr doctor

rr doctor checks that your FPGA tools (Vivado, Quartus, etc.) are reachable and correctly configured. See the Installation Guide for platform-specific setup (Linux, WSL2, macOS).

8. Can RouteRTL generate RTL code?

Yes. Built-in generators include:

• Bridge generator — AXI ↔ Avalon ↔ Native Memory crossbar, with SystemVerilog Assertions (SVA) for protocol compliance.
• Register bank generator — YAML register description → VHDL + C headers + HTML documentation. One source of truth for hardware and firmware.
• Test generator — Cocotb boilerplate from entity/module declarations (rr testgen <entity>).
• IP auto-discovery — Scans existing source trees and proposes an ip.yml manifest (rr ip auto-discover).

9. Does it work in CI/CD?

Yes. RouteRTL is designed for automated workflows:

• Pre-commit quality gates — lint, YAML validation, Python checks, and test execution block commits on failure. Configured in project.yml:

  hooks:
    pre_commit:
      lint: true
      check_yaml: true
      lint_python: true
      tests: auto
  

• Docker provisioning — rr docker install vivado (or quartus, radiant, libero) gives you deterministic build environments across local dev and CI.

• Standard CI systems — GitHub Actions, GitLab CI, Bitbucket Pipelines, and Jenkins all work. The CLI is a single pip install with no system dependencies beyond the vendor tools themselves.

10. Does RouteRTL include a waveform viewer?

Yes. RouteRTL ships with logic-trace, a hardware-accelerated waveform viewer built from the ground up as a modern replacement for GTKWave.

When you run rr sim, logic-trace is automatically downloaded on first use and launched with your simulation output — no manual tool switching.

Key features:

• 60 FPS OpenGL rendering — smooth pan/zoom on traces with millions of transitions, using hierarchical LOD (renders in O(screen width), not O(data))
• Multi-format support — VCD, FST, GHW (GHDL native), Vivado ILA CSV, and its own .ltrace JSON format
• Built-in protocol decoders — UART (auto-baud), SPI, I2C, AXI4, AXI-Stream, with chainable HLA (Higher-Level Analysis) stacking
• Plugin SDK (MIT) — write custom protocol decoders as .so/.dll plugins
• Scriptable console — command palette, fuzzy search, macro recording, undo/redo on all operations
• Hot reload — edit RTL, re-run simulation, waveform refreshes automatically
• Virtual signals — expression engine for AND, OR, edge detect, bus slicing, arithmetic on existing channels
• Wireshark-style data table — decoded protocol transactions with search

logic-trace is free (proprietary binary + MIT plugin SDK) and available as an AppImage (Linux) or zip (Windows).

11. Where do I get help if I hit a problem?

1. Check the Troubleshooting Guide — organized error catalog by build phase (environment, simulation, synthesis, implementation).
2. GitHub Discussions — for questions, "how do I..." topics, and general usage help.
3. GitHub Issues — for confirmed bugs and reproducible problems only.

RouteRTL is a small-team project. There is no SLA on response times, but we read everything. Well-written bug reports with reproducible steps get addressed fastest.