BugFinder

BugFinder is a Linty scan engine that provides additional rules based on synthesized code analysis. Those advanced rules will help you detect bugs and vulnerabilities to improve reliability and security of your IPs.

BugFinder embeds Tabby CAD Suite from YosysHQ to synthesize your code.

BugFinder rules are tagged as bug-finder.

Usage

Activate some rules tagged as bug-finder, configure BugFinder and scan your code.

Configuration

Read your HDL files

Add a read.ys file to the root of your project to tell Linty how to read the VHDL/Verilog files of your project in the right order.

If your project already defines a filelist (Verilog/SystemVerilog only):

verific -f -sv my_filelist.f

Otherwise, manually list all files. This list of files is likely already stored somewhere in a configuration file in your project, or it can be generated from your synthesis tool. We advise you to add a script to your continuous integration process to automatically convert this configuration file to the Yosys format described below.

# List all the files of your IP in the right order.
#
# For instance, let's say that:
#   - Your IP consists of two VHDL files and one Verilog/SystemVerilog file: fly.vhd, dream.v and top.vhd
#   - The top module is defined in top.vhd
#
verific -vhdl ./fly.vhd
verific -sv ./dream.v
verific -vhdl ./top.vhd

If some files should not be compiled in work but in a specific library:

verific -work <my_specific_lib> -[vhdl|sv] <my_file>

# Example #1: Compile 'fly.vhd' VHDL file into 'dream' library
verific -work dream -vhdl fly.vhd

# Example #2: Compile 'fly.sv' SystemVerilog file into 'dream' library
verific -work dream -sv fly.sv

It’s very likely that your IP uses third-party libraries. In this case, Linty will need to read interfaces with these third-party libraries:

# If you get the following kind of error:
# VERIFIC-ERROR [VHDL-1240] ./xxx.vhd:xxx: 'vcomponents' is not compiled in library 'xpm',
# You need to add the following at the beginning of your read.ys file:
verific -work xpm -vhdl ./third-party-libraries/.../xpm_VCOMP.vhd

# If you get the following kind of error:
# VERIFIC-ERROR [VHDL-1240] ./xxx.vhd:xxx: 'blabla' is not compiled in library 'work',
# You need to add the following at the beginning of your read.ys file:
verific -vhdl -lib ./third-party-libraries/.../blabla.vhd

If for some reason, you do not have access to these third-party libraries during the Linty scan, you can tell Linty to consider third-party components as blackboxes by adding the following to the top of the read.ys file:

verific -set-warning VHDL-1240

With this configuration, note that Linty may fail to detect some errors (such as a CDC between a third-party component and your code) as Linty knows nothing about these third-party components.

See Yosys documentation for more details.

Elaborate and synthesize your design

Add a hierarchy.ys file to the root of your project to set the top module/entity and optionally pass generics/parameters.

# Example #1: Let's say that the top module/entity of your IP is 'dream'
# Make sure to pass the name of your top module and not the name of the file containing your top module.
hierarchy -top dream

# Example #2: Let's say that the top module/entity of your IP is 'dream'
# and that you want to set values for generics/parameters 'ABC' and 'DEF'
hierarchy -top dream -chparam ABC 10 -chparam DEF true

See Yosys documentation for more details.

Configuration examples

Simple VHDL project: https://github.com/Linty-Services/linty-hdl-designer-sample
Simple Verilog project reading files from filelist: https://github.com/Linty-Services/cv32e40p/blob/linty/read.ys
NEORV32, generating Linty configuration files in GitHub workflow: https://github.com/stnolting/neorv32/blob/linty_test/.github/workflows/Linty.yml
xifu-irap/fpasim-fw, list of files generated from Vivado with a Tcl command, and configuration of Xilinx third-party libraries (XPM, UNISIM, etc.): https://github.com/xifu-irap/fpasim-fw/blob/develop/read.ys
xifu-irap/dmx-fw, using third-party IP from NanoXplore: https://github.com/xifu-irap/dmx-fw/blob/develop/read.ys

Debug

Debug information is available in the .linty/bugfinder/ directory from the root of your project:

build.tcl is the script that is run to synthesize your code and gather information for BugFinder rules
The logs directory contains an output.log file that is the output of the synthesis execution and gathering of information for BugFinder rules
*.json files are data gathered from the synthesized output to feed the Linty bug-finder rules

Troubleshooting

Top module/entity not found

If you face the following issue:

Executing HIERARCHY pass (managing design hierarchy).
Statically elaborating the Verific parse tree.
Elaborating all modules in library 'work'
[HIER-1013] could not find top-level module/unit; aborting hierarchy tree creation
ERROR: Module `xxx' not found!

it means that the file containing your top module has not been read.

The reason could be that:

There is a typo in the name of the module set as top in hierarchy.ys
The top module has been compiled but in a library that is different from work. In the Linty context, make sure to always compile the top module in library work. Note that it should be the last instruction of your read.ys file. For instance, if your top module is defined in file top.v:

...
verific -sv top.v
# No more instruction