rtlguard 0.5.0

AI-assisted verification gap analysis for safety-critical FPGA/RTL designs

RTLGuard

Generate test cases for your RTL designs in seconds.

RTLGuard is a command-line tool that reads your VHDL or SystemVerilog source files, checks for FPGA best-practice violations, generates concrete AI-powered test cases, and produces a ready-to-simulate SystemVerilog testbench.

---

Installation

Requires Python 3.10 or later.

pip install rtlguard

Set your API key before running:

# macOS / Linux
export ANTHROPIC_API_KEY=sk-ant-...

# Windows (Command Prompt)
set ANTHROPIC_API_KEY=sk-ant-...

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY="sk-ant-..."

---

Usage

rtlguard analyze FILE [FILE ...] [options]

Basic example

rtlguard analyze counter.sv

With a design spec for additional context

rtlguard analyze counter.sv --spec requirements.txt

Multiple files

rtlguard analyze ctrl.vhd datapath.sv alu.vhd

Custom output directory

rtlguard analyze my_module.vhd -o results/

---

Options

Flag	Default	Description
FILE	—	VHDL (.vhd, .vhdl) or SystemVerilog (.sv, .v) source file(s)
--spec FILE	—	Optional design spec or requirements document for AI context
-o DIR, --output-dir DIR	./rtlguard_out	Directory to write output files
-v, --verbose	off	Print parser warnings and validation issues
-h, --help	—	Show help and exit

---

What it does

Step 1 — FPGA best-practice check

RTLGuard checks your source code for common FPGA design issues before generating test cases:

Severity	Examples
Critical	Combinational feedback loops, multiple drivers, undriven outputs
High	Inferred latches, blocking assignments in sequential logic, inconsistent resets
Medium	Missing reset handler, incomplete sensitivity lists, magic numbers
Low	Naming inconsistencies, missing comments

Results are saved to <output-dir>/<module>_fpga_check.txt.

If violations are found, RTLGuard asks whether to proceed or fix the file first. If you choose to fix, edit the file in your editor, save, and press Enter — RTLGuard re-checks only the original violations, not the full design from scratch.

Step 2 — Test case generation

RTLGuard uses AI to generate concrete, module-specific test cases covering:

• Reset and power-on behaviour
• Normal operating modes
• Boundary and edge cases (overflow, underflow, max values)
• Any requirements from the spec (if provided)

Results are saved to <output-dir>/<module>_test_cases.txt.

Step 3 — Review and edit test cases (optional)

Before the testbench is generated, RTLGuard asks if you want to edit the test cases file. This lets you add, remove, or modify test cases to match your exact requirements.

If you choose to edit:

1. Open <module>_test_cases.txt in any editor and make your changes — add new test cases, delete ones you don't need, or add notes.
2. Save the file and press Enter in the terminal.
3. RTLGuard re-parses your edits using AI: it removes duplicates, discards incomplete entries, renumbers IDs, and fixes formatting.
4. The cleaned test cases are printed in the terminal for review.
5. Confirm to proceed with the cleaned version, or decline to use your raw edits as-is.

Step 4 — SystemVerilog testbench

RTLGuard always generates a complete, ready-to-simulate SystemVerilog testbench:

• Correct DUT instantiation
• Clock generation
• Reset sequence
• Each test case as a labelled block with $display and automated pass/fail checks

The testbench is saved to <output-dir>/<module>_tb.sv.

---

Example output

  counter.sv
  Checking FPGA best practices ... ✓  Saved to rtlguard_out/counter_fpga_check.txt
  Generating test cases ... ✓  Saved to rtlguard_out/counter_test_cases.txt

  Edit test cases before generating testbench? [y/n]: y

  Edit rtlguard_out/counter_test_cases.txt and press Enter when ready ...
  Reparsing test cases ... ✓

  ------------------------------------------------------------
  [TC-001] Reset asserted holds output at zero  (CRITICAL)
    Verify output is zeroed when reset is asserted.
    Stimulus:
      rstn = 0
      clk = posedge
    Expected:
      out == 4'b0000

  [TC-002] Counter increments after reset de-asserted  (CRITICAL)
    Verify counter begins counting from zero after reset is released.
    Stimulus:
      rstn = 1
      clk = posedge
    Expected:
      out == 4'b0001
  ------------------------------------------------------------

  Proceed with these test cases? [y/n]: y
  Generating testbench ... ✓  Saved to rtlguard_out/counter_tb.sv

counter_test_cases.txt

[TC-001] Reset asserted holds output at zero  (CRITICAL)
  Verify output is zeroed when reset is asserted.
  Stimulus:
    rstn = 0
    clk = posedge
  Expected:
    out == 4'b0000

[TC-002] Counter increments after reset de-asserted  (CRITICAL)
  Verify counter begins counting from zero after reset is released.
  Stimulus:
    rstn = 0
    clk = posedge
    rstn = 1
    clk = posedge
  Expected:
    out == 4'b0001

---

Requirements

Requirement	Version
Python	≥ 3.10
anthropic	≥ 0.40.0 (installed automatically)

---

Source

github.com/kingsleyamiah/rtl-guard-ai