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?
|
|||
|
|