diff --git a/BUGS.txt b/BUGS.txt new file mode 100644 index 000000000..781d7e172 --- /dev/null +++ b/BUGS.txt @@ -0,0 +1,137 @@ + +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. + +* The Compiler Doesn't Compile + +If the tools 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 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?" + +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 or unified 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.