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. Even better, create a test in the test_regress/t directory, as follows:

cd test_regress
cp -p t/t_EXAMPLE.pl t/t_BUG.pl
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.pl documentation which can be seen by running:

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

Edit t/t_BUG.pl 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.pl  # Run on Verilator
t/t_BUG.pl --debug # Run on Verilator, passing --debug to Verilator
t/t_BUG.pl --vcs  # Run on VCS simulator
t/t_BUG.pl --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.pl --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.

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.

  • 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 docs/internals.

Did you write a patch that fixes a bug?

  • Please Open a new issue.

  • You may attach a patch to the issue, or (preferred) may request a GitHub pull request.

    • 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. See docs/internals.

  • 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).

    • Use “git -s” as part of your commit. This adds a “signed-of-by” attribute which will certify your contribution as described in the Signed-of-By convention.

    • 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. If you’d like to clean up indentation and related issues ahead of our feedback, that is appreciated; please see the coding conventions in docs/internals.

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!