codejunkie99/gf-lint

GF Lint Skill

Lint SystemVerilog files with structured output for orchestration.

Tool Detection

Before running lint, check if Verilator is available:

which verilator

If Verilator is not available, check for Verible:

which verible-verilog-lint

If neither is available, return immediately:

---GATEFLOW-RESULT---
STATUS: ERROR
ERRORS: 0
WARNINGS: 0
FILES: []
DETAILS: No lint tool available. Install Verilator (recommended) or Verible.
  macOS: brew install verilator
  Linux: sudo apt install verilator
---END-GATEFLOW-RESULT---

Do NOT attempt to lint without a tool. Return the ERROR status and let the orchestrator handle it.

---

Instructions

1. Identify Files to Lint

If files specified in args: Use the provided file paths.

If no files specified: Auto-detect SV files:

ls *.sv rtl/*.sv 2>/dev/null | head -20

2. Run Verilator Lint

verilator --lint-only -Wall <files>

3. Parse and Categorize Output

Count issues by category:

• ERRORS: %Error: lines - must be fixed
• WARNINGS: %Warning-*: lines - should be reviewed

4. Explain Common Warnings

For each warning type found, explain:

| Warning | Meaning | Fix | |---------|---------|-----| | UNUSED | Signal declared but not used | Remove signal or suppress with /* verilator lint_off UNUSED */ | | UNDRIVEN | Signal never assigned a value | Assign the signal or connect it | | WIDTH | Bit width mismatch in operation | Add explicit sizing: [7:0] | | CASEINCOMPLETE | Case statement missing items | Add default: branch | | LATCH | Inferred latch from incomplete if/case | Add default assignment at start of always_comb | | BLKSEQ | Blocking assignment in always_ff | Use <= (non-blocking) in sequential blocks | | PINCONNECTEMPTY | Module port left unconnected | Connect or explicitly mark as .* | | IMPLICIT | Implicit wire declaration | Declare with logic or wire |

5. 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: No errors, warnings OK (0-N warnings acceptable)
• FAIL: One or more errors found
• ERROR: Could not run lint (missing files, tool error)

6. Example Output

Running lint on: rtl/fifo.sv, rtl/uart.sv

$ verilator --lint-only -Wall rtl/fifo.sv rtl/uart.sv

%Warning-UNUSED: rtl/fifo.sv:25: Signal 'debug_flag' is not used
%Warning-WIDTH: rtl/uart.sv:42: Operator ASSIGN expects 8 bits but got 16

## Summary

**Files:** 2 | **Errors:** 0 | **Warnings:** 2

### Warnings Explained

1. **UNUSED** (rtl/fifo.sv:25): `debug_flag` is declared but never read
   - Fix: Remove if unneeded, or suppress with lint pragma

2. **WIDTH** (rtl/uart.sv:42): Assigning 16-bit value to 8-bit signal
   - Fix: Truncate explicitly `data[7:0]` or widen the target

---GATEFLOW-RESULT---
STATUS: PASS
ERRORS: 0
WARNINGS: 2
FILES: rtl/fifo.sv,rtl/uart.sv
DETAILS: Lint passed with 2 warnings
---END-GATEFLOW-RESULT---

7. Error Case Example

$ verilator --lint-only -Wall rtl/broken.sv

%Error: rtl/broken.sv:10: syntax error, unexpected IDENTIFIER

---GATEFLOW-RESULT---
STATUS: FAIL
ERRORS: 1
WARNINGS: 0
FILES: rtl/broken.sv
DETAILS: Syntax error on line 10
---END-GATEFLOW-RESULT---

Usage by /gf Orchestrator

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

Parse ---GATEFLOW-RESULT--- block:
- STATUS: PASS -> proceed to next step
- STATUS: FAIL -> spawn sv-refactor agent with error context
- STATUS: ERROR -> report issue to user

Verilator v5 New Warnings

Lint Warnings (enabled by -Wall)

| Code | Description | |---|---| | ASSIGNEQEXPR | = used inside expression (may mean ==) | | ALWNEVER | always @* has empty event list | | ALWCOMBORDER | Variable set after use in always_comb | | IMPLICITSTATIC | Task/function variable implicitly static | | WIDTHEXPAND | Value is zero-expanded | | WIDTHTRUNC | Value is truncated | | ENUMVALUE | Enum assigned incompatible type | | CASEOVERLAP | Case values overlap | | CASTCONST | $cast always succeeds or fails | | CMPCONST | Comparison always yields constant | | MISINDENT | Misleading indentation | | MULTIDRIVEN | Signal driven by multiple always blocks | | SYNCASYNCNET | Signal mixed sync/async resets | | INFINITELOOP | Loop condition always true | | SELRANGE | Selection index out of bounds |

Style Warnings (enabled by -Wall)

| Code | Description | |---|---| | ASCRANGE | Packed vector with ascending range [0:7] | | DECLFILENAME | Module name doesn't match filename | | DEFPARAM | Deprecated defparam | | GENUNNAMED | Generate block unnamed | | IMPORTSTAR | import pkg::* in $unit scope |

v5 Behavior Changes

• WIDTH is now a meta-category: disabling WIDTH disables WIDTHEXPAND + WIDTHTRUNC
• --assert enabled by default since v5.038
• --lint-only now implies --timing

Warning Suppression

Inline Pragma

/* verilator lint_off WIDTH */
assign narrow = wide;
/* verilator lint_on WIDTH */

Control File

lint_off -rule WIDTH -file "*.sv" -match "Operator ASSIGN*"

Error Message Format

%Error: file.sv:42:5: syntax error, unexpected ';'
%Warning-WIDTH: file.sv:25:15: Operator ASSIGN expects 8 bits

Exit Codes

| Code | Meaning | |---|---| | 0 | Success (no errors or fatal warnings) | | 1 | Errors or warnings (warnings are fatal by default) |

Use -Wno-fatal to make warnings non-fatal.

Machine-Readable Output

verilator --lint-only --diagnostics-sarif *.sv  # SARIF JSON output