314 lines
13 KiB
Plaintext
314 lines
13 KiB
Plaintext
This is Info file as.info, produced by Makeinfo-1.64 from the input
|
||
file ./as.texinfo.
|
||
|
||
START-INFO-DIR-ENTRY
|
||
* As: (as). The GNU assembler.
|
||
END-INFO-DIR-ENTRY
|
||
|
||
This file documents the GNU Assembler "as".
|
||
|
||
Copyright (C) 1991, 92, 93, 94, 95, 96, 1997 Free Software
|
||
Foundation, Inc.
|
||
|
||
Permission is granted to make and distribute verbatim copies of this
|
||
manual provided the copyright notice and this permission notice are
|
||
preserved on all copies.
|
||
|
||
Permission is granted to copy and distribute modified versions of
|
||
this manual under the conditions for verbatim copying, provided that
|
||
the entire resulting derived work is distributed under the terms of a
|
||
permission notice identical to this one.
|
||
|
||
Permission is granted to copy and distribute translations of this
|
||
manual into another language, under the above conditions for modified
|
||
versions.
|
||
|
||
|
||
File: as.info, Node: Reporting Bugs, Next: Acknowledgements, Prev: Machine Dependencies, Up: Top
|
||
|
||
Reporting Bugs
|
||
**************
|
||
|
||
Your bug reports play an essential role in making `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 `as' work
|
||
better. Bug reports are your contribution to the maintenance of `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
|
||
|
||
|
||
File: as.info, Node: Bug Criteria, Next: Bug Reporting, Up: Reporting Bugs
|
||
|
||
Have you found a bug?
|
||
=====================
|
||
|
||
If you are not sure whether you have found a bug, here are some
|
||
guidelines:
|
||
|
||
* If the assembler gets a fatal signal, for any input whatever, that
|
||
is a `as' bug. Reliable assemblers never crash.
|
||
|
||
* If `as' produces an error message for valid input, that is a bug.
|
||
|
||
* If `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".
|
||
|
||
* If you are an experienced user of assemblers, your suggestions for
|
||
improvement of `as' are welcome in any case.
|
||
|
||
|
||
File: as.info, Node: Bug Reporting, Prev: Bug Criteria, Up: Reporting Bugs
|
||
|
||
How to report bugs
|
||
==================
|
||
|
||
A number of companies and individuals offer support for GNU
|
||
products. If you obtained `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 `etc/SERVICE' in the GNU Emacs distribution.
|
||
|
||
In any event, we also recommend that you send bug reports for `as'
|
||
to `bug-gnu-utils@prep.ai.mit.edu'.
|
||
|
||
The fundamental principle of reporting bugs usefully is this:
|
||
*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 *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:
|
||
|
||
* The version of `as'. `as' announces it if you start it with the
|
||
`--version' argument.
|
||
|
||
Without this, we will not know whether there is any point in
|
||
looking for the bug in the current version of `as'.
|
||
|
||
* Any patches you may have applied to the `as' source.
|
||
|
||
* The type of machine you are using, and the operating system name
|
||
and version number.
|
||
|
||
* What compiler (and its version) was used to compile `as'--e.g.
|
||
"`gcc-2.7'".
|
||
|
||
* 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.
|
||
|
||
* 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 `-S'
|
||
option. If you are using `gcc', use the options `-v
|
||
--save-temps'; this will save the assembler source in a file with
|
||
an extension of `.s', and also show you exactly how `as' is being
|
||
run.
|
||
|
||
* 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 `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 `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.
|
||
|
||
* If you wish to suggest changes to the `as' source, send us context
|
||
diffs, as generated by `diff' with the `-u', `-c', or `-p' option.
|
||
Always send diffs from the old file to the new file. If you even
|
||
discuss something in the `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.
|
||
|
||
Here are some things that are not necessary:
|
||
|
||
* 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 *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.
|
||
|
||
* 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 `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.
|
||
|
||
* 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.
|
||
|
||
|
||
File: as.info, Node: Acknowledgements, Next: Index, Prev: Reporting Bugs, Up: Top
|
||
|
||
Acknowledgements
|
||
****************
|
||
|
||
If you have contributed to `as' and your name isn't listed here, it
|
||
is not meant as a slight. We just don't know about it. Send mail to
|
||
the maintainer, and we'll correct the situation. Currently the
|
||
maintainer is Ken Raeburn (email address `raeburn@cygnus.com').
|
||
|
||
Dean Elsner wrote the original GNU assembler for the VAX.(1)
|
||
|
||
Jay Fenlason maintained GAS for a while, adding support for
|
||
GDB-specific debug information and the 68k series machines, most of the
|
||
preprocessing pass, and extensive changes in `messages.c',
|
||
`input-file.c', `write.c'.
|
||
|
||
K. Richard Pixley maintained GAS for a while, adding various
|
||
enhancements and many bug fixes, including merging support for several
|
||
processors, breaking GAS up to handle multiple object file format back
|
||
ends (including heavy rewrite, testing, an integration of the coff and
|
||
b.out back ends), adding configuration including heavy testing and
|
||
verification of cross assemblers and file splits and renaming,
|
||
converted GAS to strictly ANSI C including full prototypes, added
|
||
support for m680[34]0 and cpu32, did considerable work on i960
|
||
including a COFF port (including considerable amounts of reverse
|
||
engineering), a SPARC opcode file rewrite, DECstation, rs6000, and
|
||
hp300hpux host ports, updated "know" assertions and made them work,
|
||
much other reorganization, cleanup, and lint.
|
||
|
||
Ken Raeburn wrote the high-level BFD interface code to replace most
|
||
of the code in format-specific I/O modules.
|
||
|
||
The original VMS support was contributed by David L. Kashtan. Eric
|
||
Youngdale has done much work with it since.
|
||
|
||
The Intel 80386 machine description was written by Eliot Dresselhaus.
|
||
|
||
Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
|
||
|
||
The Motorola 88k machine description was contributed by Devon Bowen
|
||
of Buffalo University and Torbjorn Granlund of the Swedish Institute of
|
||
Computer Science.
|
||
|
||
Keith Knowles at the Open Software Foundation wrote the original
|
||
MIPS back end (`tc-mips.c', `tc-mips.h'), and contributed Rose format
|
||
support (which hasn't been merged in yet). Ralph Campbell worked with
|
||
the MIPS code to support a.out format.
|
||
|
||
Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors
|
||
(tc-z8k, tc-h8300, tc-h8500), and IEEE 695 object file format
|
||
(obj-ieee), was written by Steve Chamberlain of Cygnus Support. Steve
|
||
also modified the COFF back end to use BFD for some low-level
|
||
operations, for use with the H8/300 and AMD 29k targets.
|
||
|
||
John Gilmore built the AMD 29000 support, added `.include' support,
|
||
and simplified the configuration of which versions accept which
|
||
directives. He updated the 68k machine description so that Motorola's
|
||
opcodes always produced fixed-size instructions (e.g. `jsr'), while
|
||
synthetic instructions remained shrinkable (`jbsr'). John fixed many
|
||
bugs, including true tested cross-compilation support, and one bug in
|
||
relaxation that took a week and required the proverbial one-bit fix.
|
||
|
||
Ian Lance Taylor of Cygnus Support merged the Motorola and MIT
|
||
syntax for the 68k, completed support for some COFF targets (68k, i386
|
||
SVR3, and SCO Unix), added support for MIPS ECOFF and ELF targets,
|
||
wrote the initial RS/6000 and PowerPC assembler, and made a few other
|
||
minor patches.
|
||
|
||
Steve Chamberlain made `as' able to generate listings.
|
||
|
||
Hewlett-Packard contributed support for the HP9000/300.
|
||
|
||
Jeff Law wrote GAS and BFD support for the native HPPA object format
|
||
(SOM) along with a fairly extensive HPPA testsuite (for both SOM and
|
||
ELF object formats). This work was supported by both the Center for
|
||
Software Science at the University of Utah and Cygnus Support.
|
||
|
||
Support for ELF format files has been worked on by Mark Eichin of
|
||
Cygnus Support (original, incomplete implementation for SPARC), Pete
|
||
Hoogenboom and Jeff Law at the University of Utah (HPPA mainly),
|
||
Michael Meissner of the Open Software Foundation (i386 mainly), and Ken
|
||
Raeburn of Cygnus Support (sparc, and some initial 64-bit support).
|
||
|
||
Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote
|
||
GAS and BFD support for openVMS/Alpha.
|
||
|
||
Several engineers at Cygnus Support have also provided many small
|
||
bug fixes and configuration enhancements.
|
||
|
||
Many others have contributed large or small bugfixes and
|
||
enhancements. If you have contributed significant work and are not
|
||
mentioned on this list, and want to be, let us know. Some of the
|
||
history has been lost; we are not intentionally leaving anyone out.
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) Any more details?
|
||
|