An open-source Verilog/SystemVerilog testing and debugging framework in F#. Drive your RTL through Verilator and Icarus Verilog with type-safe, structured access to every signal, memory, and register — and let an AI agent debug it for you over MCP.
Traditional Verilog testbenches are tedious and inexpressive; UVM is powerful but heavyweight. Verifrog gives you Verilator's speed with the ergonomics of a modern language — tests that read like specifications, checkpoint/restore and fork-based hypothesis testing, and an MCP server so an agent can open your design, step it, force signals, and pinpoint a bug on its own.
Verifrog ships an MCP server, so an AI agent can drive your RTL simulation directly — opening a design, stepping cycles, reading and forcing signals, and checkpointing state to test hypotheses. In this demo, a failing test leads the agent to investigate, checkpoint, force signals, and pinpoint a bug in the ALU's SUB operation:
verifrog-debugging-demo-2x.mp4 #
Write structured, readable tests in F# that compile and run your RTL through Verilator. Read and write any signal, memory, or register by name. Assert values with clear failure messages. Run Verilator and Icarus Verilog tests side-by-side under a single dotnet test
.
Verifrog's simulation model is fully controllable from code — you can at any point, inspect every signal in the design, and step forward cycle-by-cycle. But the real power is in the tools built on top of this:
Checkpoint/Restore— Snapshot the entire simulation state (every register, every memory cell) and restore it later in microseconds. Hit a bug at cycle 50,000? Save a checkpoint before the failure, then repeatedly restore and probe different signals without re-running the simulation from scratch. -
Fork— Explore a what-if scenario and automatically snap back. "What would happen if I forced this signal high?" Fork runs your experiment, captures the result, and restores the original state — so you can try multiple hypotheses from the same point without manual save/restore. -
Compare and Sweep— Run two configurations side-by-side from the same state (Compare
), or sweep a parameter across many values (Sweep
). Both use checkpoints internally to ensure each scenario starts from identical state. -
Signal forcing— Override any internal signal and hold it across clock cycles. Inject faults, disable clock gating, force a bus value — then release and watch the design recover. -
Tracing and RunUntil— Record signal values over a window of cycles (Trace
), or advance the simulation until a condition is met (RunUntil
,RunUntilSignal
). No more guessing how many cycles to step. -
VCD waveform analysis— Parse simulation waveform dumps and query them programmatically: find when a signal first changed, count pulses, check timing relationships, verify FSM state coverage. Available as both a library (Verifrog.Vcd
) for use in tests and a command-line tool (verifrog-vcd
) for quick analysis.
| Verifrog | Raw Verilator (C++) | cocotb | UVM | |
|---|---|---|---|---|
| Testbench language | ||||
F# (Expecto) + declarative .verifrog |
||||
| C++ | Python | SystemVerilog | ||
| Simulation engine | ||||
| Verilator / Icarus | Verilator | any VPI simulator | any SV simulator | |
| Checkpoint / restore | ||||
| Built in (state snapshot in µs) | Hand-rolled | No | No | |
| Fork / compare / sweep | ||||
| Built in | Hand-rolled | No | Manual | |
| Signal forcing | ||||
| By name, held across cycles | Manual pointer writes | .value assignment |
||
uvm_hdl_force |
||||
| Named memory / register access | ||||
| TOML-driven, by name | Manual | Manual | Config DB / RAL | |
| AI agent debugging (MCP) | ||||
| Built in | No | No | No | |
| Learning curve | ||||
| Low | Medium | Low | High |
Verifrog leans on Verilator for raw speed, so it inherits Verilator's two-state limitation — for timing-accurate, four-state (X/Z) testbenches it can also drive Icarus Verilog under the same test suite. If you need cycle-accurate X-propagation as the default, a VPI-based flow like cocotb may fit better; if you want fast checkpoint/fork-driven debugging with an agent in the loop, that's where Verifrog is aimed.
.NET 8+ SDKVerilator 5+- clang++ (macOS, included with Xcode) or g++ (Linux) Icarus Verilog(optional, for timing-accurate testbenches)
git clone https://github.com/bryancostanich/verifrog.git
cd verifrog
./install.sh # Symlinks verifrog to /usr/local/bin
Or add bin/
to your PATH manually: export PATH="/path/to/verifrog/bin:$PATH"
verifrog build samples/counter
verifrog test samples/counter
cd your-project
verifrog init .
verifrog build
verifrog test
See the full Getting Started Guide for a step-by-step walkthrough.
Most hardware tests are just "set signals, step, check." Write those declaratively in a .verifrog
file — no F# needed:
test "counts to 10 when enabled" [Smoke]:
write enable = 1
step 10
expect count == 10
test "load then count" [Unit]:
write load_value = 42, load_en = 1
step 1
write load_en = 0, enable = 1
step 5
expect count == 47
Or in F# when you need more control:
open Verifrog.Sim
open Verifrog.Runner
let tests = testList "counter" [
test "counts to 10 when enabled" {
use sim = SimFixture.create ()
sim.Write("enable", 1L) |> ignore
sim.Step(10)
Expect.signal sim "count" 10L "count should reach 10"
}
]
Both run in the same test suite — same categories, same --report
, same verifrog test
.
Save simulation state, run forward, restore, try something different — all in code:
test "investigate overflow behavior" {
use sim = SimFixture.create ()
sim.Write("enable", 1L) |> ignore
sim.Step(200)
// Save state right before the interesting part
let cp = sim.SaveCheckpoint("before_overflow")
// Run forward and observe
sim.Step(60)
let count = sim.ReadOrFail("count")
let overflowed = sim.ReadOrFail("overflow")
printfn "After 60 more cycles: count=%d overflow=%d" count overflowed
// Restore and try a different approach
sim.RestoreCheckpoint("before_overflow")
// What if we load a value near the limit?
let result = sim.Fork(fun s ->
s.Write("load_en", 1L) |> ignore
s.Write("load_value", 250L) |> ignore
s.Step(1)
s.Write("load_en", 0L) |> ignore
s.Step(10)
s.ReadOrFail("overflow"))
// sim is back to "before_overflow" — Fork restored automatically
// Sweep across multiple load values to find the boundary
let results = sim.Sweep(
[248L; 249L; 250L; 251L; 252L],
fun loadVal s ->
s.Write("load_en", 1L) |> ignore
s.Write("load_value", loadVal) |> ignore
s.Step(1)
s.Write("load_en", 0L) |> ignore
s.Step(10)
s.ReadOrFail("overflow"))
for (loadVal, overflow) in results do
printfn " load=%d -> overflow=%d" loadVal overflow
}
test "verify timing with VCD analysis" {
use sim = SimFixture.create ()
// ... run stimulus ...
let vcd = VcdParser.parseAll "output/sim.vcd"
// When did the FSM first enter state 5?
let t = VcdParser.firstTimeAtValue vcd "fsm_state" 5
// How many times did overflow pulse?
let pulses = VcdParser.highPulseCount vcd "counter.overflow"
// What states did the FSM visit?
let states = VcdParser.uniqueValues vcd "fsm_state"
}
Verifrog provides hardware-domain test categories so you can run the right tests at the right time:
verifrog test --category Smoke # Quick sanity — design is alive (seconds)
verifrog test --category Unit # Focused signal/block tests
verifrog test --category Integration # Multi-block data flow
verifrog test --category Parametric # Sweeps and value ranges
verifrog test # Everything
Categories are lightweight testList
wrappers — just group your tests:
open Verifrog.Runner.Category
let tests = testList "MySoC" [
smoke [
test "comes out of reset" { ... }
]
unit [
test "counter increments" { ... }
]
golden [
test "matches reference output" { ... }
]
]
Also available: stress
(long-running), golden
(reference outputs), regression
(bug-fix coverage).
Your Test Project (Expecto)
|
v
Verifrog.Runner — SimFixture, Iverilog backend, Expect helpers
|
v
Verifrog.Sim — Sim type, Memory/Register accessors, TOML config
|
v
libverifrog_sim — Generic Verilator C++ wrapper (built per-design)
|
v
Verilator — Your compiled RTL
| Library | What it does |
|---|---|
| Verifrog.Sim | |
| Core simulation API: create, step, read/write signals, checkpoint/restore, force, fork/sweep, memory/register access | |
| Verifrog.Runner | |
| Test infrastructure: SimFixture lifecycle, Iverilog backend, Expect assertions, test categories (Smoke/Unit/Parametric/Integration/Stress/Golden/Regression) | |
| Verifrog.Vcd | |
| Standalone VCD waveform parser: parse files, query signals, value-at-time, transitions, timing analysis | |
| Verifrog.Vcd.Cli | |
| Command-line VCD analysis tool with text and JSON output | |
| verifrog CLI | |
Build tool: init , build , clean , test , debug (interactive REPL), debug-server (JSON), mcp-server (MCP for Claude) |
|
| libverifrog_sim | |
| Design-agnostic C++ shim: signal discovery, direct-pointer access, checkpoint via memcpy | |
| VS Code Extension | |
Syntax highlighting for .verifrog files, signals panel, checkpoints panel, debug toolbar (experimental) |
All project configuration lives in verifrog.toml
:
[design]
top = "my_module"
sources = ["rtl/*.v"]
[test]
output = "build"
[memories.data_ram]
path = "u_ram.mem"
banks = 1
depth = 1024
width = 32
[registers]
path = "u_regfile.regs"
width = 8
[registers.map]
CTRL = 0x00
STATUS = 0x01
DATA = 0x02
See the full Configuration Reference.
| Sample | What it demonstrates |
|---|---|
alu_regfilesramiverilog_tbdotnet test
i2c_bfmMultiple ways to debug your simulations:
Interactive REPL — the fastest path. Step the simulation, read/write signals, set checkpoints, force values, all from the command line:
verifrog debug
sim> write enable 1
sim> step 10
sim> read count
count = 10
sim> checkpoint before_overflow
sim> step 300
sim> restore before_overflow # Back to cycle 10 instantly
JSON debug server — for programmatic access. Reads JSON commands from stdin, writes JSON responses to stdout:
echo '{"cmd":"read","signals":["count","enable"]}' | verifrog debug-server
MCP server — exposes simulation tools directly to Claude:
verifrog mcp-server # Speaks MCP protocol (JSON-RPC 2.0 over stdio)
VS Code extension — syntax highlighting for .verifrog
files, signals panel, test running. VS Code step-through debugging of F# test code is experimental and has known limitations.
See the full Debug Guide for all options.
| Guide | For |
|---|---|
Core ConceptsDebug GuideAPI ReferenceVCD Parser GuideVCD CLI ReferenceCLI Referenceverifrog init
, build
, clean
, test
, debug
, results
Configuration Referenceverifrog.toml
section and keyDeclarative Tests.verifrog
files without F# codeCookbookCI Integration GuideExtension GuideArchitectureArchitecture DecisionsTroubleshootingApache 2.0