* doc/as.texinfo: Added section on reporting bugs.
This commit is contained in:
parent
eb1b89196c
commit
9a5acea834
|
@ -1,5 +1,7 @@
|
||||||
Fri Nov 1 10:42:49 1996 Ian Lance Taylor <ian@cygnus.com>
|
Fri Nov 1 10:42:49 1996 Ian Lance Taylor <ian@cygnus.com>
|
||||||
|
|
||||||
|
* doc/as.texinfo: Added section on reporting bugs.
|
||||||
|
|
||||||
* config/tc-alpha.c: Change uses of void * to PTR. Change the
|
* config/tc-alpha.c: Change uses of void * to PTR. Change the
|
||||||
alpha_macro emit field to expect a const argument, and change the
|
alpha_macro emit field to expect a const argument, and change the
|
||||||
arg field to be const. Fix some spacing to follow the GNU
|
arg field to be const. Fix some spacing to follow the GNU
|
||||||
|
|
|
@ -170,6 +170,7 @@ code for @value{TARGET} architectures.
|
||||||
* Expressions:: Expressions
|
* Expressions:: Expressions
|
||||||
* Pseudo Ops:: Assembler Directives
|
* Pseudo Ops:: Assembler Directives
|
||||||
* Machine Dependencies:: Machine Dependent Features
|
* Machine Dependencies:: Machine Dependent Features
|
||||||
|
* Reporting Bugs:: Reporting Bugs
|
||||||
* Acknowledgements:: Who Did What
|
* Acknowledgements:: Who Did What
|
||||||
* Index:: Index
|
* Index:: Index
|
||||||
@end menu
|
@end menu
|
||||||
|
@ -206,6 +207,12 @@ Here is a brief summary of how to invoke @code{@value{AS}}. For details,
|
||||||
[ -mbig-endian | -mlittle-endian ]
|
[ -mbig-endian | -mlittle-endian ]
|
||||||
@end ifset
|
@end ifset
|
||||||
@c end-sanitize-arc
|
@c end-sanitize-arc
|
||||||
|
@c start-sanitize-d10v
|
||||||
|
@ifset D10V
|
||||||
|
[ -O ]
|
||||||
|
@end ifset
|
||||||
|
@c end-sanitize-d10v
|
||||||
|
|
||||||
@ifset H8
|
@ifset H8
|
||||||
@c Hitachi family chips have no machine-dependent assembler options
|
@c Hitachi family chips have no machine-dependent assembler options
|
||||||
@end ifset
|
@end ifset
|
||||||
|
@ -352,6 +359,19 @@ Generate ``little endian'' format output.
|
||||||
@end table
|
@end table
|
||||||
@end ifset
|
@end ifset
|
||||||
|
|
||||||
|
@c start-sanitize-d10v
|
||||||
|
@ifset D10V
|
||||||
|
The following options are available when @value{AS} is configured for
|
||||||
|
a D10V processor.
|
||||||
|
@table @code
|
||||||
|
@cindex D10V optimization
|
||||||
|
@cindex optimization, D10V
|
||||||
|
@item -O
|
||||||
|
Optimize output by parallelizing instructions.
|
||||||
|
@end table
|
||||||
|
@end ifset
|
||||||
|
@c end-sanitize-d10v
|
||||||
|
|
||||||
@ifset I960
|
@ifset I960
|
||||||
The following options are available when @value{AS} is configured for the
|
The following options are available when @value{AS} is configured for the
|
||||||
Intel 80960 processor.
|
Intel 80960 processor.
|
||||||
|
@ -3002,7 +3022,9 @@ storage boundary. The first expression (which must be absolute) is the
|
||||||
alignment required, as described below.
|
alignment required, as described below.
|
||||||
The second expression (also absolute) gives the value to be stored in
|
The second expression (also absolute) gives the value to be stored in
|
||||||
the padding bytes. It (and the comma) may be omitted. If it is
|
the padding bytes. It (and the comma) may be omitted. If it is
|
||||||
omitted, the padding bytes are zero.
|
omitted, the padding bytes are zero.
|
||||||
|
For the alpha, if the section is marked as containing code and the
|
||||||
|
padding expression is omitted, then the space is filled with no-ops.
|
||||||
|
|
||||||
The way the required alignment is specified varies from system to system.
|
The way the required alignment is specified varies from system to system.
|
||||||
For the a29k, hppa, m68k, m88k, w65, sparc, and Hitachi SH, and i386 using ELF
|
For the a29k, hppa, m68k, m88k, w65, sparc, and Hitachi SH, and i386 using ELF
|
||||||
|
@ -4353,6 +4375,11 @@ subject, see the hardware manufacturer's manual.
|
||||||
* ARC-Dependent:: ARC Dependent Features
|
* ARC-Dependent:: ARC Dependent Features
|
||||||
@end ifset
|
@end ifset
|
||||||
@c end-sanitize-arc
|
@c end-sanitize-arc
|
||||||
|
@c start-sanitize-d10v
|
||||||
|
@ifset D10V
|
||||||
|
* D10V-Dependent:: D10V Dependent Features
|
||||||
|
@end ifset
|
||||||
|
@c end-sanitize-d10v
|
||||||
@ifset H8/300
|
@ifset H8/300
|
||||||
* H8/300-Dependent:: Hitachi H8/300 Dependent Features
|
* H8/300-Dependent:: Hitachi H8/300 Dependent Features
|
||||||
@end ifset
|
@end ifset
|
||||||
|
@ -4499,6 +4526,12 @@ family.
|
||||||
@end ifclear
|
@end ifclear
|
||||||
@end ifset
|
@end ifset
|
||||||
|
|
||||||
|
@c start-sanitize-d10v
|
||||||
|
@ifset D10V
|
||||||
|
@include c-d10v.texi
|
||||||
|
@end ifset
|
||||||
|
@c end-sanitize-d10v
|
||||||
|
|
||||||
@ifset H8/300
|
@ifset H8/300
|
||||||
@include c-h8300.texi
|
@include c-h8300.texi
|
||||||
@end ifset
|
@end ifset
|
||||||
|
@ -4552,6 +4585,208 @@ family.
|
||||||
@raisesections
|
@raisesections
|
||||||
@end ifset
|
@end ifset
|
||||||
|
|
||||||
|
@node Reporting Bugs
|
||||||
|
@chapter Reporting Bugs
|
||||||
|
@cindex bugs in @code{@value{AS}}
|
||||||
|
@cindex reporting bugs in @code{@value{AS}}
|
||||||
|
|
||||||
|
Your bug reports play an essential role in making @code{@value{AS}} reliable.
|
||||||
|
|
||||||
|
Reporting a bug may help you by bringing a solution to your problem, or it may
|
||||||
|
not. But in any case the principal function of a bug report is to help the
|
||||||
|
entire community by making the next version of @code{@value{AS}} work better.
|
||||||
|
Bug reports are your contribution to the maintenance of @code{@value{AS}}.
|
||||||
|
|
||||||
|
In order for a bug report to serve its purpose, you must include the
|
||||||
|
information that enables us to fix the bug.
|
||||||
|
|
||||||
|
@menu
|
||||||
|
* Bug Criteria:: Have you found a bug?
|
||||||
|
* Bug Reporting:: How to report bugs
|
||||||
|
@end menu
|
||||||
|
|
||||||
|
@node Bug Criteria
|
||||||
|
@section Have you found a bug?
|
||||||
|
@cindex bug criteria
|
||||||
|
|
||||||
|
If you are not sure whether you have found a bug, here are some guidelines:
|
||||||
|
|
||||||
|
@itemize @bullet
|
||||||
|
@cindex fatal signal
|
||||||
|
@cindex assembler crash
|
||||||
|
@cindex crash of assembler
|
||||||
|
@item
|
||||||
|
If the assembler gets a fatal signal, for any input whatever, that is a
|
||||||
|
@code{@value{AS}} bug. Reliable assemblers never crash.
|
||||||
|
|
||||||
|
@cindex error on valid input
|
||||||
|
@item
|
||||||
|
If @code{@value{AS}} produces an error message for valid input, that is a bug.
|
||||||
|
|
||||||
|
@cindex invalid input
|
||||||
|
@item
|
||||||
|
If @code{@value{AS}} does not produce an error message for invalid input, that
|
||||||
|
is a bug. However, you should note that your idea of ``invalid input'' might
|
||||||
|
be our idea of ``an extension'' or ``support for traditional practice''.
|
||||||
|
|
||||||
|
@item
|
||||||
|
If you are an experienced user of assemblers, your suggestions for improvement
|
||||||
|
of @code{@value{AS}} are welcome in any case.
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
@node Bug Reporting
|
||||||
|
@section How to report bugs
|
||||||
|
@cindex bug reports
|
||||||
|
@cindex @code{@value{AS}} bugs, reporting
|
||||||
|
|
||||||
|
A number of companies and individuals offer support for @sc{gnu} products. If
|
||||||
|
you obtained @code{@value{AS}} from a support organization, we recommend you
|
||||||
|
contact that organization first.
|
||||||
|
|
||||||
|
You can find contact information for many support companies and
|
||||||
|
individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
|
||||||
|
distribution.
|
||||||
|
|
||||||
|
In any event, we also recommend that you send bug reports for @code{@value{AS}}
|
||||||
|
to @samp{bug-gnu-utils@@prep.ai.mit.edu}.
|
||||||
|
|
||||||
|
The fundamental principle of reporting bugs usefully is this:
|
||||||
|
@strong{report all the facts}. If you are not sure whether to state a
|
||||||
|
fact or leave it out, state it!
|
||||||
|
|
||||||
|
Often people omit facts because they think they know what causes the problem
|
||||||
|
and assume that some details do not matter. Thus, you might assume that the
|
||||||
|
name of a symbol you use in an example does not matter. Well, probably it does
|
||||||
|
not, but one cannot be sure. Perhaps the bug is a stray memory reference which
|
||||||
|
happens to fetch from the location where that name is stored in memory;
|
||||||
|
perhaps, if the name were different, the contents of that location would fool
|
||||||
|
the assembler into doing the right thing despite the bug. Play it safe and
|
||||||
|
give a specific, complete example. That is the easiest thing for you to do,
|
||||||
|
and the most helpful.
|
||||||
|
|
||||||
|
Keep in mind that the purpose of a bug report is to enable us to fix the bug if
|
||||||
|
it is new to us. Therefore, always write your bug reports on the assumption
|
||||||
|
that the bug has not been reported previously.
|
||||||
|
|
||||||
|
Sometimes people give a few sketchy facts and ask, ``Does this ring a
|
||||||
|
bell?'' Those bug reports are useless, and we urge everyone to
|
||||||
|
@emph{refuse to respond to them} except to chide the sender to report
|
||||||
|
bugs properly.
|
||||||
|
|
||||||
|
To enable us to fix the bug, you should include all these things:
|
||||||
|
|
||||||
|
@itemize @bullet
|
||||||
|
@item
|
||||||
|
The version of @code{@value{AS}}. @code{@value{AS}} announces it if you start
|
||||||
|
with the @samp{--version} argument.
|
||||||
|
|
||||||
|
Without this, we will not know whether there is any point in looking for
|
||||||
|
the bug in the current version of @code{@value{AS}}.
|
||||||
|
|
||||||
|
@item
|
||||||
|
Any patches you may have applied to the @code{@value{AS}} source.
|
||||||
|
|
||||||
|
@item
|
||||||
|
The type of machine you are using, and the operating system name and
|
||||||
|
version number.
|
||||||
|
|
||||||
|
@item
|
||||||
|
What compiler (and its version) was used to compile @code{@value{AS}}---e.g.
|
||||||
|
``@code{gcc-2.7}''.
|
||||||
|
|
||||||
|
@item
|
||||||
|
The command arguments you gave the assembler to assemble your example and
|
||||||
|
observe the bug. To guarantee you will not omit something important, list them
|
||||||
|
all. A copy of the Makefile (or the output from make) is sufficient.
|
||||||
|
|
||||||
|
If we were to try to guess the arguments, we would probably guess wrong
|
||||||
|
and then we might not encounter the bug.
|
||||||
|
|
||||||
|
@item
|
||||||
|
A complete input file that will reproduce the bug. If the bug is observed when
|
||||||
|
the assembler is invoked via a compiler, send the assembler source, not the
|
||||||
|
high level language source. Most compilers will produce the assembler source
|
||||||
|
when run with the @samp{-S} option. If you are using @code{@value{GCC}}, use
|
||||||
|
the options @samp{-v --save-temps}; this will save the assembler source in a
|
||||||
|
file with an extension of @file{.s}, and also show you exactly how
|
||||||
|
@code{@value{AS}} is being run.
|
||||||
|
|
||||||
|
@item
|
||||||
|
A description of what behavior you observe that you believe is
|
||||||
|
incorrect. For example, ``It gets a fatal signal.''
|
||||||
|
|
||||||
|
Of course, if the bug is that @code{@value{AS}} gets a fatal signal, then we
|
||||||
|
will certainly notice it. But if the bug is incorrect output, we might not
|
||||||
|
notice unless it is glaringly wrong. You might as well not give us a chance to
|
||||||
|
make a mistake.
|
||||||
|
|
||||||
|
Even if the problem you experience is a fatal signal, you should still say so
|
||||||
|
explicitly. Suppose something strange is going on, such as, your copy of
|
||||||
|
@code{@value{AS}} is out of synch, or you have encountered a bug in the C
|
||||||
|
library on your system. (This has happened!) Your copy might crash and ours
|
||||||
|
would not. If you told us to expect a crash, then when ours fails to crash, we
|
||||||
|
would know that the bug was not happening for us. If you had not told us to
|
||||||
|
expect a crash, then we would not be able to draw any conclusion from our
|
||||||
|
observations.
|
||||||
|
|
||||||
|
@item
|
||||||
|
If you wish to suggest changes to the @code{@value{AS}} source, send us context
|
||||||
|
diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p}
|
||||||
|
option. Always send diffs from the old file to the new file. If you even
|
||||||
|
discuss something in the @code{@value{AS}} source, refer to it by context, not
|
||||||
|
by line number.
|
||||||
|
|
||||||
|
The line numbers in our development sources will not match those in your
|
||||||
|
sources. Your line numbers would convey no useful information to us.
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
Here are some things that are not necessary:
|
||||||
|
|
||||||
|
@itemize @bullet
|
||||||
|
@item
|
||||||
|
A description of the envelope of the bug.
|
||||||
|
|
||||||
|
Often people who encounter a bug spend a lot of time investigating
|
||||||
|
which changes to the input file will make the bug go away and which
|
||||||
|
changes will not affect it.
|
||||||
|
|
||||||
|
This is often time consuming and not very useful, because the way we
|
||||||
|
will find the bug is by running a single example under the debugger
|
||||||
|
with breakpoints, not by pure deduction from a series of examples.
|
||||||
|
We recommend that you save your time for something else.
|
||||||
|
|
||||||
|
Of course, if you can find a simpler example to report @emph{instead}
|
||||||
|
of the original one, that is a convenience for us. Errors in the
|
||||||
|
output will be easier to spot, running under the debugger will take
|
||||||
|
less time, and so on.
|
||||||
|
|
||||||
|
However, simplification is not vital; if you do not want to do this,
|
||||||
|
report the bug anyway and send us the entire test case you used.
|
||||||
|
|
||||||
|
@item
|
||||||
|
A patch for the bug.
|
||||||
|
|
||||||
|
A patch for the bug does help us if it is a good one. But do not omit
|
||||||
|
the necessary information, such as the test case, on the assumption that
|
||||||
|
a patch is all we need. We might see problems with your patch and decide
|
||||||
|
to fix the problem another way, or we might not understand it at all.
|
||||||
|
|
||||||
|
Sometimes with a program as complicated as @code{@value{AS}} it is very hard to
|
||||||
|
construct an example that will make the program follow a certain path through
|
||||||
|
the code. If you do not send us the example, we will not be able to construct
|
||||||
|
one, so we will not be able to verify that the bug is fixed.
|
||||||
|
|
||||||
|
And if we cannot understand what bug you are trying to fix, or why your
|
||||||
|
patch should be an improvement, we will not install it. A test case will
|
||||||
|
help us to understand.
|
||||||
|
|
||||||
|
@item
|
||||||
|
A guess about what the bug is or what it depends on.
|
||||||
|
|
||||||
|
Such guesses are usually wrong. Even we cannot guess right about such
|
||||||
|
things without first using the debugger to find the facts.
|
||||||
|
@end itemize
|
||||||
|
|
||||||
@node Acknowledgements
|
@node Acknowledgements
|
||||||
@chapter Acknowledgements
|
@chapter Acknowledgements
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue