gf-sim

name	gf-sim
description	SystemVerilog simulator with structured output for orchestration. Auto-detects DUT vs testbench, compiles with Verilator, runs simulation, and returns a parseable result block for /gf orchestration.
allowed-tools	["Bash","Read","Glob","Grep"]

GF Sim Skill

Compile and run SystemVerilog simulation with structured output.

Tool Detection

Before running simulation, check if Verilator is available:

which verilator

If Verilator is not available, return immediately:

---GATEFLOW-RESULT---
STATUS: ERROR
ERRORS: 0
WARNINGS: 0
FILES: []
DETAILS: Simulation requires Verilator. Install it to enable simulation.
  macOS: brew install verilator
  Linux: sudo apt install verilator
---END-GATEFLOW-RESULT---

Do NOT attempt to simulate without Verilator. Return the ERROR status and let the orchestrator handle it.

---

Instructions

1. Identify Files

If files specified in args: Use provided paths. First file is typically the testbench.

If no files specified: Auto-detect by scanning for SV files:

ls *.sv rtl/*.sv tb/*.sv 2>/dev/null

2. Classify Files: DUT vs Testbench

Testbench indicators (has any of):

• initial begin
• $display, $monitor
• $finish, $fatal
• $dumpfile, $dumpvars
• Clock generation: always #N clk = ~clk
• File in tb/ directory or named *_tb.sv, tb_*.sv

DUT indicators (has any of):

• always_ff, always_comb
• Synthesizable constructs only
• No $ system tasks (except assertions)
• File in rtl/ directory

Quick classification:

# Files with testbench markers
grep -l '\$display\|\$finish\|initial begin' *.sv 2>/dev/null

# Files with DUT markers
grep -l 'always_ff\|always_comb' *.sv 2>/dev/null

3. Compile with Verilator

verilator --binary -j 0 -Wall --trace <dut-files> <testbench> -o sim

Notes:

• DUT files listed first, testbench last
• --trace enables VCD waveform generation
• -o sim names the output executable

If multiple top modules detected:

verilator --binary -j 0 -Wall --trace --top-module <tb_name> <files> -o sim

4. Run Simulation

./obj_dir/sim

Or if named differently:

./obj_dir/V<top_module>

5. Parse Results

Check output for:

• PASS, SUCCESS, All tests passed -> PASS
• FAIL, ERROR, MISMATCH, ASSERT -> FAIL
• $fatal or non-zero exit code -> FAIL
• $finish reached without errors -> PASS

Check exit code:

./obj_dir/sim
echo "Exit code: $?"

• Exit 0: Success
• Non-zero: Failure

6. Return Structured Result

ALWAYS end your response with this exact block format:

---GATEFLOW-RESULT---
STATUS: PASS|FAIL|ERROR
ERRORS: <count>
WARNINGS: <count>
FILES: <comma-separated list>
DETAILS: <one-line summary>
---END-GATEFLOW-RESULT---

Status definitions:

• PASS: Simulation completed, tests passed
• FAIL: Simulation failed (compile error, assertion failure, test failure)
• ERROR: Could not run simulation (missing files, setup error)

7. Example: Successful Run

## File Classification

| File | Type | Reason |
|------|------|--------|
| rtl/fifo.sv | DUT | has always_ff, no $display |
| tb/tb_fifo.sv | TB | has $display, $finish, initial |

## Compilation

$ verilator --binary -j 0 -Wall --trace rtl/fifo.sv tb/tb_fifo.sv -o sim

(compilation output...)

## Simulation

$ ./obj_dir/sim

Test 1: Write single item... PASS
Test 2: Fill FIFO... PASS
Test 3: Overflow check... PASS
All tests passed!

---GATEFLOW-RESULT---
STATUS: PASS
ERRORS: 0
WARNINGS: 0
FILES: rtl/fifo.sv,tb/tb_fifo.sv
DETAILS: All 3 tests passed
---END-GATEFLOW-RESULT---

8. Example: Failed Run

## Simulation

$ ./obj_dir/sim

Test 1: Write single item... PASS
Test 2: Read back... FAIL
  Expected: 0xAB
  Got: 0x00
$fatal called at tb_fifo.sv:87

---GATEFLOW-RESULT---
STATUS: FAIL
ERRORS: 1
WARNINGS: 0
FILES: rtl/fifo.sv,tb/tb_fifo.sv
DETAILS: Test 2 failed - read data mismatch at line 87
---END-GATEFLOW-RESULT---

9. Example: Compile Error

$ verilator --binary -j 0 -Wall rtl/fifo.sv tb/tb_fifo.sv -o sim

%Error: rtl/fifo.sv:45: Cannot find: fifo_mem

---GATEFLOW-RESULT---
STATUS: FAIL
ERRORS: 1
WARNINGS: 0
FILES: rtl/fifo.sv,tb/tb_fifo.sv
DETAILS: Compile error - undefined reference to fifo_mem
---END-GATEFLOW-RESULT---

Common Issues and Solutions

Issue	Symptom	Solution
Multiple tops	"Multiple top modules"	Add --top-module <name>
Missing module	"Cannot find: X"	Include file defining X
X-values	Output shows X	Check reset coverage
Timeout	Simulation hangs	Add timeout or fix FSM
No $finish	Runs forever	Ensure TB calls $finish

Verilator v5 Performance Options

Multi-Threaded Simulation

verilator --binary --threads N -Wall --trace <files> -o sim

Use numactl to pin to physical cores for best performance.

Trace Formats

Format	Flag	Size	Viewers
VCD	--trace	Large	Universal
FST	--trace-fst	Small	GTKWave, Surfer

Use --trace-fst for large designs. Add --trace-threads 2 to offload FST writing.

Assertions (SVA)

verilator --binary --assert <files>     # DEFAULT in v5.038+
verilator --binary --no-assert <files>  # Disable for performance

Supports one-cycle concurrent assert/cover, $past, $stable, $rose, $fell. Does NOT support multi-cycle sequences (SEREs).

Code Coverage

verilator --binary --coverage <files>        # All coverage
verilator --binary --coverage-line <files>   # Line only
verilator --binary --coverage-toggle <files> # Toggle only

Maximum Performance

verilator --binary -O3 --x-assign fast --x-initial fast --no-assert --threads N <files>

Verilator SV Support

Construct	Support
always_comb/always_ff	Full
Interfaces and modports	Full
Packages, structs, enums	Full
Generate	Full
DPI (C/C++ import/export)	Full
Classes	Partial
Constrained randomization	Partial
SVA (one-cycle)	Full
SVA (multi-cycle)	Not supported

Simulation Timeout

Prevent simulation hangs:

timeout 60 ./obj_dir/sim

Or in testbench:

initial begin
    #1000000;
    $display("TIMEOUT");
    $finish;
end

Usage by /gf Orchestrator

The /gf skill uses this skill internally and parses the result block:

Parse ---GATEFLOW-RESULT--- block:
- STATUS: PASS -> report success, done
- STATUS: FAIL -> spawn sv-debug agent with failure context
- STATUS: ERROR -> report setup issue to user