19990502 sourceware importbinu_ss_19990502

1 files changed, 5322 insertions, 0 deletions

diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
new file mode 100644
index 0000000..afe362a
--- /dev/null
+++ b/gas/doc/as.texinfo
@@ -0,0 +1,5322 @@
+\input texinfo @c                               -*-Texinfo-*-
+@c  Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 1998
+@c  Free Software Foundation, Inc.
+@c UPDATE!!  On future updates--
+@c   (1)   check for new machine-dep cmdline options in
+@c         md_parse_option definitions in config/tc-*.c
+@c   (2)   for platform-specific directives, examine md_pseudo_op
+@c         in config/tc-*.c
+@c   (3)   for object-format specific directives, examine obj_pseudo_op
+@c         in config/obj-*.c       
+@c   (4)   portable directives in potable[] in read.c
+@c %**start of header
+@setfilename as.info
+@c ---config---
+@c defaults, config file may override:
+@set have-stabs
+@c ---
+@include asconfig.texi
+@include gasver.texi
+@c ---
+@c common OR combinations of conditions
+@ifset AOUT
+@set aout-bout
+@end ifset
+@ifset ARM/Thumb
+@set ARM
+@end ifset
+@ifset BOUT
+@set aout-bout
+@end ifset
+@ifset H8/300
+@set H8
+@end ifset
+@ifset H8/500
+@set H8
+@end ifset
+@ifset SH
+@set H8
+@end ifset
+@ifset HPPA
+@set abnormal-separator
+@end ifset
+@c ------------
+@ifset GENERIC
+@settitle Using @value{AS}
+@end ifset
+@ifclear GENERIC
+@settitle Using @value{AS} (@value{TARGET})
+@end ifclear
+@setchapternewpage odd
+@c %**end of header
+
+@c @smallbook
+@c @set SMALL
+@c WARE! Some of the machine-dependent sections contain tables of machine
+@c instructions.  Except in multi-column format, these tables look silly.
+@c Unfortunately, Texinfo doesn't have a general-purpose multi-col format, so
+@c the multi-col format is faked within @example sections.
+@c 
+@c Again unfortunately, the natural size that fits on a page, for these tables,
+@c is different depending on whether or not smallbook is turned on.
+@c This matters, because of order: text flow switches columns at each page
+@c break.
+@c 
+@c The format faked in this source works reasonably well for smallbook,
+@c not well for the default large-page format.  This manual expects that if you
+@c turn on @smallbook, you will also uncomment the "@set SMALL" to enable the
+@c tables in question.  You can turn on one without the other at your
+@c discretion, of course. 
+@ifinfo
+@set SMALL
+@c the insn tables look just as silly in info files regardless of smallbook,
+@c might as well show 'em anyways.
+@end ifinfo
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* As: (as).                     The GNU assembler.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@finalout
+@syncodeindex ky cp
+
+@ifinfo
+This file documents the GNU Assembler "@value{AS}".
+
+Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 1998 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.
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+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.
+@end ifinfo
+
+@titlepage
+@title Using @value{AS}
+@subtitle The @sc{gnu} Assembler
+@ifclear GENERIC
+@subtitle for the @value{TARGET} family
+@end ifclear
+@sp 1
+@subtitle Version @value{VERSION}
+@sp 1
+@sp 13
+The Free Software Foundation Inc.  thanks The Nice Computer
+Company of Australia for loaning Dean Elsner to write the
+first (Vax) version of @code{as} for Project @sc{gnu}.
+The proprietors, management and staff of TNCCA thank FSF for
+distracting the boss while they got some work
+done.
+@sp 3
+@author Dean Elsner, Jay Fenlason & friends
+@page
+@tex
+{\parskip=0pt
+\hfill {\it Using {\tt @value{AS}}}\par
+\hfill Edited by Cygnus Support\par
+}
+%"boxit" macro for figures:
+%Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
+\gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
+     \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
+#2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
+\gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
+@end tex
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 1998 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.
+@end titlepage
+
+@ifinfo
+@node Top
+@top Using @value{AS}
+
+This file is a user guide to the @sc{gnu} assembler @code{@value{AS}} version
+@value{VERSION}.
+@ifclear GENERIC
+This version of the file describes @code{@value{AS}} configured to generate
+code for @value{TARGET} architectures.
+@end ifclear
+@menu
+* Overview::                    Overview
+* Invoking::                    Command-Line Options
+* Syntax::                      Syntax
+* Sections::                    Sections and Relocation
+* Symbols::                     Symbols
+* Expressions::                 Expressions
+* Pseudo Ops::                  Assembler Directives
+* Machine Dependencies::        Machine Dependent Features
+* Reporting Bugs::              Reporting Bugs
+* Acknowledgements::            Who Did What
+* Index::                       Index
+@end menu
+@end ifinfo
+
+@node Overview
+@chapter Overview
+@iftex
+This manual is a user guide to the @sc{gnu} assembler @code{@value{AS}}.
+@ifclear GENERIC
+This version of the manual describes @code{@value{AS}} configured to generate
+code for @value{TARGET} architectures.
+@end ifclear
+@end iftex
+
+@cindex invocation summary
+@cindex option summary
+@cindex summary of options
+Here is a brief summary of how to invoke @code{@value{AS}}.  For details,
+@pxref{Invoking,,Comand-Line Options}.
+
+@c We don't use deffn and friends for the following because they seem
+@c to be limited to one line for the header.
+@smallexample
+@value{AS} [ -a[cdhlns][=file] ] [ -D ]  [ --defsym @var{sym}=@var{val} ]
+ [ -f ] [ --gstabs ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ]
+ [ --keep-locals ] [ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ]
+ [ -version ] [ --version ] [ -W ] [ -w ] [ -x ] [ -Z ]
+@ifset A29K
+@c am29k has no machine-dependent assembler options
+@end ifset
+@ifset ARC
+ [ -mbig-endian | -mlittle-endian ]
+@end ifset
+@ifset ARM
+ [ -m[arm]1 | -m[arm]2 | -m[arm]250 | -m[arm]3 | -m[arm]6 | -m[arm]7[t][[d]m[i]] ]
+ [ -m[arm]v2 | -m[arm]v2a | -m[arm]v3 | -m[arm]v3m | -m[arm]v4 | -m[arm]v4t ]
+ [ -mthumb | -mall ]
+ [ -mfpa10 | -mfpa11 | -mfpe-old | -mno-fpu ]
+ [ -EB | -EL ]
+ [ -mapcs-32 | -mapcs-26 ]
+@end ifset
+@ifset D10V
+ [ -O ]
+@end ifset
+@ifset D30V
+ [ -O | -n | -N ]
+@end ifset
+@ifset H8
+@c Hitachi family chips have no machine-dependent assembler options
+@end ifset
+@ifset HPPA
+@c HPPA has no machine-dependent assembler options (yet).
+@end ifset
+@ifset SPARC
+@c The order here is important.  See c-sparc.texi.
+ [ -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
+   -Av8plus | -Av8plusa | -Av9 | -Av9a ]
+ [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ] [ -32 | -64 ]
+@end ifset
+@ifset Z8000
+@c Z8000 has no machine-dependent assembler options
+@end ifset
+@ifset I960
+@c see md_parse_option in tc-i960.c
+ [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
+ [ -b ] [ -no-relax ]
+@end ifset
+@ifset M680X0
+ [ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
+@end ifset
+@ifset MCORE
+ [ -jsri2bsr ] [ -sifilter ] [ -relax ]
+@end ifset
+@ifset MIPS
+ [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ]
+ [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ]
+ [ --trap ] [ --break ]
+ [ --emulation=@var{name} ]
+@end ifset
+ [ -- | @var{files} @dots{} ]
+@end smallexample
+
+@table @code
+@item -a[cdhlmns]
+Turn on listings, in any of a variety of ways:
+
+@table @code
+@item -ac
+omit false conditionals
+
+@item -ad
+omit debugging directives
+
+@item -ah
+include high-level source
+
+@item -al
+include assembly
+
+@item -am
+include macro expansions
+
+@item -an
+omit forms processing
+
+@item -as
+include symbols
+
+@item =file
+set the name of the listing file
+@end table
+
+You may combine these options; for example, use @samp{-aln} for assembly
+listing without forms processing.  The @samp{=file} option, if used, must be
+the last one.  By itself, @samp{-a} defaults to @samp{-ahls}.
+
+@item -D
+Ignored.  This option is accepted for script compatibility with calls to
+other assemblers.
+
+@item --defsym @var{sym}=@var{value}
+Define the symbol @var{sym} to be @var{value} before assembling the input file.
+@var{value} must be an integer constant.  As in C, a leading @samp{0x}
+indicates a hexadecimal value, and a leading @samp{0} indicates an octal value.
+
+@item -f
+``fast''---skip whitespace and comment preprocessing (assume source is
+compiler output).
+
+@item --gstabs
+Generate stabs debugging information for each assembler line.  This
+may help debugging assembler code, if the debugger can handle it.
+
+@item --help
+Print a summary of the command line options and exit.
+
+@item -I @var{dir}
+Add directory @var{dir} to the search list for @code{.include} directives.
+
+@item -J
+Don't warn about signed overflow.
+
+@item -K
+@ifclear DIFF-TBL-KLUGE
+This option is accepted but has no effect on the @value{TARGET} family.
+@end ifclear
+@ifset DIFF-TBL-KLUGE
+Issue warnings when difference tables altered for long displacements.
+@end ifset
+
+@item -L
+@itemx --keep-locals
+Keep (in the symbol table) local symbols.  On traditional a.out systems
+these start with @samp{L}, but different systems have different local
+label prefixes.
+
+@item -o @var{objfile}
+Name the object-file output from @code{@value{AS}} @var{objfile}.
+
+@item -R
+Fold the data section into the text section.
+
+@item --statistics
+Print the maximum space (in bytes) and total time (in seconds) used by
+assembly.
+
+@item --strip-local-absolute
+Remove local absolute symbols from the outgoing symbol table.
+
+@item -v
+@itemx -version
+Print the @code{as} version.
+
+@item --version
+Print the @code{as} version and exit.
+
+@item -W
+Suppress warning messages.
+
+@item -w
+Ignored.
+
+@item -x
+Ignored.
+
+@item -Z
+Generate an object file even after errors.
+
+@item -- | @var{files} @dots{}
+Standard input, or source files to assemble.
+
+@end table
+
+@ifset ARC
+The following options are available when @value{AS} is configured for
+an ARC processor.
+
+@table @code
+
+@cindex ARC endianness
+@cindex endianness, ARC
+@cindex big endian output, ARC
+@item -mbig-endian
+Generate ``big endian'' format output.
+
+@cindex little endian output, ARC
+@item -mlittle-endian
+Generate ``little endian'' format output.
+
+@end table
+@end ifset
+
+@ifset ARM
+The following options are available when @value{AS} is configured for the ARM
+processor family.
+
+@table @code
+@item -m[arm]1 | -m[arm]2 | -m[arm]250 | -m[arm]3 | -m[arm]6 | -m[arm]7[t][[d]m] | -m[arm]v2 | -m[arm]v2a | -m[arm]v3 | -m[arm]v3m | -m[arm]v4 | -m[arm]v4t 
+Specify which variant of the ARM architecture is the target.
+@item -mthumb | -mall
+Enable or disable Thumb only instruction decoding.
+@item -mfpa10 | -mfpa11 | -mfpe-old | -mno-fpu
+Select which Floating Point architcture is the target.
+@item -mapcs-32 | -mapcs-26
+Select which procedure calling convention is in use.
+@item -EB | -EL
+Select either big-endian (-EB) or little-endian (-EL) output.
+@end table
+@end ifset
+
+@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
+
+@ifset D30V
+The following options are available when @value{AS} is configured for a D30V
+processor.
+@table @code
+@cindex D30V optimization
+@cindex optimization, D30V
+@item -O
+Optimize output by parallelizing instructions.
+
+@cindex D30V nops
+@item -n
+Warn when nops are generated.
+
+@cindex D30V nops after 32-bit multiply
+@item -N
+Warn when a nop after a 32-bit multiply instruction is generated.
+@end table
+@end ifset
+
+@ifset I960
+The following options are available when @value{AS} is configured for the
+Intel 80960 processor.
+
+@table @code
+@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
+Specify which variant of the 960 architecture is the target.
+
+@item -b
+Add code to collect statistics about branches taken.
+
+@item -no-relax
+Do not alter compare-and-branch instructions for long displacements;
+error if necessary.
+
+@end table
+@end ifset
+
+
+@ifset M680X0
+The following options are available when @value{AS} is configured for the
+Motorola 68000 series.
+
+@table @code
+
+@item -l
+Shorten references to undefined symbols, to one word instead of two.
+
+@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -m68060
+@itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32 | -m5200
+Specify what processor in the 68000 family is the target.  The default
+is normally the 68020, but this can be changed at configuration time.
+
+@item -m68881 | -m68882 | -mno-68881 | -mno-68882
+The target machine does (or does not) have a floating-point coprocessor.
+The default is to assume a coprocessor for 68020, 68030, and cpu32.  Although
+the basic 68000 is not compatible with the 68881, a combination of the
+two can be specified, since it's possible to do emulation of the
+coprocessor instructions with the main processor.
+
+@item -m68851 | -mno-68851
+The target machine does (or does not) have a memory-management
+unit coprocessor.  The default is to assume an MMU for 68020 and up.
+
+@end table
+@end ifset
+
+@ifset SPARC
+The following options are available when @code{@value{AS}} is configured
+for the SPARC architecture:
+
+@table @code
+@item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
+@itemx -Av8plus | -Av8plusa | -Av9 | -Av9a
+Explicitly select a variant of the SPARC architecture.
+
+@samp{-Av8plus} and @samp{-Av8plusa} select a 32 bit environment.
+@samp{-Av9} and @samp{-Av9a} select a 64 bit environment.
+
+@samp{-Av8plusa} and @samp{-Av9a} enable the SPARC V9 instruction set with
+UltraSPARC extensions.
+
+@item -xarch=v8plus | -xarch=v8plusa
+For compatibility with the Solaris v9 assembler.  These options are
+equivalent to -Av8plus and -Av8plusa, respectively.
+
+@item -bump
+Warn when the assembler switches to another architecture.
+@end table
+@end ifset
+
+@ifset MIPS
+The following options are available when @value{AS} is configured for
+a MIPS processor.
+
+@table @code
+@item -G @var{num}
+This option sets the largest size of an object that can be referenced
+implicitly with the @code{gp} register.  It is only accepted for targets that
+use ECOFF format, such as a DECstation running Ultrix.  The default value is 8.
+
+@cindex MIPS endianness
+@cindex endianness, MIPS
+@cindex big endian output, MIPS
+@item -EB
+Generate ``big endian'' format output.
+
+@cindex little endian output, MIPS
+@item -EL
+Generate ``little endian'' format output.
+
+@cindex MIPS ISA
+@item -mips1
+@itemx -mips2
+@itemx -mips3
+Generate code for a particular MIPS Instruction Set Architecture level.
+@samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
+@samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000}
+processor.
+
+@item -m4650
+@itemx -no-m4650
+Generate code for the MIPS @sc{r4650} chip.  This tells the assembler to accept
+the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
+instructions around accesses to the @samp{HI} and @samp{LO} registers.
+@samp{-no-m4650} turns off this option.
+
+@item -mcpu=@var{CPU}
+Generate code for a particular MIPS cpu.  This has little effect on the
+assembler, but it is passed by @code{@value{GCC}}.
+
+@cindex emulation
+@item --emulation=@var{name}
+This option causes @code{@value{AS}} to emulate @code{@value{AS}} configured
+for some other target, in all respects, including output format (choosing
+between ELF and ECOFF only), handling of pseudo-opcodes which may generate
+debugging information or store symbol table information, and default
+endianness.  The available configuration names are: @samp{mipsecoff},
+@samp{mipself}, @samp{mipslecoff}, @samp{mipsbecoff}, @samp{mipslelf},
+@samp{mipsbelf}.  The first two do not alter the default endianness from that
+of the primary target for which the assembler was configured; the others change
+the default to little- or big-endian as indicated by the @samp{b} or @samp{l}
+in the name.  Using @samp{-EB} or @samp{-EL} will override the endianness
+selection in any case.
+
+This option is currently supported only when the primary target
+@code{@value{AS}} is configured for is a MIPS ELF or ECOFF target.
+Furthermore, the primary target or others specified with
+@samp{--enable-targets=@dots{}} at configuration time must include support for
+the other format, if both are to be available.  For example, the Irix 5
+configuration includes support for both.
+
+Eventually, this option will support more configurations, with more
+fine-grained control over the assembler's behavior, and will be supported for
+more processors.
+
+@item -nocpp
+@code{@value{AS}} ignores this option.  It is accepted for compatibility with
+the native tools.
+
+@need 900
+@item --trap
+@itemx --no-trap
+@itemx --break
+@itemx --no-break
+Control how to deal with multiplication overflow and division by zero.
+@samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception
+(and only work for Instruction Set Architecture level 2 and higher);
+@samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a
+break exception.
+@end table
+@end ifset
+
+@ifset MCORE
+The following options are available when @value{AS} is configured for
+an MCore processor.
+
+@table @code
+@item -jsri2bsr
+@itemx -nojsri2bsr
+Enable or disable the JSRI to BSR transformation.  By default this is enabled.
+The command line option @samp{-nojsri2bsr} can be used to disable it.
+
+@item -sifilter
+@itemx -nosifilter
+Enable or disable the silicon filter behaviour.  By default this is disabled.
+The default can be overidden by the @samp{-sifilter} command line option.
+
+@item -relax
+Alter jump instructions for long displacements.
+
+
+@end table
+@end ifset
+
+@menu
+* Manual::                      Structure of this Manual
+* GNU Assembler::               The GNU Assembler
+* Object Formats::              Object File Formats
+* Command Line::                Command Line
+* Input Files::                 Input Files
+* Object::                      Output (Object) File
+* Errors::                      Error and Warning Messages
+@end menu
+
+@node Manual
+@section Structure of this Manual
+
+@cindex manual, structure and purpose
+This manual is intended to describe what you need to know to use
+@sc{gnu} @code{@value{AS}}.  We cover the syntax expected in source files, including
+notation for symbols, constants, and expressions; the directives that
+@code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}.
+
+@ifclear GENERIC
+We also cover special features in the @value{TARGET}
+configuration of @code{@value{AS}}, including assembler directives.
+@end ifclear
+@ifset GENERIC
+This manual also describes some of the machine-dependent features of
+various flavors of the assembler.
+@end ifset
+
+@cindex machine instructions (not covered)
+On the other hand, this manual is @emph{not} intended as an introduction
+to programming in assembly language---let alone programming in general!
+In a similar vein, we make no attempt to introduce the machine
+architecture; we do @emph{not} describe the instruction set, standard
+mnemonics, registers or addressing modes that are standard to a
+particular architecture.
+@ifset GENERIC
+You may want to consult the manufacturer's
+machine architecture manual for this information.
+@end ifset
+@ifclear GENERIC
+@ifset H8/300
+For information on the H8/300 machine instruction set, see @cite{H8/300
+Series Programming Manual} (Hitachi ADE--602--025).  For the H8/300H,
+see @cite{H8/300H Series Programming Manual} (Hitachi).
+@end ifset
+@ifset H8/500
+For information on the H8/500 machine instruction set, see @cite{H8/500
+Series Programming Manual} (Hitachi M21T001).
+@end ifset
+@ifset SH
+For information on the Hitachi SH machine instruction set, see
+@cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.).
+@end ifset
+@ifset Z8000
+For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
+@end ifset
+@end ifclear
+
+@c I think this is premature---doc@cygnus.com, 17jan1991
+@ignore
+Throughout this manual, we assume that you are running @dfn{GNU},
+the portable operating system from the @dfn{Free Software
+Foundation, Inc.}.  This restricts our attention to certain kinds of
+computer (in particular, the kinds of computers that @sc{gnu} can run on);
+once this assumption is granted examples and definitions need less
+qualification.
+
+@code{@value{AS}} is part of a team of programs that turn a high-level
+human-readable series of instructions into a low-level
+computer-readable series of instructions.  Different versions of
+@code{@value{AS}} are used for different kinds of computer.
+@end ignore
+
+@c There used to be a section "Terminology" here, which defined
+@c "contents", "byte", "word", and "long".  Defining "word" to any
+@c particular size is confusing when the .word directive may generate 16
+@c bits on one machine and 32 bits on another; in general, for the user
+@c version of this manual, none of these terms seem essential to define.
+@c They were used very little even in the former draft of the manual;
+@c this draft makes an effort to avoid them (except in names of
+@c directives).
+
+@node GNU Assembler
+@section The GNU Assembler
+
+@sc{gnu} @code{as} is really a family of assemblers.
+@ifclear GENERIC
+This manual describes @code{@value{AS}}, a member of that family which is
+configured for the @value{TARGET} architectures.
+@end ifclear
+If you use (or have used) the @sc{gnu} assembler on one architecture, you
+should find a fairly similar environment when you use it on another
+architecture.  Each version has much in common with the others,
+including object file formats, most assembler directives (often called
+@dfn{pseudo-ops}) and assembler syntax.@refill
+
+@cindex purpose of @sc{gnu} assembler
+@code{@value{AS}} is primarily intended to assemble the output of the
+@sc{gnu} C compiler @code{@value{GCC}} for use by the linker
+@code{@value{LD}}.  Nevertheless, we've tried to make @code{@value{AS}}
+assemble correctly everything that other assemblers for the same
+machine would assemble.
+@ifset VAX
+Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
+@end ifset
+@ifset M680X0
+@c This remark should appear in generic version of manual; assumption
+@c here is that generic version sets M680x0.
+This doesn't mean @code{@value{AS}} always uses the same syntax as another
+assembler for the same architecture; for example, we know of several
+incompatible versions of 680x0 assembly language syntax.
+@end ifset
+
+Unlike older assemblers, @code{@value{AS}} is designed to assemble a source
+program in one pass of the source file.  This has a subtle impact on the
+@kbd{.org} directive (@pxref{Org,,@code{.org}}).
+
+@node Object Formats
+@section Object File Formats
+
+@cindex object file format
+The @sc{gnu} assembler can be configured to produce several alternative
+object file formats.  For the most part, this does not affect how you
+write assembly language programs; but directives for debugging symbols
+are typically different in different file formats.  @xref{Symbol
+Attributes,,Symbol Attributes}.
+@ifclear GENERIC
+@ifclear MULTI-OBJ
+On the @value{TARGET}, @code{@value{AS}} is configured to produce
+@value{OBJ-NAME} format object files.
+@end ifclear
+@c The following should exhaust all configs that set MULTI-OBJ, ideally
+@ifset A29K
+On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
+@code{a.out} or COFF format object files.
+@end ifset
+@ifset I960
+On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
+@code{b.out} or COFF format object files.
+@end ifset
+@ifset HPPA
+On the @value{TARGET}, @code{@value{AS}} can be configured to produce either
+SOM or ELF format object files.
+@end ifset
+@end ifclear
+
+@node Command Line
+@section Command Line
+
+@cindex command line conventions
+After the program name @code{@value{AS}}, the command line may contain
+options and file names.  Options may appear in any order, and may be
+before, after, or between file names.  The order of file names is
+significant.
+
+@cindex standard input, as input file
+@kindex --
+@file{--} (two hyphens) by itself names the standard input file
+explicitly, as one of the files for @code{@value{AS}} to assemble.
+
+@cindex options, command line
+Except for @samp{--} any command line argument that begins with a
+hyphen (@samp{-}) is an option.  Each option changes the behavior of
+@code{@value{AS}}.  No option changes the way another option works.  An
+option is a @samp{-} followed by one or more letters; the case of
+the letter is important.   All options are optional.
+
+Some options expect exactly one file name to follow them.  The file
+name may either immediately follow the option's letter (compatible
+with older assemblers) or it may be the next command argument (@sc{gnu}
+standard).  These two command lines are equivalent:
+
+@smallexample
+@value{AS} -o my-object-file.o mumble.s
+@value{AS} -omy-object-file.o mumble.s
+@end smallexample
+
+@node Input Files
+@section Input Files
+
+@cindex input
+@cindex source program
+@cindex files, input
+We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
+describe the program input to one run of @code{@value{AS}}.  The program may
+be in one or more files; how the source is partitioned into files
+doesn't change the meaning of the source.
+
+@c I added "con" prefix to "catenation" just to prove I can overcome my
+@c APL training...   doc@cygnus.com
+The source program is a concatenation of the text in all the files, in the
+order specified.
+
+Each time you run @code{@value{AS}} it assembles exactly one source
+program.  The source program is made up of one or more files.
+(The standard input is also a file.)
+
+You give @code{@value{AS}} a command line that has zero or more input file
+names.  The input files are read (from left file name to right).  A
+command line argument (in any position) that has no special meaning
+is taken to be an input file name.
+
+If you give @code{@value{AS}} no file names it attempts to read one input file
+from the @code{@value{AS}} standard input, which is normally your terminal.  You
+may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program
+to assemble.
+
+Use @samp{--} if you need to explicitly name the standard input file
+in your command line.
+
+If the source is empty, @code{@value{AS}} produces a small, empty object
+file.
+
+@subheading Filenames and Line-numbers
+
+@cindex input file linenumbers
+@cindex line numbers, in input files
+There are two ways of locating a line in the input file (or files) and
+either may be used in reporting error messages.  One way refers to a line
+number in a physical file; the other refers to a line number in a
+``logical'' file.  @xref{Errors, ,Error and Warning Messages}.
+
+@dfn{Physical files} are those files named in the command line given
+to @code{@value{AS}}.
+
+@dfn{Logical files} are simply names declared explicitly by assembler
+directives; they bear no relation to physical files.  Logical file names help
+error messages reflect the original source file, when @code{@value{AS}} source
+is itself synthesized from other files.  @code{@value{AS}} understands the
+@samp{#} directives emitted by the @code{@value{GCC}} preprocessor.  See also
+@ref{File,,@code{.file}}.
+
+@node Object
+@section Output (Object) File
+
+@cindex object file
+@cindex output file
+@kindex a.out
+@kindex .o
+Every time you run @code{@value{AS}} it produces an output file, which is
+your assembly language program translated into numbers.  This file
+is the object file.  Its default name is
+@ifclear BOUT
+@code{a.out}.
+@end ifclear
+@ifset BOUT
+@ifset GENERIC
+@code{a.out}, or 
+@end ifset
+@code{b.out} when @code{@value{AS}} is configured for the Intel 80960.
+@end ifset
+You can give it another name by using the @code{-o} option.  Conventionally,
+object file names end with @file{.o}.  The default name is used for historical
+reasons: older assemblers were capable of assembling self-contained programs
+directly into a runnable program.  (For some formats, this isn't currently
+possible, but it can be done for the @code{a.out} format.)
+
+@cindex linker
+@kindex ld
+The object file is meant for input to the linker @code{@value{LD}}.  It contains
+assembled program code, information to help @code{@value{LD}} integrate
+the assembled program into a runnable file, and (optionally) symbolic
+information for the debugger.
+
+@c link above to some info file(s) like the description of a.out.
+@c don't forget to describe @sc{gnu} info as well as Unix lossage.
+
+@node Errors
+@section Error and Warning Messages
+
+@cindex error messsages
+@cindex warning messages
+@cindex messages from assembler
+@code{@value{AS}} may write warnings and error messages to the standard error
+file (usually your terminal).  This should not happen when  a compiler
+runs @code{@value{AS}} automatically.  Warnings report an assumption made so
+that @code{@value{AS}} could keep assembling a flawed program; errors report a
+grave problem that stops the assembly.
+
+@cindex format of warning messages
+Warning messages have the format
+
+@smallexample
+file_name:@b{NNN}:Warning Message Text
+@end smallexample
+
+@noindent
+@cindex line numbers, in warnings/errors
+(where @b{NNN} is a line number).  If a logical file name has been given
+(@pxref{File,,@code{.file}}) it is used for the filename, otherwise the name of
+the current input file is used.  If a logical line number was given
+@ifset GENERIC
+(@pxref{Line,,@code{.line}})
+@end ifset
+@ifclear GENERIC
+@ifclear A29K
+(@pxref{Line,,@code{.line}})
+@end ifclear
+@ifset A29K
+(@pxref{Ln,,@code{.ln}})
+@end ifset
+@end ifclear
+then it is used to calculate the number printed,
+otherwise the actual line in the current source file is printed.  The
+message text is intended to be self explanatory (in the grand Unix
+tradition).
+
+@cindex format of error messages
+Error messages have the format
+@smallexample
+file_name:@b{NNN}:FATAL:Error Message Text
+@end smallexample
+The file name and line number are derived as for warning
+messages.  The actual message text may be rather less explanatory
+because many of them aren't supposed to happen.
+
+@node Invoking
+@chapter Command-Line Options
+
+@cindex options, all versions of assembler
+This chapter describes command-line options available in @emph{all}
+versions of the @sc{gnu} assembler; @pxref{Machine Dependencies}, for options specific
+@ifclear GENERIC
+to the @value{TARGET}.
+@end ifclear
+@ifset GENERIC
+to particular machine architectures.
+@end ifset
+
+If you are invoking @code{@value{AS}} via the @sc{gnu} C compiler (version 2),
+you can use the @samp{-Wa} option to pass arguments through to the assembler.
+The assembler arguments must be separated from each other (and the @samp{-Wa})
+by commas.  For example:
+
+@smallexample
+gcc -c -g -O -Wa,-alh,-L file.c
+@end smallexample
+
+@noindent
+This passes two options to the assembler: @samp{-alh} (emit a listing to
+standard output with with high-level and assembly source) and @samp{-L} (retain
+local symbols in the symbol table).
+
+Usually you do not need to use this @samp{-Wa} mechanism, since many compiler
+command-line options are automatically passed to the assembler by the compiler.
+(You can call the @sc{gnu} compiler driver with the @samp{-v} option to see
+precisely what options it passes to each compilation pass, including the
+assembler.)
+
+@menu
+* a::             -a[cdhlns] enable listings
+* D::             -D for compatibility
+* f::             -f to work faster
+* I::             -I for .include search path
+@ifclear DIFF-TBL-KLUGE
+* K::             -K for compatibility
+@end ifclear
+@ifset DIFF-TBL-KLUGE
+* K::             -K for difference tables
+@end ifset
+
+* L::             -L to retain local labels
+* M::		  -M or --mri to assemble in MRI compatibility mode
+* MD::            --MD for dependency tracking
+* o::             -o to name the object file
+* R::             -R to join data and text sections
+* statistics::    --statistics to see statistics about assembly
+* traditional-format:: --traditional-format for compatible output
+* v::             -v to announce version
+* W::             -W to suppress warnings
+* Z::             -Z to make object file even after errors
+@end menu
+
+@node a
+@section Enable Listings: @code{-a[cdhlns]}
+
+@kindex -a
+@kindex -ac
+@kindex -ad
+@kindex -ah
+@kindex -al
+@kindex -an
+@kindex -as
+@cindex listings, enabling
+@cindex assembly listings, enabling
+
+These options enable listing output from the assembler.  By itself,
+@samp{-a} requests high-level, assembly, and symbols listing.
+You can use other letters to select specific options for the list:
+@samp{-ah} requests a high-level language listing,
+@samp{-al} requests an output-program assembly listing, and
+@samp{-as} requests a symbol table listing.
+High-level listings require that a compiler debugging option like
+@samp{-g} be used, and that assembly listings (@samp{-al}) be requested
+also.
+
+Use the @samp{-ac} option to omit false conditionals from a listing.  Any lines
+which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any
+other conditional), or a true @code{.if} followed by an @code{.else}, will be
+omitted from the listing.
+
+Use the @samp{-ad} option to omit debugging directives from the
+listing.
+
+Once you have specified one of these options, you can further control
+listing output and its appearance using the directives @code{.list},
+@code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
+@code{.sbttl}.
+The @samp{-an} option turns off all forms processing.
+If you do not request listing output with one of the @samp{-a} options, the
+listing-control directives have no effect.
+
+The letters after @samp{-a} may be combined into one option,
+@emph{e.g.}, @samp{-aln}.
+
+@node D
+@section @code{-D}
+
+@kindex -D
+This option has no effect whatsoever, but it is accepted to make it more
+likely that scripts written for other assemblers also work with
+@code{@value{AS}}.
+
+@node f
+@section Work Faster: @code{-f}
+
+@kindex -f
+@cindex trusted compiler
+@cindex faster processing (@code{-f})
+@samp{-f} should only be used when assembling programs written by a
+(trusted) compiler.  @samp{-f} stops the assembler from doing whitespace
+and comment preprocessing on
+the input file(s) before assembling them.  @xref{Preprocessing,
+,Preprocessing}.
+
+@quotation
+@emph{Warning:} if you use @samp{-f} when the files actually need to be
+preprocessed (if they contain comments, for example), @code{@value{AS}} does
+not work correctly.
+@end quotation
+
+@node I
+@section @code{.include} search path: @code{-I} @var{path}
+
+@kindex -I @var{path}
+@cindex paths for @code{.include}
+@cindex search path for @code{.include}
+@cindex @code{include} directive search path
+Use this option to add a @var{path} to the list of directories
+@code{@value{AS}} searches for files specified in @code{.include}
+directives (@pxref{Include,,@code{.include}}).  You may use @code{-I} as
+many times as necessary to include a variety of paths.  The current
+working directory is always searched first; after that, @code{@value{AS}}
+searches any @samp{-I} directories in the same order as they were
+specified (left to right) on the command line.
+
+@node K
+@section Difference Tables: @code{-K}
+
+@kindex -K
+@ifclear DIFF-TBL-KLUGE
+On the @value{TARGET} family, this option is allowed, but has no effect.  It is
+permitted for compatibility with the @sc{gnu} assembler on other platforms,
+where it can be used to warn when the assembler alters the machine code
+generated for @samp{.word} directives in difference tables.  The @value{TARGET}
+family does not have the addressing limitations that sometimes lead to this
+alteration on other platforms.
+@end ifclear
+
+@ifset DIFF-TBL-KLUGE
+@cindex difference tables, warning
+@cindex warning for altered difference tables
+@code{@value{AS}} sometimes alters the code emitted for directives of the form
+@samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
+You can use the @samp{-K} option if you want a warning issued when this
+is done.
+@end ifset
+
+@node L
+@section Include Local Labels: @code{-L}
+
+@kindex -L
+@cindex local labels, retaining in output
+Labels beginning with @samp{L} (upper case only) are called @dfn{local
+labels}. @xref{Symbol Names}.  Normally you do not see such labels when
+debugging, because they are intended for the use of programs (like
+compilers) that compose assembler programs, not for your notice.
+Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not
+normally debug with them.
+
+This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols
+in the object file.  Usually if you do this you also tell the linker
+@code{@value{LD}} to preserve symbols whose names begin with @samp{L}.
+
+By default, a local label is any label beginning with @samp{L}, but each
+target is allowed to redefine the local label prefix.
+@ifset HPPA
+On the HPPA local labels begin with @samp{L$}.
+@end ifset
+@ifset ARM
+@samp{;} for the ARM family;
+@end ifset
+
+@node M
+@section Assemble in MRI Compatibility Mode: @code{-M}
+
+@kindex -M
+@cindex MRI compatibility mode
+The @code{-M} or @code{--mri} option selects MRI compatibility mode.  This
+changes the syntax and pseudo-op handling of @code{@value{AS}} to make it
+compatible with the @code{ASM68K} or the @code{ASM960} (depending upon the
+configured target) assembler from Microtec Research.  The exact nature of the
+MRI syntax will not be documented here; see the MRI manuals for more
+information.  Note in particular that the handling of macros and macro
+arguments is somewhat different.  The purpose of this option is to permit
+assembling existing MRI assembler code using @code{@value{AS}}.
+
+The MRI compatibility is not complete.  Certain operations of the MRI assembler
+depend upon its object file format, and can not be supported using other object
+file formats.  Supporting these would require enhancing each object file format
+individually.  These are:
+
+@itemize @bullet
+@item global symbols in common section
+
+The m68k MRI assembler supports common sections which are merged by the linker.
+Other object file formats do not support this.  @code{@value{AS}} handles
+common sections by treating them as a single common symbol.  It permits local
+symbols to be defined within a common section, but it can not support global
+symbols, since it has no way to describe them.
+
+@item complex relocations
+
+The MRI assemblers support relocations against a negated section address, and
+relocations which combine the start addresses of two or more sections.  These
+are not support by other object file formats.
+
+@item @code{END} pseudo-op specifying start address
+
+The MRI @code{END} pseudo-op permits the specification of a start address.
+This is not supported by other object file formats.  The start address may
+instead be specified using the @code{-e} option to the linker, or in a linker
+script.
+
+@item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops
+
+The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module
+name to the output file.  This is not supported by other object file formats.
+
+@item @code{ORG} pseudo-op
+
+The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given
+address.  This differs from the usual @code{@value{AS}} @code{.org} pseudo-op,
+which changes the location within the current section.  Absolute sections are
+not supported by other object file formats.  The address of a section may be
+assigned within a linker script.
+@end itemize
+
+There are some other features of the MRI assembler which are not supported by
+@code{@value{AS}}, typically either because they are difficult or because they
+seem of little consequence.  Some of these may be supported in future releases.
+
+@itemize @bullet
+
+@item EBCDIC strings
+
+EBCDIC strings are not supported.
+
+@item packed binary coded decimal
+
+Packed binary coded decimal is not supported.  This means that the @code{DC.P}
+and @code{DCB.P} pseudo-ops are not supported.
+
+@item @code{FEQU} pseudo-op
+
+The m68k @code{FEQU} pseudo-op is not supported.
+
+@item @code{NOOBJ} pseudo-op
+
+The m68k @code{NOOBJ} pseudo-op is not supported.
+
+@item @code{OPT} branch control options
+
+The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB},
+@code{BRL}, and @code{BRW}---are ignored.  @code{@value{AS}} automatically
+relaxes all branches, whether forward or backward, to an appropriate size, so
+these options serve no purpose.
+
+@item @code{OPT} list control options
+
+The following m68k @code{OPT} list control options are ignored: @code{C},
+@code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M},
+@code{MEX}, @code{MC}, @code{MD}, @code{X}.
+
+@item other @code{OPT} options
+
+The following m68k @code{OPT} options are ignored: @code{NEST}, @code{O},
+@code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}.
+
+@item @code{OPT} @code{D} option is default
+
+The m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler.
+@code{OPT NOD} may be used to turn it off.
+
+@item @code{XREF} pseudo-op.
+
+The m68k @code{XREF} pseudo-op is ignored.
+
+@item @code{.debug} pseudo-op
+
+The i960 @code{.debug} pseudo-op is not supported.
+
+@item @code{.extended} pseudo-op
+
+The i960 @code{.extended} pseudo-op is not supported.
+
+@item @code{.list} pseudo-op.
+
+The various options of the i960 @code{.list} pseudo-op are not supported.
+
+@item @code{.optimize} pseudo-op
+
+The i960 @code{.optimize} pseudo-op is not supported.
+
+@item @code{.output} pseudo-op
+
+The i960 @code{.output} pseudo-op is not supported.
+
+@item @code{.setreal} pseudo-op
+
+The i960 @code{.setreal} pseudo-op is not supported.
+
+@end itemize
+
+@node MD
+@section Dependency tracking: @code{--MD}
+
+@kindex --MD
+@cindex dependency tracking
+@cindex make rules
+
+@code{@value{AS}} can generate a dependency file for the file it creates.  This
+file consists of a single rule suitable for @code{make} describing the
+dependencies of the main source file.
+
+The rule is written to the file named in its argument.
+
+This feature is used in the automatic updating of makefiles.
+
+@node o
+@section Name the Object File: @code{-o}
+
+@kindex -o
+@cindex naming object file
+@cindex object file name
+There is always one object file output when you run @code{@value{AS}}.  By
+default it has the name
+@ifset GENERIC
+@ifset I960
+@file{a.out} (or @file{b.out}, for Intel 960 targets only).
+@end ifset
+@ifclear I960
+@file{a.out}.
+@end ifclear
+@end ifset
+@ifclear GENERIC
+@ifset I960
+@file{b.out}.
+@end ifset
+@ifclear I960
+@file{a.out}.
+@end ifclear
+@end ifclear
+You use this option (which takes exactly one filename) to give the
+object file a different name.
+
+Whatever the object file is called, @code{@value{AS}} overwrites any
+existing file of the same name.
+
+@node R
+@section Join Data and Text Sections: @code{-R}
+
+@kindex -R
+@cindex data and text sections, joining
+@cindex text and data sections, joining
+@cindex joining text and data sections
+@cindex merging text and data sections
+@code{-R} tells @code{@value{AS}} to write the object file as if all
+data-section data lives in the text section.  This is only done at
+the very last moment:  your binary data are the same, but data
+section parts are relocated differently.  The data section part of
+your object file is zero bytes long because all its bytes are
+appended to the text section.  (@xref{Sections,,Sections and Relocation}.)
+
+When you specify @code{-R} it would be possible to generate shorter
+address displacements (because we do not have to cross between text and
+data section).  We refrain from doing this simply for compatibility with
+older versions of @code{@value{AS}}.  In future, @code{-R} may work this way.
+
+@ifset COFF
+When @code{@value{AS}} is configured for COFF output,
+this option is only useful if you use sections named @samp{.text} and
+@samp{.data}.
+@end ifset
+
+@ifset HPPA
+@code{-R} is not supported for any of the HPPA targets.  Using
+@code{-R} generates a warning from @code{@value{AS}}.
+@end ifset
+
+@node statistics
+@section Display Assembly Statistics: @code{--statistics}
+
+@kindex --statistics
+@cindex statistics, about assembly
+@cindex time, total for assembly
+@cindex space used, maximum for assembly
+Use @samp{--statistics} to display two statistics about the resources used by
+@code{@value{AS}}: the maximum amount of space allocated during the assembly
+(in bytes), and the total execution time taken for the assembly (in @sc{cpu}
+seconds).
+
+@node traditional-format
+@section Compatible output: @code{--traditional-format}
+
+@kindex --traditional-format
+For some targets, the output of @code{@value{AS}} is different in some ways
+from the output of some existing assembler.  This switch requests
+@code{@value{AS}} to use the traditional format instead.
+
+For example, it disables the exception frame optimizations which
+@code{@value{AS}} normally does by default on @code{@value{GCC}} output.
+
+@node v
+@section Announce Version: @code{-v}
+
+@kindex -v
+@kindex -version
+@cindex assembler version
+@cindex version of assembler
+You can find out what version of as is running by including the
+option @samp{-v} (which you can also spell as @samp{-version}) on the
+command line.
+
+@node W
+@section Suppress Warnings: @code{-W}
+
+@kindex -W
+@cindex suppressing warnings
+@cindex warnings, suppressing
+@code{@value{AS}} should never give a warning or error message when
+assembling compiler output.  But programs written by people often
+cause @code{@value{AS}} to give a warning that a particular assumption was
+made.  All such warnings are directed to the standard error file.
+If you use this option, no warnings are issued.  This option only
+affects the warning messages: it does not change any particular of how
+@code{@value{AS}} assembles your file.  Errors, which stop the assembly, are
+still reported.
+
+@node Z
+@section Generate Object File in Spite of Errors: @code{-Z}
+@cindex object file, after errors
+@cindex errors, continuing after
+After an error message, @code{@value{AS}} normally produces no output.  If for
+some reason you are interested in object file output even after
+@code{@value{AS}} gives an error message on your program, use the @samp{-Z}
+option.  If there are any errors, @code{@value{AS}} continues anyways, and
+writes an object file after a final warning message of the form @samp{@var{n}
+errors, @var{m} warnings, generating bad object file.}
+
+@node Syntax
+@chapter Syntax
+
+@cindex machine-independent syntax
+@cindex syntax, machine-independent
+This chapter describes the machine-independent syntax allowed in a
+source file.  @code{@value{AS}} syntax is similar to what many other
+assemblers use; it is inspired by the BSD 4.2
+@ifclear VAX
+assembler.
+@end ifclear
+@ifset VAX
+assembler, except that @code{@value{AS}} does not assemble Vax bit-fields.
+@end ifset
+
+@menu
+* Preprocessing::              Preprocessing
+* Whitespace::                  Whitespace
+* Comments::                    Comments
+* Symbol Intro::                Symbols
+* Statements::                  Statements
+* Constants::                   Constants
+@end menu
+
+@node Preprocessing
+@section Preprocessing
+
+@cindex preprocessing
+The @code{@value{AS}} internal preprocessor:
+@itemize @bullet
+@cindex whitespace, removed by preprocessor
+@item
+adjusts and removes extra whitespace.  It leaves one space or tab before
+the keywords on a line, and turns any other whitespace on the line into
+a single space.
+
+@cindex comments, removed by preprocessor
+@item
+removes all comments, replacing them with a single space, or an
+appropriate number of newlines.
+
+@cindex constants, converted by preprocessor
+@item
+converts character constants into the appropriate numeric values.
+@end itemize
+
+It does not do macro processing, include file handling, or
+anything else you may get from your C compiler's preprocessor.  You can
+do include file processing with the @code{.include} directive
+(@pxref{Include,,@code{.include}}).  You can use the @sc{gnu} C compiler driver
+to get other ``CPP'' style preprocessing, by giving the input file a
+@samp{.S} suffix.  @xref{Overall Options,, Options Controlling the Kind of
+Output, gcc.info, Using GNU CC}.
+
+Excess whitespace, comments, and character constants
+cannot be used in the portions of the input text that are not
+preprocessed.
+
+@cindex turning preprocessing on and off
+@cindex preprocessing, turning on and off
+@kindex #NO_APP
+@kindex #APP
+If the first line of an input file is @code{#NO_APP} or if you use the
+@samp{-f} option, whitespace and comments are not removed from the input file.
+Within an input file, you can ask for whitespace and comment removal in
+specific portions of the by putting a line that says @code{#APP} before the
+text that may contain whitespace or comments, and putting a line that says
+@code{#NO_APP} after this text.  This feature is mainly intend to support
+@code{asm} statements in compilers whose output is otherwise free of comments
+and whitespace.
+
+@node Whitespace
+@section Whitespace
+
+@cindex whitespace
+@dfn{Whitespace} is one or more blanks or tabs, in any order.
+Whitespace is used to separate symbols, and to make programs neater for
+people to read.  Unless within character constants
+(@pxref{Characters,,Character Constants}), any whitespace means the same
+as exactly one space.
+
+@node Comments
+@section Comments
+
+@cindex comments
+There are two ways of rendering comments to @code{@value{AS}}.  In both
+cases the comment is equivalent to one space.
+
+Anything from @samp{/*} through the next @samp{*/} is a comment.
+This means you may not nest these comments.
+
+@smallexample
+/*
+  The only way to include a newline ('\n') in a comment
+  is to use this sort of comment.
+*/
+
+/* This sort of comment does not nest. */
+@end smallexample
+
+@cindex line comment character
+Anything from the @dfn{line comment} character to the next newline
+is considered a comment and is ignored.  The line comment character is
+@ifset A29K
+@samp{;} for the AMD 29K family;
+@end ifset
+@ifset ARC
+@samp{;} on the ARC;
+@end ifset
+@ifset H8/300
+@samp{;} for the H8/300 family;
+@end ifset
+@ifset H8/500
+@samp{!} for the H8/500 family;
+@end ifset
+@ifset HPPA
+@samp{;} for the HPPA;
+@end ifset
+@ifset I960
+@samp{#} on the i960;
+@end ifset
+@ifset SH
+@samp{!} for the Hitachi SH;
+@end ifset
+@ifset SPARC
+@samp{!} on the SPARC;
+@end ifset
+@ifset M32R
+@samp{#} on the m32r;
+@end ifset
+@ifset M680X0
+@samp{|} on the 680x0;
+@end ifset
+@ifset VAX
+@samp{#} on the Vax;
+@end ifset
+@ifset Z8000
+@samp{!} for the Z8000;
+@end ifset
+@ifset V850
+@samp{#} on the V850;
+@end ifset
+see @ref{Machine Dependencies}.  @refill
+@c FIXME What about i386, m88k, i860?
+
+@ifset GENERIC
+On some machines there are two different line comment characters.  One
+character only begins a comment if it is the first non-whitespace character on
+a line, while the other always begins a comment.
+@end ifset
+
+@ifset V850
+The V850 assembler also supports a double dash as starting a comment that
+extends to the end of the line.
+
+@samp{--};
+@end ifset
+
+@kindex #
+@cindex lines starting with @code{#}
+@cindex logical line numbers
+To be compatible with past assemblers, lines that begin with @samp{#} have a
+special interpretation.  Following the @samp{#} should be an absolute
+expression (@pxref{Expressions}): the logical line number of the @emph{next}
+line.  Then a string (@pxref{Strings,, Strings}) is allowed: if present it is a
+new logical file name.  The rest of the line, if any, should be whitespace.
+
+If the first non-whitespace characters on the line are not numeric,
+the line is ignored.  (Just like a comment.)
+
+@smallexample
+                          # This is an ordinary comment.
+# 42-6 "new_file_name"    # New logical file name
+                          # This is logical line # 36.
+@end smallexample
+This feature is deprecated, and may disappear from future versions
+of @code{@value{AS}}.
+
+@node Symbol Intro
+@section Symbols
+
+@cindex characters used in symbols
+@ifclear SPECIAL-SYMS
+A @dfn{symbol} is one or more characters chosen from the set of all
+letters (both upper and lower case), digits and the three characters
+@samp{_.$}.
+@end ifclear
+@ifset SPECIAL-SYMS
+@ifclear GENERIC
+@ifset H8
+A @dfn{symbol} is one or more characters chosen from the set of all
+letters (both upper and lower case), digits and the three characters
+@samp{._$}.  (Save that, on the H8/300 only, you may not use @samp{$} in
+symbol names.)
+@end ifset
+@end ifclear
+@end ifset
+@ifset GENERIC
+On most machines, you can also use @code{$} in symbol names; exceptions
+are noted in @ref{Machine Dependencies}.
+@end ifset
+No symbol may begin with a digit.  Case is significant.
+There is no length limit: all characters are significant.  Symbols are
+delimited by characters not in that set, or by the beginning of a file
+(since the source program must end with a newline, the end of a file is
+not a possible symbol delimiter).  @xref{Symbols}.
+@cindex length of symbols
+
+@node Statements
+@section Statements
+
+@cindex statements, structure of
+@cindex line separator character
+@cindex statement separator character
+@ifclear GENERIC
+@ifclear abnormal-separator
+A @dfn{statement} ends at a newline character (@samp{\n}) or at a
+semicolon (@samp{;}).  The newline or semicolon is considered part of
+the preceding statement.  Newlines and semicolons within character
+constants are an exception: they do not end statements.
+@end ifclear
+@ifset abnormal-separator
+@ifset A29K
+A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
+sign (@samp{@@}).  The newline or at sign is considered part of the
+preceding statement.  Newlines and at signs within character constants
+are an exception: they do not end statements.
+@end ifset
+@ifset HPPA
+A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation 
+point (@samp{!}).  The newline or exclamation point is considered part of the
+preceding statement.  Newlines and exclamation points within character
+constants are an exception: they do not end statements.
+@end ifset
+@ifset H8
+A @dfn{statement} ends at a newline character (@samp{\n}); or (for the
+H8/300) a dollar sign (@samp{$}); or (for the
+Hitachi-SH or the
+H8/500) a semicolon
+(@samp{;}).  The newline or separator character is considered part of
+the preceding statement.  Newlines and separators within character
+constants are an exception: they do not end statements.
+@end ifset
+@end ifset
+@end ifclear
+@ifset GENERIC
+A @dfn{statement} ends at a newline character (@samp{\n}) or line
+separator character.  (The line separator is usually @samp{;}, unless
+this conflicts with the comment character; @pxref{Machine Dependencies}.)  The
+newline or separator character is considered part of the preceding
+statement.  Newlines and separators within character constants are an
+exception: they do not end statements.
+@end ifset
+
+@cindex newline, required at file end
+@cindex EOF, newline must precede
+It is an error to end any statement with end-of-file:  the last
+character of any input file should be a newline.@refill
+
+An empty statement is allowed, and may include whitespace.  It is ignored.
+
+@cindex instructions and directives
+@cindex directives and instructions
+@c "key symbol" is not used elsewhere in the document; seems pedantic to
+@c @defn{} it in that case, as was done previously...  doc@cygnus.com,
+@c 13feb91.
+A statement begins with zero or more labels, optionally followed by a
+key symbol which determines what kind of statement it is.  The key
+symbol determines the syntax of the rest of the statement.  If the
+symbol begins with a dot @samp{.} then the statement is an assembler
+directive: typically valid for any computer.  If the symbol begins with
+a letter the statement is an assembly language @dfn{instruction}: it
+assembles into a machine language instruction.
+@ifset GENERIC
+Different versions of @code{@value{AS}} for different computers
+recognize different instructions.  In fact, the same symbol may
+represent a different instruction in a different computer's assembly
+language.@refill
+@end ifset
+
+@cindex @code{:} (label)
+@cindex label (@code{:})
+A label is a symbol immediately followed by a colon (@code{:}).
+Whitespace before a label or after a colon is permitted, but you may not
+have whitespace between a label's symbol and its colon. @xref{Labels}.
+
+@ifset HPPA
+For HPPA targets, labels need not be immediately followed by a colon, but 
+the definition of a label must begin in column zero.  This also implies that
+only one label may be defined on each line.
+@end ifset
+
+@smallexample
+label:     .directive    followed by something
+another_label:           # This is an empty statement.
+           instruction   operand_1, operand_2, @dots{}
+@end smallexample
+
+@node Constants
+@section Constants
+
+@cindex constants
+A constant is a number, written so that its value is known by
+inspection, without knowing any context.  Like this:
+@smallexample
+@group
+.byte  74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
+.ascii "Ring the bell\7"                  # A string constant.
+.octa  0x123456789abcdef0123456789ABCDEF0 # A bignum.
+.float 0f-314159265358979323846264338327\
+95028841971.693993751E-40                 # - pi, a flonum.
+@end group
+@end smallexample
+
+@menu
+* Characters::                  Character Constants
+* Numbers::                     Number Constants
+@end menu
+
+@node Characters
+@subsection Character Constants
+
+@cindex character constants
+@cindex constants, character
+There are two kinds of character constants.  A @dfn{character} stands
+for one character in one byte and its value may be used in
+numeric expressions.  String constants (properly called string
+@emph{literals}) are potentially many bytes and their values may not be
+used in arithmetic expressions.
+
+@menu
+* Strings::                     Strings
+* Chars::                       Characters
+@end menu
+
+@node Strings
+@subsubsection Strings
+
+@cindex string constants
+@cindex constants, string
+A @dfn{string} is written between double-quotes.  It may contain
+double-quotes or null characters.  The way to get special characters
+into a string is to @dfn{escape} these characters: precede them with
+a backslash @samp{\} character.  For example @samp{\\} represents
+one backslash:  the first @code{\} is an escape which tells
+@code{@value{AS}} to interpret the second character literally as a backslash
+(which prevents @code{@value{AS}} from recognizing the second @code{\} as an
+escape character).  The complete list of escapes follows.
+
+@cindex escape codes, character
+@cindex character escape codes
+@table @kbd
+@c      @item \a
+@c      Mnemonic for ACKnowledge; for ASCII this is octal code 007.
+@c
+@cindex @code{\b} (backspace character)
+@cindex backspace (@code{\b})
+@item \b
+Mnemonic for backspace; for ASCII this is octal code 010.
+
+@c      @item \e
+@c      Mnemonic for EOText; for ASCII this is octal code 004.
+@c
+@cindex @code{\f} (formfeed character)
+@cindex formfeed (@code{\f})
+@item \f
+Mnemonic for FormFeed; for ASCII this is octal code 014.
+
+@cindex @code{\n} (newline character)
+@cindex newline (@code{\n})
+@item \n
+Mnemonic for newline; for ASCII this is octal code 012.
+
+@c      @item \p
+@c      Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
+@c
+@cindex @code{\r} (carriage return character)
+@cindex carriage return (@code{\r})
+@item \r
+Mnemonic for carriage-Return; for ASCII this is octal code 015.
+
+@c      @item \s
+@c      Mnemonic for space; for ASCII this is octal code 040.  Included for compliance with
+@c      other assemblers.
+@c
+@cindex @code{\t} (tab)
+@cindex tab (@code{\t})
+@item \t
+Mnemonic for horizontal Tab; for ASCII this is octal code 011.
+
+@c      @item \v
+@c      Mnemonic for Vertical tab; for ASCII this is octal code 013.
+@c      @item \x @var{digit} @var{digit} @var{digit}
+@c      A hexadecimal character code.  The numeric code is 3 hexadecimal digits.
+@c
+@cindex @code{\@var{ddd}} (octal character code)
+@cindex octal character code (@code{\@var{ddd}})
+@item \ @var{digit} @var{digit} @var{digit}
+An octal character code.  The numeric code is 3 octal digits.
+For compatibility with other Unix systems, 8 and 9 are accepted as digits:
+for example, @code{\008} has the value 010, and @code{\009} the value 011.
+
+@cindex @code{\@var{xd...}} (hex character code)
+@cindex hex character code (@code{\@var{xd...}})
+@item \@code{x} @var{hex-digits...}
+A hex character code.  All trailing hex digits are combined.  Either upper or
+lower case @code{x} works.
+
+@cindex @code{\\} (@samp{\} character)
+@cindex backslash (@code{\\})
+@item \\
+Represents one @samp{\} character.
+
+@c      @item \'
+@c      Represents one @samp{'} (accent acute) character.
+@c      This is needed in single character literals
+@c      (@xref{Characters,,Character Constants}.) to represent
+@c      a @samp{'}.
+@c
+@cindex @code{\"} (doublequote character)
+@cindex doublequote (@code{\"})
+@item \"
+Represents one @samp{"} character.  Needed in strings to represent
+this character, because an unescaped @samp{"} would end the string.
+
+@item \ @var{anything-else}
+Any other character when escaped by @kbd{\} gives a warning, but
+assembles as if the @samp{\} was not present.  The idea is that if
+you used an escape sequence you clearly didn't want the literal
+interpretation of the following character.  However @code{@value{AS}} has no
+other interpretation, so @code{@value{AS}} knows it is giving you the wrong
+code and warns you of the fact.
+@end table
+
+Which characters are escapable, and what those escapes represent,
+varies widely among assemblers.  The current set is what we think
+the BSD 4.2 assembler recognizes, and is a subset of what most C
+compilers recognize.  If you are in doubt, do not use an escape
+sequence.
+
+@node Chars
+@subsubsection Characters
+
+@cindex single character constant
+@cindex character, single
+@cindex constant, single character
+A single character may be written as a single quote immediately
+followed by that character.  The same escapes apply to characters as
+to strings.  So if you want to write the character backslash, you
+must write @kbd{'\\} where the first @code{\} escapes the second
+@code{\}.  As you can see, the quote is an acute accent, not a
+grave accent.  A newline
+@ifclear GENERIC
+@ifclear abnormal-separator
+(or semicolon @samp{;})
+@end ifclear
+@ifset abnormal-separator
+@ifset A29K
+(or at sign @samp{@@})
+@end ifset
+@ifset H8
+(or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
+Hitachi SH or
+H8/500)
+@end ifset
+@end ifset
+@end ifclear
+immediately following an acute accent is taken as a literal character
+and does not count as the end of a statement.  The value of a character
+constant in a numeric expression is the machine's byte-wide code for
+that character.  @code{@value{AS}} assumes your character code is ASCII:
+@kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
+
+@node Numbers
+@subsection Number Constants
+
+@cindex constants, number
+@cindex number constants
+@code{@value{AS}} distinguishes three kinds of numbers according to how they
+are stored in the target machine.  @emph{Integers} are numbers that
+would fit into an @code{int} in the C language.  @emph{Bignums} are
+integers, but they are stored in more than 32 bits.  @emph{Flonums}
+are floating point numbers, described below.
+
+@menu
+* Integers::                    Integers
+* Bignums::                     Bignums
+* Flonums::                     Flonums
+@ifclear GENERIC
+@ifset I960
+* Bit Fields::                  Bit Fields
+@end ifset
+@end ifclear
+@end menu
+
+@node Integers
+@subsubsection Integers
+@cindex integers
+@cindex constants, integer
+
+@cindex binary integers
+@cindex integers, binary
+A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
+the binary digits @samp{01}.
+
+@cindex octal integers
+@cindex integers, octal
+An octal integer is @samp{0} followed by zero or more of the octal
+digits (@samp{01234567}).
+
+@cindex decimal integers
+@cindex integers, decimal
+A decimal integer starts with a non-zero digit followed by zero or
+more digits (@samp{0123456789}).
+
+@cindex hexadecimal integers
+@cindex integers, hexadecimal
+A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
+more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
+
+Integers have the usual values.  To denote a negative integer, use
+the prefix operator @samp{-} discussed under expressions
+(@pxref{Prefix Ops,,Prefix Operators}).
+
+@node Bignums
+@subsubsection Bignums
+
+@cindex bignums
+@cindex constants, bignum
+A @dfn{bignum} has the same syntax and semantics as an integer
+except that the number (or its negative) takes more than 32 bits to
+represent in binary.  The distinction is made because in some places
+integers are permitted while bignums are not.
+
+@node Flonums
+@subsubsection Flonums
+@cindex flonums
+@cindex floating point numbers
+@cindex constants, floating point
+
+@cindex precision, floating point
+A @dfn{flonum} represents a floating point number.  The translation is
+indirect: a decimal floating point number from the text is converted by
+@code{@value{AS}} to a generic binary floating point number of more than
+sufficient precision.  This generic floating point number is converted
+to a particular computer's floating point format (or formats) by a
+portion of @code{@value{AS}} specialized to that computer.
+
+A flonum is written by writing (in order)
+@itemize @bullet
+@item
+The digit @samp{0}.
+@ifset HPPA
+(@samp{0} is optional on the HPPA.)
+@end ifset
+
+@item
+A letter, to tell @code{@value{AS}} the rest of the number is a flonum.
+@ifset GENERIC
+@kbd{e} is recommended.  Case is not important.
+@ignore
+@c FIXME: verify if flonum syntax really this vague for most cases
+(Any otherwise illegal letter works here, but that might be changed.  Vax BSD
+4.2 assembler seems to allow any of @samp{defghDEFGH}.)
+@end ignore
+
+On the H8/300, H8/500,
+Hitachi SH,
+and AMD 29K architectures, the letter must be
+one of the letters @samp{DFPRSX} (in upper or lower case).
+
+On the ARC, the letter must be one of the letters @samp{DFRS}
+(in upper or lower case).
+
+On the Intel 960 architecture, the letter must be
+one of the letters @samp{DFT} (in upper or lower case).
+
+On the HPPA architecture, the letter must be @samp{E} (upper case only).
+@end ifset
+@ifclear GENERIC
+@ifset A29K
+One of the letters @samp{DFPRSX} (in upper or lower case).
+@end ifset
+@ifset ARC
+One of the letters @samp{DFRS} (in upper or lower case).
+@end ifset
+@ifset H8
+One of the letters @samp{DFPRSX} (in upper or lower case).
+@end ifset
+@ifset HPPA
+The letter @samp{E} (upper case only).
+@end ifset
+@ifset I960
+One of the letters @samp{DFT} (in upper or lower case).
+@end ifset
+@end ifclear
+
+@item
+An optional sign: either @samp{+} or @samp{-}.
+
+@item
+An optional @dfn{integer part}: zero or more decimal digits.
+
+@item
+An optional @dfn{fractional part}: @samp{.} followed by zero
+or more decimal digits.
+
+@item
+An optional exponent, consisting of:
+
+@itemize @bullet
+@item
+An @samp{E} or @samp{e}.
+@c I can't find a config where "EXP_CHARS" is other than 'eE', but in
+@c principle this can perfectly well be different on different targets.
+@item
+Optional sign: either @samp{+} or @samp{-}.
+@item
+One or more decimal digits.
+@end itemize
+
+@end itemize
+
+At least one of the integer part or the fractional part must be
+present.  The floating point number has the usual base-10 value.
+
+@code{@value{AS}} does all processing using integers.  Flonums are computed
+independently of any floating point hardware in the computer running
+@code{@value{AS}}.
+
+@ifclear GENERIC
+@ifset I960
+@c Bit fields are written as a general facility but are also controlled
+@c by a conditional-compilation flag---which is as of now (21mar91)
+@c turned on only by the i960 config of GAS.
+@node Bit Fields
+@subsubsection Bit Fields
+
+@cindex bit fields
+@cindex constants, bit field
+You can also define numeric constants as @dfn{bit fields}.
+specify two numbers separated by a colon---
+@example
+@var{mask}:@var{value}
+@end example
+@noindent
+@code{@value{AS}} applies a bitwise @sc{and} between @var{mask} and
+@var{value}.
+
+The resulting number is then packed
+@ifset GENERIC
+@c this conditional paren in case bit fields turned on elsewhere than 960
+(in host-dependent byte order)
+@end ifset
+into a field whose width depends on which assembler directive has the
+bit-field as its argument.  Overflow (a result from the bitwise and
+requiring more binary digits to represent) is not an error; instead,
+more constants are generated, of the specified width, beginning with the
+least significant digits.@refill
+
+The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
+@code{.short}, and @code{.word} accept bit-field arguments.
+@end ifset
+@end ifclear
+
+@node Sections
+@chapter Sections and Relocation
+@cindex sections
+@cindex relocation
+
+@menu
+* Secs Background::             Background
+* Ld Sections::                 Linker Sections
+* As Sections::                 Assembler Internal Sections
+* Sub-Sections::                Sub-Sections
+* bss::                         bss Section
+@end menu
+
+@node Secs Background
+@section Background
+
+Roughly, a section is a range of addresses, with no gaps; all data
+``in'' those addresses is treated the same for some particular purpose.
+For example there may be a ``read only'' section.
+
+@cindex linker, and assembler
+@cindex assembler, and linker
+The linker @code{@value{LD}} reads many object files (partial programs) and
+combines their contents to form a runnable program.  When @code{@value{AS}}
+emits an object file, the partial program is assumed to start at address 0.
+@code{@value{LD}} assigns the final addresses for the partial program, so that
+different partial programs do not overlap.  This is actually an
+oversimplification, but it suffices to explain how @code{@value{AS}} uses
+sections.
+
+@code{@value{LD}} moves blocks of bytes of your program to their run-time
+addresses.  These blocks slide to their run-time addresses as rigid
+units; their length does not change and neither does the order of bytes
+within them.  Such a rigid unit is called a @emph{section}.  Assigning
+run-time addresses to sections is called @dfn{relocation}.  It includes
+the task of adjusting mentions of object-file addresses so they refer to
+the proper run-time addresses.
+@ifset H8
+For the H8/300 and H8/500,
+and for the Hitachi SH,
+@code{@value{AS}} pads sections if needed to
+ensure they end on a word (sixteen bit) boundary.
+@end ifset
+
+@cindex standard assembler sections
+An object file written by @code{@value{AS}} has at least three sections, any
+of which may be empty.  These are named @dfn{text}, @dfn{data} and
+@dfn{bss} sections.
+
+@ifset COFF
+@ifset GENERIC
+When it generates COFF output,
+@end ifset
+@code{@value{AS}} can also generate whatever other named sections you specify
+using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
+If you do not use any directives that place output in the @samp{.text}
+or @samp{.data} sections, these sections still exist, but are empty.
+@end ifset
+
+@ifset HPPA
+@ifset GENERIC
+When @code{@value{AS}} generates SOM or ELF output for the HPPA,
+@end ifset
+@code{@value{AS}} can also generate whatever other named sections you
+specify using the @samp{.space} and @samp{.subspace} directives.  See
+@cite{HP9000 Series 800 Assembly Language Reference Manual}
+(HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
+assembler directives.
+
+@ifset SOM
+Additionally, @code{@value{AS}} uses different names for the standard
+text, data, and bss sections when generating SOM output.  Program text
+is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
+BSS into @samp{$BSS$}.
+@end ifset
+@end ifset
+
+Within the object file, the text section starts at address @code{0}, the
+data section follows, and the bss section follows the data section.
+
+@ifset HPPA
+When generating either SOM or ELF output files on the HPPA, the text
+section starts at address @code{0}, the data section at address
+@code{0x4000000}, and the bss section follows the data section.
+@end ifset
+
+To let @code{@value{LD}} know which data changes when the sections are
+relocated, and how to change that data, @code{@value{AS}} also writes to the
+object file details of the relocation needed.  To perform relocation
+@code{@value{LD}} must know, each time an address in the object
+file is mentioned:
+@itemize @bullet
+@item
+Where in the object file is the beginning of this reference to
+an address?
+@item
+How long (in bytes) is this reference?
+@item
+Which section does the address refer to?  What is the numeric value of
+@display
+(@var{address}) @minus{} (@var{start-address of section})?
+@end display
+@item
+Is the reference to an address ``Program-Counter relative''?
+@end itemize
+
+@cindex addresses, format of
+@cindex section-relative addressing
+In fact, every address @code{@value{AS}} ever uses is expressed as
+@display
+(@var{section}) + (@var{offset into section})
+@end display
+@noindent
+Further, most expressions @code{@value{AS}} computes have this section-relative
+nature.
+@ifset SOM
+(For some object formats, such as SOM for the HPPA, some expressions are
+symbol-relative instead.)
+@end ifset
+
+In this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset
+@var{N} into section @var{secname}.''
+
+Apart from text, data and bss sections you need to know about the
+@dfn{absolute} section.  When @code{@value{LD}} mixes partial programs,
+addresses in the absolute section remain unchanged.  For example, address
+@code{@{absolute 0@}} is ``relocated'' to run-time address 0 by
+@code{@value{LD}}.  Although the linker never arranges two partial programs'
+data sections with overlapping addresses after linking, @emph{by definition}
+their absolute sections must overlap.  Address @code{@{absolute@ 239@}} in one
+part of a program is always the same address when the program is running as
+address @code{@{absolute@ 239@}} in any other part of the program.
+
+The idea of sections is extended to the @dfn{undefined} section.  Any
+address whose section is unknown at assembly time is by definition
+rendered @{undefined @var{U}@}---where @var{U} is filled in later.
+Since numbers are always defined, the only way to generate an undefined
+address is to mention an undefined symbol.  A reference to a named
+common block would be such a symbol: its value is unknown at assembly
+time so it has section @emph{undefined}.
+
+By analogy the word @emph{section} is used to describe groups of sections in
+the linked program.  @code{@value{LD}} puts all partial programs' text
+sections in contiguous addresses in the linked program.  It is
+customary to refer to the @emph{text section} of a program, meaning all
+the addresses of all partial programs' text sections.  Likewise for
+data and bss sections.
+
+Some sections are manipulated by @code{@value{LD}}; others are invented for
+use of @code{@value{AS}} and have no meaning except during assembly.
+
+@node Ld Sections
+@section Linker Sections
+@code{@value{LD}} deals with just four kinds of sections, summarized below.
+
+@table @strong
+
+@ifset COFF
+@cindex named sections
+@cindex sections, named
+@item named sections
+@end ifset
+@ifset aout-bout
+@cindex text section
+@cindex data section
+@itemx text section
+@itemx data section
+@end ifset
+These sections hold your program.  @code{@value{AS}} and @code{@value{LD}} treat them as
+separate but equal sections.  Anything you can say of one section is
+true another.
+@ifset aout-bout
+When the program is running, however, it is
+customary for the text section to be unalterable.  The
+text section is often shared among processes: it contains
+instructions, constants and the like.  The data section of a running
+program is usually alterable: for example, C variables would be stored
+in the data section.
+@end ifset
+
+@cindex bss section
+@item bss section
+This section contains zeroed bytes when your program begins running.  It
+is used to hold unitialized variables or common storage.  The length of
+each partial program's bss section is important, but because it starts
+out containing zeroed bytes there is no need to store explicit zero
+bytes in the object file.  The bss section was invented to eliminate
+those explicit zeros from object files.
+
+@cindex absolute section
+@item absolute section
+Address 0 of this section is always ``relocated'' to runtime address 0.
+This is useful if you want to refer to an address that @code{@value{LD}} must
+not change when relocating.  In this sense we speak of absolute
+addresses being ``unrelocatable'': they do not change during relocation.
+
+@cindex undefined section
+@item undefined section
+This ``section'' is a catch-all for address references to objects not in
+the preceding sections.
+@c FIXME: ref to some other doc on obj-file formats could go here.
+@end table
+
+@cindex relocation example
+An idealized example of three relocatable sections follows.
+@ifset COFF
+The example uses the traditional section names @samp{.text} and @samp{.data}.
+@end ifset
+Memory addresses are on the horizontal axis.
+
+@c TEXI2ROFF-KILL
+@ifinfo
+@c END TEXI2ROFF-KILL
+@smallexample
+                      +-----+----+--+
+partial program # 1:  |ttttt|dddd|00|
+                      +-----+----+--+
+
+                      text   data bss
+                      seg.   seg. seg.
+
+                      +---+---+---+
+partial program # 2:  |TTT|DDD|000|
+                      +---+---+---+
+
+                      +--+---+-----+--+----+---+-----+~~
+linked program:       |  |TTT|ttttt|  |dddd|DDD|00000|
+                      +--+---+-----+--+----+---+-----+~~
+
+    addresses:        0 @dots{}
+@end smallexample
+@c TEXI2ROFF-KILL
+@end ifinfo
+@need 5000
+@tex
+
+\line{\it Partial program \#1: \hfil}
+\line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
+\line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
+
+\line{\it Partial program \#2: \hfil}
+\line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
+\line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
+
+\line{\it linked program: \hfil}
+\line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
+\line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
+ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
+DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
+
+\line{\it addresses: \hfil}
+\line{0\dots\hfil}
+
+@end tex
+@c END TEXI2ROFF-KILL
+
+@node As Sections
+@section Assembler Internal Sections
+
+@cindex internal assembler sections
+@cindex sections in messages, internal
+These sections are meant only for the internal use of @code{@value{AS}}.  They
+have no meaning at run-time.  You do not really need to know about these
+sections for most purposes; but they can be mentioned in @code{@value{AS}}
+warning messages, so it might be helpful to have an idea of their
+meanings to @code{@value{AS}}.  These sections are used to permit the
+value of every expression in your assembly language program to be a
+section-relative address.
+
+@table @b
+@cindex assembler internal logic error
+@item ASSEMBLER-INTERNAL-LOGIC-ERROR!
+An internal assembler logic error has been found.  This means there is a
+bug in the assembler.
+
+@cindex expr (internal section)
+@item expr section
+The assembler stores complex expression internally as combinations of
+symbols.  When it needs to represent an expression as a symbol, it puts
+it in the expr section.
+@c FIXME item debug
+@c FIXME item transfer[t] vector preload
+@c FIXME item transfer[t] vector postload
+@c FIXME item register
+@end table
+
+@node Sub-Sections
+@section Sub-Sections
+
+@cindex numbered subsections
+@cindex grouping data
+@ifset aout-bout
+Assembled bytes
+@ifset COFF
+conventionally
+@end ifset
+fall into two sections: text and data.
+@end ifset
+You may have separate groups of
+@ifset GENERIC
+data in named sections
+@end ifset
+@ifclear GENERIC
+@ifclear aout-bout
+data in named sections
+@end ifclear
+@ifset aout-bout
+text or data
+@end ifset
+@end ifclear
+that you want to end up near to each other in the object file, even though they
+are not contiguous in the assembler source.  @code{@value{AS}} allows you to
+use @dfn{subsections} for this purpose.  Within each section, there can be
+numbered subsections with values from 0 to 8192.  Objects assembled into the
+same subsection go into the object file together with other objects in the same
+subsection.  For example, a compiler might want to store constants in the text
+section, but might not want to have them interspersed with the program being
+assembled.  In this case, the compiler could issue a @samp{.text 0} before each
+section of code being output, and a @samp{.text 1} before each group of
+constants being output.
+
+Subsections are optional.  If you do not use subsections, everything
+goes in subsection number zero.
+
+@ifset GENERIC
+Each subsection is zero-padded up to a multiple of four bytes.
+(Subsections may be padded a different amount on different flavors
+of @code{@value{AS}}.)
+@end ifset
+@ifclear GENERIC
+@ifset H8
+On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word
+boundary (two bytes).
+The same is true on the Hitachi SH.
+@end ifset
+@ifset I960
+@c FIXME section padding (alignment)?
+@c Rich Pixley says padding here depends on target obj code format; that
+@c doesn't seem particularly useful to say without further elaboration,
+@c so for now I say nothing about it.  If this is a generic BFD issue,
+@c these paragraphs might need to vanish from this manual, and be
+@c discussed in BFD chapter of binutils (or some such).
+@end ifset
+@ifset A29K
+On the AMD 29K family, no particular padding is added to section or
+subsection sizes; @value{AS} forces no alignment on this platform.
+@end ifset
+@end ifclear
+
+Subsections appear in your object file in numeric order, lowest numbered
+to highest.  (All this to be compatible with other people's assemblers.)
+The object file contains no representation of subsections; @code{@value{LD}} and
+other programs that manipulate object files see no trace of them.
+They just see all your text subsections as a text section, and all your
+data subsections as a data section.
+
+To specify which subsection you want subsequent statements assembled
+into, use a numeric argument to specify it, in a @samp{.text
+@var{expression}} or a @samp{.data @var{expression}} statement.
+@ifset COFF
+@ifset GENERIC
+When generating COFF output, you
+@end ifset
+@ifclear GENERIC
+You
+@end ifclear
+can also use an extra subsection
+argument with arbitrary named sections: @samp{.section @var{name},
+@var{expression}}.
+@end ifset
+@var{Expression} should be an absolute expression.
+(@xref{Expressions}.)  If you just say @samp{.text} then @samp{.text 0}
+is assumed.  Likewise @samp{.data} means @samp{.data 0}.  Assembly
+begins in @code{text 0}.  For instance:
+@smallexample
+.text 0     # The default subsection is text 0 anyway.
+.ascii "This lives in the first text subsection. *"
+.text 1
+.ascii "But this lives in the second text subsection."
+.data 0
+.ascii "This lives in the data section,"
+.ascii "in the first data subsection."
+.text 0
+.ascii "This lives in the first text section,"
+.ascii "immediately following the asterisk (*)."
+@end smallexample
+
+Each section has a @dfn{location counter} incremented by one for every byte
+assembled into that section.  Because subsections are merely a convenience
+restricted to @code{@value{AS}} there is no concept of a subsection location
+counter.  There is no way to directly manipulate a location counter---but the
+@code{.align} directive changes it, and any label definition captures its
+current value.  The location counter of the section where statements are being
+assembled is said to be the @dfn{active} location counter.
+
+@node bss
+@section bss Section
+
+@cindex bss section
+@cindex common variable storage
+The bss section is used for local common variable storage.
+You may allocate address space in the bss section, but you may
+not dictate data to load into it before your program executes.  When
+your program starts running, all the contents of the bss
+section are zeroed bytes.
+
+The @code{.lcomm} pseudo-op defines a symbol in the bss section; see
+@ref{Lcomm,,@code{.lcomm}}.
+
+The @code{.comm} pseudo-op may be used to declare a common symbol, which is
+another form of uninitialized symbol; see @xref{Comm,,@code{.comm}}.
+
+@ifset GENERIC
+When assembling for a target which supports multiple sections, such as ELF or
+COFF, you may switch into the @code{.bss} section and define symbols as usual;
+see @ref{Section,,@code{.section}}.  You may only assemble zero values into the
+section.  Typically the section will only contain symbol definitions and
+@code{.skip} directives (@pxref{Skip,,@code{.skip}}).
+@end ifset
+
+@node Symbols
+@chapter Symbols
+
+@cindex symbols
+Symbols are a central concept: the programmer uses symbols to name
+things, the linker uses symbols to link, and the debugger uses symbols
+to debug.
+
+@quotation
+@cindex debuggers, and symbol order
+@emph{Warning:} @code{@value{AS}} does not place symbols in the object file in
+the same order they were declared.  This may break some debuggers.
+@end quotation
+
+@menu
+* Labels::                      Labels
+* Setting Symbols::             Giving Symbols Other Values
+* Symbol Names::                Symbol Names
+* Dot::                         The Special Dot Symbol
+* Symbol Attributes::           Symbol Attributes
+@end menu
+
+@node Labels
+@section Labels
+
+@cindex labels
+A @dfn{label} is written as a symbol immediately followed by a colon
+@samp{:}.  The symbol then represents the current value of the
+active location counter, and is, for example, a suitable instruction
+operand.  You are warned if you use the same symbol to represent two
+different locations: the first definition overrides any other
+definitions.
+
+@ifset HPPA
+On the HPPA, the usual form for a label need not be immediately followed by a
+colon, but instead must start in column zero.  Only one label may be defined on
+a single line.  To work around this, the HPPA version of @code{@value{AS}} also
+provides a special directive @code{.label} for defining labels more flexibly.
+@end ifset
+
+@node Setting Symbols
+@section Giving Symbols Other Values
+
+@cindex assigning values to symbols
+@cindex symbol values, assigning
+A symbol can be given an arbitrary value by writing a symbol, followed
+by an equals sign @samp{=}, followed by an expression
+(@pxref{Expressions}).  This is equivalent to using the @code{.set}
+directive.  @xref{Set,,@code{.set}}.
+
+@node Symbol Names
+@section Symbol Names
+
+@cindex symbol names
+@cindex names, symbol
+@ifclear SPECIAL-SYMS
+Symbol names begin with a letter or with one of @samp{._}.  On most
+machines, you can also use @code{$} in symbol names; exceptions are
+noted in @ref{Machine Dependencies}.  That character may be followed by any
+string of digits, letters, dollar signs (unless otherwise noted in
+@ref{Machine Dependencies}), and underscores.
+@end ifclear
+@ifset A29K
+For the AMD 29K family, @samp{?} is also allowed in the
+body of a symbol name, though not at its beginning.
+@end ifset
+
+@ifset SPECIAL-SYMS
+@ifset H8
+Symbol names begin with a letter or with one of @samp{._}.  On the
+Hitachi SH or the
+H8/500, you can also use @code{$} in symbol names.  That character may
+be followed by any string of digits, letters, dollar signs (save on the
+H8/300), and underscores.
+@end ifset
+@end ifset
+
+Case of letters is significant: @code{foo} is a different symbol name
+than @code{Foo}.
+
+Each symbol has exactly one name.  Each name in an assembly language program
+refers to exactly one symbol.  You may use that symbol name any number of times
+in a program.
+
+@subheading Local Symbol Names
+
+@cindex local symbol names
+@cindex symbol names, local
+@cindex temporary symbol names
+@cindex symbol names, temporary
+Local symbols help compilers and programmers use names temporarily.
+There are ten local symbol names, which are re-used throughout the
+program.  You may refer to them using the names @samp{0} @samp{1}
+@dots{} @samp{9}.  To define a local symbol, write a label of the form
+@samp{@b{N}:} (where @b{N} represents any digit).  To refer to the most
+recent previous definition of that symbol write @samp{@b{N}b}, using the
+same digit as when you defined the label.  To refer to the next
+definition of a local label, write @samp{@b{N}f}---where @b{N} gives you
+a choice of 10 forward references.  The @samp{b} stands for
+``backwards'' and the @samp{f} stands for ``forwards''.
+
+Local symbols are not emitted by the current @sc{gnu} C compiler.
+
+There is no restriction on how you can use these labels, but
+remember that at any point in the assembly you can refer to at most
+10 prior local labels and to at most 10 forward local labels.
+
+Local symbol names are only a notation device.  They are immediately
+transformed into more conventional symbol names before the assembler
+uses them.  The symbol names stored in the symbol table, appearing in
+error messages and optionally emitted to the object file have these
+parts:
+
+@table @code
+@item L
+All local labels begin with @samp{L}. Normally both @code{@value{AS}} and
+@code{@value{LD}} forget symbols that start with @samp{L}. These labels are
+used for symbols you are never intended to see.  If you use the
+@samp{-L} option then @code{@value{AS}} retains these symbols in the
+object file. If you also instruct @code{@value{LD}} to retain these symbols,
+you may use them in debugging.
+
+@item @var{digit}
+If the label is written @samp{0:} then the digit is @samp{0}.
+If the label is written @samp{1:} then the digit is @samp{1}.
+And so on up through @samp{9:}.
+
+@item @kbd{C-A}
+This unusual character is included so you do not accidentally invent
+a symbol of the same name.  The character has ASCII value
+@samp{\001}.
+
+@item @emph{ordinal number}
+This is a serial number to keep the labels distinct.  The first
+@samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the
+number @samp{15}; @emph{etc.}.  Likewise for the other labels @samp{1:}
+through @samp{9:}.
+@end table
+
+For instance, the first @code{1:} is named @code{L1@kbd{C-A}1}, the 44th
+@code{3:} is named @code{L3@kbd{C-A}44}.
+
+@node Dot
+@section The Special Dot Symbol
+
+@cindex dot (symbol)
+@cindex @code{.} (symbol)
+@cindex current address
+@cindex location counter
+The special symbol @samp{.} refers to the current address that
+@code{@value{AS}} is assembling into.  Thus, the expression @samp{melvin:
+.long .} defines @code{melvin} to contain its own address.
+Assigning a value to @code{.} is treated the same as a @code{.org}
+directive.  Thus, the expression @samp{.=.+4} is the same as saying
+@ifclear no-space-dir
+@samp{.space 4}.
+@end ifclear
+@ifset no-space-dir
+@ifset A29K
+@samp{.block 4}.
+@end ifset
+@end ifset
+
+@node Symbol Attributes
+@section Symbol Attributes
+
+@cindex symbol attributes
+@cindex attributes, symbol
+Every symbol has, as well as its name, the attributes ``Value'' and
+``Type''.  Depending on output format, symbols can also have auxiliary
+attributes.
+@ifset INTERNALS
+The detailed definitions are in @file{a.out.h}.
+@end ifset
+
+If you use a symbol without defining it, @code{@value{AS}} assumes zero for
+all these attributes, and probably won't warn you.  This makes the
+symbol an externally defined symbol, which is generally what you
+would want.
+
+@menu
+* Symbol Value::                Value
+* Symbol Type::                 Type
+@ifset aout-bout
+@ifset GENERIC
+* a.out Symbols::               Symbol Attributes: @code{a.out}
+@end ifset
+@ifclear GENERIC
+@ifclear BOUT
+* a.out Symbols::               Symbol Attributes: @code{a.out}
+@end ifclear
+@ifset BOUT
+* a.out Symbols::               Symbol Attributes: @code{a.out}, @code{b.out}
+@end ifset
+@end ifclear
+@end ifset
+@ifset COFF
+* COFF Symbols::                Symbol Attributes for COFF
+@end ifset
+@ifset SOM
+* SOM Symbols::                Symbol Attributes for SOM
+@end ifset
+@end menu
+
+@node Symbol Value
+@subsection Value
+
+@cindex value of a symbol
+@cindex symbol value
+The value of a symbol is (usually) 32 bits.  For a symbol which labels a
+location in the text, data, bss or absolute sections the value is the
+number of addresses from the start of that section to the label.
+Naturally for text, data and bss sections the value of a symbol changes
+as @code{@value{LD}} changes section base addresses during linking.  Absolute
+symbols' values do not change during linking: that is why they are
+called absolute.
+
+The value of an undefined symbol is treated in a special way.  If it is
+0 then the symbol is not defined in this assembler source file, and
+@code{@value{LD}} tries to determine its value from other files linked into the
+same program.  You make this kind of symbol simply by mentioning a symbol
+name without defining it.  A non-zero value represents a @code{.comm}
+common declaration.  The value is how much common storage to reserve, in
+bytes (addresses).  The symbol refers to the first address of the
+allocated storage.
+
+@node Symbol Type
+@subsection Type
+
+@cindex type of a symbol
+@cindex symbol type
+The type attribute of a symbol contains relocation (section)
+information, any flag settings indicating that a symbol is external, and
+(optionally), other information for linkers and debuggers.  The exact
+format depends on the object-code output format in use.
+
+@ifset aout-bout
+@ifclear GENERIC
+@ifset BOUT
+@c The following avoids a "widow" subsection title.  @group would be
+@c better if it were available outside examples.
+@need 1000
+@node a.out Symbols
+@subsection Symbol Attributes: @code{a.out}, @code{b.out}
+
+@cindex @code{b.out} symbol attributes
+@cindex symbol attributes, @code{b.out}
+These symbol attributes appear only when @code{@value{AS}} is configured for
+one of the Berkeley-descended object output formats---@code{a.out} or
+@code{b.out}.
+
+@end ifset
+@ifclear BOUT
+@node a.out Symbols
+@subsection Symbol Attributes: @code{a.out}
+
+@cindex @code{a.out} symbol attributes
+@cindex symbol attributes, @code{a.out}
+
+@end ifclear
+@end ifclear
+@ifset GENERIC
+@node a.out Symbols
+@subsection Symbol Attributes: @code{a.out}
+
+@cindex @code{a.out} symbol attributes
+@cindex symbol attributes, @code{a.out}
+
+@end ifset
+@menu
+* Symbol Desc::                 Descriptor
+* Symbol Other::                Other
+@end menu
+
+@node Symbol Desc
+@subsubsection Descriptor
+
+@cindex descriptor, of @code{a.out} symbol
+This is an arbitrary 16-bit value.  You may establish a symbol's
+descriptor value by using a @code{.desc} statement
+(@pxref{Desc,,@code{.desc}}).  A descriptor value means nothing to
+@code{@value{AS}}.
+
+@node Symbol Other
+@subsubsection Other
+
+@cindex other attribute, of @code{a.out} symbol
+This is an arbitrary 8-bit value.  It means nothing to @code{@value{AS}}.
+@end ifset
+
+@ifset COFF
+@node COFF Symbols
+@subsection Symbol Attributes for COFF
+
+@cindex COFF symbol attributes
+@cindex symbol attributes, COFF
+
+The COFF format supports a multitude of auxiliary symbol attributes;
+like the primary symbol attributes, they are set between @code{.def} and
+@code{.endef} directives.
+
+@subsubsection Primary Attributes
+
+@cindex primary attributes, COFF symbols
+The symbol name is set with @code{.def}; the value and type,
+respectively, with @code{.val} and @code{.type}.
+
+@subsubsection Auxiliary Attributes
+
+@cindex auxiliary attributes, COFF symbols
+The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
+@code{.size}, and @code{.tag} can generate auxiliary symbol table
+information for COFF.
+@end ifset
+
+@ifset SOM
+@node SOM Symbols
+@subsection Symbol Attributes for SOM
+
+@cindex SOM symbol attributes
+@cindex symbol attributes, SOM
+
+The SOM format for the HPPA supports a multitude of symbol attributes set with
+the @code{.EXPORT} and @code{.IMPORT} directives.
+
+The attributes are described in @cite{HP9000 Series 800 Assembly 
+Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
+@code{EXPORT} assembler directive documentation.
+@end ifset
+
+@node Expressions
+@chapter Expressions
+
+@cindex expressions
+@cindex addresses
+@cindex numeric values
+An @dfn{expression} specifies an address or numeric value.
+Whitespace may precede and/or follow an expression.
+
+The result of an expression must be an absolute number, or else an offset into
+a particular section.  If an expression is not absolute, and there is not
+enough information when @code{@value{AS}} sees the expression to know its
+section, a second pass over the source program might be necessary to interpret
+the expression---but the second pass is currently not implemented.
+@code{@value{AS}} aborts with an error message in this situation.
+
+@menu
+* Empty Exprs::                 Empty Expressions
+* Integer Exprs::               Integer Expressions
+@end menu
+
+@node Empty Exprs
+@section Empty Expressions
+
+@cindex empty expressions
+@cindex expressions, empty
+An empty expression has no value: it is just whitespace or null.
+Wherever an absolute expression is required, you may omit the
+expression, and @code{@value{AS}} assumes a value of (absolute) 0.  This
+is compatible with other assemblers.
+
+@node Integer Exprs
+@section Integer Expressions
+
+@cindex integer expressions
+@cindex expressions, integer
+An @dfn{integer expression} is one or more @emph{arguments} delimited
+by @emph{operators}.
+
+@menu
+* Arguments::                   Arguments
+* Operators::                   Operators
+* Prefix Ops::                  Prefix Operators
+* Infix Ops::                   Infix Operators
+@end menu
+
+@node Arguments
+@subsection Arguments
+
+@cindex expression arguments
+@cindex arguments in expressions
+@cindex operands in expressions
+@cindex arithmetic operands
+@dfn{Arguments} are symbols, numbers or subexpressions.  In other
+contexts arguments are sometimes called ``arithmetic operands''.  In
+this manual, to avoid confusing them with the ``instruction operands'' of
+the machine language, we use the term ``argument'' to refer to parts of
+expressions only, reserving the word ``operand'' to refer only to machine
+instruction operands.
+
+Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
+@var{section} is one of text, data, bss, absolute,
+or undefined.  @var{NNN} is a signed, 2's complement 32 bit
+integer.
+
+Numbers are usually integers.
+
+A number can be a flonum or bignum.  In this case, you are warned
+that only the low order 32 bits are used, and @code{@value{AS}} pretends
+these 32 bits are an integer.  You may write integer-manipulating
+instructions that act on exotic constants, compatible with other
+assemblers.
+
+@cindex subexpressions
+Subexpressions are a left parenthesis @samp{(} followed by an integer
+expression, followed by a right parenthesis @samp{)}; or a prefix
+operator followed by an argument.
+
+@node Operators
+@subsection Operators
+
+@cindex operators, in expressions
+@cindex arithmetic functions
+@cindex functions, in expressions
+@dfn{Operators} are arithmetic functions, like @code{+} or @code{%}.  Prefix
+operators are followed by an argument.  Infix operators appear
+between their arguments.  Operators may be preceded and/or followed by
+whitespace.
+
+@node Prefix Ops
+@subsection Prefix Operator
+
+@cindex prefix operators
+@code{@value{AS}} has the following @dfn{prefix operators}.  They each take
+one argument, which must be absolute.
+
+@c the tex/end tex stuff surrounding this small table is meant to make
+@c it align, on the printed page, with the similar table in the next
+@c section (which is inside an enumerate).
+@tex
+\global\advance\leftskip by \itemindent
+@end tex
+
+@table @code
+@item -
+@dfn{Negation}.  Two's complement negation.
+@item ~
+@dfn{Complementation}.  Bitwise not.
+@end table
+
+@tex
+\global\advance\leftskip by -\itemindent
+@end tex
+
+@node Infix Ops
+@subsection Infix Operators
+
+@cindex infix operators
+@cindex operators, permitted arguments
+@dfn{Infix operators} take two arguments, one on either side.  Operators
+have precedence, but operations with equal precedence are performed left
+to right.  Apart from @code{+} or @code{-}, both arguments must be
+absolute, and the result is absolute.
+
+@enumerate
+@cindex operator precedence
+@cindex precedence of operators
+
+@item
+Highest Precedence
+
+@table @code
+@item *
+@dfn{Multiplication}.
+
+@item /
+@dfn{Division}.  Truncation is the same as the C operator @samp{/}
+
+@item %
+@dfn{Remainder}.
+
+@item <
+@itemx <<
+@dfn{Shift Left}.  Same as the C operator @samp{<<}.
+
+@item >
+@itemx >>
+@dfn{Shift Right}.  Same as the C operator @samp{>>}.
+@end table
+
+@item
+Intermediate precedence
+
+@table @code
+@item |
+
+@dfn{Bitwise Inclusive Or}.
+
+@item &
+@dfn{Bitwise And}.
+
+@item ^
+@dfn{Bitwise Exclusive Or}.
+
+@item !
+@dfn{Bitwise Or Not}.
+@end table
+
+@item
+Lowest Precedence
+
+@table @code
+@cindex addition, permitted arguments
+@cindex plus, permitted arguments
+@cindex arguments for addition
+@item +
+@dfn{Addition}.  If either argument is absolute, the result has the section of
+the other argument.  You may not add together arguments from different
+sections.
+
+@cindex subtraction, permitted arguments
+@cindex minus, permitted arguments
+@cindex arguments for subtraction
+@item -
+@dfn{Subtraction}.  If the right argument is absolute, the
+result has the section of the left argument.
+If both arguments are in the same section, the result is absolute.
+You may not subtract arguments from different sections.
+@c FIXME is there still something useful to say about undefined - undefined ?
+@end table
+@end enumerate
+
+In short, it's only meaningful to add or subtract the @emph{offsets} in an
+address; you can only have a defined section in one of the two arguments.
+
+@node Pseudo Ops
+@chapter Assembler Directives
+
+@cindex directives, machine independent
+@cindex pseudo-ops, machine independent
+@cindex machine independent directives
+All assembler directives have names that begin with a period (@samp{.}).
+The rest of the name is letters, usually in lower case.
+
+This chapter discusses directives that are available regardless of the
+target machine configuration for the @sc{gnu} assembler.
+@ifset GENERIC
+Some machine configurations provide additional directives.
+@xref{Machine Dependencies}.
+@end ifset
+@ifclear GENERIC
+@ifset machine-directives
+@xref{Machine Dependencies} for additional directives.
+@end ifset
+@end ifclear
+
+@menu
+* Abort::                       @code{.abort}
+@ifset COFF
+* ABORT::                       @code{.ABORT}
+@end ifset
+
+* Align::                       @code{.align @var{abs-expr} , @var{abs-expr}}
+* Ascii::                       @code{.ascii "@var{string}"}@dots{}
+* Asciz::                       @code{.asciz "@var{string}"}@dots{}
+* Balign::                      @code{.balign @var{abs-expr} , @var{abs-expr}}
+* Byte::                        @code{.byte @var{expressions}}
+* Comm::                        @code{.comm @var{symbol} , @var{length} }
+* Data::                        @code{.data @var{subsection}}
+@ifset COFF
+* Def::                         @code{.def @var{name}}
+@end ifset
+@ifset aout-bout
+* Desc::                        @code{.desc @var{symbol}, @var{abs-expression}}
+@end ifset
+@ifset COFF
+* Dim::                         @code{.dim}
+@end ifset
+
+* Double::                      @code{.double @var{flonums}}
+* Eject::                       @code{.eject}
+* Else::                        @code{.else}
+* End::				@code{.end}
+@ifset COFF
+* Endef::                       @code{.endef}
+@end ifset
+
+* Endfunc::                     @code{.endfunc}
+* Endif::                       @code{.endif}
+* Equ::                         @code{.equ @var{symbol}, @var{expression}}
+* Equiv::                       @code{.equiv @var{symbol}, @var{expression}}
+* Err::				@code{.err}
+* Exitm::			@code{.exitm}
+* Extern::                      @code{.extern}
+* Fail::			@code{.fail}
+@ifclear no-file-dir
+* File::                        @code{.file @var{string}}
+@end ifclear
+
+* Fill::                        @code{.fill @var{repeat} , @var{size} , @var{value}}
+* Float::                       @code{.float @var{flonums}}
+* Func::                        @code{.func}  
+* Global::                      @code{.global @var{symbol}}, @code{.globl @var{symbol}}
+* hword::                       @code{.hword @var{expressions}}
+* Ident::                       @code{.ident}
+* If::                          @code{.if @var{absolute expression}}
+* Include::                     @code{.include "@var{file}"}
+* Int::                         @code{.int @var{expressions}}
+* Irp::				@code{.irp @var{symbol},@var{values}}@dots{}
+* Irpc::			@code{.irpc @var{symbol},@var{values}}@dots{}
+* Lcomm::                       @code{.lcomm @var{symbol} , @var{length}}
+* Lflags::                      @code{.lflags}
+@ifclear no-line-dir
+* Line::                        @code{.line @var{line-number}}
+@end ifclear
+
+* Ln::                          @code{.ln @var{line-number}}
+* Linkonce::			@code{.linkonce [@var{type}]}
+* List::                        @code{.list}
+* Long::                        @code{.long @var{expressions}}
+@ignore
+* Lsym::                        @code{.lsym @var{symbol}, @var{expression}}
+@end ignore
+
+* Macro::			@code{.macro @var{name} @var{args}}@dots{}
+* MRI::				@code{.mri @var{val}}
+
+* Nolist::                      @code{.nolist}
+* Octa::                        @code{.octa @var{bignums}}
+* Org::                         @code{.org @var{new-lc} , @var{fill}}
+* P2align::                     @code{.p2align @var{abs-expr} , @var{abs-expr}}
+* Print::			@code{.print @var{string}}
+* Psize::                       @code{.psize @var{lines}, @var{columns}}
+* Purgem::			@code{.purgem @var{name}}
+* Quad::                        @code{.quad @var{bignums}}
+* Rept::			@code{.rept @var{count}}
+* Sbttl::                       @code{.sbttl "@var{subheading}"}
+@ifset COFF
+* Scl::                         @code{.scl @var{class}}
+* Section::                     @code{.section @var{name}, @var{subsection}}
+@end ifset
+
+* Set::                         @code{.set @var{symbol}, @var{expression}}
+* Short::                       @code{.short @var{expressions}}
+* Single::                      @code{.single @var{flonums}}
+@ifset COFF
+* Size::                        @code{.size}
+@end ifset
+
+* Skip::                        @code{.skip @var{size} , @var{fill}}
+* Sleb128::			@code{.sleb128 @var{expressions}}
+* Space::                       @code{.space @var{size} , @var{fill}}
+@ifset have-stabs
+* Stab::                        @code{.stabd, .stabn, .stabs}
+@end ifset
+
+* String::                      @code{.string "@var{str}"}
+* Struct::			@code{.struct @var{expression}}
+@ifset ELF
+* Symver::                      @code{.symver @var{name},@var{name2@@nodename}}
+@end ifset
+@ifset COFF
+* Tag::                         @code{.tag @var{structname}}
+@end ifset
+
+* Text::                        @code{.text @var{subsection}}
+* Title::                       @code{.title "@var{heading}"}
+@ifset COFF
+* Type::                        @code{.type @var{int}}
+* Val::                         @code{.val @var{addr}}
+@end ifset
+
+* Uleb128::                     @code{.uleb128 @var{expressions}}
+* Word::                        @code{.word @var{expressions}}
+* Deprecated::                  Deprecated Directives
+@end menu
+
+@node Abort
+@section @code{.abort}
+
+@cindex @code{abort} directive
+@cindex stopping the assembly
+This directive stops the assembly immediately.  It is for
+compatibility with other assemblers.  The original idea was that the
+assembly language source would be piped into the assembler.  If the sender
+of the source quit, it could use this directive tells @code{@value{AS}} to
+quit also.  One day @code{.abort} will not be supported.
+
+@ifset COFF
+@node ABORT
+@section @code{.ABORT}
+
+@cindex @code{ABORT} directive
+When producing COFF output, @code{@value{AS}} accepts this directive as a
+synonym for @samp{.abort}.
+
+@ifset BOUT
+When producing @code{b.out} output, @code{@value{AS}} accepts this directive,
+but ignores it.
+@end ifset
+@end ifset
+
+@node Align
+@section @code{.align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
+
+@cindex padding the location counter
+@cindex @code{align} directive
+Pad the location counter (in the current subsection) to a particular storage
+boundary.  The first expression (which must be absolute) is the alignment
+required, as described below.
+
+The second expression (also absolute) gives the fill value to be stored in the
+padding bytes.  It (and the comma) may be omitted.  If it is omitted, the
+padding bytes are normally zero.  However, on some systems, if the section is
+marked as containing code and the fill value is omitted, the space is filled
+with no-op instructions.
+
+The third expression is also absolute, and is also optional.  If it is present,
+it is the maximum number of bytes that should be skipped by this alignment
+directive.  If doing the alignment would require skipping more bytes than the
+specified maximum, then the alignment is not done at all.  You can omit the
+fill value (the second argument) entirely by simply using two commas after the
+required alignment; this can be useful if you want the alignment to be filled
+with no-op instructions when appropriate.
+
+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
+format,
+the first expression is the
+alignment request in bytes.  For example @samp{.align 8} advances
+the location counter until it is a multiple of 8.  If the location counter
+is already a multiple of 8, no change is needed.
+
+For other systems, including the i386 using a.out format, it is the
+number of low-order zero bits the location counter must have after
+advancement.  For example @samp{.align 3} advances the location
+counter until it a multiple of 8.  If the location counter is already a
+multiple of 8, no change is needed.
+
+This inconsistency is due to the different behaviors of the various
+native assemblers for these systems which GAS must emulate.
+GAS also provides @code{.balign} and @code{.p2align} directives,
+described later, which have a consistent behavior across all
+architectures (but are specific to GAS).
+
+@node Ascii
+@section @code{.ascii "@var{string}"}@dots{}
+
+@cindex @code{ascii} directive
+@cindex string literals
+@code{.ascii} expects zero or more string literals (@pxref{Strings})
+separated by commas.  It assembles each string (with no automatic
+trailing zero byte) into consecutive addresses.
+
+@node Asciz
+@section @code{.asciz "@var{string}"}@dots{}
+
+@cindex @code{asciz} directive
+@cindex zero-terminated strings
+@cindex null-terminated strings
+@code{.asciz} is just like @code{.ascii}, but each string is followed by
+a zero byte.  The ``z'' in @samp{.asciz} stands for ``zero''.
+
+@node Balign
+@section @code{.balign[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
+
+@cindex padding the location counter given number of bytes
+@cindex @code{balign} directive
+Pad the location counter (in the current subsection) to a particular
+storage boundary.  The first expression (which must be absolute) is the
+alignment request in bytes.  For example @samp{.balign 8} advances
+the location counter until it is a multiple of 8.  If the location counter
+is already a multiple of 8, no change is needed.
+
+The second expression (also absolute) gives the fill value to be stored in the
+padding bytes.  It (and the comma) may be omitted.  If it is omitted, the
+padding bytes are normally zero.  However, on some systems, if the section is
+marked as containing code and the fill value is omitted, the space is filled
+with no-op instructions.
+
+The third expression is also absolute, and is also optional.  If it is present,
+it is the maximum number of bytes that should be skipped by this alignment
+directive.  If doing the alignment would require skipping more bytes than the
+specified maximum, then the alignment is not done at all.  You can omit the
+fill value (the second argument) entirely by simply using two commas after the
+required alignment; this can be useful if you want the alignment to be filled
+with no-op instructions when appropriate.
+
+@cindex @code{balignw} directive
+@cindex @code{balignl} directive
+The @code{.balignw} and @code{.balignl} directives are variants of the
+@code{.balign} directive.  The @code{.balignw} directive treats the fill
+pattern as a two byte word value.  The @code{.balignl} directives treats the
+fill pattern as a four byte longword value.  For example, @code{.balignw
+4,0x368d} will align to a multiple of 4.  If it skips two bytes, they will be
+filled in with the value 0x368d (the exact placement of the bytes depends upon
+the endianness of the processor).  If it skips 1 or 3 bytes, the fill value is
+undefined.
+
+@node Byte
+@section @code{.byte @var{expressions}}
+
+@cindex @code{byte} directive
+@cindex integers, one byte
+@code{.byte} expects zero or more expressions, separated by commas.
+Each expression is assembled into the next byte.
+
+@node Comm
+@section @code{.comm @var{symbol} , @var{length} }
+
+@cindex @code{comm} directive
+@cindex symbol, common
+@code{.comm} declares a common symbol named @var{symbol}.  When linking, a
+common symbol in one object file may be merged with a defined or common symbol
+of the same name in another object file.  If @code{@value{LD}} does not see a
+definition for the symbol--just one or more common symbols--then it will
+allocate @var{length} bytes of uninitialized memory.  @var{length} must be an
+absolute expression.  If @code{@value{LD}} sees multiple common symbols with
+the same name, and they do not all have the same size, it will allocate space
+using the largest size.
+
+@ifset ELF
+When using ELF, the @code{.comm} directive takes an optional third argument.
+This is the desired alignment of the symbol, specified as a byte boundary (for
+example, an alignment of 16 means that the least significant 4 bits of the
+address should be zero).  The alignment must be an absolute expression, and it
+must be a power of two.  If @code{@value{LD}} allocates uninitialized memory
+for the common symbol, it will use the alignment when placing the symbol.  If
+no alignment is specified, @code{@value{AS}} will set the alignment to the
+largest power of two less than or equal to the size of the symbol, up to a
+maximum of 16.
+@end ifset
+
+@ifset HPPA
+The syntax for @code{.comm} differs slightly on the HPPA.  The syntax is
+@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
+@end ifset
+
+@node Data
+@section @code{.data @var{subsection}}
+
+@cindex @code{data} directive
+@code{.data} tells @code{@value{AS}} to assemble the following statements onto the
+end of the data subsection numbered @var{subsection} (which is an
+absolute expression).  If @var{subsection} is omitted, it defaults
+to zero.
+
+@ifset COFF
+@node Def
+@section @code{.def @var{name}}
+
+@cindex @code{def} directive
+@cindex COFF symbols, debugging
+@cindex debugging COFF symbols
+Begin defining debugging information for a symbol @var{name}; the
+definition extends until the @code{.endef} directive is encountered.
+@ifset BOUT
+
+This directive is only observed when @code{@value{AS}} is configured for COFF
+format output; when producing @code{b.out}, @samp{.def} is recognized,
+but ignored.
+@end ifset
+@end ifset
+
+@ifset aout-bout
+@node Desc
+@section @code{.desc @var{symbol}, @var{abs-expression}}
+
+@cindex @code{desc} directive
+@cindex COFF symbol descriptor
+@cindex symbol descriptor, COFF
+This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
+to the low 16 bits of an absolute expression.
+
+@ifset COFF
+The @samp{.desc} directive is not available when @code{@value{AS}} is
+configured for COFF output; it is only for @code{a.out} or @code{b.out}
+object format.  For the sake of compatibility, @code{@value{AS}} accepts
+it, but produces no output, when configured for COFF.
+@end ifset
+@end ifset
+
+@ifset COFF
+@node Dim
+@section @code{.dim}
+
+@cindex @code{dim} directive
+@cindex COFF auxiliary symbol information
+@cindex auxiliary symbol information, COFF
+This directive is generated by compilers to include auxiliary debugging
+information in the symbol table.  It is only permitted inside
+@code{.def}/@code{.endef} pairs.
+@ifset BOUT
+
+@samp{.dim} is only meaningful when generating COFF format output; when
+@code{@value{AS}} is generating @code{b.out}, it accepts this directive but
+ignores it.
+@end ifset
+@end ifset
+
+@node Double
+@section @code{.double @var{flonums}}
+
+@cindex @code{double} directive
+@cindex floating point numbers (double)
+@code{.double} expects zero or more flonums, separated by commas.  It
+assembles floating point numbers.
+@ifset GENERIC
+The exact kind of floating point numbers emitted depends on how
+@code{@value{AS}} is configured.  @xref{Machine Dependencies}.
+@end ifset
+@ifclear GENERIC
+@ifset IEEEFLOAT
+On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers
+in @sc{ieee} format.
+@end ifset
+@end ifclear
+
+@node Eject
+@section @code{.eject}
+
+@cindex @code{eject} directive
+@cindex new page, in listings
+@cindex page, in listings
+@cindex listing control: new page
+Force a page break at this point, when generating assembly listings.
+
+@node Else
+@section @code{.else}
+
+@cindex @code{else} directive
+@code{.else} is part of the @code{@value{AS}} support for conditional
+assembly; @pxref{If,,@code{.if}}.  It marks the beginning of a section
+of code to be assembled if the condition for the preceding @code{.if}
+was false.
+
+@node End
+@section @code{.end}
+
+@cindex @code{end} directive
+@code{.end} marks the end of the assembly file.  @code{@value{AS}} does not
+process anything in the file past the @code{.end} directive.
+
+@ifset COFF
+@node Endef
+@section @code{.endef}
+
+@cindex @code{endef} directive
+This directive flags the end of a symbol definition begun with
+@code{.def}.
+@ifset BOUT
+
+@samp{.endef} is only meaningful when generating COFF format output; if
+@code{@value{AS}} is configured to generate @code{b.out}, it accepts this
+directive but ignores it.
+@end ifset
+@end ifset
+
+@node Endfunc
+@section @code{.endfunc}
+@cindex @code{endfunc} directive
+@code{.endfunc} marks the end of a function specified with @code{.func}.
+
+@node Endif
+@section @code{.endif}
+
+@cindex @code{endif} directive
+@code{.endif} is part of the @code{@value{AS}} support for conditional assembly;
+it marks the end of a block of code that is only assembled
+conditionally.  @xref{If,,@code{.if}}.
+
+@node Equ
+@section @code{.equ @var{symbol}, @var{expression}}
+
+@cindex @code{equ} directive
+@cindex assigning values to symbols
+@cindex symbols, assigning values to
+This directive sets the value of @var{symbol} to @var{expression}.
+It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
+
+@ifset HPPA
+The syntax for @code{equ} on the HPPA is 
+@samp{@var{symbol} .equ @var{expression}}.
+@end ifset
+
+@node Equiv
+@section @code{.equiv @var{symbol}, @var{expression}}
+@cindex @code{equiv} directive
+The @code{.equiv} directive is like @code{.equ} and @code{.set}, except that
+the assembler will signal an error if @var{symbol} is already defined.
+
+Except for the contents of the error message, this is roughly equivalent to 
+@smallexample
+.ifdef SYM
+.err
+.endif
+.equ SYM,VAL
+@end smallexample
+
+@node Err
+@section @code{.err}
+@cindex @code{err} directive
+If @code{@value{AS}} assembles a @code{.err} directive, it will print an error
+message and, unless the @code{-Z} option was used, it will not generate an
+object file.  This can be used to signal error an conditionally compiled code.
+
+@node Exitm
+@section @code{.exitm}
+Exit early from the current macro definition.  @xref{Macro}.
+
+@node Extern
+@section @code{.extern}
+
+@cindex @code{extern} directive
+@code{.extern} is accepted in the source program---for compatibility
+with other assemblers---but it is ignored.  @code{@value{AS}} treats
+all undefined symbols as external.
+
+@node Fail
+@section @code{.fail @var{expression}}
+
+@cindex @code{fail} directive
+Generates an error or a warning.  If the value of the @var{expression} is 500
+or more, @code{@value{AS}} will print a warning message.  If the value is less
+than 500, @code{@value{AS}} will print an error message.  The message will
+include the value of @var{expression}.  This can occasionally be useful inside
+complex nested macros or conditional assembly.
+
+@ifclear no-file-dir
+@node File
+@section @code{.file @var{string}}
+
+@cindex @code{file} directive
+@cindex logical file name
+@cindex file name, logical
+@code{.file} tells @code{@value{AS}} that we are about to start a new logical
+file.  @var{string} is the new file name.  In general, the filename is
+recognized whether or not it is surrounded by quotes @samp{"}; but if you wish
+to specify an empty file name, you must give the quotes--@code{""}.  This
+statement may go away in future: it is only recognized to be compatible with
+old @code{@value{AS}} programs.
+@ifset A29K
+In some configurations of @code{@value{AS}}, @code{.file} has already been
+removed to avoid conflicts with other assemblers.  @xref{Machine Dependencies}.
+@end ifset
+@end ifclear
+
+@node Fill
+@section @code{.fill @var{repeat} , @var{size} , @var{value}}
+
+@cindex @code{fill} directive
+@cindex writing patterns in memory
+@cindex patterns, writing in memory
+@var{result}, @var{size} and @var{value} are absolute expressions.
+This emits @var{repeat} copies of @var{size} bytes.  @var{Repeat}
+may be zero or more.  @var{Size} may be zero or more, but if it is
+more than 8, then it is deemed to have the value 8, compatible with
+other people's assemblers.  The contents of each @var{repeat} bytes
+is taken from an 8-byte number.  The highest order 4 bytes are
+zero.  The lowest order 4 bytes are @var{value} rendered in the
+byte-order of an integer on the computer @code{@value{AS}} is assembling for.
+Each @var{size} bytes in a repetition is taken from the lowest order
+@var{size} bytes of this number.  Again, this bizarre behavior is
+compatible with other people's assemblers.
+
+@var{size} and @var{value} are optional.
+If the second comma and @var{value} are absent, @var{value} is
+assumed zero.  If the first comma and following tokens are absent,
+@var{size} is assumed to be 1.
+
+@node Float
+@section @code{.float @var{flonums}}
+
+@cindex floating point numbers (single)
+@cindex @code{float} directive
+This directive assembles zero or more flonums, separated by commas.  It
+has the same effect as @code{.single}.
+@ifset GENERIC
+The exact kind of floating point numbers emitted depends on how
+@code{@value{AS}} is configured.
+@xref{Machine Dependencies}.
+@end ifset
+@ifclear GENERIC
+@ifset IEEEFLOAT
+On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers
+in @sc{ieee} format.
+@end ifset
+@end ifclear
+
+@node Func
+@section @code{.func @var{name}[,@var{label}]}
+@cindex @code{func} directive
+@code{.func} emits debugging information to denote function @var{name}, and
+is ignored unless the file is assembled with debugging enabled.
+Only @samp{--gstabs} is currently supported.
+@var{label} is the entry point of the function and if omitted @var{name}
+prepended with the @samp{leading char} is used.
+@samp{leading char} is usually @code{_} or nothing, depending on the target.
+All functions are currently defined to have @code{void} return type.
+The function must be terminated with @code{.endfunc}.
+
+@node Global
+@section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
+
+@cindex @code{global} directive
+@cindex symbol, making visible to linker
+@code{.global} makes the symbol visible to @code{@value{LD}}.  If you define
+@var{symbol} in your partial program, its value is made available to
+other partial programs that are linked with it.  Otherwise,
+@var{symbol} takes its attributes from a symbol of the same name
+from another file linked into the same program.
+
+Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
+compatibility with other assemblers.
+
+@ifset HPPA
+On the HPPA, @code{.global} is not always enough to make it accessible to other
+partial programs.  You may need the HPPA-only @code{.EXPORT} directive as well.
+@xref{HPPA Directives,, HPPA Assembler Directives}.
+@end ifset
+
+@node hword
+@section @code{.hword @var{expressions}}
+
+@cindex @code{hword} directive
+@cindex integers, 16-bit
+@cindex numbers, 16-bit
+@cindex sixteen bit integers
+This expects zero or more @var{expressions}, and emits
+a 16 bit number for each.
+
+@ifset GENERIC
+This directive is a synonym for @samp{.short}; depending on the target
+architecture, it may also be a synonym for @samp{.word}.
+@end ifset
+@ifclear GENERIC
+@ifset W32
+This directive is a synonym for @samp{.short}.
+@end ifset
+@ifset W16
+This directive is a synonym for both @samp{.short} and @samp{.word}.
+@end ifset
+@end ifclear
+
+@node Ident
+@section @code{.ident}
+
+@cindex @code{ident} directive
+This directive is used by some assemblers to place tags in object files.
+@code{@value{AS}} simply accepts the directive for source-file
+compatibility with such assemblers, but does not actually emit anything
+for it.
+
+@node If
+@section @code{.if @var{absolute expression}}
+
+@cindex conditional assembly
+@cindex @code{if} directive
+@code{.if} marks the beginning of a section of code which is only
+considered part of the source program being assembled if the argument
+(which must be an @var{absolute expression}) is non-zero.  The end of
+the conditional section of code must be marked by @code{.endif}
+(@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
+alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}).
+
+The following variants of @code{.if} are also supported:
+@table @code
+@cindex @code{ifdef} directive
+@item .ifdef @var{symbol}
+Assembles the following section of code if the specified @var{symbol}
+has been defined.
+
+@cindex @code{ifc} directive
+@item .ifc @var{string1},@var{string2}
+Assembles the following section of code if the two strings are the same.  The
+strings may be optionally quoted with single quotes.  If they are not quoted,
+the first string stops at the first comma, and the second string stops at the
+end of the line.  Strings which contain whitespace should be quoted.  The
+string comparison is case sensitive.
+
+@cindex @code{ifeq} directive
+@item .ifeq @var{absolute expression}
+Assembles the following section of code if the argument is zero.
+
+@cindex @code{ifeqs} directive
+@item .ifeqs @var{string1},@var{string2}
+Another form of @code{.ifc}.  The strings must be quoted using double quotes.
+
+@cindex @code{ifge} directive
+@item .ifge @var{absolute expression}
+Assembles the following section of code if the argument is greater than or
+equal to zero.
+
+@cindex @code{ifgt} directive
+@item .ifgt @var{absolute expression}
+Assembles the following section of code if the argument is greater than zero.
+
+@cindex @code{ifle} directive
+@item .ifle @var{absolute expression}
+Assembles the following section of code if the argument is less than or equal
+to zero.
+
+@cindex @code{iflt} directive
+@item .iflt @var{absolute expression}
+Assembles the following section of code if the argument is less than zero.
+
+@cindex @code{ifnc} directive
+@item .ifnc @var{string1},@var{string2}.
+Like @code{.ifc}, but the sense of the test is reversed: this assembles the
+following section of code if the two strings are not the same.
+
+@cindex @code{ifndef} directive
+@cindex @code{ifnotdef} directive
+@item .ifndef @var{symbol}
+@itemx .ifnotdef @var{symbol}
+Assembles the following section of code if the specified @var{symbol}
+has not been defined.  Both spelling variants are equivalent.
+
+@cindex @code{ifne} directive
+@item .ifne @var{absolute expression}
+Assembles the following section of code if the argument is not equal to zero
+(in other words, this is equivalent to @code{.if}).
+
+@cindex @code{ifnes} directive
+@item .ifnes @var{string1},@var{string2}
+Like @code{.ifeqs}, but the sense of the test is reversed: this assembles the
+following section of code if the two strings are not the same.
+@end table
+
+@node Include
+@section @code{.include "@var{file}"}
+
+@cindex @code{include} directive
+@cindex supporting files, including
+@cindex files, including
+This directive provides a way to include supporting files at specified
+points in your source program.  The code from @var{file} is assembled as
+if it followed the point of the @code{.include}; when the end of the
+included file is reached, assembly of the original file continues.  You
+can control the search paths used with the @samp{-I} command-line option
+(@pxref{Invoking,,Command-Line Options}).  Quotation marks are required
+around @var{file}.
+
+@node Int
+@section @code{.int @var{expressions}}
+
+@cindex @code{int} directive
+@cindex integers, 32-bit
+Expect zero or more @var{expressions}, of any section, separated by commas.
+For each expression, emit a number that, at run time, is the value of that
+expression.  The byte order and bit size of the number depends on what kind
+of target the assembly is for.
+
+@ifclear GENERIC
+@ifset H8
+On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit
+integers.  On the H8/300H and the Hitachi SH, however, @code{.int} emits
+32-bit integers.
+@end ifset
+@end ifclear
+
+@node Irp
+@section @code{.irp @var{symbol},@var{values}}@dots{}
+
+@cindex @code{irp} directive
+Evaluate a sequence of statements assigning different values to @var{symbol}.
+The sequence of statements starts at the @code{.irp} directive, and is
+terminated by an @code{.endr} directive.  For each @var{value}, @var{symbol} is
+set to @var{value}, and the sequence of statements is assembled.  If no
+@var{value} is listed, the sequence of statements is assembled once, with
+@var{symbol} set to the null string.  To refer to @var{symbol} within the
+sequence of statements, use @var{\symbol}.
+
+For example, assembling
+
+@example
+        .irp    param,1,2,3
+        move    d\param,sp@@-
+        .endr
+@end example
+
+is equivalent to assembling
+
+@example
+        move    d1,sp@@-
+        move    d2,sp@@-
+        move    d3,sp@@-
+@end example
+
+@node Irpc
+@section @code{.irpc @var{symbol},@var{values}}@dots{}
+
+@cindex @code{irpc} directive
+Evaluate a sequence of statements assigning different values to @var{symbol}.
+The sequence of statements starts at the @code{.irpc} directive, and is
+terminated by an @code{.endr} directive.  For each character in @var{value},
+@var{symbol} is set to the character, and the sequence of statements is
+assembled.  If no @var{value} is listed, the sequence of statements is
+assembled once, with @var{symbol} set to the null string.  To refer to
+@var{symbol} within the sequence of statements, use @var{\symbol}.
+
+For example, assembling
+
+@example
+        .irpc    param,123
+        move    d\param,sp@@-
+        .endr
+@end example
+
+is equivalent to assembling
+
+@example
+        move    d1,sp@@-
+        move    d2,sp@@-
+        move    d3,sp@@-
+@end example
+
+@node Lcomm
+@section @code{.lcomm @var{symbol} , @var{length}}
+
+@cindex @code{lcomm} directive
+@cindex local common symbols
+@cindex symbols, local common
+Reserve @var{length} (an absolute expression) bytes for a local common
+denoted by @var{symbol}.  The section and value of @var{symbol} are
+those of the new local common.  The addresses are allocated in the bss
+section, so that at run-time the bytes start off zeroed.  @var{Symbol}
+is not declared global (@pxref{Global,,@code{.global}}), so is normally
+not visible to @code{@value{LD}}.
+
+@ifset GENERIC
+Some targets permit a third argument to be used with @code{.lcomm}.  This
+argument specifies the desired alignment of the symbol in the bss section.
+@end ifset
+
+@ifset HPPA
+The syntax for @code{.lcomm} differs slightly on the HPPA.  The syntax is
+@samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
+@end ifset
+
+@node Lflags
+@section @code{.lflags}
+
+@cindex @code{lflags} directive (ignored)
+@code{@value{AS}} accepts this directive, for compatibility with other
+assemblers, but ignores it.
+
+@ifclear no-line-dir
+@node Line
+@section @code{.line @var{line-number}}
+
+@cindex @code{line} directive
+@end ifclear
+@ifset no-line-dir
+@node Ln
+@section @code{.ln @var{line-number}}
+
+@cindex @code{ln} directive
+@end ifset
+@cindex logical line number
+@ifset aout-bout
+Change the logical line number.  @var{line-number} must be an absolute
+expression.  The next line has that logical line number.  Therefore any other
+statements on the current line (after a statement separator character) are
+reported as on logical line number @var{line-number} @minus{} 1.  One day
+@code{@value{AS}} will no longer support this directive: it is recognized only
+for compatibility with existing assembler programs.
+
+@ifset GENERIC
+@ifset A29K
+@emph{Warning:} In the AMD29K configuration of @value{AS}, this command is
+not available; use the synonym @code{.ln} in that context.
+@end ifset
+@end ifset
+@end ifset
+
+@ifclear no-line-dir
+Even though this is a directive associated with the @code{a.out} or
+@code{b.out} object-code formats, @code{@value{AS}} still recognizes it
+when producing COFF output, and treats @samp{.line} as though it
+were the COFF @samp{.ln} @emph{if} it is found outside a
+@code{.def}/@code{.endef} pair.
+
+Inside a @code{.def}, @samp{.line} is, instead, one of the directives
+used by compilers to generate auxiliary symbol information for
+debugging.
+@end ifclear
+
+@node Linkonce
+@section @code{.linkonce [@var{type}]}
+@cindex COMDAT
+@cindex @code{linkonce} directive
+@cindex common sections
+Mark the current section so that the linker only includes a single copy of it.
+This may be used to include the same section in several different object files,
+but ensure that the linker will only include it once in the final output file.
+The @code{.linkonce} pseudo-op must be used for each instance of the section.
+Duplicate sections are detected based on the section name, so it should be
+unique.
+
+This directive is only supported by a few object file formats; as of this
+writing, the only object file format which supports it is the Portable
+Executable format used on Windows NT.
+
+The @var{type} argument is optional.  If specified, it must be one of the
+following strings.  For example:
+@smallexample
+.linkonce same_size
+@end smallexample
+Not all types may be supported on all object file formats.
+
+@table @code
+@item discard
+Silently discard duplicate sections.  This is the default.
+
+@item one_only
+Warn if there are duplicate sections, but still keep only one copy.
+
+@item same_size
+Warn if any of the duplicates have different sizes.
+
+@item same_contents
+Warn if any of the duplicates do not have exactly the same contents.
+@end table
+
+@node Ln
+@section @code{.ln @var{line-number}}
+
+@cindex @code{ln} directive
+@ifclear no-line-dir
+@samp{.ln} is a synonym for @samp{.line}.
+@end ifclear
+@ifset no-line-dir
+Tell @code{@value{AS}} to change the logical line number.  @var{line-number}
+must be an absolute expression.  The next line has that logical
+line number, so any other statements on the current line (after a
+statement separator character @code{;}) are reported as on logical
+line number @var{line-number} @minus{} 1.
+@ifset BOUT
+
+This directive is accepted, but ignored, when @code{@value{AS}} is
+configured for @code{b.out}; its effect is only associated with COFF
+output format.
+@end ifset
+@end ifset
+
+@node MRI
+@section @code{.mri @var{val}}
+
+@cindex @code{mri} directive
+@cindex MRI mode, temporarily
+If @var{val} is non-zero, this tells @code{@value{AS}} to enter MRI mode.  If
+@var{val} is zero, this tells @code{@value{AS}} to exit MRI mode.  This change
+affects code assembled until the next @code{.mri} directive, or until the end
+of the file.  @xref{M, MRI mode, MRI mode}.
+
+@node List
+@section @code{.list}
+
+@cindex @code{list} directive
+@cindex listing control, turning on
+Control (in conjunction with the @code{.nolist} directive) whether or
+not assembly listings are generated.  These two directives maintain an
+internal counter (which is zero initially).   @code{.list} increments the
+counter, and @code{.nolist} decrements it.  Assembly listings are
+generated whenever the counter is greater than zero.
+
+By default, listings are disabled.  When you enable them (with the
+@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
+the initial value of the listing counter is one.
+
+@node Long
+@section @code{.long @var{expressions}}
+
+@cindex @code{long} directive
+@code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
+
+@ignore
+@c no one seems to know what this is for or whether this description is
+@c what it really ought to do
+@node Lsym
+@section @code{.lsym @var{symbol}, @var{expression}}
+
+@cindex @code{lsym} directive
+@cindex symbol, not referenced in assembly
+@code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
+the hash table, ensuring it cannot be referenced by name during the
+rest of the assembly.  This sets the attributes of the symbol to be
+the same as the expression value:
+@smallexample
+@var{other} = @var{descriptor} = 0
+@var{type} = @r{(section of @var{expression})}
+@var{value} = @var{expression}
+@end smallexample
+@noindent
+The new symbol is not flagged as external.
+@end ignore
+
+@node Macro
+@section @code{.macro}
+
+@cindex macros
+The commands @code{.macro} and @code{.endm} allow you to define macros that
+generate assembly output.  For example, this definition specifies a macro
+@code{sum} that puts a sequence of numbers into memory:
+
+@example
+        .macro  sum from=0, to=5
+        .long   \from
+        .if     \to-\from
+        sum     "(\from+1)",\to
+        .endif
+        .endm
+@end example
+
+@noindent
+With that definition, @samp{SUM 0,5} is equivalent to this assembly input:
+
+@example
+        .long   0
+        .long   1
+        .long   2
+        .long   3
+        .long   4
+        .long   5
+@end example
+
+@ftable @code
+@item .macro @var{macname}
+@itemx .macro @var{macname} @var{macargs} @dots{}
+@cindex @code{macro} directive
+Begin the definition of a macro called @var{macname}.  If your macro
+definition requires arguments, specify their names after the macro name,
+separated by commas or spaces.  You can supply a default value for any
+macro argument by following the name with @samp{=@var{deflt}}.  For
+example, these are all valid @code{.macro} statements:
+
+@table @code
+@item .macro comm
+Begin the definition of a macro called @code{comm}, which takes no
+arguments.
+
+@item .macro plus1 p, p1
+@itemx .macro plus1 p p1
+Either statement begins the definition of a macro called @code{plus1},
+which takes two arguments; within the macro definition, write
+@samp{\p} or @samp{\p1} to evaluate the arguments.
+
+@item .macro reserve_str p1=0 p2
+Begin the definition of a macro called @code{reserve_str}, with two
+arguments.  The first argument has a default value, but not the second.
+After the definition is complete, you can call the macro either as
+@samp{reserve_str @var{a},@var{b}} (with @samp{\p1} evaluating to
+@var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str
+,@var{b}} (with @samp{\p1} evaluating as the default, in this case
+@samp{0}, and @samp{\p2} evaluating to @var{b}).
+@end table
+
+When you call a macro, you can specify the argument values either by
+position, or by keyword.  For example, @samp{sum 9,17} is equivalent to
+@samp{sum to=17, from=9}.
+
+@item .endm
+@cindex @code{endm} directive
+Mark the end of a macro definition.
+
+@item .exitm
+@cindex @code{exitm} directive
+Exit early from the current macro definition.
+
+@cindex number of macros executed
+@cindex macros, count executed
+@item \@@
+@code{@value{AS}} maintains a counter of how many macros it has
+executed in this pseudo-variable; you can copy that number to your
+output with @samp{\@@}, but @emph{only within a macro definition}.
+
+@ignore
+@item LOCAL @var{name} [ , @dots{} ]
+@emph{Warning: @code{LOCAL} is only available if you select ``alternate
+macro syntax'' with @samp{-a} or @samp{--alternate}.}  @xref{Alternate,,
+Alternate macro syntax}.
+
+Generate a string replacement for each of the @var{name} arguments, and
+replace any instances of @var{name} in each macro expansion.  The
+replacement string is unique in the assembly, and different for each
+separate macro expansion.  @code{LOCAL} allows you to write macros that
+define symbols, without fear of conflict between separate macro expansions.
+@end ignore
+@end ftable
+
+@node Nolist
+@section @code{.nolist}
+
+@cindex @code{nolist} directive
+@cindex listing control, turning off
+Control (in conjunction with the @code{.list} directive) whether or
+not assembly listings are generated.  These two directives maintain an
+internal counter (which is zero initially).   @code{.list} increments the
+counter, and @code{.nolist} decrements it.  Assembly listings are
+generated whenever the counter is greater than zero.
+
+@node Octa
+@section @code{.octa @var{bignums}}
+
+@c FIXME: double size emitted for "octa" on i960, others?  Or warn?
+@cindex @code{octa} directive
+@cindex integer, 16-byte
+@cindex sixteen byte integer
+This directive expects zero or more bignums, separated by commas.  For each
+bignum, it emits a 16-byte integer.
+
+The term ``octa'' comes from contexts in which a ``word'' is two bytes;
+hence @emph{octa}-word for 16 bytes.
+
+@node Org
+@section @code{.org @var{new-lc} , @var{fill}}
+
+@cindex @code{org} directive
+@cindex location counter, advancing
+@cindex advancing location counter
+@cindex current address, advancing
+Advance the location counter of the current section to
+@var{new-lc}.  @var{new-lc} is either an absolute expression or an
+expression with the same section as the current subsection.  That is,
+you can't use @code{.org} to cross sections: if @var{new-lc} has the
+wrong section, the @code{.org} directive is ignored.  To be compatible
+with former assemblers, if the section of @var{new-lc} is absolute,
+@code{@value{AS}} issues a warning, then pretends the section of @var{new-lc}
+is the same as the current subsection.
+
+@code{.org} may only increase the location counter, or leave it
+unchanged; you cannot use @code{.org} to move the location counter
+backwards.
+
+@c double negative used below "not undefined" because this is a specific
+@c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
+@c section. doc@cygnus.com 18feb91
+Because @code{@value{AS}} tries to assemble programs in one pass, @var{new-lc}
+may not be undefined.  If you really detest this restriction we eagerly await
+a chance to share your improved assembler.
+
+Beware that the origin is relative to the start of the section, not
+to the start of the subsection.  This is compatible with other
+people's assemblers.
+
+When the location counter (of the current subsection) is advanced, the
+intervening bytes are filled with @var{fill} which should be an
+absolute expression.  If the comma and @var{fill} are omitted,
+@var{fill} defaults to zero.
+
+@node P2align
+@section @code{.p2align[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
+
+@cindex padding the location counter given a power of two
+@cindex @code{p2align} directive
+Pad the location counter (in the current subsection) to a particular
+storage boundary.  The first expression (which must be absolute) is the
+number of low-order zero bits the location counter must have after
+advancement.  For example @samp{.p2align 3} advances the location
+counter until it a multiple of 8.  If the location counter is already a
+multiple of 8, no change is needed.
+
+The second expression (also absolute) gives the fill value to be stored in the
+padding bytes.  It (and the comma) may be omitted.  If it is omitted, the
+padding bytes are normally zero.  However, on some systems, if the section is
+marked as containing code and the fill value is omitted, the space is filled
+with no-op instructions.
+
+The third expression is also absolute, and is also optional.  If it is present,
+it is the maximum number of bytes that should be skipped by this alignment
+directive.  If doing the alignment would require skipping more bytes than the
+specified maximum, then the alignment is not done at all.  You can omit the
+fill value (the second argument) entirely by simply using two commas after the
+required alignment; this can be useful if you want the alignment to be filled
+with no-op instructions when appropriate.
+
+@cindex @code{p2alignw} directive
+@cindex @code{p2alignl} directive
+The @code{.p2alignw} and @code{.p2alignl} directives are variants of the
+@code{.p2align} directive.  The @code{.p2alignw} directive treats the fill
+pattern as a two byte word value.  The @code{.p2alignl} directives treats the
+fill pattern as a four byte longword value.  For example, @code{.p2alignw
+2,0x368d} will align to a multiple of 4.  If it skips two bytes, they will be
+filled in with the value 0x368d (the exact placement of the bytes depends upon
+the endianness of the processor).  If it skips 1 or 3 bytes, the fill value is
+undefined.
+
+@node Print
+@section @code{.print @var{string}}
+
+@cindex @code{print} directive
+@code{@value{AS}} will print @var{string} on the standard output during
+assembly.  You must put @var{string} in double quotes.
+
+@node Psize
+@section @code{.psize @var{lines} , @var{columns}}
+
+@cindex @code{psize} directive
+@cindex listing control: paper size
+@cindex paper size, for listings
+Use this directive to declare the number of lines---and, optionally, the
+number of columns---to use for each page, when generating listings.
+
+If you do not use @code{.psize}, listings use a default line-count
+of 60.  You may omit the comma and @var{columns} specification; the
+default width is 200 columns.
+
+@code{@value{AS}} generates formfeeds whenever the specified number of
+lines is exceeded (or whenever you explicitly request one, using
+@code{.eject}).
+
+If you specify @var{lines} as @code{0}, no formfeeds are generated save
+those explicitly specified with @code{.eject}.
+
+@node Purgem
+@section @code{.purgem @var{name}}
+
+@cindex @code{purgem} directive
+Undefine the macro @var{name}, so that later uses of the string will not be
+expanded.  @xref{Macro}.
+
+@node Quad
+@section @code{.quad @var{bignums}}
+
+@cindex @code{quad} directive
+@code{.quad} expects zero or more bignums, separated by commas.  For
+each bignum, it emits
+@ifclear bignum-16
+an 8-byte integer.  If the bignum won't fit in 8 bytes, it prints a
+warning message; and just takes the lowest order 8 bytes of the bignum.
+@cindex eight-byte integer
+@cindex integer, 8-byte
+
+The term ``quad'' comes from contexts in which a ``word'' is two bytes;
+hence @emph{quad}-word for 8 bytes.
+@end ifclear
+@ifset bignum-16
+a 16-byte integer.  If the bignum won't fit in 16 bytes, it prints a
+warning message; and just takes the lowest order 16 bytes of the bignum.
+@cindex sixteen-byte integer
+@cindex integer, 16-byte
+@end ifset
+
+@node Rept
+@section @code{.rept @var{count}}
+
+@cindex @code{rept} directive
+Repeat the sequence of lines between the @code{.rept} directive and the next
+@code{.endr} directive @var{count} times.
+
+For example, assembling
+
+@example
+        .rept   3
+        .long   0
+        .endr
+@end example
+
+is equivalent to assembling
+
+@example
+        .long   0
+        .long   0
+        .long   0
+@end example
+
+@node Sbttl
+@section @code{.sbttl "@var{subheading}"}
+
+@cindex @code{sbttl} directive
+@cindex subtitles for listings
+@cindex listing control: subtitle
+Use @var{subheading} as the title (third line, immediately after the
+title line) when generating assembly listings.
+
+This directive affects subsequent pages, as well as the current page if
+it appears within ten lines of the top of a page.
+
+@ifset COFF
+@node Scl
+@section @code{.scl @var{class}}
+
+@cindex @code{scl} directive
+@cindex symbol storage class (COFF)
+@cindex COFF symbol storage class
+Set the storage-class value for a symbol.  This directive may only be
+used inside a @code{.def}/@code{.endef} pair.  Storage class may flag
+whether a symbol is static or external, or it may record further
+symbolic debugging information.
+@ifset BOUT
+
+The @samp{.scl} directive is primarily associated with COFF output; when
+configured to generate @code{b.out} output format, @code{@value{AS}}
+accepts this directive but ignores it.
+@end ifset
+@end ifset
+
+@node Section
+@section @code{.section @var{name}}
+
+@cindex @code{section} directive
+@cindex named section
+Use the @code{.section} directive to assemble the following code into a section
+named @var{name}.
+
+This directive is only supported for targets that actually support arbitrarily
+named sections; on @code{a.out} targets, for example, it is not accepted, even
+with a standard @code{a.out} section name.
+
+@ifset COFF
+For COFF targets, the @code{.section} directive is used in one of the following
+ways:
+@smallexample
+.section @var{name}[, "@var{flags}"]
+.section @var{name}[, @var{subsegment}]
+@end smallexample
+
+If the optional argument is quoted, it is taken as flags to use for the
+section.  Each flag is a single character.  The following flags are recognized:
+@table @code
+@item b
+bss section (uninitialized data)
+@item n
+section is not loaded
+@item w
+writable section
+@item d
+data section
+@item r
+read-only section
+@item x
+executable section
+@end table
+
+If no flags are specified, the default flags depend upon the section name.  If
+the section name is not recognized, the default will be for the section to be
+loaded and writable.
+
+If the optional argument to the @code{.section} directive is not quoted, it is
+taken as a subsegment number (@pxref{Sub-Sections}).
+@end ifset
+
+@ifset ELF
+For ELF targets, the @code{.section} directive is used like this:
+@smallexample
+.section @var{name}[, "@var{flags}"[, @@@var{type}]]
+@end smallexample
+The optional @var{flags} argument is a quoted string which may contain any
+combintion of the following characters:
+@table @code
+@item a
+section is allocatable
+@item w
+section is writable
+@item x
+section is executable
+@end table
+
+The optional @var{type} argument may contain one of the following constants:
+@table @code
+@item @@progbits
+section contains data
+@item @@nobits
+section does not contain data (i.e., section only occupies space)
+@end table
+
+If no flags are specified, the default flags depend upon the section name.  If
+the section name is not recognized, the default will be for the section to have
+none of the above flags: it will not be allocated in memory, nor writable, nor
+executable.  The section will contain data.
+
+For ELF targets, the assembler supports another type of @code{.section}
+directive for compatibility with the Solaris assembler:
+@smallexample
+.section "@var{name}"[, @var{flags}...]
+@end smallexample
+Note that the section name is quoted.  There may be a sequence of comma
+separated flags:
+@table @code
+@item #alloc
+section is allocatable
+@item #write
+section is writable
+@item #execinstr
+section is executable
+@end table
+@end ifset
+
+@node Set
+@section @code{.set @var{symbol}, @var{expression}}
+
+@cindex @code{set} directive
+@cindex symbol value, setting
+Set the value of @var{symbol} to @var{expression}.  This
+changes @var{symbol}'s value and type to conform to
+@var{expression}.  If @var{symbol} was flagged as external, it remains
+flagged (@pxref{Symbol Attributes}).
+
+You may @code{.set} a symbol many times in the same assembly.
+
+If you @code{.set} a global symbol, the value stored in the object
+file is the last value stored into it.
+
+@ifset HPPA
+The syntax for @code{set} on the HPPA is
+@samp{@var{symbol} .set @var{expression}}.
+@end ifset
+
+@node Short
+@section @code{.short @var{expressions}}
+
+@cindex @code{short} directive
+@ifset GENERIC
+@code{.short} is normally the same as @samp{.word}.
+@xref{Word,,@code{.word}}.
+
+In some configurations, however, @code{.short} and @code{.word} generate
+numbers of different lengths; @pxref{Machine Dependencies}.
+@end ifset
+@ifclear GENERIC
+@ifset W16
+@code{.short} is the same as @samp{.word}.  @xref{Word,,@code{.word}}.
+@end ifset
+@ifset W32
+This expects zero or more @var{expressions}, and emits
+a 16 bit number for each.
+@end ifset
+@end ifclear
+
+@node Single
+@section @code{.single @var{flonums}}
+
+@cindex @code{single} directive
+@cindex floating point numbers (single)
+This directive assembles zero or more flonums, separated by commas.  It
+has the same effect as @code{.float}.
+@ifset GENERIC
+The exact kind of floating point numbers emitted depends on how
+@code{@value{AS}} is configured.  @xref{Machine Dependencies}.
+@end ifset
+@ifclear GENERIC
+@ifset IEEEFLOAT
+On the @value{TARGET} family, @code{.single} emits 32-bit floating point
+numbers in @sc{ieee} format.
+@end ifset
+@end ifclear
+
+@ifset COFF
+@node Size
+@section @code{.size}
+
+@cindex @code{size} directive
+This directive is generated by compilers to include auxiliary debugging
+information in the symbol table.  It is only permitted inside
+@code{.def}/@code{.endef} pairs.
+@ifset BOUT
+
+@samp{.size} is only meaningful when generating COFF format output; when
+@code{@value{AS}} is generating @code{b.out}, it accepts this directive but
+ignores it.
+@end ifset
+@end ifset
+
+@node Sleb128
+@section @code{.sleb128 @var{expressions}}
+
+@cindex @code{sleb128} directive
+@var{sleb128} stands for ``signed little endian base 128.''  This is a 
+compact, variable length representation of numbers used by the DWARF
+symbolic debugging format.  @xref{Uleb128,@code{.uleb128}}.
+
+@ifclear no-space-dir
+@node Skip
+@section @code{.skip @var{size} , @var{fill}}
+
+@cindex @code{skip} directive
+@cindex filling memory
+This directive emits @var{size} bytes, each of value @var{fill}.  Both
+@var{size} and @var{fill} are absolute expressions.  If the comma and
+@var{fill} are omitted, @var{fill} is assumed to be zero.  This is the same as
+@samp{.space}.
+
+@node Space
+@section @code{.space @var{size} , @var{fill}}
+
+@cindex @code{space} directive
+@cindex filling memory
+This directive emits @var{size} bytes, each of value @var{fill}.  Both
+@var{size} and @var{fill} are absolute expressions.  If the comma
+and @var{fill} are omitted, @var{fill} is assumed to be zero.  This is the same
+as @samp{.skip}.
+
+@ifset HPPA
+@quotation
+@emph{Warning:} @code{.space} has a completely different meaning for HPPA
+targets; use @code{.block} as a substitute.  See @cite{HP9000 Series 800
+Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the
+@code{.space} directive.  @xref{HPPA Directives,,HPPA Assembler Directives},
+for a summary.
+@end quotation
+@end ifset
+@end ifclear
+
+@ifset A29K
+@ifclear GENERIC
+@node Space
+@section @code{.space}
+@cindex @code{space} directive
+@end ifclear
+On the AMD 29K, this directive is ignored; it is accepted for
+compatibility with other AMD 29K assemblers.
+
+@quotation
+@emph{Warning:} In most versions of the @sc{gnu} assembler, the directive
+@code{.space} has the effect of @code{.block}  @xref{Machine Dependencies}.
+@end quotation
+@end ifset
+
+@ifset have-stabs
+@node Stab
+@section @code{.stabd, .stabn, .stabs}
+
+@cindex symbolic debuggers, information for
+@cindex @code{stab@var{x}} directives
+There are three directives that begin @samp{.stab}.
+All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
+The symbols are not entered in the @code{@value{AS}} hash table: they
+cannot be referenced elsewhere in the source file.
+Up to five fields are required:
+
+@table @var
+@item string
+This is the symbol's name.  It may contain any character except
+@samp{\000}, so is more general than ordinary symbol names.  Some
+debuggers used to code arbitrarily complex structures into symbol names
+using this field.
+
+@item type
+An absolute expression.  The symbol's type is set to the low 8 bits of
+this expression.  Any bit pattern is permitted, but @code{@value{LD}}
+and debuggers choke on silly bit patterns.
+
+@item other
+An absolute expression.  The symbol's ``other'' attribute is set to the
+low 8 bits of this expression.
+
+@item desc
+An absolute expression.  The symbol's descriptor is set to the low 16
+bits of this expression.
+
+@item value
+An absolute expression which becomes the symbol's value.
+@end table
+
+If a warning is detected while reading a @code{.stabd}, @code{.stabn},
+or @code{.stabs} statement, the symbol has probably already been created;
+you get a half-formed symbol in your object file.  This is
+compatible with earlier assemblers!
+
+@table @code
+@cindex @code{stabd} directive
+@item .stabd @var{type} , @var{other} , @var{desc}
+
+The ``name'' of the symbol generated is not even an empty string.
+It is a null pointer, for compatibility.  Older assemblers used a
+null pointer so they didn't waste space in object files with empty
+strings.
+
+The symbol's value is set to the location counter,
+relocatably.  When your program is linked, the value of this symbol
+is the address of the location counter when the @code{.stabd} was
+assembled.
+
+@cindex @code{stabn} directive
+@item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
+The name of the symbol is set to the empty string @code{""}.
+
+@cindex @code{stabs} directive
+@item .stabs @var{string} ,  @var{type} , @var{other} , @var{desc} , @var{value}
+All five fields are specified.
+@end table
+@end ifset
+@c end     have-stabs
+
+@node String
+@section @code{.string} "@var{str}"
+
+@cindex string, copying to object file
+@cindex @code{string} directive
+
+Copy the characters in @var{str} to the object file.  You may specify more than
+one string to copy, separated by commas.  Unless otherwise specified for a
+particular machine, the assembler marks the end of each string with a 0 byte.
+You can use any of the escape sequences described in @ref{Strings,,Strings}.
+
+@node Struct
+@section @code{.struct @var{expression}}
+
+@cindex @code{struct} directive
+Switch to the absolute section, and set the section offset to @var{expression},
+which must be an absolute expression.  You might use this as follows:
+@smallexample
+        .struct 0
+field1:
+        .struct field1 + 4
+field2:
+        .struct field2 + 4
+field3:
+@end smallexample
+This would define the symbol @code{field1} to have the value 0, the symbol
+@code{field2} to have the value 4, and the symbol @code{field3} to have the
+value 8.  Assembly would be left in the absolute section, and you would need to
+use a @code{.section} directive of some sort to change to some other section
+before further assembly.
+
+@ifset ELF
+@node Symver
+@section @code{.symver}
+@cindex @code{symver} directive
+@cindex symbol versioning
+@cindex versions of symbols
+Use the @code{.symver} directive to bind symbols to specific version nodes
+within a source file.  This is only supported on ELF platforms, and is
+typically used when assembling files to be linked into a shared library.
+There are cases where it may make sense to use this in objects to be bound
+into an application itself so as to override a versioned symbol from a
+shared library.
+
+For ELF targets, the @code{.symver} directive is used like this:
+@smallexample
+.symver @var{name}, @var{name2@@nodename}
+@end smallexample
+In this case, the symbol @var{name} must exist and be defined within the file
+being assembled.  The @code{.versym} directive effectively creates a symbol
+alias with the name @var{name2@@nodename}, and in fact the main reason that we
+just don't try and create a regular alias is that the @var{@@} character isn't
+permitted in symbol names.  The @var{name2} part of the name is the actual name
+of the symbol by which it will be externally referenced.  The name @var{name}
+itself is merely a name of convenience that is used so that it is possible to
+have definitions for multiple versions of a function within a single source
+file, and so that the compiler can unambiguously know which version of a
+function is being mentioned.  The @var{nodename} portion of the alias should be
+the name of a node specified in the version script supplied to the linker when
+building a shared library.  If you are attempting to override a versioned
+symbol from a shared library, then @var{nodename} should correspond to the
+nodename of the symbol you are trying to override.
+@end ifset
+
+@ifset COFF
+@node Tag
+@section @code{.tag @var{structname}}
+
+@cindex COFF structure debugging
+@cindex structure debugging, COFF
+@cindex @code{tag} directive
+This directive is generated by compilers to include auxiliary debugging
+information in the symbol table.  It is only permitted inside
+@code{.def}/@code{.endef} pairs.  Tags are used to link structure
+definitions in the symbol table with instances of those structures.
+@ifset BOUT
+
+@samp{.tag} is only used when generating COFF format output; when
+@code{@value{AS}} is generating @code{b.out}, it accepts this directive but
+ignores it.
+@end ifset
+@end ifset
+
+@node Text
+@section @code{.text @var{subsection}}
+
+@cindex @code{text} directive
+Tells @code{@value{AS}} to assemble the following statements onto the end of
+the text subsection numbered @var{subsection}, which is an absolute
+expression.  If @var{subsection} is omitted, subsection number zero
+is used.
+
+@node Title
+@section @code{.title "@var{heading}"}
+
+@cindex @code{title} directive
+@cindex listing control: title line
+Use @var{heading} as the title (second line, immediately after the
+source file name and pagenumber) when generating assembly listings.
+
+This directive affects subsequent pages, as well as the current page if
+it appears within ten lines of the top of a page.
+
+@ifset COFF
+@node Type
+@section @code{.type @var{int}}
+
+@cindex COFF symbol type
+@cindex symbol type, COFF
+@cindex @code{type} directive
+This directive, permitted only within @code{.def}/@code{.endef} pairs,
+records the integer @var{int} as the type attribute of a symbol table entry.
+@ifset BOUT
+
+@samp{.type} is associated only with COFF format output; when
+@code{@value{AS}} is configured for @code{b.out} output, it accepts this
+directive but ignores it.
+@end ifset
+@end ifset
+
+@ifset COFF
+@node Val
+@section @code{.val @var{addr}}
+
+@cindex @code{val} directive
+@cindex COFF value attribute
+@cindex value attribute, COFF
+This directive, permitted only within @code{.def}/@code{.endef} pairs,
+records the address @var{addr} as the value attribute of a symbol table
+entry.
+@ifset BOUT
+
+@samp{.val} is used only for COFF output; when @code{@value{AS}} is
+configured for @code{b.out}, it accepts this directive but ignores it.
+@end ifset
+@end ifset
+
+@node Uleb128
+@section @code{.uleb128 @var{expressions}}
+
+@cindex @code{uleb128} directive
+@var{uleb128} stands for ``unsigned little endian base 128.''  This is a 
+compact, variable length representation of numbers used by the DWARF
+symbolic debugging format.  @xref{Sleb128,@code{.sleb128}}.
+
+@node Word
+@section @code{.word @var{expressions}}
+
+@cindex @code{word} directive
+This directive expects zero or more @var{expressions}, of any section,
+separated by commas.
+@ifclear GENERIC
+@ifset W32
+For each expression, @code{@value{AS}} emits a 32-bit number.
+@end ifset
+@ifset W16
+For each expression, @code{@value{AS}} emits a 16-bit number.
+@end ifset
+@end ifclear
+@ifset GENERIC
+
+The size of the number emitted, and its byte order,
+depend on what target computer the assembly is for.
+@end ifset
+
+@c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
+@c happen---32-bit addressability, period; no long/short jumps.
+@ifset DIFF-TBL-KLUGE
+@cindex difference tables altered
+@cindex altered difference tables
+@quotation
+@emph{Warning: Special Treatment to support Compilers}
+@end quotation
+
+@ifset GENERIC
+Machines with a 32-bit address space, but that do less than 32-bit
+addressing, require the following special treatment.  If the machine of
+interest to you does 32-bit addressing (or doesn't require it;
+@pxref{Machine Dependencies}), you can ignore this issue.
+
+@end ifset
+In order to assemble compiler output into something that works,
+@code{@value{AS}} occasionlly does strange things to @samp{.word} directives.
+Directives of the form @samp{.word sym1-sym2} are often emitted by
+compilers as part of jump tables.  Therefore, when @code{@value{AS}} assembles a
+directive of the form @samp{.word sym1-sym2}, and the difference between
+@code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}}
+creates a @dfn{secondary jump table}, immediately before the next label.
+This secondary jump table is preceded by a short-jump to the
+first byte after the secondary table.  This short-jump prevents the flow
+of control from accidentally falling into the new table.  Inside the
+table is a long-jump to @code{sym2}.  The original @samp{.word}
+contains @code{sym1} minus the address of the long-jump to
+@code{sym2}.
+
+If there were several occurrences of @samp{.word sym1-sym2} before the
+secondary jump table, all of them are adjusted.  If there was a
+@samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
+long-jump to @code{sym4} is included in the secondary jump table,
+and the @code{.word} directives are adjusted to contain @code{sym3}
+minus the address of the long-jump to @code{sym4}; and so on, for as many
+entries in the original jump table as necessary.
+
+@ifset INTERNALS
+@emph{This feature may be disabled by compiling @code{@value{AS}} with the
+@samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
+assembly language programmers.
+@end ifset
+@end ifset
+@c end     DIFF-TBL-KLUGE
+
+@node Deprecated
+@section Deprecated Directives
+
+@cindex deprecated directives
+@cindex obsolescent directives
+One day these directives won't work.
+They are included for compatibility with older assemblers.
+@table @t
+@item .abort
+@item .line
+@end table
+
+@ifset GENERIC
+@node Machine Dependencies
+@chapter Machine Dependent Features
+
+@cindex machine dependencies
+The machine instruction sets are (almost by definition) different on
+each machine where @code{@value{AS}} runs.  Floating point representations
+vary as well, and @code{@value{AS}} often supports a few additional
+directives or command-line options for compatibility with other
+assemblers on a particular platform.  Finally, some versions of
+@code{@value{AS}} support special pseudo-instructions for branch
+optimization.
+
+This chapter discusses most of these differences, though it does not
+include details on any machine's instruction set.  For details on that
+subject, see the hardware manufacturer's manual.
+
+@menu
+@ifset A29K
+* AMD29K-Dependent::            AMD 29K Dependent Features
+@end ifset
+@ifset ARC
+* ARC-Dependent::               ARC Dependent Features
+@end ifset
+@ifset ARM
+* ARM-Dependent::               ARM Dependent Features
+@end ifset
+@ifset D10V
+* D10V-Dependent::              D10V Dependent Features
+@end ifset
+@ifset D30V
+* D30V-Dependent::              D30V Dependent Features
+@end ifset
+@ifset H8/300
+* H8/300-Dependent::            Hitachi H8/300 Dependent Features
+@end ifset
+@ifset H8/500
+* H8/500-Dependent::            Hitachi H8/500 Dependent Features
+@end ifset
+@ifset HPPA
+* HPPA-Dependent::              HPPA Dependent Features
+@end ifset
+@ifset I80386
+* i386-Dependent::              Intel 80386 Dependent Features
+@end ifset
+@ifset I960
+* i960-Dependent::              Intel 80960 Dependent Features
+@end ifset
+@ifset M680X0
+* M68K-Dependent::              M680x0 Dependent Features
+@end ifset
+@ifset MIPS
+* MIPS-Dependent::              MIPS Dependent Features
+@end ifset
+@ifset SH
+* SH-Dependent::                Hitachi SH Dependent Features
+@end ifset
+@ifset SPARC
+* Sparc-Dependent::             SPARC Dependent Features
+@end ifset
+@ifset V850
+* V850-Dependent::              V850 Dependent Features
+@end ifset
+@ifset Z8000
+* Z8000-Dependent::             Z8000 Dependent Features
+@end ifset
+@ifset VAX
+* Vax-Dependent::               VAX Dependent Features
+@end ifset
+@end menu
+
+@lowersections
+@end ifset
+
+@c The following major nodes are *sections* in the GENERIC version, *chapters*
+@c in single-cpu versions.  This is mainly achieved by @lowersections.  There is a
+@c peculiarity: to preserve cross-references, there must be a node called
+@c "Machine Dependencies".  Hence the conditional nodenames in each
+@c major node below.  Node defaulting in makeinfo requires adjacency of
+@c node and sectioning commands; hence the repetition of @chapter BLAH
+@c in both conditional blocks.
+
+@ifset ARC
+@ifset GENERIC
+@page
+@node ARC-Dependent
+@chapter ARC Dependent Features
+@end ifset
+@ifclear GENERIC
+@node Machine Dependencies
+@chapter ARC Dependent Features
+@end ifclear
+
+@cindex ARC support
+@menu
+* ARC-Opts::                    Options
+* ARC-Float::                   Floating Point
+* ARC-Directives::              Sparc Machine Directives
+@end menu
+
+@node ARC-Opts
+@section Options
+
+@cindex options for ARC
+@cindex ARC options
+@cindex architectures, ARC
+@cindex ARC architectures
+The ARC chip family includes several successive levels (or other
+variants) of chip, using the same core instruction set, but including
+a few additional instructions at each level.
+
+By default, @code{@value{AS}} assumes the core instruction set (ARC
+base).  The @code{.cpu} pseudo-op is intended to be used to select
+the variant.
+
+@table @code
+@cindex @code{-mbig-endian} option (ARC)
+@cindex @code{-mlittle-endian} option (ARC)
+@cindex ARC big-endian output
+@cindex ARC little-endian output
+@cindex big-endian output, ARC
+@cindex little-endian output, ARC
+@item -mbig-endian
+@itemx -mlittle-endian
+Any @sc{arc} configuration of @code{@value{AS}} can select big-endian or
+little-endian output at run time (unlike most other @sc{gnu} development
+tools, which must be configured for one or the other).  Use
+@samp{-mbig-endian} to select big-endian output, and @samp{-mlittle-endian}
+for little-endian.
+@end table
+
+@node ARC-Float
+@section Floating Point
+
+@cindex floating point, ARC (@sc{ieee})
+@cindex ARC floating point (@sc{ieee})
+The ARC cpu family currently does not have hardware floating point
+support.  Software floating point support is provided by @code{GCC}
+and uses @sc{ieee} floating-point numbers.
+
+@node ARC-Directives
+@section ARC Machine Directives
+
+@cindex ARC machine directives
+@cindex machine directives, ARC
+The ARC version of @code{@value{AS}} supports the following additional
+machine directives:
+
+@table @code
+@item .cpu
+@cindex @code{cpu} directive, SPARC
+This must be followed by the desired cpu.
+The ARC is intended to be customizable, @code{.cpu} is used to
+select the desired variant [though currently there are none].
+
+@end table
+
+@end ifset
+
+@ifset A29K
+@include c-a29k.texi
+@end ifset
+
+@ifset ARM
+@include c-arm.texi
+@end ifset
+
+@ifset Hitachi-all
+@ifclear GENERIC
+@node Machine Dependencies
+@chapter Machine Dependent Features
+
+The machine instruction sets are different on each Hitachi chip family,
+and there are also some syntax differences among the families.  This
+chapter describes the specific @code{@value{AS}} features for each
+family.
+
+@menu
+* H8/300-Dependent::            Hitachi H8/300 Dependent Features
+* H8/500-Dependent::            Hitachi H8/500 Dependent Features
+* SH-Dependent::                Hitachi SH Dependent Features
+@end menu
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset D10V
+@include c-d10v.texi
+@end ifset
+
+@ifset D30V
+@include c-d30v.texi
+@end ifset
+
+@ifset H8/300
+@include c-h8300.texi
+@end ifset
+
+@ifset H8/500
+@include c-h8500.texi
+@end ifset
+
+@ifset HPPA
+@include c-hppa.texi
+@end ifset
+
+@ifset I80386
+@include c-i386.texi
+@end ifset
+
+@ifset I960
+@include c-i960.texi
+@end ifset
+
+
+@ifset M680X0
+@include c-m68k.texi
+@end ifset
+
+@ifset MIPS
+@include c-mips.texi
+@end ifset
+
+@ifset NS32K
+@include c-ns32k.texi
+@end ifset
+
+@ifset SH
+@include c-sh.texi
+@end ifset
+
+@ifset SPARC
+@include c-sparc.texi
+@end ifset
+
+@ifset Z8000
+@include c-z8k.texi
+@end ifset
+
+@ifset VAX
+@include c-vax.texi
+@end ifset
+
+@ifset V850
+@include c-v850.texi
+@end ifset
+
+@ifset GENERIC
+@c reverse effect of @down at top of generic Machine-Dep chapter
+@raisesections
+@end ifset
+
+@node Reporting Bugs
+@chapter Reporting Bugs
+@cindex bugs in assembler
+@cindex reporting bugs in assembler
+
+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 assembler 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@@gnu.org}.
+
+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
+it 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
+@chapter Acknowledgements
+
+If you have contributed to @code{@value{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 
+@c (January 1994), 
+the maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
+
+Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any
+more details?}
+
+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 @file{messages.c}, @file{input-file.c}, @file{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
+(@file{tc-mips.c}, @file{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 @code{.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. @code{jsr}), while synthetic instructions
+remained shrinkable (@code{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 @code{@value{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.
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@contents
+@bye
+@c Local Variables:
+@c fill-column: 79
+@c End: