Icarus Verilog

This guide is intended to help you get started working with the Icarus Verilog source code, beyond simply compiling it. If all you want is to get and compile the code on your system, see the Installation Guide. But if you intend to work on the code, whether you intend to submit patches or not, this guide is for you.

There is a moderated mailing list for developers on sourceforge.net. This list is intended for discussion amongst the developers, hence the moderation. Although off-topic messages will be discarded (and that includes general usage support requests) questions about how to help yourself, or at least how to diagnose problems, are entertained.

If you are looking for project ideas, go to the Projects page.

Getting Started with the Source Code[]

For development it is suggested to base changes on the current git repository. This will allow you to submit changes as a patch against the latest git version. Submitting patches relative the latest git saves everyone concerned a lot of headaches.

There is a section in the Installation Guide that explains how to check out the code from the main repository. It also explains how to prepare it to compile on the local system.

As the main repository is changed, you can update your copy with a simple "git pull". This combines the "git fetch" (fetch change sets from the remote repository) and "git merge" (merge those changes with your working branch.) This will automatically bring down just the changes from the upstream. That way, you always have access to the very latest version of the source.

When you are done with work of your own, make sure you commit your work into your local repository. Don't be afraid of this word, "commit". In git, "commit" only puts changes together into a change set. It is entirely local. To commit your changes, therefore:

% git add <files that have been changed>
% git commit

Note that with git, all changes must be added, and not just new files. Use the "git status" and "git diff" commands to help figure out what those files are. Add those files with the "git add" command, then wrap the lot into a change set with the "git commit" command.

The commit will ask for a commit message. The convention for commit messages is to include two paragraphs: The first is a single line short description of what the change set is about, then after a blank line the second paragraph is a more verbose description of the patch.

To get the changes into the upstream, you need to submit a patch to the owner of the repository, who can push it in.

The command:

% git format-patch -o patches

puts together patches that you can submit for inclusion in the main repository. This command may produce a long run of patches (one for each change set) and it is common to want to make a patch for only the last change set. That can be managed with this command:

% git format-patch -o patches '@{1}'

This makes a patch for only the last change set in the current branch.

Of course, there is much more to git. This summary should be enough to get you started, especially if you are used to working with CVS, but for an understanding of the full power of git, see the various documentation resources on the 'net.

For a summary of the current conventions for the main git repository at icarus.com, see the GIT Branch Summary page.

Testing Your Work[]

There is a test suite created by Steve Wilson and maintained by the Icarus Verilog project. Bug trackers are available at its github presence at http://gethub.com/steveicarus/iverilog, and the files themselves are available as part of the iverilog source tree.

Because the test suite is constantly growing, no effort is made to make release files. Instead, always use git to get the current test suite. The instructions for accessing the git repository are available on the github help pages, but the short story is:

% git clone git://github.com/steveicarus/iverilog.git

The test suite contains a large number of regression tests, as well as scripts to run the tests, and files that show the expected results for various branches and the current devel version of Icarus Verilog. This test suite is also the core of continuous integration for Icarus Verilog, and every PR to iverilog is run through the test suite.

The main script to run the test suite is "vvp_reg.pl". Yes, it is a Perl script. This assumes that the iverilog and vvp programs you want to test are in your path.

The regression_reports-v11.txt file is the expected results for the v11 branch of Icarus Verilog. After you run the vvp_reg.pl program, you will get the output file "regression_report.txt" that you can compare with the "regression_report-v11.txt" file to see where there are differences.

Similarly, the "regression_report-devel.txt" file is the expected results for the current development. The file is tagged with Icarus Verilog snapshot names so that you can get historical results as well.

It is recommended that after you make changes to Icarus Verilog, you rerun the regression test suite to check that you didn't break something else. The compiler is a very complicated thing and regressions are easy to trip over.

There is also a vpi_reg.pl script for testing the VPI interface.

Both scripts take a --suffix= flag that can be used to test a suffixed version of iverilog e.g.(--suffix=-11). They also take a --with-valgrind flag that will run the tests using valgrind to check for memory errors, etc. (very very slow). It is assumed that valgrind is in your path. Use --help to get basic usage information.

There is a "find_valg_errs" script that creates a summary of the valgrind errors and memory issues in vvp. The iverilog driver program should be clean and the ivlpp pre-processor should also be clean. The compiler is know to have a number of memory leaks or more likely things that look like leaks. vvp is mostly clean, but has a few remaining issues that have not been resolved. The goal is to make vvp clean for the v10 release and to make progress cleaning up the compiler. We believe we have removed all the memory leaks in vvp and what is left is memory that is allocated and used throughout the simulation, but is never released.

It is also highly recommended that you create regression tests of your own to test the results of your own work. These tests can go into the regression test suite so that others who edit the compiler can be sure they are not breaking your code in the process.

Submitting Patches[]

You should be using a local git repository to develop your patch, so the proper way to submit a patch is to format it by committing your work to your local repository using:

% git commit

In your commit message, include a short 1-line summary, then a blank line, then a description of the purpose of the patch. The "git commit" command doesn't enforce this format, but the visualizing tools assume it when making pretty displays of the tree of patches.

Once your work is committed to your local repository, you can format the patch with the command:

% git format-patch '@{1}'

This will format your last commit into a git-style patch that you can submit to the Icarus Verilog Patches tracker.

The patch you submit is handled by a developer who applies the patch you submit with the command:

% git am <your-patch-file>

to an integration repository. It is tested, then pushed into the main repository. When the patch is applied to the main repository, you then use the command:

% git pull

to merge. You will be able to then use

% gitk

to see your patch in the main branch that you are tracking.

When you become more expert with using git, then you can in principle do a bunch of changes in a bunch of commits and submit them as a set of patches at a later time.

Valgrind is your Debugging Friend[]

If you are working under Linux valgrind can be used to find a number of memory/initialization problems. When using valgrind on the compiler (iverilog) you must use the --trace-children=yes option to test the various executables in the main compiler. If you do not supply this, valgrind will only check the iverilog (driver) executable which is almost certainly not what you want. Since vvp is a single executable you do not need this option, though debugging the loaded dlls can be challenging.

Choosing a Task[]

The task you choose is entirely up to you. Some thought through suggestions can be found in the Projects page.

There is also a rough Development Time Line that reflects the intended development path as it stands currently. This may include some ideas as well.