BUGS.txt

   1
   2 HOW TO REPORT BUGS
   3
   4 Before I can fix an error, I need to understand what the problem
   5 is. Try to explain what is wrong and why you think it is wrong. Please
   6 try to include sample code that demonstrates the problem. Include a
   7 description of what ivl does that is wrong, and what you expect should
   8 happen. And include the command line flags passed to the compiler to make
   9 the error happen. (This is often overlooked, and sometimes important.)
  10
  11 * The Compiler Doesn't Compile
  12
  13 If the Icarus Verilog don't compile, I need to know about the
  14 compilation tools you are using. Specifically, I need to know:
  15
  16         - Operating system and processor type,
  17         - Compiler w/ version,
  18         - Library version, and
  19         - anything else you think relevant.
  20
  21 Be aware that I do not have at my disposal a porting lab. I have the
  22 alpha on my desk, and the Linux/Intel box with a logic analyzer and
  23 'scope hanging off it.
  24
  25 * The Compiler Crashes
  26
  27 No compiler should crash, no matter what kind of garbage is fed to
  28 it. If the compiler crashes, you definitely found a bug and I need to
  29 know about it.
  30
  31 Ivl internally checks its state while it works, and if it detects
  32 something wrong that it cannot recover from, it will abort
  33 intentionally. The "assertion failure" message that the program
  34 prints in the process of dying is very important. It tells me where in
  35 the source the bad thing happened. Include that message in the bug
  36 report.
  37
  38 If there are not assertion messages, I need to know that as well.
  39
  40 I also need a complete test program that demonstrates the crash.
  41
  42 * It Doesn't Like My Perfectly Valid Program(tm)
  43
  44 I need to know what you think is right that ivl gets wrong. Does it
  45 reject your "Perfectly Valid Program(tm)" or does it compile it but
  46 give incorrect results? The latter is the most insidious as it doesn't
  47 scream out to be fixed unless someone is watching closely. However, if
  48 I get a sample program from you, and I can compile it, and I run it
  49 and nuclear junk doesn't fall from the sky, I'm moving on to the next
  50 problem.
  51
  52 So, if your program doesn't compile, tell me so, tell me where the
  53 error occurs, and include a complete Perfectly Valid Test Program(tm).
  54 You tell me that it fails to compile for you, and I find that it
  55 compiles for me, then hooray I fixed it. It can happen, you
  56 know. What's on my disk is more recent then the latest snapshot.
  57
  58 If your program does compile, but generates incorrect output, I need
  59 to know what it says and what you think it should say. From this I can
  60 take your sample program and work on ivl until it gets the proper
  61 results. For this to work, of course, I first need to know what is
  62 wrong with the output. Spell it out, because I've been known to miss
  63 the obvious. Compiler writers often get buried in the details of the
  64 wrong problem.
  65
  66 * It Generates Incorrect Target Code (XNF, EDIF/LPM, etc.)
  67
  68 As ivl adds target code generators, there will be cases where errors
  69 in the output netlist format occur. This is a tough nut because I
  70 might not have all the tools to test the target format you are
  71 reporting problems with. However, if you clearly explain what is right
  72 and wrong about the generated netlist, I will probably be able to fix
  73 the problem. It may take a few iterations.
  74
  75 In this case, if possible include not only the sample verilog program,
  76 but the generated netlist file(s) and a clear indication of what went
  77 wrong. If it is not clear to me, I will ask for clarification.
  78
  79 * The Output is Correct, But Less Then Ideal
  80
  81 If the output is strictly correct, but just not good enough for
  82 practical use, I would like to know. These sorts of problems are
  83 likely to be more subjective then a core dump, but are worthy of
  84 consideration. However, realize that outright errors will get more
  85 attention then missed optimizations.
  86
  87 THE MAKING OF A GOOD TEST PROGRAM
  88
  89 If at all possible, please submit a complete source file that
  90 demonstrates the problem. If the error occurs after elaboration,
  91 please include a top level module in the program that is suitable for
  92 the target format. If I have to write the module myself, I might not
  93 write it in a way that tickles the bug. So please, send all the
  94 Verilog source (after preprocessing) that I need to invoke the error.
  95
  96 Also, include the command line you use to invoke the compiler. For
  97 example:
  98
  99         ivl foo.vl -o foo.cc -tvvm
 100         ivl foo.vl -s starthere
 101
 102 If the error occurs with the null target (``-tnull'') then a top level
 103 module may not be needed as long as the ``-s <name>'' switch is
 104 given.
 105
 106 So when you send a test case, ask yourself "Can poor overworked Steve
 107 invoke the error without any Verilog other than what is included?" And
 108 while we are at it, please place a copyright notice in your test
 109 program and include a GPL license statement if you can. Your test
 110 program may find its way into the test suite, and the notices will
 111 make it all nice and legal.
 112
 113 RESEARCHING EXISTING/PAST BUGS, AND FILING REPORTS
 114
 115 The URL <http://www.icarus.com/cgi-bin/ivl-bugs> is the main bug
 116 tracking system. Once you believe you have found a bug, you may browse
 117 the bugs database for existing bugs that may be related to yours. You
 118 might find that your bug has already been fixed in a later release or
 119 snapshot. If that's the case, then you are set.
 120
 121 The bug database supports basic keyword searches, and you can
 122 optionally limit your search to active bugs, or fixed bugs. You may
 123 also browse the bug database, just to get an idea what is still
 124 broken. You may for example find a related bug that explains your
 125 symptom.
 126
 127 The root page of the bug report database describes how to submit your
 128 completed bug report. You may submit it via the web form, or via
 129 e-mail.
 130
 131 HOW TO SEND PATCHES
 132
 133 Bug reports with patches are very welcome, especially if they are
 134 formatted such that I can inspect them, decide that they are obviously
 135 correct, and apply them without worry.
 136
 137 I prefer context diffs as emitted by diff from GNU diffutils.  Human
 138 beings can read such things, and they are resilient to changing
 139 originals. A good set of flags to diff are ``diff -cNB''.  With such
 140 diffs, I can look at the changes you are offering and probably tell at
 141 a glance that they are plausible. Then I can use patch(1) to apply
 142 them. Or I can apply them by hand.
 143
 144 However, if you send patches, *please* tell me what this patch is
 145 supposed to accomplish, and if appropriate include a test program that
 146 demonstrates the efficacy of the patch. (If I have no idea what the
 147 patch is for, I will ask for clarification before applying it.)
 148
 149 COPYRIGHT ISSUES
 150
 151 Icarus Verilog is Copyright (c) 1998-2003 Stephen Williams except
 152 where otherwise noted. Minor patches are covered as derivative works
 153 (or editorial comment or whatever the appropriate legal term is) and
 154 folded into the rest of ivl. However, if a submission can reasonably
 155 be considered independently copyrightable, it's yours and I encourage
 156 you to claim it with appropriate copyright notices. This submission
 157 then falls under the "otherwise noted" category.
 158
 159 I must insist that any copyright material submitted for inclusion
 160 include the GPL license notice as shown in the rest of the source.
 161
 162
 163 $Id: BUGS.txt,v 1.5 2007/03/22 16:08:14 steve Exp $
 164 $Log: BUGS.txt,v $
 165 Revision 1.5  2007/03/22 16:08:14  steve
 166  Spelling fixes from Larry
 167
 168 Revision 1.4  2003/02/19 04:36:31  steve
 169  Notes on hte bug database.
 170
 171 Revision 1.3  2003/01/30 16:23:07  steve
 172  Spelling fixes.
 173
 174 Revision 1.2  1999/08/06 04:05:28  steve
 175  Handle scope of parameters.
 176