RapidRTL SDK Feature Roadmap

This document outlines potential features to extend the RapidRTL SDK beyond its current RTL synthesis, simulation, and dependency resolution capabilities.

1. Timing Report Analysis

Goal

Provide automated parsing and validation of post-synthesis/post-implementation timing reports to catch timing failures early and provide actionable feedback.

Challenges

• Vendor Dependency: Each vendor (Xilinx/AMD, Lattice, Intel/Altera) produces timing reports in different formats.
  • Xilinx: report_timing_summary outputs text with sections like "Timing Summary", "Intra-Clock Paths", "Inter-Clock Paths". Can also export as .rpx (XML-based).
  • Lattice (Radiant): Uses PAR timing report, different structure.
  • Intel (Quartus): Uses TimeQuest Timing Analyzer, .sta.rpt format.
• RTL Dependency: Clock names, generated clocks, and constraint names are project-specific.

Proposed Approach

1. Abstraction Layer: Create a TimingReport Python class with vendor-specific parsers.

   tools/report-analyzer/
   ├── timing_report.py       # Abstract base class
   ├── xilinx_parser.py       # Parses Vivado timing summaries
   ├── lattice_parser.py      # Parses Radiant timing reports
   └── intel_parser.py        # Parses Quartus STA reports
   

2. Core Metrics to Extract:

   • Worst Negative Slack (WNS) / Total Negative Slack (TNS)
   • Worst Hold Slack (WHS) / Total Hold Slack (THS)
   • Number of failing endpoints
   • Critical path summary (start/end registers, clock domain)

3. Makefile Integration:

   timing-check: ## Analyze timing report for failures (after implementation)
       @python3 $(SDK_ROOT)/tools/report-analyzer/check_timing.py \
           --vendor $(VENDOR) \
           --report dcp/$(TOP)/$(TOP)_timing.rpt \
           --top-n 10
   

4. Output:

   • ✅ TIMING MET: WNS = 0.234ns (Green)

   • ❌ TIMING FAILED: WNS = -0.150ns (5 failing paths) (Red)

   • Top N Failing Paths (Required Feature):

     Top 10 Failing Paths:
     1. -0.150ns: clk_100mhz → reg_a/D → reg_b/Q
     2. -0.120ns: clk_100mhz → fifo_inst/wr_ptr → fifo_inst/rd_ptr
     ...
     

Implementation Priority: Medium

Requires sample reports from each vendor to develop parsers.

2. Constraints Analysis / Clock Inference

Goal

Assist users in generating or validating timing constraints (XDC/SDC) based on the RTL structure.

Challenges

• RTL Dependency: Clock sources, clock domains, and CDC paths are entirely design-specific.
• Inference Accuracy: Automatic clock inference from RTL is non-trivial (e.g., differentiating a clock from a data signal).
• Exception Paths (False Paths / Multi-Cycle Paths): These are designer-intent decisions, not easily automatable.

Proposed Approach (Conservative)

Rather than full inference, provide templates and validation utilities:

1. Constraint Templates (make gen-xdc-template): Generates a starter XDC file with common patterns:

   • Primary clock definition (create_clock)
   • I/O delay templates (set_input_delay, set_output_delay)
   • set_max_delay with -datapath_only tips for CDC paths
   • Placeholder for false paths

   Example output:

   # Primary Clock
   create_clock -period 10.000 -name clk_100mhz [get_ports clk]
   
   # CDC Paths (use set_max_delay -datapath_only for async crossings)
   # set_max_delay -datapath_only -from [get_cells src_reg] -to [get_cells dst_reg] 10.0
   
   # False Paths
   # set_false_path -from [get_clocks clk_a] -to [get_clocks clk_b]
   

2. Clock Domain Report (RTL-based):

   [!WARNING] Complexity Note: Clocks can be named differently across RTL modules. Tracking clock domains accurately requires hierarchical analysis of clock signal propagation—a significant parser effort with unclear benefit-to-effort ratio.

   Recommendation: Defer this feature or implement as a best-effort heuristic with explicit caveats.

3. XDC Linter:

   • Check XDC syntax for common mistakes.
   • Warn if a clock is defined but not used in the design.
   • Warn if a constraint references a non-existent port/cell.

   [!NOTE] Limitation: Synthesis tools often rename nets (e.g., my_signal → my_signal_reg). XDC validation against RTL may produce false positives. Consider post-synthesis validation against the elaborated netlist instead.

Makefile Integration

gen-xdc-template: ## Generate XDC constraint template
    @python3 $(SDK_ROOT)/tools/constraint-analyzer/gen_template.py \
        --src $(SRC_DIR) --top $(TOP) --out $(XDC_DIR)/$(TOP)_timing.xdc

xdc-lint: ## Validate XDC constraint syntax and references
    @python3 $(SDK_ROOT)/tools/constraint-analyzer/xdc_lint.py \
        --xdc $(XDC_FILES) --src $(SRC_DIR)

Implementation Priority: Low-Medium

Template generation is a simpler starting point. Full CDC analysis is high complexity with limited ROI.

3. Waveform Viewing Integration

Goal

Streamline the workflow of viewing simulation waveforms generated by GHDL, NVC, or Verilator.

Design Decisions

[!IMPORTANT] Waveform generation should be the default behavior. Disabling waves should be explicit (e.g., WAVES=0 or --no-waves), useful for regressions where speed matters.

Proposed Workflows

make waves (Open Existing Waveform)

Opens the most recent waveform file for a specified top module.

• Behavior:
  1. Look for sim_build/<TOP>/<TOP>.ghw (GHDL) or .vcd / .fst (Verilator/NVC).
  2. If found, launch GTKWave (or nvc --wave).
  3. If not found, print error: "No waveform found for <TOP>. Run make sim MODULE=<TOP> first."
• Usage: make waves TOP=tb_uart_sniffer

make sim (Default: Generates Waves)

Standard simulation now generates waves by default.

• Disable waves for regressions: make simulation WAVES=0

make sim-waves (Explicit Run + Open)

Runs simulation and opens viewer after completion.

• Usage: make sim-waves MODULE=tb_uart_sniffer

Tool Detection

• Check for gtkwave in $PATH.
• If not found, suggest installation or use nvc --wave fallback for NVC users.

Makefile Integration

# Default: waves enabled
WAVES ?= 1

waves: ## Open waveform viewer for a module (Usage: make waves TOP=tb_name)
    @if [ -z "$(TOP)" ]; then echo "❌ Error: TOP not specified."; exit 1; fi
    @WAVE_FILE=$$(find sim_build -name "$(TOP).ghw" -o -name "$(TOP).vcd" | head -1); \
    if [ -n "$$WAVE_FILE" ]; then \
        gtkwave $$WAVE_FILE &; \
    else \
        echo "❌ No waveform found for $(TOP). Run simulation first."; \
    fi

sim-waves: ## Run simulation and open waveform viewer
    @$(MAKE) sim MODULE=$(MODULE) WAVES=1
    @$(MAKE) waves TOP=$(MODULE)

Implementation Priority: 🟢 High

Low complexity, high daily user value.

4. Code Coverage

Goal

Provide code coverage metrics (statement, branch, toggle, FSM) for RTL designs during simulation.

Licensing Reality

[!IMPORTANT] Most robust code coverage tools for VHDL/Verilog are commercial/paid:

• Synopsys VCS: Paid.
• Cadence Xcelium: Paid.
• Mentor/Siemens Questa: Paid.
• Xilinx Vivado Simulator: Paid (part of Enterprise edition for coverage).

Open-Source Alternatives

Proposed Approach

Since Verilator supports coverage, we can add support for Verilog/SV designs:

1. Enable Coverage in Verilator Build:

   • Modify Cocotb Verilator build args to include --coverage.
   • Post-simulation, collect .dat files.

2. Coverage Report Generation:

   • Run verilator_coverage --write-info coverage.info <files>.
   • Optionally generate HTML report with genhtml (lcov).

3. Makefile Target:

   coverage: ## Run simulation with code coverage (Verilog only, requires Verilator)
       @SIM=verilator EXTRA_ARGS="--coverage" make simulation
       @verilator_coverage --write-info coverage.info sim_build/**/*.dat
       @genhtml coverage.info -o coverage_report
       @echo "✅ Coverage report: coverage_report/index.html"
   

VHDL Coverage (Future-Proofing)

[!TIP] Architecture for future VHDL support: Design the coverage infrastructure with an abstract backend interface. If GHDL or NVC adds coverage support in the future, a new backend can be plugged in without restructuring.

# Conceptual: tools/coverage/backend.py
class CoverageBackend(ABC):
    @abstractmethod
    def collect(self, sim_build_dir: Path) -> CoverageData: ...
    @abstractmethod
    def generate_report(self, data: CoverageData, output: Path): ...

class VerilatorBackend(CoverageBackend): ...
class GHDLBackend(CoverageBackend):  # Future
    pass

Implementation Priority: Medium (Verilog only)

VHDL coverage is blocked by tooling limitations. Design for future extensibility.

5. Formal Verification with SymbiYosys

What is Formal Verification?

Formal verification uses mathematical proofs (SAT/SMT solvers) to exhaustively check that a design meets specified properties (assertions). Unlike simulation, which tests specific input vectors, formal proves correctness for all possible inputs within bounded time steps.

What SymbiYosys Provides

SymbiYosys is an open-source formal verification front-end for Yosys. It supports:

Use Cases for RapidRTL

1. Assertion Checking: Verify that FSMs don't enter illegal states.
2. Interface Protocol Verification: Prove AXI/Wishbone handshakes follow protocol.
3. CDC Verification: Prove that CDC synchronizers are correctly implemented.
4. Equivalence Checking: (Limited) Compare two versions of a module.

Proposed SDK Integration

1. Property File Convention:

   • Users write *.sby (SymbiYosys job files) alongside their RTL.
   • Or: Users annotate RTL with // synopsys translate_off / assert property(...).

2. Makefile Target:

   formal: ## Run formal verification with SymbiYosys (Usage: make formal TOP=module)
       @sby -f $(SRC_DIR)/$(TOP).sby
   

3. Result Parsing:

   • Parse PASS / FAIL / TIMEOUT from SymbiYosys output.
   • On failure, provide path to counterexample VCD.

Limitations

• Verilog/SV Only: SymbiYosys (via Yosys) has limited VHDL support. GHDL-Yosys-Plugin exists but is experimental for synthesis; formal support is even more limited.
• Not a Synthesis Replacement: SymbiYosys uses Yosys internally for elaboration/netlist generation, but we are not relying on it for synthesis. The goal is property checking, not bitstream generation.

Implementation Priority: Low-Medium

Valuable for safety-critical designs; requires user familiarity with formal concepts.

6. RTL Schematic Viewer

Goal

Provide a visual schematic representation of RTL modules for visualization only, without relying on vendor synthesis tools.

Proposed Tool: Yosys + Netlistsvg

1. Yosys: Elaborate RTL to a JSON netlist (write_json).

   Note: We use Yosys only for elaboration to JSON, not for synthesis. All actual synthesis remains with vendor tools.

2. Netlistsvg: Convert JSON netlist to SVG schematic.

Workflow

# Elaborate to JSON (Yosys) - Visualization only, NOT synthesis
yosys -p "read_verilog src/my_module.v; prep; write_json my_module.json"

# Generate SVG schematic
netlistsvg my_module.json -o my_module.svg

Makefile Target

schematic: ## Generate SVG schematic from RTL (Usage: make schematic TOP=module)
    @if [ -z "$(TOP)" ]; then echo "❌ Error: TOP not specified."; exit 1; fi
    @mkdir -p schematics
    @yosys -q -p "read_verilog $(shell python3 $(SDK_ROOT)/tools/project-manager/dependency_resolver.py --top $(TOP) --src $(SRC_DIR) --list); prep -top $(TOP); write_json schematics/$(TOP).json"
    @netlistsvg schematics/$(TOP).json -o schematics/$(TOP).svg
    @echo "✅ Schematic: schematics/$(TOP).svg"

VHDL Support

Yosys VHDL support is provided via the GHDL-Yosys-Plugin (ghdl --synth). This converts VHDL to Yosys's internal representation.

yosys -m ghdl -p "ghdl --std=08 src/my_module.vhd -e my_module; prep; write_json my_module.json"

[!WARNING] Visualization Only: GHDL-Yosys-Plugin elaboration fidelity is not guaranteed to match vendor tools. Use schematics for design understanding and documentation, not as a synthesis reference. All synthesis is performed by vendor tools (Vivado, Radiant, Quartus).

Implementation Priority: Medium-High

High user value for design understanding; relatively low complexity.

Summary & Priority (Post-Review)

Based on user feedback, the following priority ordering is recommended:

Next Steps

1. Implement Wave Viewing (make waves, make sim-waves, WAVES=0 for regressions).
2. Implement Schematic Viewer (make schematic with Yosys + Netlistsvg).
3. Gather Sample Reports from Xilinx for timing analysis parser development.
4. Create XDC Template Generator with set_max_delay tips.