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 ivl 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 the Icarus Verilog don'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 the alpha 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. Ivl 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 not 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 ivl 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 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 ivl 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 ivl 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 netlist, 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. If it is not clear to me, I will ask for clarification. * 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: ivl foo.vl -o foo.cc -tvvm ivl 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 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. 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 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. However, if you send patches, *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.) COPYRIGHT ISSUES Icarus Verilog is Copyright (c) 1998-1999 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. $Id: BUGS.txt,v 1.2 1999/08/06 04:05:28 steve Exp $ $Log: BUGS.txt,v $ Revision 1.2 1999/08/06 04:05:28 steve Handle scope of parameters.