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

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

```bash
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:**
```bash
verilator --binary -j 0 -Wall --trace --top-module <tb_name> <files> -o sim
```

### 4. Run Simulation

```bash
./obj_dir/sim
```

Or if named differently:
```bash
./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:**
```bash
./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
```bash
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)
```bash
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
```bash
verilator --binary --coverage <files>        # All coverage
verilator --binary --coverage-line <files>   # Line only
verilator --binary --coverage-toggle <files> # Toggle only
```

### Maximum Performance
```bash
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:
```bash
timeout 60 ./obj_dir/sim
```

Or in testbench:
```systemverilog
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
```