RTL Design / Module 9: Lint Β· CDC Β· Timing Β· Area Β· QoR
Lesson 9.4

Reading a lint report and fixing root causes

A lint report is a structured bug list. The skill is not clicking "waive all" β€” it is triage by severity, cluster by rule, and fix the RTL pattern that caused a dozen related violations.

Root cause fix

Change the RTL so the violation class disappears everywhere β€” not just silence one line with a pragma while the same pattern repeats in 40 modules.

1

Anatomy of a lint report line

Every violation has the same skeleton. Learn to read it once and you can triage any tool β€” SpyGlass, VC SpyGlass, Verilator -Wall, or your CI dashboard.

[ERROR] W123 INFERRED_LATCH (severity=8) fifo_ctrl.v : 47 : 3-12 Signal 'ptr_gray' may infer latch β€” not all branches assign [WARNING] CDC_NO_SYNC uart_top.v : 112 Crossing from clk_uart to clk_sys without synchronizer Source: tx_done_reg Dest: irq_pending[3] [INFO] STY_NON_BLOCK alu.v : 88 Blocking assignment in sequential block
FieldMeaningAction
SeverityERROR / WARNING / INFOERROR blocks merge; WARNING needs fix or waiver
Rule IDe.g. INFERRED_LATCHLook up in rule deck; cluster fixes
File:lineExact locationJump there β€” but check pattern elsewhere
MessageHuman-readable whyMaps to fix pattern from 9.1–9.3
Lint triage workflow
2

Sample violations β€” read and fix

violation_source.v
// This file generates 4 lint violations β€” find and fix each
module violation_source (
  input  wire       clk, clk_uart,
  input  wire       rst_n,
  input  wire       en,
  input  wire [7:0] data,
  input  wire       tx_done,
  output reg  [7:0] out,
  output reg        irq
);
  // V1: INFERRED_LATCH β€” line 15
  always @(*) begin
    if (en) out = data;
  end

  // V2: GATED_CLOCK β€” line 20
  wire gclk = clk & en;
  reg [3:0] cnt;
  always @(posedge gclk) cnt <= cnt + 1;

  // V3: CDC_NO_SYNC β€” line 26
  always @(posedge clk)
    irq <= tx_done;  // tx_done from clk_uart domain

  // V4: MULTIPLE_DRIVER β€” line 30 (if assign added below)
endmodule
// assign out = 8'hFF;  // uncomment β†’ MULTIPLE_DRIVER
violation_fixed.v
// Root-cause fixes for all four violation classes
module violation_fixed (
  input  wire       clk, clk_uart,
  input  wire       rst_n,
  input  wire       en,
  input  wire [7:0] data,
  input  wire       tx_done,
  output reg  [7:0] out,
  output reg        irq
);
  // Fix V1: default assignment
  always @(*) begin
    out = 8'h00;
    if (en) out = data;
  end

  // Fix V2: enable flop, not gated clock
  reg [3:0] cnt;
  always @(posedge clk) begin
    if (!rst_n) cnt <= 0;
    else if (en) cnt <= cnt + 1;
  end

  // Fix V3: 2-flop synchronizer for CDC
  reg tx_done_meta, tx_done_sync;
  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) {tx_done_meta, tx_done_sync} <= 2'b00;
    else        {tx_done_meta, tx_done_sync} <= {tx_done, tx_done_meta};
  end
  always @(posedge clk)
  irq <= tx_done_sync;
endmodule
3

Severity policy β€” when to fix vs waive

SeverityTypical policyWaiver acceptable when…
ERRORZero at mergeAlmost never β€” fix RTL
WARNINGFix or approved waiverThird-party encrypted IP, documented false positive
INFOTeam discretionStyle rules with agreed exceptions
Trap

Waiving without a root-cause note creates audit debt. Six months later nobody knows if the waiver hid a real CDC bug or a style nit. Every waiver needs: rule ID, justification, owner, expiry date.

Read line→Understand rule→Fix pattern→Re-run lint→Waive only if false positive
4

Clustering β€” one fix, many violations

A report with 200 INFERRED_LATCH warnings often means one coding habit, not 200 unique bugs. Fix the macro pattern:

  1. Sort report by rule ID β€” count occurrences
  2. Pick the top rule β€” usually latch, CDC, or clock
  3. Find the shared anti-pattern (missing default, no sync, gated clk)
  4. Apply team coding template β€” re-run lint
  5. Repeat until ERROR count is zero

Pro workflow: Export lint to CSV, pivot by rule ID and module. Present "top 5 rule clusters" in review instead of scrolling 10,000 lines.

5

False positives β€” verify before waiving

Some violations are tool limitations, not real bugs. Before waiving, confirm:

  • The signal is actually in the domain the tool claims
  • Encrypted IP black-boxes aren't generating phantom crossings
  • Your SDC/UPF matches the RTL clock names
  • Generated RTL (FIFO wrappers) has lint waivers in the generator, not hand-edited
  • Simulation and formal agree the path is safe (for CDC waivers)
waiver_template.txt
# Waiver record β€” required fields
Rule:       CDC_NO_SYNC
Module:     third_party_phy_wrap
Line:       0 (encrypted)
Severity:   WARNING
Owner:      jsmith
Date:       2026-03-15
Expiry:     2027-03-15  (annual review)
Justification: Encrypted PHY IP; vendor signoff doc #PHY-CDC-042
              confirms internal 2FF sync. Our lint cannot see inside.
Action:     None β€” IP-level waiver in waiver.tcl
Re-verify:  Re-run after PHY IP version bump
6

CI integration β€” lint as a merge gate

Production flows wire lint into CI with a pass/fail threshold. Your job as a designer is to keep the local run green before pushing.

lint_ci_example.sh
#!/bin/bash
# Typical block-level lint CI step
sg_shell -tcl lint_block.tcl | tee lint.rpt
ERROR_COUNT=$(grep -c "Severity: Error" lint.rpt)
WARN_COUNT=$(grep -c "Severity: Warning" lint.rpt)
echo "Errors: $ERROR_COUNT  Warnings: $WARN_COUNT"
if [ "$ERROR_COUNT" -gt 0 ]; then
  echo "LINT FAILED β€” fix ERRORs before merge"
  exit 1
fi
# Warnings over threshold also fail in strict teams
if [ "$WARN_COUNT" -gt 50 ]; then
  echo "WARNING budget exceeded β€” triage before merge"
  exit 1
fi
echo "LINT PASSED"
CI stageRuntimeRules enabled
Pre-commit (local)< 2 minLatch, multi-drive, basic clock
PR check5–15 minFull block deck
Nightly SoC1–4 hrsCDC, RDC, full chip
7

From lint clean to CDC mindset

Clock/reset and CDC rules dominate signoff reports on SoCs. Lessons 9.5–9.6 shift from "fix the warning" to "design domains correctly." For the full CDC methodology, see the CDC deep-dive course.

🎯 What to remember

  • Read severity β†’ rule ID β†’ location β†’ message. Cluster by rule, not by line.
  • ERROR = fix RTL. WARNING = fix or documented waiver. INFO = team policy.
  • One anti-pattern often causes dozens of violations β€” fix the pattern.
  • Waivers need owner, justification, and expiry β€” not "waive all."
  • Next: why multi-clock SoCs exist and why CDC is a designer concern.
Advertisement