rtlguard 0.2.0

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

RTLGuard

Find what your testbench is missing.

RTLGuard is a command-line tool for verification gap analysis on safety-critical FPGA and RTL designs. It parses VHDL and SystemVerilog source files, runs static analysis to identify untested logic, and generates structured reports with concrete test scenarios. An optional AI review pass enriches findings with deeper rationale and an executive risk assessment — supporting Anthropic, OpenAI, and Google AI providers.

Designed for engineers working to IEC 61508, DO-178C, ISO 26262, MIL-STD-882, and IEC 62061.

---

Contents

• Installation
• Quick Start
• Commands
  • analyze
• Output Formats
• Understanding the Report
  • Coverage Percentage
  • Findings
  • Scenarios
• AI Review
• Multi-File Analysis
• Examples

---

Installation

Requires Python 3.10 or later.

pip install rtlguard

That's it. The rtlguard command is available immediately after install — no cloning, no build steps.

Optional: AI provider packages

To use the AI review feature, install the package for your chosen provider:

Provider	Install	API Key
Anthropic (default)	included	ANTHROPIC_API_KEY
OpenAI	pip install rtlguard[openai]	OPENAI_API_KEY
Google Gemini	pip install rtlguard[google]	GOOGLE_API_KEY
All providers	pip install rtlguard[all]	—

Set your API key before running with --ai:

# macOS / Linux
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=AIza...

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

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

Verify the install:

rtlguard --help

---

Quick Start

# Analyze a single VHDL file, write all report formats to ./rtlguard_out/
rtlguard analyze my_module.vhd

# Analyze a SystemVerilog file, HTML output only, custom output directory
rtlguard analyze counter.sv -f html -o reports/

# Analyze multiple files — findings and scenarios are merged and deduplicated
rtlguard analyze ctrl.vhd datapath.sv top.sv -o reports/

# AI review with the default provider (Anthropic)
rtlguard analyze my_module.vhd --ai

# AI review with OpenAI
rtlguard analyze my_module.vhd --ai --provider openai

# AI review with Google Gemini
rtlguard analyze my_module.vhd --ai --provider google

# Verbose output: shows parser warnings and per-field validation issues
rtlguard analyze my_module.vhd -v

---

Commands

rtlguard analyze

Parses one or more RTL source files, runs the full static analysis pipeline, and writes a verification gap report.

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

Positional arguments

Argument	Description
FILE	One or more VHDL (.vhd, .vhdl) or SystemVerilog (.sv, .v) source files to analyze. Multiple files trigger multi-file merge mode.

Options

Flag	Default	Description
-o DIR, --output-dir DIR	./rtlguard_out	Directory to write reports into. Created automatically if it does not exist.
-f FORMAT, --format FORMAT	all	Report format(s) to produce. Choices: json, markdown, html, all.
--ai	off	Run AI-assisted gap enrichment. Requires an API key for the chosen provider. Adds three analysis passes: gap enrichment, scenario enrichment, and an executive risk review.
--provider PROVIDER	anthropic	AI provider to use. Choices: anthropic, openai, google.
--model MODEL	provider default	Model name for the AI review passes. If not specified, uses the provider's default (see AI Review).
--no-dedup	off	Skip deduplication when merging results from multiple files. By default, findings and scenarios with the same semantic key are deduplicated, keeping the highest-priority copy.
-v, --verbose	off	Print parser warnings, validation issues, and per-step detail during analysis. Useful for diagnosing unexpected results.
-h, --help	—	Show help and exit.

Pipeline (per file)

1. Parse — VHDL or SystemVerilog parser extracts entity/module structure, ports, generics, internal signals, processes, and architecture body.
2. Signal graph — builds a directed dependency graph; detects clocks, resets, floating signals, and undriven outputs.
3. Coverage analysis — identifies every measurable coverage point: reset handlers, branch conditions, toggle requirements, FSM states and transitions, functional requirements.
4. Gap detection — compares the coverage map against the signal graph to produce GapFinding objects sorted by priority.
5. Scenario generation — converts each gap into one or more concrete Scenario objects with stimulus, expectations, preconditions, and rationale.
6. Validation — validates the entity, scenarios, and coverage map against named rule sets (RTL-001–009, SCN-001–009, COV-001–006).

---

Output Formats

All formats are written to <output-dir>/ with the filename <entity_name>_report.<ext> for single-file runs, or merged_report.<ext> for multi-file runs.

Format	File	Description
json	.json	Machine-readable JSON. Suitable for CI pipelines, dashboards, and custom tooling. Contains the full report including all findings, scenarios, and coverage points.
markdown	.md	Human-readable Markdown with severity badges, summary tables, and per-finding detail. Renders well in GitHub, GitLab, and most documentation tools.
html	.html	Self-contained HTML with inline CSS. No external dependencies — open directly in any browser. Colour-coded by severity with a summary grid and collapsible cards.
all	all three	Produces JSON, Markdown, and HTML in a single run. Default behaviour.

---

Understanding the Report

Coverage Percentage

RTLGuard reports static coverage — what it can determine from source code alone, without running simulation. Coverage points have one of five statuses:

Status	Meaning
covered	Statically confirmed: the design has this property (e.g. clock signal present, reset handler exists).
uncovered	Statically confirmed: the property is missing (e.g. output port is never driven).
unknown	Cannot determine without simulation (e.g. whether a branch is actually taken in tests).
partial	Some but not all sub-conditions met.
excluded	Intentionally out of scope.

The coverage percentage is calculated over deterministic points only (covered, uncovered, partial). Points with unknown status are excluded from the denominator — they are gaps in simulation coverage, not in structural correctness, and including them would make every static report show artificially low numbers.

coverage % = covered / (covered + uncovered + partial) × 100

A typical well-structured design with clock, reset, and process handlers scores 60–80% on a fresh (untested) analysis. Remaining gaps are the test scenarios RTLGuard generates for you.

Findings

Each finding (FND-XXX) represents a specific verification gap:

Severity	Meaning
critical	Safety-critical gap that must be closed before sign-off
high	Significant gap that will likely cause failures in production
medium	Coverage gap that reduces confidence in the design
low	Minor gap or informational finding

Gap kinds detected:

Kind	Description
missing_reset_test	Sequential process has no reset handler
missing_normal_op_test	No test for normal (non-reset) operation path
undriven_output	An output port has no signal path driving it
floating_signal	Internal signal has no driver
untested_toggle	Signal is never toggled in any known test
untested_fsm_state	An FSM state is never visited
untested_fsm_transition	An FSM transition is never exercised
missing_clock	No clock signal detected in the design
missing_reset_signal	No reset signal detected in the design
missing_power_on_state	No sequential process defines reset/power-on behaviour
sensitivity_list_gap	Reset signal missing from a process sensitivity list
unobservable_signal	Internal signal has no path to any output
missing_branch	A branch of a conditional (if/case) is not exercised

Scenarios

Each scenario (SCN-XXX) is a concrete test case generated from a finding. Scenarios include:

• Stimulus — which signals to drive and to what values
• Expectations — what outputs or internal signals should respond
• Preconditions — system state required before the test
• Rationale — why this scenario is needed and which gap it closes
• Confidence — 0.0–1.0 score indicating how certain RTLGuard is the scenario is correct
• Safety reference — applicable standard clause (IEC 61508, DO-178C, etc.)

---

AI Review

The --ai flag enables three additional analysis passes using an AI provider of your choice:

Pass	Description
Gap enrichment	Deepens each static finding with AI-generated rationale, additional context, and standard references specific to the design.
Scenario enrichment	Adds pseudocode, assertion templates, and step-by-step test procedures to each scenario.
Executive review	Produces a risk-level assessment (low / medium / high / critical), an executive summary, compliance notes, and recommended actions.

AI output is merged with static analysis results in the report — AI-discovered gaps are appended alongside static findings, and enriched rationale replaces the static rationale where available.

Providers and default models

Provider	Flag	Default model	API key env var
Anthropic	--provider anthropic	claude-sonnet-4-6	ANTHROPIC_API_KEY
OpenAI	--provider openai	gpt-4o	OPENAI_API_KEY
Google	--provider google	gemini-2.0-flash	GOOGLE_API_KEY

Usage

# Default (Anthropic, claude-sonnet-4-6)
rtlguard analyze my_module.vhd --ai

# Anthropic — specific model
rtlguard analyze my_module.vhd --ai --model claude-opus-4-7

# OpenAI — default model (gpt-4o)
rtlguard analyze my_module.vhd --ai --provider openai

# OpenAI — specific model
rtlguard analyze my_module.vhd --ai --provider openai --model gpt-4o-mini

# Google Gemini — default model (gemini-2.0-flash)
rtlguard analyze my_module.vhd --ai --provider google

# Google Gemini — specific model
rtlguard analyze my_module.vhd --ai --provider google --model gemini-1.5-pro

Token usage and cache statistics are printed after the AI review completes. The Anthropic provider uses prompt caching on system blocks to reduce cost on repeated runs against the same design.

Note: If the AI API call fails, RTLGuard prints the error and continues — the static report is always written regardless of AI availability.

---

Multi-File Analysis

Pass multiple source files to analyze an entire design in one run:

rtlguard analyze ctrl.vhd alu.vhd datapath.vhd top.sv -o reports/

RTLGuard processes each file through the full pipeline independently, then:

1. Merges all findings and scenario lists
2. Deduplicates by semantic key: (gap kind, entity name, signals involved) — keeping the highest-priority copy when duplicates exist
3. Re-sequences scenario IDs globally (SCN-001, SCN-002, …)
4. Writes a single merged_report.<ext> to the output directory

To disable deduplication and keep every finding from every file:

rtlguard analyze a.vhd b.sv --no-dedup

---

Examples

Single VHDL file, all formats:

rtlguard analyze my_module.vhd
# Writes: rtlguard_out/my_module_report.{json,md,html}

SystemVerilog, HTML only, custom output directory:

rtlguard analyze counter.sv -f html -o reports/
# Writes: reports/counter_report.html

Multi-file, merged report:

rtlguard analyze ctrl.vhd datapath.sv alu.sv -f markdown -o reports/
# Writes: reports/merged_report.md

With AI review (Anthropic):

export ANTHROPIC_API_KEY=sk-ant-...
rtlguard analyze my_module.vhd --ai -f html

With AI review (OpenAI):

export OPENAI_API_KEY=sk-...
rtlguard analyze my_module.vhd --ai --provider openai

With AI review (Google Gemini):

export GOOGLE_API_KEY=AIza...
rtlguard analyze my_module.vhd --ai --provider google

Verbose output (shows validation issues and parser warnings):

rtlguard analyze my_design.vhd -v

CI pipeline (JSON only):

rtlguard analyze src/top.sv -f json -o ci_reports/

---

Requirements

Requirement	Version
Python	≥ 3.10
anthropic	≥ 0.40.0 (installed automatically)
openai	≥ 1.0.0 (optional: pip install rtlguard[openai])
google-genai	≥ 0.5.0 (optional: pip install rtlguard[google])

---

Contributing / Source

Source code and issue tracker: github.com/kingsleyamiah/rtl-guard-ai