HOW TO REPORT BUGS 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 is often overlooked, and sometimes important.) * The Compiler Doesn't Compile If Icarus Verilog 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, - Versions of any libraries being linked, and - anything else you think relevant. Be aware that I do not have at my disposal a porting lab. I have the workstation on my desk, a Mac laptop, 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. * It Doesn't Like My Perfectly Valid Program(tm) I need to know what you think is right that Icarus Verilog 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 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 than 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 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. However, if you clearly explain what is right and wrong about the generated output, I will probably be able to fix the problem. It may take a few iterations. In this case, if possible include not only the sample Verilog program, but the generated netlist file(s) and a clear indication of what went wrong or what is expected. If it is not clear to me, I will ask for clarification. * The Output is Correct, But Less Than 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 than a core dump, but are worthy of consideration. However, realize that outright errors will get more attention than 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 that I need to invoke the error. Also, include the command line you use to invoke the compiler. For example: iverilog -o foo.out -tvvp foo.v iverilog foo.vl -s starthere If the error occurs with the null target (``-tnull'') then a top level module may not be needed as long as the ``-s '' switch is given. So when you send a test case, ask yourself "Can poor overworked Steve invoke the error without any Verilog other than 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. Please look at the existing tests in the test suite for examples of good test programs. RESEARCHING EXISTING/PAST BUGS, AND FILING REPORTS The URL is the main bug tracking system, although some users have reported bugs at . Once you believe you have found a bug, you may browse the bugs database for existing bugs that may be related to yours. You might find that your bug has already been fixed in a later release or snapshot. If that's the case, then you are set. Also, consider if you are reporting a bug or really asking for a new feature, and use the appropriate tracker. system (although you will also find bug rep The bug database supports basic keyword searches, and you can optionally limit your search to active bugs, or fixed bugs. You may also browse the bug database, just to get an idea what is still broken. You may for example find a related bug that explains your symptom. The root page of the bug report database describes how to submit your completed bug report. HOW TO SEND PATCHES Bug reports with patches are very welcome, especially if they are formatted such that I can inspect them, decide that they are obviously correct, and apply them without worry. I prefer patches generated by the git source code tracking system. If you are editing the source, you really should be using the latest version from git. Please see the developer documentation for more detailed instructions -- . When you make a patch, submit it to the "Patches" tracker at . Patches added to the "Patches" tracker enter the developer workflow, are checked, applied to the appropriate git branch, and are pushed. Then the tracker item is closed. If you send patches, *please* tell me what this patch is supposed to accomplish, which branch you intended to be patched, 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.) COPYRIGHT ISSUES Icarus Verilog is Copyright (c) 1998-2018 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 ivl. 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.