Icarus Verilog -- Bugs

Presumably, you are reading this page because you believe you found a problem with Icarus Verilog. That's great, I very much appreciate and I do what I can to encourage effective bug reports. There is a searchable reporting system to help you to help yourself, and to help me track problems. However, in order to get a bug fixed, I still need that first bug report, and if you are like me, the labor of writing a convincing bug report (or the fear of writing an unconvincing bug report) gets in the way, especially if you find a work around. In spite of the run-around you've learned to expect from commercial software vendors, I encourage you to try to make a good report, and this page is here to help you understand what I need.

The most important rule, though, is please browse the rest of this page before sending a bug report. It is much easier for both of us if we understand what is expected.

Before I can fix an error, I need to understand what the problem is. Try to explain what is wrong and why you think it is wrong. Please try to include sample code that demonstrates the problem. Include a description of what Icarus Verilog does that is wrong, and what you expect should happen, and include the command line flags passed to the compiler to make the error happen. (This last step is often overlooked, and sometimes important.)

Browse and report bugs through the Sorceforge based bug tracking system at this link (http://sourceforge.net/tracker/?group_id=149850). If the sourceforge tracker is unavailable or if you have suggestions for improvements, send them to the <geda-dev@seul.org> mailing list, or directly to me.

The old ivl-bugs reporting system has been abused by spammers to the point where it is no longer maintainable. The system is still on line at< http://www.icarus.com/cgi-bin/ivl-bugs > for browsing old bugs, but please do not submit new bugs by the old system.

So now what sorts of problems might you report? Let's see...

The Compiler Doesn't Compile

If the Icarus Verilog distribution doesn't compile, I need to know about the compilation tools you are using. Specifically, I need to know:

Operating system and processor type,
Compiler w/ version,
Library version, and
anything else you think relevent.

Be aware that I do not have at my disposal a porting lab. I have Linux/AMD64 on my desk, and the Linux/Intel box with a logic analyzer and 'scope hanging off it.

The Compiler Crashes

No compiler should crash, no matter what kind of garbage is fed to it. If the compiler crashes, you definitely found a bug and I need to know about it.

Icarus Verilog internally checks its state while it works, and if it detects something wrong that it cannot recover from, it will abort intentionally. The "assertion failure" message that the program prints in the process of dying is very important. It tells me where in the source the bad thing happened. Include that message in the bug report. If there are no assertion messages, I need to know that as well.

I also need a complete test program that demonstrates the crash. See below.

It Doesn't Like My Perfectly Valid Program(tm)

I need to know what you think is right that iverilog gets wrong. Does it reject your "Perfectly Valid Program(tm)" or does it compile it but give incorrect results? The latter is the most insidious as it doesn't scream out to be fixed unless someone is watching closely. However, if I get a sample program from you, and I can compile it, and I run it and nuclear junk doesn't fall from the sky, I'm assuming all is well and moving on to the next problem.

So, if your program doesn't compile, tell me so. Tell me where the error occurs, and include a complete Perfectly Valid Test Program(tm). You tell me that it fails to compile for you, and I find that it compiles for me, then hooray I fixed it. It can happen, you know. What's on my disk is more recent then the latest snapshot.

If your program does compile, but generates incorrect output, I need to know what it says and what you think it should say. From this I can take your sample program and work on Icarus Verilog until it gets the proper results. For this to work, of course, I first need to know what is wrong with the output. Spell it out, because I've been known to miss the obvious. Compiler writers often get buried in the details of the wrong problem.

It Generates Incorrect Target Code (XNF, EDIF/LPM, etc.)

As Icarus Verilog adds target code generators, there will be cases where errors in the output netlist format occur. This is a tough nut because I might not have all the tools to test the target format you are reporting problems with. (They are often very expensive, as I'm sure you are aware.) However, if you clearly explain what is right and wrong about the generated netlist, I will probably be able to fix the problem. It may take a few iterations.

In any case, please include not only the sample Verilog program, but the generated netlist file(s) and a clear indication of what went wrong. If it is not clear to me, I will ask for clarification. Be explicit. Again, I have been known to miss the obvious.

The Output is Correct, But Less Then Ideal

If the output is strictly correct, but just not good enough for practical use, I would like to know. These sorts of problems are likely to be more subjective then a core dump, but are worthy of consideration. However, realize that outright errors will get more attention then missed optimizations.

The Making of a Good Test Program

If at all possible, please submit a complete source file that demonstrates the problem. If the error occurs after elaboration, please include a top level module in the program that is suitable for the target format. If I have to write the module myself, I might not write it in a way that tickles the bug. So please, send all the Verilog source (after preprocessing) that I need to invoke the error.

Also, include the command line you use to invoke the compiler. For example:

iverilog -txnf -DTEST=5 foo.vl
iverilog -s starthere foo.vl

If the error occurs with the null target (``-tnull'') then a top level module may not be needed as long as the ``-s <name>'' switch is given.

So when you send a test case, ask yourself "Can poor overworked Steve invoke the error without any Verilog other then what is included?" And while we are at it, please place a copyright notice in your test program and include a GPL license statement if you can. Your test program may find its way into the test suite, and the notices will make it all nice and legal. (See COPYRIGHT ISSUES below.)

How To Send Patches

Bug reports with patches are very welcome, if they are formatted such that I can inspect them, decide that they are obviously correct, and apply them without worry. It is important that I be able to read submitted patches.

I prefer context diffs as emitted by diff from GNU diffutils. Human beings can read such things, and they are resilient to changing originals. A good set of flags to diff are ``diff -cNB''. With such diffs, I can look at the changes you are offering and probably tell at a glance that they are plausible. Then I can use patch(1) to apply them. Or I can apply them by hand.

I find replacement files particularly inconvenient. Replacement files do not clearly highlight what they change, and they are particularly difficult to merge with local changes to the file. Please, if your changes are restricted to a single file, it is easy for you to use the diff command on that file, and diffs of this form are infinitely easier for me to accept, approve and apply.

Now that you have the perfect patch, please tell me what this patch is supposed to accomplish, and if appropriate include a test program that demonstrates the efficacy of the patch. (If I have no idea what the patch is for, I will ask for clarification before applying it.) The test program may well find its way into the regression test suite, so include copyright notices.

COPYRIGHT ISSUES

Icarus Verilog is Copyright (c) 1998-2000 Stephen Williams except where otherwise noted. Minor patches are covered as derivative works (or editorial comment or whatever the appropriate legal term is) and folded into the rest of Icarus Verilog. However, if a submission can reasonably be considered independently copyrightable, it's yours and I encourage you to claim it with appropriate copyright notices. This submission then falls under the "otherwise noted" category.

I must insist that any copyright material submitted for inclusion include the GPL license notice as shown in the rest of the source.

And this of course brings up the issue of copyright status of test programs sent as bug reports. Basically, I presume when sample code is sent as part of a bug report that you are granting me license to redistribute it (properly attributed, of course) in a test suite or other forum. In particular, code that might reveal trade secrets and intellectual property should not be sent to me. If you are reporting a problem you are encountering in such code, try making a contrived example that does the trick. Just realize that I signed no non-disclosure agreements, so am not bound to non-disclosure.

$Id: bugs.html,v 1.10 2006/02/21 22:00:39 steve Exp $