Linting RTL with Verilator, slang and svlint

fan_ctrl.sv is a 31-line fan controller, and its directed test passes all 12 of its checks. Three linters read the same file without running it and report six problems, four of them bugs: at 46 °C the fan stops, at −5 °C it runs, full mode is not full and the overheat flag never rises.

Each linter reads code in its own way. Verilator reads the design as a simulator does, slang checks it against the language standard to the letter, and svlint checks the rules a team has chosen. Here you run all three on that file, read what each one reports, fix or waive every finding, and turn the three into a gate that a change must pass before it merges.

A passing test hid four bugs that lint reports

The controller sets a fan’s duty cycle, from 0 to 15 sixteenths of full speed, from the temperature and a mode: off, quiet, auto or full. Its author tested what they had in mind, twelve cases from 20 to 45 °C in the first three modes, and built the simulation the way their script always had, with Verilator’s lint warnings switched off:

// A fan controller: the duty cycle, 0 to 15 sixteenths of full speed, follows the temperature.
module fan_ctrl (
  input  logic              clk,
  input  logic              rst_n,
  input  logic signed [7:0] temp_c,   // degrees Celsius, -128 to 127
  input  logic        [7:0] start_c,  // the fan starts above this temperature
  input  logic        [1:0] mode,     // 0 off, 1 quiet, 2 auto, 3 full
  output logic        [3:0] duty,     // sixteenths of full speed
  output logic              hot       // above 80 degrees for 300 cycles
);
  logic [7:0] excess;                 // degrees above start_c
  logic [7:0] hot_count;

  always_ff @(posedge clk or negedge rst_n)
    if (!rst_n)                excess = '0;
    else if (temp_c > start_c) excess = temp_c - start_c;
    else                       excess = '0;

  always_comb
    case (mode)
      2'd0: duty = 4'd0;
      2'd1: duty = excess[7:1];
      2'd2: duty = excess;
    endcase

  always_ff @(posedge clk or negedge rst_n)
    if (!rst_n)               hot_count <= '0;
    else if (temp_c > 8'sd80) hot_count <= hot_count + 1'b1;

  assign hot = hot_count == 300;
endmodule

// The fan controller's directed test: the twelve cases its author thought of, then, with +skipped, four that the
// test left out. Expected duty: off 0; quiet half the degrees above start_c; auto the degrees above start_c; full
// 15; never more than 15.
`timescale 1ns / 1ps
module tb_fan_ctrl;
  logic              clk;
  logic              rst_n;
  logic signed [7:0] temp_c;
  logic signed [7:0] start_c;
  logic        [1:0] mode;
  logic        [3:0] duty;
  logic              hot;
  int                checks = 0, failed = 0;

  fan_ctrl dut (.clk(clk), .rst_n(rst_n), .temp_c(temp_c), .start_c(start_c), .mode(mode), .duty(duty), .hot(hot));

  initial clk = 1'b0;
  always #5 clk = ~clk;

  function automatic int expected(input int t, input int m);
    int above;
    above = (t > 30) ? t - 30 : 0;
    case (m)
      0:       return 0;
      1:       return (above / 2 > 15) ? 15 : above / 2;
      2:       return (above > 15) ? 15 : above;
      default: return 15;
    endcase
  endfunction

  task automatic check(input int t, input int m);
    int want;
    want   = expected(t, m);
    temp_c = 8'(t);
    mode   = 2'(m);
    @(posedge clk);
    #1;
    checks++;
    if (int'(duty) != want) begin
      failed++;
      $display("FAIL %4d C, mode %0d: duty %2d, expected %2d", t, m, duty, want);
    end
  endtask

  initial begin
    rst_n   = 1'b0;
    temp_c  = 8'sd20;
    start_c = 8'sd30;
    mode    = 2'd0;
    #12 rst_n = 1'b1;
    for (int m = 0; m < 3; m++) begin
      check(20, m);
      check(30, m);
      check(40, m);
      check(45, m);
    end
    if ($test$plusargs("skipped")) begin
      check(46, 2);
      check(-5, 2);
      check(40, 3);
      temp_c = 8'sd85;
      repeat (300) @(posedge clk);
      #1;
      checks++;
      if (hot !== 1'b1) begin
        failed++;
        $display("FAIL   85 C for 300 cycles: hot %b, expected 1", hot);
      end
    end
    $display("%0d of %0d checks passed", checks - failed, checks);
    $finish;
  end
endmodule

from session import run

# The directed test as its author ran it: Verilator builds the simulation with its lint warnings switched off
# (-Wno-lint), the twelve checks pass, and +skipped adds the four cases the test left out. Then the fixed design,
# built with every warning on.
run("""
verilator --binary -j 0 --quiet -Wno-lint --top-module tb_fan_ctrl tb_fan_ctrl.sv fan_ctrl.sv
obj_dir/Vtb_fan_ctrl +verilator+quiet
obj_dir/Vtb_fan_ctrl +verilator+quiet +skipped
verilator --binary -j 0 --quiet -Wall --top-module tb_fan_ctrl -Mdir obj_fixed tb_fan_ctrl.sv fixed/fan_ctrl.sv
obj_fixed/Vtb_fan_ctrl +verilator+quiet +skipped
""")

# Verilator 5.052
$ verilator --binary -j 0 --quiet -Wno-lint --top-module tb_fan_ctrl tb_fan_ctrl.sv fan_ctrl.sv
$ obj_dir/Vtb_fan_ctrl +verilator+quiet
12 of 12 checks passed
- tb_fan_ctrl.sv:71: Verilog $finish
$ obj_dir/Vtb_fan_ctrl +verilator+quiet +skipped
FAIL   46 C, mode 2: duty  0, expected 15
FAIL   -5 C, mode 2: duty 13, expected  0
FAIL   40 C, mode 3: duty 13, expected 15
FAIL   85 C for 300 cycles: hot 0, expected 1
12 of 16 checks passed
- tb_fan_ctrl.sv:71: Verilog $finish
$ verilator --binary -j 0 --quiet -Wall --top-module tb_fan_ctrl -Mdir obj_fixed tb_fan_ctrl.sv fixed/fan_ctrl.sv
$ obj_fixed/Vtb_fan_ctrl +verilator+quiet +skipped
16 of 16 checks passed
- tb_fan_ctrl.sv:71: Verilog $finish

All twelve checks passed. The four cases the test left out failed: 46 °C in auto mode gave a duty of 0, −5 °C gave 13, full mode kept the 13 it had, and 300 cycles at 85 °C never raised hot. None of them is exotic; each is one input the author did not try.

Lintlint: Checking source code without running it for constructs that are legal but suspicious, such as a signal that is never read or a width that does not match; a lint tool reports them as warnings. More in “How chips are designed and verified” finds such bugs from the code alone, because each one leaves a mark that a reader can see: an 8-bit value assigned to a 4-bit output, a case with a missing value, a signed number compared with an unsigned one, an 8-bit counter compared with 300. A test finds a bug only when it happens to drive the input that shows it; a linter reads every line on every run. The last run above is the same test on fixed/fan_ctrl.sv, the version that every linter of this lesson passes: 16 of 16 checks.

Verilator reports lint warnings by default, and style warnings when asked

verilator --lint-only reads and elaborates the design as it would for a simulation, then stops before it writes any C++. Its manual describes the option as a check for lint violations that creates no other output, and -Wall adds the messages it considers stylistic, the style warningsstyle warning (Verilator): A Verilator warning about a way of writing code that tends to cause mistakes later, such as BLKSEQ for a blocking = in a clocked block. Style warnings are off by default and switched on with -Wall., which are off by default. Here is fan_ctrl.sv with every class on, then a count of the warnings with and without -Wall:

from session import run

# Verilator's lint with every warning class on (-Wall), then how many warnings each setting reports. With -Wno-fatal
# the warnings are still printed, but the command succeeds, so a script that reads only the exit status sees none.
run("""
!verilator --lint-only -Wall fan_ctrl.sv
verilator --lint-only fan_ctrl.sv 2>&1 | grep -c "^%Warning"
verilator --lint-only -Wall -Wno-fatal fan_ctrl.sv > lint.log 2>&1
grep -c "^%Warning" lint.log
""")

# Verilator 5.052
$ verilator --lint-only -Wall fan_ctrl.sv
%Warning-WIDTHTRUNC: fan_ctrl.sv:22:18: Operator ASSIGN expects 4 bits on the Assign RHS, but Assign RHS's SEL generates 7 bits.
                                      : ... note: In instance 'fan_ctrl'
   22 |       2'd1: duty = excess[7:1];
      |                  ^
                     ... For warning description see https://verilator.org/warn/WIDTHTRUNC?v=5.052
                     ... Use "/* verilator lint_off WIDTHTRUNC */" and lint_on around source to disable this message.
%Warning-WIDTHTRUNC: fan_ctrl.sv:23:18: Operator ASSIGN expects 4 bits on the Assign RHS, but Assign RHS's VARREF 'excess' generates 8 bits.
                                      : ... note: In instance 'fan_ctrl'
   23 |       2'd2: duty = excess;
      |                  ^
%Warning-WIDTHEXPAND: fan_ctrl.sv:30:26: Operator EQ expects 32 or 9 bits on the LHS, but LHS's VARREF 'hot_count' generates 8 bits.
                                       : ... note: In instance 'fan_ctrl'
   30 |   assign hot = hot_count == 300;
      |                          ^~
                      ... For warning description see https://verilator.org/warn/WIDTHEXPAND?v=5.052
                      ... Use "/* verilator lint_off WIDTHEXPAND */" and lint_on around source to disable this message.
%Warning-BLKSEQ: fan_ctrl.sv:15:39: Blocking assignment '=' in sequential logic process
                                  : ... note: In instance 'fan_ctrl'
                                  : ... Suggest using delayed assignment '<='
   15 |     if (!rst_n)                excess = '0;
      |                                       ^
                 ... For warning description see https://verilator.org/warn/BLKSEQ?v=5.052
                 ... Use "/* verilator lint_off BLKSEQ */" and lint_on around source to disable this message.
%Warning-BLKSEQ: fan_ctrl.sv:16:39: Blocking assignment '=' in sequential logic process
                                  : ... note: In instance 'fan_ctrl'
                                  : ... Suggest using delayed assignment '<='
   16 |     else if (temp_c > start_c) excess = temp_c - start_c;
      |                                       ^
%Warning-BLKSEQ: fan_ctrl.sv:17:39: Blocking assignment '=' in sequential logic process
                                  : ... note: In instance 'fan_ctrl'
                                  : ... Suggest using delayed assignment '<='
   17 |     else                       excess = '0;
      |                                       ^
%Warning-CASEINCOMPLETE: fan_ctrl.sv:20:5: Case values incompletely covered (example pattern 0x3)
   20 |     case (mode)
      |     ^~~~
                         ... For warning description see https://verilator.org/warn/CASEINCOMPLETE?v=5.052
                         ... Use "/* verilator lint_off CASEINCOMPLETE */" and lint_on around source to disable this message.
%Warning-LATCH: fan_ctrl.sv:19:3: Latch inferred for signal 'duty' (not all control paths of combinational always assign a value)
                                : ... Suggest use of always_latch for intentional latches
   19 |   always_comb
      |   ^~~~~~~~~~~
                ... For warning description see https://verilator.org/warn/LATCH?v=5.052
                ... Use "/* verilator lint_off LATCH */" and lint_on around source to disable this message.
%Error: Exiting due to 8 warning(s)
[exit status 1]
$ verilator --lint-only fan_ctrl.sv 2>&1 | grep -c "^%Warning"
5
$ verilator --lint-only -Wall -Wno-fatal fan_ctrl.sv > lint.log 2>&1
$ grep -c "^%Warning" lint.log
8

Each warning starts with its code, then the file, line and column, then what Verilator expected and what it found: Operator ASSIGN expects 4 bits on the Assign RHS, but Assign RHS's VARREF 'excess' generates 8 bits. The excerpt under it marks the place, and the last two lines say where the code is described and how to waive it. Read the code first, because it names the kind of mistake:

Without -Wall Verilator reported 5 warnings; with it, 8, the three BLKSEQ lines added. The lint class is about what the code computes, the style class about ways of writing that cause mistakes later. BLKSEQ is harmless in this file today, because only the combinational block reads excess, and it becomes a race on the day another clocked block reads it.

The -Wall run ended with %Error: Exiting due to 8 warning(s) and exit statusexit status: The number a program returns when it ends: 0 for success, any other value for failure. Scripts and continuous integration jobs read it to decide whether to go on. 1, and that status is what a script can act on. -Wno-fatal keeps the messages and returns 0: the run with it wrote all 8 warnings into lint.log and still succeeded, so a job that reads only the exit status would have passed the file.

slang and svlint report what Verilator does not

slang is a SystemVerilog compiler front end whose stated aim is complete support of the 1800-2023 standard, and its warnings come in groups: -Wextra adds width and latch checks to a small default set, and a single warning can be named, such as -Wsign-compare. svlint checks each file’s syntax tree against rules that a team switches on in a file named .svlint.toml unless --config names another, svlint.toml here; its manual says every rule is off until it is enabled there. Yosys, this track’s synthesis tool, runs too, because synthesis refuses some code outright:

# The project's svlint rules: every rule is off until this file switches it on.
[option]
textwidth = 100

[textrules]
style_textwidth = true

[syntaxrules]
default_nettype_none = true
blocking_assignment_in_always_ff = true
case_default = true
keyword_forbidden_always = true

from session import run

# The same file through slang, svlint and synthesis. slang reports warnings as errors here (-Werror), so that its
# exit status says whether it found anything; svlint reads the project's rules from svlint.toml.
run("""
!slang -Wextra -Wsign-compare -Werror fan_ctrl.sv
!svlint --config svlint.toml fan_ctrl.sv
!yosys -q -p "read_verilog -sv fan_ctrl.sv; proc"
""")

# slang 12.0.0 · svlint 0.9.5 · Yosys 0.69
$ slang -Wextra -Wsign-compare -Werror fan_ctrl.sv
fan_ctrl.sv:16:21: error: comparison of differently signed types ('logic signed[7:0]' and 'logic[7:0]') [-Wsign-compare]
    else if (temp_c > start_c) excess = temp_c - start_c;
             ~~~~~~ ^ ~~~~~~~
fan_ctrl.sv:22:20: error: implicit conversion truncates from 7 to 4 bits [-Wwidth-trunc]
      2'd1: duty = excess[7:1];
                 ~ ^~~~~~~~~~~
fan_ctrl.sv:23:20: error: implicit conversion truncates from 8 to 4 bits [-Wwidth-trunc]
      2'd2: duty = excess;
                 ~ ^~~~~~
fan_ctrl.sv:21:13: error: latch inferred for 'duty' because it is not assigned on all control paths [-Winferred-latch]
      2'd0: duty = 4'd0;
            ^~~~
Top level design units:
    fan_ctrl


Build failed: 4 errors, 0 warnings
[exit status 1]
$ svlint --config svlint.toml fan_ctrl.sv
Fail: default_nettype_none
   --> fan_ctrl.sv:2:1
  |
2 | module fan_ctrl (
  | ^^^^^^ hint  : Place `` `default_nettype none`` at the top of source code.
  |        reason: Compiler directive `` `default_nettype none`` detects unintentional implicit wires.

Fail: blocking_assignment_in_always_ff
   --> fan_ctrl.sv:14:3
   |
14 |   always_ff @(posedge clk or negedge rst_n)
   |   ^^^^^^^^^ hint  : Do not use blocking assignments within `always_ff`.
   |             reason: Blocking assignment in `always_ff` may cause undefined event ordering.

Fail: case_default
   --> fan_ctrl.sv:20:5
   |
20 |     case (mode)
   |     ^^^^ hint  : Use a `default` expression in `case` statements.
   |          reason: Incomplete case may cause simulation/synthesis mismatch in `always_comb` and `function`.
[exit status 1]
$ yosys -q -p "read_verilog -sv fan_ctrl.sv; proc"
ERROR: Latch inferred for signal `\fan_ctrl.\duty' from always_comb process `\fan_ctrl.$proc$fan_ctrl.sv:19$5'.
[exit status 1]

slang’s first error is the bug that no other tool reported. temp_c is signed and start_c is not, and the standard’s rule for an expression’s type (IEEE 1800-2023, 11.8.1) makes the whole comparison unsigned when one operand is unsigned. −5 °C is the bit pattern 251, which is greater than 30, so the fan starts, and 251 − 30 = 221 leaves 13 in the four bits of duty: the 13 of the failed check. svlint found three breaks of the team’s rules. One of them, the missing `default_nettype none, is no bug today, but without it a misspelt name becomes a new 1-bit wire instead of an error. Yosys stopped at the latch, so this file would never reach a netlistnetlist: A list of the cells a design uses and the wires that connect them, written by synthesis and read by place and route and by timing analysis. More in “How chips are designed and verified”.

Read the table down the right-hand column: each of the three linters has a row that only it reports, and each misses something. That is why a project runs more than one linter.

A waiver names one warning, one place and the reason for it

Most findings are fixed in the code, and the fix usually says more than the old code did: fixed/fan_ctrl.sv compares two signed values, saturates the duty before it takes excess[3:0], counts to 300 in 9 bits and gives mode 3 its own item. A warning about something the design really wants, such as a truncation, is often best answered with a cast, 16'(now_us), which states the intent where it applies and leaves nothing to waive.

When the code cannot change, a lint waiverlint waiver: A comment or a configuration line that turns off one lint warning at one named place in the code, with the reason for it. A flag that turns a warning off for a whole design hides every later instance of it too. More in “RTL coding style that scales” is the tool, and it should be as narrow as it can be: one rule, one place and a comment that says why. Each tool has its own comment form:

• Verilator: /* verilator lint_off WIDTHTRUNC */ before the line and /* verilator lint_on WIDTHTRUNC */ after it.
• slang: // slang lint_off width-trunc and // slang lint_on width-trunc.
• svlint: /* svlint off case_default */ and /* svlint on case_default */, for its syntax rules.

For a file you may not edit, such as a supplied block, Verilator reads a control filecontrol file (Verilator): A file that begins with `verilator_config and holds commands such as lint_off -rule WIDTHTRUNC -file "*x.sv" -lines 10, so that a warning in a file you may not edit is waived without changing the file. with the same waiver for a named file and line: lint_off -rule WIDTHTRUNC -file "*stamp_legacy.sv" -lines 10. Its manual says that such a waiver applies only to files read after the control file, so the control file goes first on the command line.

A switch on the command line, -Wno-WIDTHTRUNC, is a waiver for every line of every file, the lines written next year included. Walk through what that did in one project:

The drill replays the last two changes: the old command with its two global switches, then the control file that waives the two warnings for the supplied file’s two lines only.

`default_nettype none
// A supplied timestamp block: it keeps the low 16 bits of a 32-bit time on purpose, so that the stamp wraps.
module stamp_legacy (
  input  logic        clk,
  input  logic        take,
  input  logic [31:0] now_us,
  output logic [15:0] stamp
);
  always_ff @(posedge clk)
    if (take) stamp <= now_us;
endmodule
`default_nettype wire

`default_nettype none
// A later change: the fan's speed can be set by hand, in percent.
module fan_override (
  input  logic       clk,
  input  logic       set,          // a new setting arrives
  input  logic [6:0] pct,          // 0 to 100 percent
  output logic [3:0] duty          // sixteenths of full speed
);
  always_ff @(posedge clk)
    if (set) duty <= pct * 16 / 100;
endmodule
`default_nettype wire

`verilator_config
// stamp_legacy.sv is supplied and not ours to edit: it keeps the low 16 bits of the time on purpose (its spec, 4.2).
lint_off -rule WIDTHTRUNC -file "*stamp_legacy.sv" -lines 10
lint_off -rule UNUSEDSIGNAL -file "*stamp_legacy.sv" -lines 6

from session import run

# The project's old lint command switched two warnings off for every file, to quiet the supplied stamp_legacy.sv.
# Then fan_override.sv arrived. The new command waives the two warnings for the supplied file's two lines only.
run("""
for f in stamp_legacy.sv fan_override.sv; do verilator --lint-only -Wall --quiet -Wno-WIDTHTRUNC -Wno-UNUSEDSIGNAL $f; done
!for f in stamp_legacy.sv fan_override.sv; do verilator --lint-only -Wall --quiet waivers.vlt $f || exit 1; done
""")

# Verilator 5.052
$ for f in stamp_legacy.sv fan_override.sv; do verilator --lint-only -Wall --quiet -Wno-WIDTHTRUNC -Wno-UNUSEDSIGNAL $f; done
$ for f in stamp_legacy.sv fan_override.sv; do verilator --lint-only -Wall --quiet waivers.vlt $f || exit 1; done
%Warning-WIDTHTRUNC: fan_override.sv:10:19: Operator ASSIGNDLY expects 4 bits on the Assign RHS, but Assign RHS's DIV generates 32 or 7 bits.
                                          : ... note: In instance 'fan_override'
   10 |     if (set) duty <= pct * 16 / 100;
      |                   ^~
                     ... For warning description see https://verilator.org/warn/WIDTHTRUNC?v=5.052
                     ... Use "/* verilator lint_off WIDTHTRUNC */" and lint_on around source to disable this message.
[exit status 1]

The old command printed nothing for either file, so the bug in fan_override.sv would have merged unseen: 100 × 16 / 100 = 16, which needs five bits, and the four bits of duty keep 0, so the override turns the fan off at 100 %. The scoped waiver kept the supplied file quiet and reported line 10 of the new one.

Lint becomes a gate when its exit status stops a merge

A linter that someone runs when they remember protects nothing. A gate runs on every change, the same way on every computer, and a change merges only when the gate ends with exit status 0. lint.sh is this project’s gate: it runs all three linters on the files it is given, so that one run lists everything to fix, and it fails if any of them fails.

#!/bin/sh
# The lint gate: three linters on the files given. Each must be clean, or the gate fails (exit status 1) and the
# change does not merge. Every linter runs, so one run shows everything that needs fixing.
status=0
verilator --lint-only -Wall --quiet waivers.vlt "$@" > verilator.log 2>&1 ||
  { echo "verilator: $(grep -c '^%Warning' verilator.log) warnings"; status=1; }
slang -q -Wextra -Wsign-compare -Werror "$@" > slang.log 2>&1 ||
  { echo "slang: $(grep -c ': error:' slang.log) errors"; status=1; }
svlint --config svlint.toml "$@" > svlint.log 2>&1 ||
  { echo "svlint: $(grep -c '^Fail' svlint.log) rule failures"; status=1; }
if [ "$status" -eq 0 ]; then echo "lint gate: clean"; fi
exit "$status"

from session import run

# The gate on the original file, then on the fixed one.
run("""
!sh lint.sh fan_ctrl.sv
sh lint.sh fixed/fan_ctrl.sv
""")

# Verilator 5.052 · slang 12.0.0 · svlint 0.9.5
$ sh lint.sh fan_ctrl.sv
verilator: 8 warnings
slang: 4 errors
svlint: 3 rule failures
[exit status 1]
$ sh lint.sh fixed/fan_ctrl.sv
lint gate: clean

On the original file the gate reported 8 Verilator warnings, 4 slang errors and 3 svlint rule failures and ended with status 1; on the fixed file it printed lint gate: clean. Each tool’s exit status needs care. Verilator fails on any warning unless it is given -Wno-fatal, so the gate never gives it that. slang fails only on errors, so the gate passes -Werror, which its manual describes as treating all warnings as errors; without it the four findings would have printed and passed. svlint fails on any rule failure.

In a project the same script runs in two places: on the engineer’s computer before a commit, and in the continuous integrationcontinuous integration (CI): A service that builds and checks every change pushed to a shared repository, such as a pull request, so that a change that fails a check is stopped before it merges. job of every pull request, which the repository can be set to require before a merge. Step through one change on its way to the main branch:

The gate earns its place only while it stays fast and strict: seconds per change, no finding allowed, and every waiver written in the code, next to the line it waives, where the next reader of the change sees it.

Practise: audit a file’s waivers

A gate can check the waivers too. The exercise writes the check that every waiver names its rule, gives its reason and is closed again; the sample tests use the waiver forms of this lesson:

def audit(source):
    """The problems of the file's Verilator waivers, as (line, problem) tuples sorted by line."""
    return []

from audit import audit

STAMP = """always_ff @(posedge clk)
  /* verilator lint_off WIDTHTRUNC */  // the stamp wraps on purpose
  if (take) stamp <= now_us;
  /* verilator lint_on WIDTHTRUNC */
"""


def test_clean_waiver():
    """accepts a waiver that names its rule, gives its reason and is closed"""
    assert audit(STAMP) == []
    assert audit("") == []


def test_no_reason():
    """reports a lint_off with no reason after it, or an empty one"""
    src = "/* verilator lint_off UNUSEDSIGNAL */\nlogic [7:0] spare;\n/* verilator lint_on UNUSEDSIGNAL */\n"
    assert audit(src) == [(1, "no reason")]
    assert audit(src.replace("*/\nlogic", "*/ //   \nlogic")) == [(1, "no reason")]


def test_never_closed():
    """reports a lint_off left open at the end of the file, at its own line"""
    src = "logic a;\n/* verilator lint_off WIDTHTRUNC */  // supplied code\nassign y = a;\n"
    assert audit(src) == [(2, "never closed")]


def test_no_rule():
    """reports a waiver without a rule, which would switch every warning off"""
    assert audit("/* verilator lint_off */  // quiet, please\n") == [(1, "no rule")]


def test_nothing_to_close():
    """reports a lint_on that closes nothing, here because the rules differ"""
    src = ("/* verilator lint_off WIDTHTRUNC */  // supplied code\nassign y = a;\n"
           "/* verilator lint_on WIDTHEXPAND */\n")
    assert audit(src) == [(1, "never closed"), (3, "nothing to close")]


def test_two_rules():
    """keeps the open waivers of each rule apart, and closes the latest one of the same rule"""
    src = ("/* verilator lint_off WIDTHTRUNC */  // a\n"
           "/* verilator lint_off UNUSEDSIGNAL */  // b\n"
           "/* verilator lint_on WIDTHTRUNC */\n"
           "/* verilator lint_off WIDTHTRUNC */  // c\n"
           "/* verilator lint_on UNUSEDSIGNAL */\n"
           "/* verilator lint_on WIDTHTRUNC */\n")
    assert audit(src) == []

Then check yourself on the five ideas, from the test that passed to the gate that stops a merge. The questions start where your answers have been weakest so far:

Interview questions

Why lint RTL when its testbench already passes?

A test checks only the inputs it drives, and a linter reads every line. In this lesson’s fan controller the directed test passed 12 of 12 checks while three linters reported six problems, four of them bugs: a truncated duty that stopped the fan at 46 °C, an unsigned comparison that ran it at −5 °C, a missing case item that made a latch, and a count that could never reach 300. Lint takes seconds and runs on every change, so it is the cheapest check a design has. It does not replace tests: it says whether the code is written the way its author most likely meant, not whether the design does what its specification asks.

Two harder questions follow, a global switch that let a bug through and a lint gate for a whole team:

Key takeaways

• A passing directed test checks only the inputs it drives; lint reads every line, and on fan_ctrl.sv it found four bugs that the test’s twelve checks missed.
• Verilator reports lint warnings by default and style warnings with -Wall, and it exits with status 1 on any warning unless -Wno-fatal hides them from scripts.
• slang applies the standard’s rules, such as the unsigned comparison that one unsigned operand makes, and svlint applies the rules a team switches on; each finds problems the others miss.
• Fix a finding in the code where you can, and waive it only for one rule at one place with its reason, never with a -Wno flag for the whole design.
• A lint gate runs every linter on every change and lets the change merge only when all of them end with status 0.