Metadata-Version: 2.4
Name: rtlguard
Version: 0.5.0
Summary: AI-assisted verification gap analysis for safety-critical FPGA/RTL designs
Author: RTLGuard.ai
License: MIT
Project-URL: Homepage, https://github.com/kingsleyamiah/rtl-guard-ai
Project-URL: Repository, https://github.com/kingsleyamiah/rtl-guard-ai
Project-URL: Issues, https://github.com/kingsleyamiah/rtl-guard-ai/issues
Keywords: rtl,vhdl,systemverilog,fpga,verification,coverage,safety-critical
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Testing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: anthropic>=0.40.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: google
Requires-Dist: google-genai>=0.5.0; extra == "google"
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: google-genai>=0.5.0; extra == "all"

# 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.

```bash
pip install rtlguard
```

Set your API key before running:

```bash
# 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

```bash
rtlguard analyze FILE [FILE ...] [options]
```

### Basic example

```bash
rtlguard analyze counter.sv
```

### With a design spec for additional context

```bash
rtlguard analyze counter.sv --spec requirements.txt
```

### Multiple files

```bash
rtlguard analyze ctrl.vhd datapath.sv alu.vhd
```

### Custom output directory

```bash
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](https://github.com/kingsleyamiah/rtl-guard-ai)
