Contributing and Reporting Bugs

Announcements

To get notified of new releases and other important announcements, go to Verilator announcement repository and follow the instructions there.

Reporting Bugs

First, check the Language Limitations section.

Next, try the --debug option. This will enable additional internal assertions, and may help identify the problem.

Finally, reduce your code to the smallest possible routine that exhibits the bug (see: Minimizing bug-inducing code). Even better, create a test in the test_regress/t directory, as follows:

cd test_regress
cp -p t/t_EXAMPLE.py t/t_BUG.py
cp -p t/t_EXAMPLE.v t/t_BUG.v

There are many hints on how to write a good test in the test_regress/driver.py documentation which can be seen by running:

cd $VERILATOR_ROOT  # Need the original distribution kit
test_regress/driver.py --help

Edit t/t_BUG.py to suit your example; you can do anything you want in the Verilog code there; just make sure it retains the single clk input and no outputs. Now, the following should fail:

cd $VERILATOR_ROOT  # Need the original distribution kit
cd test_regress
t/t_BUG.py  # Run on Verilator
t/t_BUG.py --debug # Run on Verilator, passing --debug to Verilator
t/t_BUG.py --vcs  # Run on VCS simulator
t/t_BUG.py --nc|--iv|--ghdl  # Likewise on other simulators

The test driver accepts a number of options, many of which mirror the main Verilator options. For example the previous test could have been run with debugging enabled. The full set of test options can be seen by running driver.py --help as shown above.

Finally, report the bug at Verilator Issues. The bug will become publicly visible; if this is unacceptable, mail the bug report to wsnyder@wsnyder.org.

Minimizing bug-inducing code

In some cases, the part of the code that causes the bug is clearly visible and the design can be easily manually reduced. In other cases, the bug is caused by a complex interaction of many parts of the design, and it is not clear which parts are necessary to reproduce the bug. In these cases, an Open Source tool called sv-bugpoint <https://github.com/antmicro/sv-bugpoint>_ can be used to automatically reduce a SystemVerilog design to the smallest possible reproducer. It can be used to automatically reduce a design with hundreds of thousands of lines to a minimal test case while preserving the bug-inducing behavior.

Please refer to the README file for more information on how to use sv-bugpoint.

Contributing to Verilator

Thanks for using Verilator! We welcome your contributions in whatever form.

This contributing document contains some suggestions that may make contributions flow more efficiently.

Did you find a bug?

  • Please ensure the bug was not already reported by searching Verilator Issues.

  • Please download the latest development GitHub version, build, and see if the issue has been fixed.

  • If you’re unable to find an open issue addressing the problem, open a new Verilator issue.

    • Be sure to include a code sample or an executable test case demonstrating the bug and expected behavior that is not occurring.

    • The ideal example works against other simulators, and is in the test_regress/t test format, as described in Verilator Internals Documentation.

Did you write a patch that fixes a bug?

  • Please Open a new Verilator issue if there is not one already describing the bug.

  • Please Open a Verilator pull request.

  • See the coding conventions, and other developer information in docs/internals.rst in the distribution, or as rendered at Verilator Internals Documentation.

  • Verilator uses GitHub Actions to provide continuous integration. You may want to enable Actions on your GitHub branch to ensure your changes keep the tests passing.

  • Your source-code contributions must be certified as open source, under the Developer Certificate of Origin. On your first contribution, you must either:

    • Have your patch include the addition of your name to docs/CONTRIBUTORS (preferred).

    • Email, or post in an issue a statement that you certify your contributions.

    • In any of these cases, your name will be added to docs/CONTRIBUTORS and you are agreeing all future contributions are also certified.

    • We occasionally accept contributions where people do not want their name published. Please email us; you must still privately certify your contribution.

  • Your test contributions are generally considered released into the Creative Commons Public Domain (CC0), unless you request otherwise, or put a GNU/Artistic license on your file.

  • Most important is we get your patch.

Do you have questions?

Code of Conduct

  • Our contributors and participants pledge to make participation in our project and our community a positive experience for everyone. We follow the Contributor Covenant version 1.4.

Thanks!