# 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](https://www.yosyshq.com/tabby-cad-datasheet) from [YosysHQ](https://www.yosyshq.com/)
to synthesize your code.

BugFinder is available as part of [Linty Ultra](https://linty-services.com/pricing).

BugFinder rules are tagged as [`bug-finder`](https://demo.linty-services.com/coding_rules?tags=bug-finder).

## Usage

[Activate some rules](rules_to_check) tagged
as [`bug-finder`](https://demo.linty-services.com/coding_rules?tags=bug-finder), [configure BugFinder](#configuration)
and [scan your code](scan.md#run-linty-scan).

## 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):

```bash
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.

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
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](https://yosyshq.readthedocs.io/projects/yosys/en/stable/cmd/verific.html) 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.

```bash
# 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
```

```bash
# 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](https://yosyshq.readthedocs.io/projects/yosys/en/latest/cmd/hierarchy.html) for more details.

### Configuration examples

* Simple VHDL
  project: [https://github.com/Linty-Services/linty-hdl-designer-sample](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](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](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](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](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`](https://demo.linty-services.com/coding_rules?tags=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`](#elaborate-and-synthesize-your-design)
* 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`:

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