iverilog/BUGS.txt

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 <name>'' 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.