system tasks (except assertions)\n- File in `rtl/` directory\n\n**Quick classification:**\n```bash\n# Files with testbench markers\ngrep -l '\\$display\\|\\$finish\\|initial begin' *.sv 2\u003e/dev/null\n\n# Files with DUT markers\ngrep -l 'always_ff\\|always_comb' *.sv 2\u003e/dev/null\n```\n\n### 3. Compile with Verilator\n\n```bash\nverilator --binary -j 0 -Wall --trace \u003cdut-files\u003e \u003ctestbench\u003e -o sim\n```\n\n**Notes:**\n- DUT files listed first, testbench last\n- `--trace` enables VCD waveform generation\n- `-o sim` names the output executable\n\n**If multiple top modules detected:**\n```bash\nverilator --binary -j 0 -Wall --trace --top-module \u003ctb_name\u003e \u003cfiles\u003e -o sim\n```\n\n### 4. Run Simulation\n\n```bash\n./obj_dir/sim\n```\n\nOr if named differently:\n```bash\n./obj_dir/V\u003ctop_module\u003e\n```\n\n### 5. Parse Results\n\n**Check output for:**\n- `PASS`, `SUCCESS`, `All tests passed` -\u003e PASS\n- `FAIL`, `ERROR`, `MISMATCH`, `ASSERT` -\u003e FAIL\n- `$fatal` or non-zero exit code -\u003e FAIL\n- `$finish` reached without errors -\u003e PASS\n\n**Check exit code:**\n```bash\n./obj_dir/sim\necho \"Exit code: $?\"\n```\n- Exit 0: Success\n- Non-zero: Failure\n\n### 6. Return Structured Result\n\n**ALWAYS end your response with this exact block format:**\n\n```\n---GATEFLOW-RESULT---\nSTATUS: PASS|FAIL|ERROR\nERRORS: \u003ccount\u003e\nWARNINGS: \u003ccount\u003e\nFILES: \u003ccomma-separated list\u003e\nDETAILS: \u003cone-line summary\u003e\n---END-GATEFLOW-RESULT---\n```\n\n**Status definitions:**\n- `PASS`: Simulation completed, tests passed\n- `FAIL`: Simulation failed (compile error, assertion failure, test failure)\n- `ERROR`: Could not run simulation (missing files, setup error)\n\n### 7. Example: Successful Run\n\n```\n## File Classification\n\n| File | Type | Reason |\n|------|------|--------|\n| rtl/fifo.sv | DUT | has always_ff, no $display |\n| tb/tb_fifo.sv | TB | has $display, $finish, initial |\n\n## Compilation\n\n$ verilator --binary -j 0 -Wall --trace rtl/fifo.sv tb/tb_fifo.sv -o sim\n\n(compilation output...)\n\n## Simulation\n\n$ ./obj_dir/sim\n\nTest 1: Write single item... PASS\nTest 2: Fill FIFO... PASS\nTest 3: Overflow check... PASS\nAll tests passed!\n\n---GATEFLOW-RESULT---\nSTATUS: PASS\nERRORS: 0\nWARNINGS: 0\nFILES: rtl/fifo.sv,tb/tb_fifo.sv\nDETAILS: All 3 tests passed\n---END-GATEFLOW-RESULT---\n```\n\n### 8. Example: Failed Run\n\n```\n## Simulation\n\n$ ./obj_dir/sim\n\nTest 1: Write single item... PASS\nTest 2: Read back... FAIL\n Expected: 0xAB\n Got: 0x00\n$fatal called at tb_fifo.sv:87\n\n---GATEFLOW-RESULT---\nSTATUS: FAIL\nERRORS: 1\nWARNINGS: 0\nFILES: rtl/fifo.sv,tb/tb_fifo.sv\nDETAILS: Test 2 failed - read data mismatch at line 87\n---END-GATEFLOW-RESULT---\n```\n\n### 9. Example: Compile Error\n\n```\n$ verilator --binary -j 0 -Wall rtl/fifo.sv tb/tb_fifo.sv -o sim\n\n%Error: rtl/fifo.sv:45: Cannot find: fifo_mem\n\n---GATEFLOW-RESULT---\nSTATUS: FAIL\nERRORS: 1\nWARNINGS: 0\nFILES: rtl/fifo.sv,tb/tb_fifo.sv\nDETAILS: Compile error - undefined reference to fifo_mem\n---END-GATEFLOW-RESULT---\n```\n\n## Common Issues and Solutions\n\n| Issue | Symptom | Solution |\n|-------|---------|----------|\n| Multiple tops | \"Multiple top modules\" | Add `--top-module \u003cname\u003e` |\n| Missing module | \"Cannot find: X\" | Include file defining X |\n| X-values | Output shows X | Check reset coverage |\n| Timeout | Simulation hangs | Add timeout or fix FSM |\n| No $finish | Runs forever | Ensure TB calls $finish |\n\n## Verilator v5 Performance Options\n\n### Multi-Threaded Simulation\n```bash\nverilator --binary --threads N -Wall --trace \u003cfiles\u003e -o sim\n```\nUse `numactl` to pin to physical cores for best performance.\n\n### Trace Formats\n| Format | Flag | Size | Viewers |\n|---|---|---|---|\n| VCD | `--trace` | Large | Universal |\n| FST | `--trace-fst` | Small | GTKWave, Surfer |\n\nUse `--trace-fst` for large designs. Add `--trace-threads 2` to offload FST writing.\n\n### Assertions (SVA)\n```bash\nverilator --binary --assert \u003cfiles\u003e # DEFAULT in v5.038+\nverilator --binary --no-assert \u003cfiles\u003e # Disable for performance\n```\nSupports one-cycle concurrent assert/cover, `$past`, `$stable`, `$rose`, `$fell`.\nDoes NOT support multi-cycle sequences (SEREs).\n\n### Code Coverage\n```bash\nverilator --binary --coverage \u003cfiles\u003e # All coverage\nverilator --binary --coverage-line \u003cfiles\u003e # Line only\nverilator --binary --coverage-toggle \u003cfiles\u003e # Toggle only\n```\n\n### Maximum Performance\n```bash\nverilator --binary -O3 --x-assign fast --x-initial fast --no-assert --threads N \u003cfiles\u003e\n```\n\n## Verilator SV Support\n\n| Construct | Support |\n|---|---|\n| `always_comb`/`always_ff` | Full |\n| Interfaces and modports | Full |\n| Packages, structs, enums | Full |\n| Generate | Full |\n| DPI (C/C++ import/export) | Full |\n| Classes | Partial |\n| Constrained randomization | Partial |\n| SVA (one-cycle) | Full |\n| SVA (multi-cycle) | Not supported |\n\n## Simulation Timeout\n\nPrevent simulation hangs:\n```bash\ntimeout 60 ./obj_dir/sim\n```\n\nOr in testbench:\n```systemverilog\ninitial begin\n #1000000;\n $display(\"TIMEOUT\");\n $finish;\nend\n```\n\n## Usage by /gf Orchestrator\n\nThe `/gf` skill uses this skill internally and parses the result block:\n\n```\nParse ---GATEFLOW-RESULT--- block:\n- STATUS: PASS -\u003e report success, done\n- STATUS: FAIL -\u003e spawn sv-debug agent with failure context\n- STATUS: ERROR -\u003e report setup issue to user\n```\n","repo_fullName":"codejunkie99/Gateflow-Plugin","repo_stars":86,"repo_language":"Python","repo_license":"NOASSERTION","repo_pushedAt":"2026-05-21T02:12:27Z","owner_login":"codejunkie99","owner_type":"User","owner_name":"Avidlive","owner_avatarUrl":"https://avatars.githubusercontent.com/u/52658655?v=4"}};