Vl-lint
A linting tool for Verilog and SystemVerilog.
Introduction
A linter is a
tool that looks for possible bugs in a program. We have used vl to
implement a linter for Verilog and SystemVerilog designs. It can warn you
about things such as:
- Wires driven by multiple sources
- Width mismatches in assignments and subexpressions
- Strange expressions like a & a
- Duplicated module elements
- Unused and unset wires and parts of wires
- Possible confusion about operator precedence
- Strange statements that sometimes indicate copy/paste errors
Running the Linter
For detailed usage run vl lint --help or see *vl-lint-help*.
A typical invocation might look like this:
vl lint my_mod1.v my_mod2.v <-- starting files to load
-s libs/my_lib1 <-- search paths for finding
-s libs/my_lib2 additional modules
The linter will print some progress messages as it runs, then writes its
report in both text and json formats.
Output Text Files
The linter generally produces many warnings. To try to filter this out and
make it easy to focus on the most important warnings, we split the output into
several files. Here is a summary;
- Generic warnings: (probably the most interesting)
- vl-basic.txt - basic warnings
- Size warnings: (often interesting)
- vl-trunc.txt - truncations and extensions in assignments
- vl-fussy.txt - size mismatches inside of expressions like a & b
- vl-trunc-minor.txt - unlikely to be problems
- vl-fussy-minor.txt - unlikely to be problems
- Code cleanup: (helpful when refactoring)
- vl-lucid.txt - unused/undriven and multiply driven wires
- vl-same-ports.txt - redundant submodule instances
- vl-same-ports-minor.txt - unlikely to be problems
- Code smells (sometimes interesting)
- vl-smells.txt - weird expressions, duplicate rhs expressions
- Skipped wire detection (only occasionally useful)
- vl-skipdet.txt - high-scoring expressions, more likely to be problems
- vl-skipdet-minor.txt - low-scoring expressions, unlikely to be problems
- Other unclassified warnings
- vl-other.txt - tool errors, misc garble
Output JSON files
All warnings produced by the linter are also put into vl-warnings.json.
This file is intended for use in scripts that process the linter's output, such
as lint warning emailers or similar.
Suppressing False Positives
You can tell the linter to ignore certain things by adding comments to your
Verilog source files. For instance:
//@VL LINT_IGNORE_TRUNCATION // to suppress the truncation warning
assign foo[3:0] = bar[5:0];
//@VL LINT_IGNORE // to suppress all warnings
assign foo[3:0] = bar[5:0];
This feature is probably fancier than anyone needs; see lint-warning-suppression for details.
Note that there are also some command-line options to suppress all warnings
for particular modules, or all warnings of particular types, etc. See *vl-lint-help* for details.
Subtopics
- Vl-lintconfig-p
- Command-line options for running vl lint.
- Condcheck
- Check for ?:-expressions with strange conditions.
- Lint-warning-suppression
- An attribute- mechanism for suppressing particular warnings
when using vl-lint.
- Lucid
- Check for unused, unset, spurious wires, and multiply driven wires.
- Lvaluecheck
- Checks to ensure that expressions used in lvalue positions are valid
in the sense of vl-expr-net-lvalue-p or vl-expr-variable-lvalue-p, depending on the context.
- Vl-interfacelist-alwaysstyle
- (vl-interfacelist-alwaysstyle x) maps vl-interface-alwaysstyle across a list.
- Truncation-warnings
- Warnings about implicit truncation and extensions in assignments,
casts, and so forth.
- Vl-modulelist-alwaysstyle
- (vl-modulelist-alwaysstyle x) maps vl-module-alwaysstyle across a list.
- Skip-detection
- We try to detect missing signals from expressions.
- Vl-lint-report
- Vl-lintresult
- Results from running the linter.
- Vl::vl-design-sv-use-set
- Analyze used/set variables using SV's semantics.
- Oddexpr-check
- Check for odd expressions that might indicate precedence problems.
- Leftright-check
- Check for strange expressions like A [op] A.
- Duplicate-detect
- Check for instances and assignments that are literally identical.
- Selfassigns
- Simple check for self-assignments.
- *vl-lint-help*
- Usage message for vl lint.
- Arith-compare-check
- Warn about comparisons involving arithmetic operators.
- Dupeinst-check
- Check for module instances that are driving wires in identical ways.
- Qmarksize-check
- Check the sizes of conditional expression tests.
- Lint-whole-file-suppression
- A filter for dropping warnings from whole modules (and other
design elements) based on filenames.
- Run-vl-lint-main
- Logicassign
- Basic check for declaration-time assignments to logic variables.
- Run-vl-lint
- Vl-print-certain-warnings
- Print warnings of interest to standard output, while hiding other
warnings.
- Duperhs-check
- Check for assignments with the same right-hand side.
- Vl-lint-top
- Top-level vl lint command.
- Sd-filter-problems
- Vl-modulelist-add-svbad-warnings
- Vl-module-add-svbad-warnings
- Check-case
- Basic checker to ensure that wire names don't differ only by case.
- Vl-lint-extra-actions
- Customizable hook to run at the end of VL Lint.
- Drop-lint-stubs
- (Unsound transform) Replace instances annotated with LINT_IGNORE_INST,
with an instance intended not to generate uninteresting lint
warnings.
- Vl-lint-print-warnings
- Drop-user-submodules
- (Unsound transform) Remove modules that the user says to drop, and
simultaneously remove all instances of these submodules.
- Check-namespace
- A check for basic, incorrect constructs like name clashes.
- Vl-lintconfig-loadconfig
- Vl-lint-design->svex-modalist-wrapper
- Vl-delete-sd-problems-for-modnames-aux
- Vl-collect-new-names-from-orignames
- Vl-lint-print-all-warnings
- Vl-design-remove-unnecessary-modules
- Vl-delete-sd-problems-for-modnames
- Vl-always-check-style
- Vl-vardecllist-svbad-warnings
- Vl-vardecl-svbad-warnings
- Vl-reportcard-remove-suppressed
- Vl-reportcard-keep-suppressed
- Vl-alwayslist-check-style
- Vl-remove-nameless-descriptions
- Vl-lint-apply-quiet
- Vl-warninglist-remove-suppressed
- Vl-warninglist-keep-suppressed
- Vl-print-eliminated-descs
- Vl-module-alwaysstyle
- Vl-jp-reportcard-aux
- Vl-interface-alwaysstyle
- Vl-design-alwaysstyle
- Vl-jp-description-locations
- Vl-jp-reportcard
- Vl-pp-stringlist-lines
- Vl-jp-design-locations
- Vl-datatype-svbad-p
- Unpacked-range-check
- Warn about partselects on unpacked arrays.
- Sd-problem-major-p
- Vl-alwaysstyle
- Simple lint check for any uses of legacy style always
statements, as opposed to the newer always_comb, always_ff, or
always_latch versions.
