| blob | 387b64d65963e88a6905834144490745932b77eb |
2 HOW TO REPORT BUGS
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.)
11 * The Compiler Doesn't Compile
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:
16 - Operating system and processor type,
17 - Compiler w/ version,
18 - Library version, and
19 - anything else you think relevant.
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.
25 * The Compiler Crashes
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.
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.
38 If there are not assertion messages, I need to know that as well.
40 I also need a complete test program that demonstrates the crash.
42 * It Doesn't Like My Perfectly Valid Program(tm)
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.
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.
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.
66 * It Generates Incorrect Target Code (XNF, EDIF/LPM, etc.)
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.
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.
79 * The Output is Correct, But Less Than Ideal
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.
87 THE MAKING OF A GOOD TEST PROGRAM
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.
96 Also, include the command line you use to invoke the compiler. For
97 example:
99 ivl foo.vl -o foo.cc -tvvm
100 ivl foo.vl -s starthere
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.
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.
113 RESEARCHING EXISTING/PAST BUGS, AND FILING REPORTS
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.
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.
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.
131 HOW TO SEND PATCHES
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.
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.
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.)
149 COPYRIGHT ISSUES
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.
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.
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
168 Revision 1.4 2003/02/19 04:36:31 steve
169 Notes on hte bug database.
171 Revision 1.3 2003/01/30 16:23:07 steve
172 Spelling fixes.
174 Revision 1.2 1999/08/06 04:05:28 steve
175 Handle scope of parameters.