rtlguard 0.1.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 (powered by the Anthropic API) enriches findings with deeper rationale and an executive risk assessment.

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
• Project Structure

---

Installation

Requires Python 3.10 or later.

git clone https://github.com/kingsleyamiah/rtl-guard-ai.git
cd rtl-guard-ai
pip install -e .

To use the AI review feature, install with the Anthropic client and set your API key:

export 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/

# Run with AI-assisted gap enrichment and executive risk assessment
rtlguard analyze my_module.vhd --ai

# 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 using the Anthropic API. Requires ANTHROPIC_API_KEY to be set. Adds three analysis passes: gap enrichment, scenario enrichment, and an executive risk review.
--model MODEL	claude-sonnet-4-6	Anthropic model to use for the AI review passes. Any model accessible via your API key is accepted (e.g. claude-opus-4-7, claude-haiku-4-5-20251001).
--no-dedup	off	Skip deduplication when merging results from multiple files. By default, findings and scenarios with the same semantic key (kind + entity + signals involved) 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 via the Anthropic API:

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.

Usage:

export ANTHROPIC_API_KEY=sk-ant-...

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

# Choose a specific model
rtlguard analyze my_module.vhd --ai --model claude-opus-4-7

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

Note: AI review requires a valid ANTHROPIC_API_KEY. If the 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 file, all formats:

rtlguard analyze examples/sample_vhdl_entity.vhd
# Writes: rtlguard_out/sample_vhdl_entity_report.{json,md,html}

SystemVerilog, HTML only, custom output:

rtlguard analyze examples/sample_sv_module.sv -f html -o reports/
# Writes: reports/sample_sv_module_report.html

Multi-file, merged report:

rtlguard analyze examples/sample_vhdl_entity.vhd examples/sample_sv_module.sv -f markdown
# Writes: rtlguard_out/merged_report.md

With AI review:

export ANTHROPIC_API_KEY=sk-ant-...
rtlguard analyze examples/sample_vhdl_entity.vhd --ai -f html

Verbose output (shows validation issues and parser warnings):

rtlguard analyze my_design.vhd -v

CI pipeline (JSON only, fail on write error):

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

---

Project Structure

rtlguard/
├── models/          Data classes: Entity, Signal, Scenario, CoverageMap, Report
├── parser/          VHDL and SystemVerilog parsers; ParserFactory
├── analysis/        SignalGraph, CoverageAnalyzer, GapDetector,
│                    ScenarioGenerator, EdgeCaseFinder, StateMachineAnalyzer
├── prompts/         Anthropic API prompt construction with prompt caching
├── review/          AIReviewer (3-pass), DiffChecker, HumanReviewFormatter
├── validation/      RTLValidator, ScenarioValidator, CoverageValidator
├── report/          ReportGenerator, JSONExporter, MarkdownExporter, HTMLExporter
├── merge/           CoverageMerger, ScenarioMerger, Deduplicator
└── cli/             argparse entry point and pipeline orchestration

examples/
├── sample_vhdl_entity.vhd    8-bit enable-gated register (VHDL)
└── sample_sv_module.sv       Saturating up-counter (SystemVerilog)

tests/
├── test_models.py
├── test_parser.py
├── test_analysis.py
├── test_validation.py
├── test_report.py
├── test_merge.py
└── test_cli.py

341 tests, all passing.

---

Requirements

Requirement	Version
Python	≥ 3.10
anthropic	≥ 0.40.0 (required for --ai flag)

No other runtime dependencies.