aboutsummaryrefslogtreecommitdiff
path: root/gas/doc/as.texi
diff options
context:
space:
mode:
Diffstat (limited to 'gas/doc/as.texi')
-rw-r--r--gas/doc/as.texi8249
1 files changed, 8249 insertions, 0 deletions
diff --git a/gas/doc/as.texi b/gas/doc/as.texi
new file mode 100644
index 0000000..493049c
--- /dev/null
+++ b/gas/doc/as.texi
@@ -0,0 +1,8249 @@
+\input texinfo @c -*-Texinfo-*-
+@c Copyright (C) 1991-2018 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---
+@macro gcctabopt{body}
+@code{\body\}
+@end macro
+@c defaults, config file may override:
+@set have-stabs
+@c ---
+@c man begin NAME
+@c ---
+@include asconfig.texi
+@include bfdver.texi
+@c ---
+@c man end
+@c ---
+@c common OR combinations of conditions
+@ifset COFF
+@set COFF-ELF
+@end ifset
+@ifset ELF
+@set COFF-ELF
+@end ifset
+@ifset AOUT
+@set aout
+@end ifset
+@ifset ARM/Thumb
+@set ARM
+@end ifset
+@ifset Blackfin
+@set Blackfin
+@end ifset
+@ifset H8/300
+@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
+
+@ifnottex
+@dircategory Software development
+@direntry
+* As: (as). The GNU assembler.
+* Gas: (as). The GNU assembler.
+@end direntry
+@end ifnottex
+
+@finalout
+@syncodeindex ky cp
+
+@copying
+This file documents the GNU Assembler "@value{AS}".
+
+@c man begin COPYRIGHT
+Copyright @copyright{} 1991-2018 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts. A copy of the license is included in the
+section entitled ``GNU Free Documentation License''.
+
+@c man end
+@end copying
+
+@titlepage
+@title Using @value{AS}
+@subtitle The @sc{gnu} Assembler
+@ifclear GENERIC
+@subtitle for the @value{TARGET} family
+@end ifclear
+@ifset VERSION_PACKAGE
+@sp 1
+@subtitle @value{VERSION_PACKAGE}
+@end ifset
+@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 @command{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-2018 Free Software Foundation, Inc.
+
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.3
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, with no Front-Cover Texts, and with no
+ Back-Cover Texts. A copy of the license is included in the
+ section entitled ``GNU Free Documentation License''.
+
+@end titlepage
+@contents
+
+@ifnottex
+@node Top
+@top Using @value{AS}
+
+This file is a user guide to the @sc{gnu} assembler @command{@value{AS}}
+@ifset VERSION_PACKAGE
+@value{VERSION_PACKAGE}
+@end ifset
+version @value{VERSION}.
+@ifclear GENERIC
+This version of the file describes @command{@value{AS}} configured to generate
+code for @value{TARGET} architectures.
+@end ifclear
+
+This document is distributed under the terms of the GNU Free
+Documentation License. A copy of the license is included in the
+section entitled ``GNU Free Documentation License''.
+
+@menu
+* Overview:: Overview
+* Invoking:: Command-Line Options
+* Syntax:: Syntax
+* Sections:: Sections and Relocation
+* Symbols:: Symbols
+* Expressions:: Expressions
+* Pseudo Ops:: Assembler Directives
+@ifset ELF
+* Object Attributes:: Object Attributes
+@end ifset
+* Machine Dependencies:: Machine Dependent Features
+* Reporting Bugs:: Reporting Bugs
+* Acknowledgements:: Who Did What
+* GNU Free Documentation License:: GNU Free Documentation License
+* AS Index:: AS Index
+@end menu
+@end ifnottex
+
+@node Overview
+@chapter Overview
+@iftex
+This manual is a user guide to the @sc{gnu} assembler @command{@value{AS}}.
+@ifclear GENERIC
+This version of the manual describes @command{@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 @command{@value{AS}}. For details,
+see @ref{Invoking,,Command-Line Options}.
+
+@c man title AS the portable GNU assembler.
+
+@ignore
+@c man begin SEEALSO
+gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
+@c man end
+@end ignore
+
+@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
+@c man begin SYNOPSIS
+@value{AS} [@b{-a}[@b{cdghlns}][=@var{file}]] [@b{--alternate}] [@b{-D}]
+ [@b{--compress-debug-sections}] [@b{--nocompress-debug-sections}]
+ [@b{--debug-prefix-map} @var{old}=@var{new}]
+ [@b{--defsym} @var{sym}=@var{val}] [@b{-f}] [@b{-g}] [@b{--gstabs}]
+ [@b{--gstabs+}] [@b{--gdwarf-2}] [@b{--gdwarf-sections}]
+ [@b{--help}] [@b{-I} @var{dir}] [@b{-J}]
+ [@b{-K}] [@b{-L}] [@b{--listing-lhs-width}=@var{NUM}]
+ [@b{--listing-lhs-width2}=@var{NUM}] [@b{--listing-rhs-width}=@var{NUM}]
+ [@b{--listing-cont-lines}=@var{NUM}] [@b{--keep-locals}]
+ [@b{--no-pad-sections}]
+ [@b{-o} @var{objfile}] [@b{-R}]
+ [@b{--hash-size}=@var{NUM}] [@b{--reduce-memory-overheads}]
+ [@b{--statistics}]
+ [@b{-v}] [@b{-version}] [@b{--version}]
+ [@b{-W}] [@b{--warn}] [@b{--fatal-warnings}] [@b{-w}] [@b{-x}]
+ [@b{-Z}] [@b{@@@var{FILE}}]
+ [@b{--sectname-subst}] [@b{--size-check=[error|warning]}]
+ [@b{--elf-stt-common=[no|yes]}]
+ [@b{--generate-missing-build-notes=[no|yes]}]
+ [@b{--target-help}] [@var{target-options}]
+ [@b{--}|@var{files} @dots{}]
+@c
+@c man end
+@c Target dependent options are listed below. Keep the list sorted.
+@c Add an empty line for separation.
+@c man begin TARGET
+@ifset AARCH64
+
+@emph{Target AArch64 options:}
+ [@b{-EB}|@b{-EL}]
+ [@b{-mabi}=@var{ABI}]
+@end ifset
+@ifset ALPHA
+
+@emph{Target Alpha options:}
+ [@b{-m@var{cpu}}]
+ [@b{-mdebug} | @b{-no-mdebug}]
+ [@b{-replace} | @b{-noreplace}]
+ [@b{-relax}] [@b{-g}] [@b{-G@var{size}}]
+ [@b{-F}] [@b{-32addr}]
+@end ifset
+@ifset ARC
+
+@emph{Target ARC options:}
+ [@b{-mcpu=@var{cpu}}]
+ [@b{-mA6}|@b{-mARC600}|@b{-mARC601}|@b{-mA7}|@b{-mARC700}|@b{-mEM}|@b{-mHS}]
+ [@b{-mcode-density}]
+ [@b{-mrelax}]
+ [@b{-EB}|@b{-EL}]
+@end ifset
+@ifset ARM
+
+@emph{Target ARM options:}
+@c Don't document the deprecated options
+ [@b{-mcpu}=@var{processor}[+@var{extension}@dots{}]]
+ [@b{-march}=@var{architecture}[+@var{extension}@dots{}]]
+ [@b{-mfpu}=@var{floating-point-format}]
+ [@b{-mfloat-abi}=@var{abi}]
+ [@b{-meabi}=@var{ver}]
+ [@b{-mthumb}]
+ [@b{-EB}|@b{-EL}]
+ [@b{-mapcs-32}|@b{-mapcs-26}|@b{-mapcs-float}|
+ @b{-mapcs-reentrant}]
+ [@b{-mthumb-interwork}] [@b{-k}]
+@end ifset
+@ifset Blackfin
+
+@emph{Target Blackfin options:}
+ [@b{-mcpu}=@var{processor}[-@var{sirevision}]]
+ [@b{-mfdpic}]
+ [@b{-mno-fdpic}]
+ [@b{-mnopic}]
+@end ifset
+@ifset CRIS
+
+@emph{Target CRIS options:}
+ [@b{--underscore} | @b{--no-underscore}]
+ [@b{--pic}] [@b{-N}]
+ [@b{--emulation=criself} | @b{--emulation=crisaout}]
+ [@b{--march=v0_v10} | @b{--march=v10} | @b{--march=v32} | @b{--march=common_v10_v32}]
+@c Deprecated -- deliberately not documented.
+@c [@b{-h}] [@b{-H}]
+@end ifset
+@ifset D10V
+
+@emph{Target D10V options:}
+ [@b{-O}]
+@end ifset
+@ifset D30V
+
+@emph{Target D30V options:}
+ [@b{-O}|@b{-n}|@b{-N}]
+@end ifset
+@ifset EPIPHANY
+
+@emph{Target EPIPHANY options:}
+ [@b{-mepiphany}|@b{-mepiphany16}]
+@end ifset
+@ifset H8
+
+@emph{Target H8/300 options:}
+ [-h-tick-hex]
+@end ifset
+@ifset HPPA
+@c HPPA has no machine-dependent assembler options (yet).
+@end ifset
+@ifset I80386
+
+@emph{Target i386 options:}
+ [@b{--32}|@b{--x32}|@b{--64}] [@b{-n}]
+ [@b{-march}=@var{CPU}[+@var{EXTENSION}@dots{}]] [@b{-mtune}=@var{CPU}]
+@end ifset
+@ifset IA64
+
+@emph{Target IA-64 options:}
+ [@b{-mconstant-gp}|@b{-mauto-pic}]
+ [@b{-milp32}|@b{-milp64}|@b{-mlp64}|@b{-mp64}]
+ [@b{-mle}|@b{mbe}]
+ [@b{-mtune=itanium1}|@b{-mtune=itanium2}]
+ [@b{-munwind-check=warning}|@b{-munwind-check=error}]
+ [@b{-mhint.b=ok}|@b{-mhint.b=warning}|@b{-mhint.b=error}]
+ [@b{-x}|@b{-xexplicit}] [@b{-xauto}] [@b{-xdebug}]
+@end ifset
+@ifset IP2K
+
+@emph{Target IP2K options:}
+ [@b{-mip2022}|@b{-mip2022ext}]
+@end ifset
+@ifset M32C
+
+@emph{Target M32C options:}
+ [@b{-m32c}|@b{-m16c}] [-relax] [-h-tick-hex]
+@end ifset
+@ifset M32R
+
+@emph{Target M32R options:}
+ [@b{--m32rx}|@b{--[no-]warn-explicit-parallel-conflicts}|
+ @b{--W[n]p}]
+@end ifset
+@ifset M680X0
+
+@emph{Target M680X0 options:}
+ [@b{-l}] [@b{-m68000}|@b{-m68010}|@b{-m68020}|@dots{}]
+@end ifset
+@ifset M68HC11
+
+@emph{Target M68HC11 options:}
+ [@b{-m68hc11}|@b{-m68hc12}|@b{-m68hcs12}|@b{-mm9s12x}|@b{-mm9s12xg}]
+ [@b{-mshort}|@b{-mlong}]
+ [@b{-mshort-double}|@b{-mlong-double}]
+ [@b{--force-long-branches}] [@b{--short-branches}]
+ [@b{--strict-direct-mode}] [@b{--print-insn-syntax}]
+ [@b{--print-opcodes}] [@b{--generate-example}]
+@end ifset
+@ifset MCORE
+
+@emph{Target MCORE options:}
+ [@b{-jsri2bsr}] [@b{-sifilter}] [@b{-relax}]
+ [@b{-mcpu=[210|340]}]
+@end ifset
+@ifset METAG
+
+@emph{Target Meta options:}
+ [@b{-mcpu=@var{cpu}}] [@b{-mfpu=@var{cpu}}] [@b{-mdsp=@var{cpu}}]
+@end ifset
+@ifset MICROBLAZE
+@emph{Target MICROBLAZE options:}
+@c MicroBlaze has no machine-dependent assembler options.
+@end ifset
+@ifset MIPS
+
+@emph{Target MIPS options:}
+ [@b{-nocpp}] [@b{-EL}] [@b{-EB}] [@b{-O}[@var{optimization level}]]
+ [@b{-g}[@var{debug level}]] [@b{-G} @var{num}] [@b{-KPIC}] [@b{-call_shared}]
+ [@b{-non_shared}] [@b{-xgot} [@b{-mvxworks-pic}]
+ [@b{-mabi}=@var{ABI}] [@b{-32}] [@b{-n32}] [@b{-64}] [@b{-mfp32}] [@b{-mgp32}]
+ [@b{-mfp64}] [@b{-mgp64}] [@b{-mfpxx}]
+ [@b{-modd-spreg}] [@b{-mno-odd-spreg}]
+ [@b{-march}=@var{CPU}] [@b{-mtune}=@var{CPU}] [@b{-mips1}] [@b{-mips2}]
+ [@b{-mips3}] [@b{-mips4}] [@b{-mips5}] [@b{-mips32}] [@b{-mips32r2}]
+ [@b{-mips32r3}] [@b{-mips32r5}] [@b{-mips32r6}] [@b{-mips64}] [@b{-mips64r2}]
+ [@b{-mips64r3}] [@b{-mips64r5}] [@b{-mips64r6}]
+ [@b{-construct-floats}] [@b{-no-construct-floats}]
+ [@b{-mignore-branch-isa}] [@b{-mno-ignore-branch-isa}]
+ [@b{-mnan=@var{encoding}}]
+ [@b{-trap}] [@b{-no-break}] [@b{-break}] [@b{-no-trap}]
+ [@b{-mips16}] [@b{-no-mips16}]
+ [@b{-mmips16e2}] [@b{-mno-mips16e2}]
+ [@b{-mmicromips}] [@b{-mno-micromips}]
+ [@b{-msmartmips}] [@b{-mno-smartmips}]
+ [@b{-mips3d}] [@b{-no-mips3d}]
+ [@b{-mdmx}] [@b{-no-mdmx}]
+ [@b{-mdsp}] [@b{-mno-dsp}]
+ [@b{-mdspr2}] [@b{-mno-dspr2}]
+ [@b{-mdspr3}] [@b{-mno-dspr3}]
+ [@b{-mmsa}] [@b{-mno-msa}]
+ [@b{-mxpa}] [@b{-mno-xpa}]
+ [@b{-mmt}] [@b{-mno-mt}]
+ [@b{-mmcu}] [@b{-mno-mcu}]
+ [@b{-mcrc}] [@b{-mno-crc}]
+ [@b{-mginv}] [@b{-mno-ginv}]
+ [@b{-minsn32}] [@b{-mno-insn32}]
+ [@b{-mfix7000}] [@b{-mno-fix7000}]
+ [@b{-mfix-rm7000}] [@b{-mno-fix-rm7000}]
+ [@b{-mfix-vr4120}] [@b{-mno-fix-vr4120}]
+ [@b{-mfix-vr4130}] [@b{-mno-fix-vr4130}]
+ [@b{-mdebug}] [@b{-no-mdebug}]
+ [@b{-mpdr}] [@b{-mno-pdr}]
+@end ifset
+@ifset MMIX
+
+@emph{Target MMIX options:}
+ [@b{--fixed-special-register-names}] [@b{--globalize-symbols}]
+ [@b{--gnu-syntax}] [@b{--relax}] [@b{--no-predefined-symbols}]
+ [@b{--no-expand}] [@b{--no-merge-gregs}] [@b{-x}]
+ [@b{--linker-allocated-gregs}]
+@end ifset
+@ifset NIOSII
+
+@emph{Target Nios II options:}
+ [@b{-relax-all}] [@b{-relax-section}] [@b{-no-relax}]
+ [@b{-EB}] [@b{-EL}]
+@end ifset
+@ifset NDS32
+
+@emph{Target NDS32 options:}
+ [@b{-EL}] [@b{-EB}] [@b{-O}] [@b{-Os}] [@b{-mcpu=@var{cpu}}]
+ [@b{-misa=@var{isa}}] [@b{-mabi=@var{abi}}] [@b{-mall-ext}]
+ [@b{-m[no-]16-bit}] [@b{-m[no-]perf-ext}] [@b{-m[no-]perf2-ext}]
+ [@b{-m[no-]string-ext}] [@b{-m[no-]dsp-ext}] [@b{-m[no-]mac}] [@b{-m[no-]div}]
+ [@b{-m[no-]audio-isa-ext}] [@b{-m[no-]fpu-sp-ext}] [@b{-m[no-]fpu-dp-ext}]
+ [@b{-m[no-]fpu-fma}] [@b{-mfpu-freg=@var{FREG}}] [@b{-mreduced-regs}]
+ [@b{-mfull-regs}] [@b{-m[no-]dx-regs}] [@b{-mpic}] [@b{-mno-relax}]
+ [@b{-mb2bb}]
+@end ifset
+@ifset PDP11
+
+@emph{Target PDP11 options:}
+ [@b{-mpic}|@b{-mno-pic}] [@b{-mall}] [@b{-mno-extensions}]
+ [@b{-m}@var{extension}|@b{-mno-}@var{extension}]
+ [@b{-m}@var{cpu}] [@b{-m}@var{machine}]
+@end ifset
+@ifset PJ
+
+@emph{Target picoJava options:}
+ [@b{-mb}|@b{-me}]
+@end ifset
+@ifset PPC
+
+@emph{Target PowerPC options:}
+ [@b{-a32}|@b{-a64}]
+ [@b{-mpwrx}|@b{-mpwr2}|@b{-mpwr}|@b{-m601}|@b{-mppc}|@b{-mppc32}|@b{-m603}|@b{-m604}|@b{-m403}|@b{-m405}|
+ @b{-m440}|@b{-m464}|@b{-m476}|@b{-m7400}|@b{-m7410}|@b{-m7450}|@b{-m7455}|@b{-m750cl}|@b{-mppc64}|
+ @b{-m620}|@b{-me500}|@b{-e500x2}|@b{-me500mc}|@b{-me500mc64}|@b{-me5500}|@b{-me6500}|@b{-mppc64bridge}|
+ @b{-mbooke}|@b{-mpower4}|@b{-mpwr4}|@b{-mpower5}|@b{-mpwr5}|@b{-mpwr5x}|@b{-mpower6}|@b{-mpwr6}|
+ @b{-mpower7}|@b{-mpwr7}|@b{-mpower8}|@b{-mpwr8}|@b{-mpower9}|@b{-mpwr9}@b{-ma2}|
+ @b{-mcell}|@b{-mspe}|@b{-mspe2}|@b{-mtitan}|@b{-me300}|@b{-mcom}]
+ [@b{-many}] [@b{-maltivec}|@b{-mvsx}|@b{-mhtm}|@b{-mvle}]
+ [@b{-mregnames}|@b{-mno-regnames}]
+ [@b{-mrelocatable}|@b{-mrelocatable-lib}|@b{-K PIC}] [@b{-memb}]
+ [@b{-mlittle}|@b{-mlittle-endian}|@b{-le}|@b{-mbig}|@b{-mbig-endian}|@b{-be}]
+ [@b{-msolaris}|@b{-mno-solaris}]
+ [@b{-nops=@var{count}}]
+@end ifset
+@ifset PRU
+
+@emph{Target PRU options:}
+ [@b{-link-relax}]
+ [@b{-mnolink-relax}]
+ [@b{-mno-warn-regname-label}]
+@end ifset
+@ifset RISCV
+
+@emph{Target RISC-V options:}
+ [@b{-fpic}|@b{-fPIC}|@b{-fno-pic}]
+ [@b{-march}=@var{ISA}]
+ [@b{-mabi}=@var{ABI}]
+@end ifset
+@ifset RL78
+
+@emph{Target RL78 options:}
+ [@b{-mg10}]
+ [@b{-m32bit-doubles}|@b{-m64bit-doubles}]
+@end ifset
+@ifset RX
+
+@emph{Target RX options:}
+ [@b{-mlittle-endian}|@b{-mbig-endian}]
+ [@b{-m32bit-doubles}|@b{-m64bit-doubles}]
+ [@b{-muse-conventional-section-names}]
+ [@b{-msmall-data-limit}]
+ [@b{-mpid}]
+ [@b{-mrelax}]
+ [@b{-mint-register=@var{number}}]
+ [@b{-mgcc-abi}|@b{-mrx-abi}]
+@end ifset
+@ifset S390
+
+@emph{Target s390 options:}
+ [@b{-m31}|@b{-m64}] [@b{-mesa}|@b{-mzarch}] [@b{-march}=@var{CPU}]
+ [@b{-mregnames}|@b{-mno-regnames}]
+ [@b{-mwarn-areg-zero}]
+@end ifset
+@ifset SCORE
+
+@emph{Target SCORE options:}
+ [@b{-EB}][@b{-EL}][@b{-FIXDD}][@b{-NWARN}]
+ [@b{-SCORE5}][@b{-SCORE5U}][@b{-SCORE7}][@b{-SCORE3}]
+ [@b{-march=score7}][@b{-march=score3}]
+ [@b{-USE_R1}][@b{-KPIC}][@b{-O0}][@b{-G} @var{num}][@b{-V}]
+@end ifset
+@ifset SPARC
+
+@emph{Target SPARC options:}
+@c The order here is important. See c-sparc.texi.
+ [@b{-Av6}|@b{-Av7}|@b{-Av8}|@b{-Aleon}|@b{-Asparclet}|@b{-Asparclite}
+ @b{-Av8plus}|@b{-Av8plusa}|@b{-Av8plusb}|@b{-Av8plusc}|@b{-Av8plusd}
+ @b{-Av8plusv}|@b{-Av8plusm}|@b{-Av9}|@b{-Av9a}|@b{-Av9b}|@b{-Av9c}
+ @b{-Av9d}|@b{-Av9e}|@b{-Av9v}|@b{-Av9m}|@b{-Asparc}|@b{-Asparcvis}
+ @b{-Asparcvis2}|@b{-Asparcfmaf}|@b{-Asparcima}|@b{-Asparcvis3}
+ @b{-Asparcvisr}|@b{-Asparc5}]
+ [@b{-xarch=v8plus}|@b{-xarch=v8plusa}]|@b{-xarch=v8plusb}|@b{-xarch=v8plusc}
+ @b{-xarch=v8plusd}|@b{-xarch=v8plusv}|@b{-xarch=v8plusm}|@b{-xarch=v9}
+ @b{-xarch=v9a}|@b{-xarch=v9b}|@b{-xarch=v9c}|@b{-xarch=v9d}|@b{-xarch=v9e}
+ @b{-xarch=v9v}|@b{-xarch=v9m}|@b{-xarch=sparc}|@b{-xarch=sparcvis}
+ @b{-xarch=sparcvis2}|@b{-xarch=sparcfmaf}|@b{-xarch=sparcima}
+ @b{-xarch=sparcvis3}|@b{-xarch=sparcvisr}|@b{-xarch=sparc5}
+ @b{-bump}]
+ [@b{-32}|@b{-64}]
+ [@b{--enforce-aligned-data}][@b{--dcti-couples-detect}]
+@end ifset
+@ifset TIC54X
+
+@emph{Target TIC54X options:}
+ [@b{-mcpu=54[123589]}|@b{-mcpu=54[56]lp}] [@b{-mfar-mode}|@b{-mf}]
+ [@b{-merrors-to-file} @var{<filename>}|@b{-me} @var{<filename>}]
+@end ifset
+@ifset TIC6X
+
+@emph{Target TIC6X options:}
+ [@b{-march=@var{arch}}] [@b{-mbig-endian}|@b{-mlittle-endian}]
+ [@b{-mdsbt}|@b{-mno-dsbt}] [@b{-mpid=no}|@b{-mpid=near}|@b{-mpid=far}]
+ [@b{-mpic}|@b{-mno-pic}]
+@end ifset
+@ifset TILEGX
+
+@emph{Target TILE-Gx options:}
+ [@b{-m32}|@b{-m64}][@b{-EB}][@b{-EL}]
+@end ifset
+@ifset TILEPRO
+@c TILEPro has no machine-dependent assembler options
+@end ifset
+@ifset VISIUM
+
+@emph{Target Visium options:}
+ [@b{-mtune=@var{arch}}]
+@end ifset
+@ifset XTENSA
+
+@emph{Target Xtensa options:}
+ [@b{--[no-]text-section-literals}] [@b{--[no-]auto-litpools}]
+ [@b{--[no-]absolute-literals}]
+ [@b{--[no-]target-align}] [@b{--[no-]longcalls}]
+ [@b{--[no-]transform}]
+ [@b{--rename-section} @var{oldname}=@var{newname}]
+ [@b{--[no-]trampolines}]
+@end ifset
+@ifset Z80
+
+@emph{Target Z80 options:}
+ [@b{-z80}] [@b{-r800}]
+ [@b{ -ignore-undocumented-instructions}] [@b{-Wnud}]
+ [@b{ -ignore-unportable-instructions}] [@b{-Wnup}]
+ [@b{ -warn-undocumented-instructions}] [@b{-Wud}]
+ [@b{ -warn-unportable-instructions}] [@b{-Wup}]
+ [@b{ -forbid-undocumented-instructions}] [@b{-Fud}]
+ [@b{ -forbid-unportable-instructions}] [@b{-Fup}]
+@end ifset
+@ifset Z8000
+
+@c Z8000 has no machine-dependent assembler options
+@end ifset
+
+@c man end
+@end smallexample
+
+@c man begin OPTIONS
+
+@table @gcctabopt
+@include at-file.texi
+
+@item -a[cdghlmns]
+Turn on listings, in any of a variety of ways:
+
+@table @gcctabopt
+@item -ac
+omit false conditionals
+
+@item -ad
+omit debugging directives
+
+@item -ag
+include general information, like @value{AS} version and options passed
+
+@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 --alternate
+Begin in alternate macro mode.
+@ifclear man
+@xref{Altmacro,,@code{.altmacro}}.
+@end ifclear
+
+@item --compress-debug-sections
+Compress DWARF debug sections using zlib with SHF_COMPRESSED from the
+ELF ABI. The resulting object file may not be compatible with older
+linkers and object file utilities. Note if compression would make a
+given section @emph{larger} then it is not compressed.
+
+@ifset ELF
+@cindex @samp{--compress-debug-sections=} option
+@item --compress-debug-sections=none
+@itemx --compress-debug-sections=zlib
+@itemx --compress-debug-sections=zlib-gnu
+@itemx --compress-debug-sections=zlib-gabi
+These options control how DWARF debug sections are compressed.
+@option{--compress-debug-sections=none} is equivalent to
+@option{--nocompress-debug-sections}.
+@option{--compress-debug-sections=zlib} and
+@option{--compress-debug-sections=zlib-gabi} are equivalent to
+@option{--compress-debug-sections}.
+@option{--compress-debug-sections=zlib-gnu} compresses DWARF debug
+sections using zlib. The debug sections are renamed to begin with
+@samp{.zdebug}. Note if compression would make a given section
+@emph{larger} then it is not compressed nor renamed.
+
+@end ifset
+
+@item --nocompress-debug-sections
+Do not compress DWARF debug sections. This is usually the default for all
+targets except the x86/x86_64, but a configure time option can be used to
+override this.
+
+@item -D
+Ignored. This option is accepted for script compatibility with calls to
+other assemblers.
+
+@item --debug-prefix-map @var{old}=@var{new}
+When assembling files in directory @file{@var{old}}, record debugging
+information describing them as in @file{@var{new}} instead.
+
+@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. The value of the symbol can be overridden inside a source file via the
+use of a @code{.set} pseudo-op.
+
+@item -f
+``fast''---skip whitespace and comment preprocessing (assume source is
+compiler output).
+
+@item -g
+@itemx --gen-debug
+Generate debugging information for each assembler source line using whichever
+debug format is preferred by the target. This currently means either STABS,
+ECOFF or DWARF2.
+
+@item --gstabs
+Generate stabs debugging information for each assembler line. This
+may help debugging assembler code, if the debugger can handle it.
+
+@item --gstabs+
+Generate stabs debugging information for each assembler line, with GNU
+extensions that probably only gdb can handle, and that could make other
+debuggers crash or refuse to read your program. This
+may help debugging assembler code. Currently the only GNU extension is
+the location of the current working directory at assembling time.
+
+@item --gdwarf-2
+Generate DWARF2 debugging information for each assembler line. This
+may help debugging assembler code, if the debugger can handle it. Note---this
+option is only supported by some targets, not all of them.
+
+@item --gdwarf-sections
+Instead of creating a .debug_line section, create a series of
+.debug_line.@var{foo} sections where @var{foo} is the name of the
+corresponding code section. For example a code section called @var{.text.func}
+will have its dwarf line number information placed into a section called
+@var{.debug_line.text.func}. If the code section is just called @var{.text}
+then debug line section will still be called just @var{.debug_line} without any
+suffix.
+
+@ifset ELF
+@item --size-check=error
+@itemx --size-check=warning
+Issue an error or warning for invalid ELF .size directive.
+
+@item --elf-stt-common=no
+@itemx --elf-stt-common=yes
+These options control whether the ELF assembler should generate common
+symbols with the @code{STT_COMMON} type. The default can be controlled
+by a configure option @option{--enable-elf-stt-common}.
+
+@item --generate-missing-build-notes=yes
+@itemx --generate-missing-build-notes=no
+These options control whether the ELF assembler should generate GNU Build
+attribute notes if none are present in the input sources.
+The default can be controlled by the @option{--enable-generate-build-notes}
+configure option.
+
+@end ifset
+
+@item --help
+Print a summary of the command line options and exit.
+
+@item --target-help
+Print a summary of all target specific 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. These symbols start with
+system-specific local label prefixes, typically @samp{.L} for ELF systems
+or @samp{L} for traditional a.out systems.
+@ifclear man
+@xref{Symbol Names}.
+@end ifclear
+
+@item --listing-lhs-width=@var{number}
+Set the maximum width, in words, of the output data column for an assembler
+listing to @var{number}.
+
+@item --listing-lhs-width2=@var{number}
+Set the maximum width, in words, of the output data column for continuation
+lines in an assembler listing to @var{number}.
+
+@item --listing-rhs-width=@var{number}
+Set the maximum width of an input source line, as displayed in a listing, to
+@var{number} bytes.
+
+@item --listing-cont-lines=@var{number}
+Set the maximum number of lines printed in a listing for a single line of input
+to @var{number} + 1.
+
+@item --no-pad-sections
+Stop the assembler for padding the ends of output sections to the alignment
+of that section. The default is to pad the sections, but this can waste space
+which might be needed on targets which have tight memory constraints.
+
+@item -o @var{objfile}
+Name the object-file output from @command{@value{AS}} @var{objfile}.
+
+@item -R
+Fold the data section into the text section.
+
+@item --hash-size=@var{number}
+Set the default size of GAS's hash tables to a prime number close to
+@var{number}. Increasing this value can reduce the length of time it takes the
+assembler to perform its tasks, at the expense of increasing the assembler's
+memory requirements. Similarly reducing this value can reduce the memory
+requirements at the expense of speed.
+
+@item --reduce-memory-overheads
+This option reduces GAS's memory requirements, at the expense of making the
+assembly processes slower. Currently this switch is a synonym for
+@samp{--hash-size=4051}, but in the future it may have other effects as well.
+
+@ifset ELF
+@item --sectname-subst
+Honor substitution sequences in section names.
+@ifclear man
+@xref{Section Name Substitutions,,@code{.section @var{name}}}.
+@end ifclear
+@end ifset
+
+@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 @command{as} version.
+
+@item --version
+Print the @command{as} version and exit.
+
+@item -W
+@itemx --no-warn
+Suppress warning messages.
+
+@item --fatal-warnings
+Treat warnings as errors.
+
+@item --warn
+Don't suppress warning messages or treat them as errors.
+
+@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
+@c man end
+
+@ifset AARCH64
+
+@ifclear man
+@xref{AArch64 Options}, for the options available when @value{AS} is configured
+for the 64-bit mode of the ARM Architecture (AArch64).
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for the
+64-bit mode of the ARM Architecture (AArch64).
+@c man end
+@c man begin INCLUDE
+@include c-aarch64.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
+@ifset ALPHA
+
+@ifclear man
+@xref{Alpha Options}, for the options available when @value{AS} is configured
+for an Alpha processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for an Alpha
+processor.
+@c man end
+@c man begin INCLUDE
+@include c-alpha.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
+@c man begin OPTIONS
+@ifset ARC
+The following options are available when @value{AS} is configured for an ARC
+processor.
+
+@table @gcctabopt
+@item -mcpu=@var{cpu}
+This option selects the core processor variant.
+@item -EB | -EL
+Select either big-endian (-EB) or little-endian (-EL) output.
+@item -mcode-density
+Enable Code Density extenssion instructions.
+@end table
+@end ifset
+
+@ifset ARM
+The following options are available when @value{AS} is configured for the ARM
+processor family.
+
+@table @gcctabopt
+@item -mcpu=@var{processor}[+@var{extension}@dots{}]
+Specify which ARM processor variant is the target.
+@item -march=@var{architecture}[+@var{extension}@dots{}]
+Specify which ARM architecture variant is used by the target.
+@item -mfpu=@var{floating-point-format}
+Select which Floating Point architecture is the target.
+@item -mfloat-abi=@var{abi}
+Select which floating point ABI is in use.
+@item -mthumb
+Enable Thumb only instruction decoding.
+@item -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant
+Select which procedure calling convention is in use.
+@item -EB | -EL
+Select either big-endian (-EB) or little-endian (-EL) output.
+@item -mthumb-interwork
+Specify that the code has been generated with interworking between Thumb and
+ARM code in mind.
+@item -mccs
+Turns on CodeComposer Studio assembly syntax compatibility mode.
+@item -k
+Specify that PIC code has been generated.
+@end table
+@end ifset
+@c man end
+
+@ifset Blackfin
+
+@ifclear man
+@xref{Blackfin Options}, for the options available when @value{AS} is
+configured for the Blackfin processor family.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for
+the Blackfin processor family.
+@c man end
+@c man begin INCLUDE
+@include c-bfin.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
+@c man begin OPTIONS
+@ifset CRIS
+See the info pages for documentation of the CRIS-specific options.
+@end ifset
+
+@ifset D10V
+The following options are available when @value{AS} is configured for
+a D10V processor.
+@table @gcctabopt
+@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 @gcctabopt
+@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
+@c man end
+
+@ifset EPIPHANY
+The following options are available when @value{AS} is configured for the
+Adapteva EPIPHANY series.
+
+@ifclear man
+@xref{Epiphany Options}, for the options available when @value{AS} is
+configured for an Epiphany processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for
+an Epiphany processor.
+@c man end
+@c man begin INCLUDE
+@include c-epiphany.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
+@ifset H8300
+
+@ifclear man
+@xref{H8/300 Options}, for the options available when @value{AS} is configured
+for an H8/300 processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for an H8/300
+processor.
+@c man end
+@c man begin INCLUDE
+@include c-h8300.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
+@ifset I80386
+
+@ifclear man
+@xref{i386-Options}, for the options available when @value{AS} is
+configured for an i386 processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for
+an i386 processor.
+@c man end
+@c man begin INCLUDE
+@include c-i386.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
+@c man begin OPTIONS
+@ifset IP2K
+The following options are available when @value{AS} is configured for the
+Ubicom IP2K series.
+
+@table @gcctabopt
+
+@item -mip2022ext
+Specifies that the extended IP2022 instructions are allowed.
+
+@item -mip2022
+Restores the default behaviour, which restricts the permitted instructions to
+just the basic IP2022 ones.
+
+@end table
+@end ifset
+
+@ifset M32C
+The following options are available when @value{AS} is configured for the
+Renesas M32C and M16C processors.
+
+@table @gcctabopt
+
+@item -m32c
+Assemble M32C instructions.
+
+@item -m16c
+Assemble M16C instructions (the default).
+
+@item -relax
+Enable support for link-time relaxations.
+
+@item -h-tick-hex
+Support H'00 style hex constants in addition to 0x00 style.
+
+@end table
+@end ifset
+
+@ifset M32R
+The following options are available when @value{AS} is configured for the
+Renesas M32R (formerly Mitsubishi M32R) series.
+
+@table @gcctabopt
+
+@item --m32rx
+Specify which processor in the M32R family is the target. The default
+is normally the M32R, but this option changes it to the M32RX.
+
+@item --warn-explicit-parallel-conflicts or --Wp
+Produce warning messages when questionable parallel constructs are
+encountered.
+
+@item --no-warn-explicit-parallel-conflicts or --Wnp
+Do not produce warning messages when questionable parallel constructs are
+encountered.
+
+@end table
+@end ifset
+
+@ifset M680X0
+The following options are available when @value{AS} is configured for the
+Motorola 68000 series.
+
+@table @gcctabopt
+
+@item -l
+Shorten references to undefined symbols, to one word instead of two.
+
+@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030
+@itemx | -m68040 | -m68060 | -m68302 | -m68331 | -m68332
+@itemx | -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 NIOSII
+
+@ifclear man
+@xref{Nios II Options}, for the options available when @value{AS} is configured
+for an Altera Nios II processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for an
+Altera Nios II processor.
+@c man end
+@c man begin INCLUDE
+@include c-nios2.texi
+@c ended inside the included file
+@end ifset
+@end ifset
+
+@ifset PDP11
+
+For details about the PDP-11 machine dependent features options,
+see @ref{PDP-11-Options}.
+
+@table @gcctabopt
+@item -mpic | -mno-pic
+Generate position-independent (or position-dependent) code. The
+default is @option{-mpic}.
+
+@item -mall
+@itemx -mall-extensions
+Enable all instruction set extensions. This is the default.
+
+@item -mno-extensions
+Disable all instruction set extensions.
+
+@item -m@var{extension} | -mno-@var{extension}
+Enable (or disable) a particular instruction set extension.
+
+@item -m@var{cpu}
+Enable the instruction set extensions supported by a particular CPU, and
+disable all other extensions.
+
+@item -m@var{machine}
+Enable the instruction set extensions supported by a particular machine
+model, and disable all other extensions.
+@end table
+
+@end ifset
+
+@ifset PJ
+The following options are available when @value{AS} is configured for
+a picoJava processor.
+
+@table @gcctabopt
+
+@cindex PJ endianness
+@cindex endianness, PJ
+@cindex big endian output, PJ
+@item -mb
+Generate ``big endian'' format output.
+
+@cindex little endian output, PJ
+@item -ml
+Generate ``little endian'' format output.
+
+@end table
+@end ifset
+
+@ifset PRU
+
+@ifclear man
+@xref{PRU Options}, for the options available when @value{AS} is configured
+for a PRU processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for a
+PRU processor.
+@c man end
+@c man begin INCLUDE
+@include c-pru.texi
+@c ended inside the included file
+@end ifset
+@end ifset
+
+@ifset M68HC11
+The following options are available when @value{AS} is configured for the
+Motorola 68HC11 or 68HC12 series.
+
+@table @gcctabopt
+
+@item -m68hc11 | -m68hc12 | -m68hcs12 | -mm9s12x | -mm9s12xg
+Specify what processor is the target. The default is
+defined by the configuration option when building the assembler.
+
+@item --xgate-ramoffset
+Instruct the linker to offset RAM addresses from S12X address space into
+XGATE address space.
+
+@item -mshort
+Specify to use the 16-bit integer ABI.
+
+@item -mlong
+Specify to use the 32-bit integer ABI.
+
+@item -mshort-double
+Specify to use the 32-bit double ABI.
+
+@item -mlong-double
+Specify to use the 64-bit double ABI.
+
+@item --force-long-branches
+Relative branches are turned into absolute ones. This concerns
+conditional branches, unconditional branches and branches to a
+sub routine.
+
+@item -S | --short-branches
+Do not turn relative branches into absolute ones
+when the offset is out of range.
+
+@item --strict-direct-mode
+Do not turn the direct addressing mode into extended addressing mode
+when the instruction does not support direct addressing mode.
+
+@item --print-insn-syntax
+Print the syntax of instruction in case of error.
+
+@item --print-opcodes
+Print the list of instructions with syntax and then exit.
+
+@item --generate-example
+Print an example of instruction for each possible instruction and then exit.
+This option is only useful for testing @command{@value{AS}}.
+
+@end table
+@end ifset
+
+@ifset SPARC
+The following options are available when @command{@value{AS}} is configured
+for the SPARC architecture:
+
+@table @gcctabopt
+@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 TIC54X
+The following options are available when @value{AS} is configured for the 'c54x
+architecture.
+
+@table @gcctabopt
+@item -mfar-mode
+Enable extended addressing mode. All addresses and relocations will assume
+extended addressing (usually 23 bits).
+@item -mcpu=@var{CPU_VERSION}
+Sets the CPU version being compiled for.
+@item -merrors-to-file @var{FILENAME}
+Redirect error output to a file, for broken systems which don't support such
+behaviour in the shell.
+@end table
+@end ifset
+
+@ifset MIPS
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for
+a MIPS processor.
+
+@table @gcctabopt
+@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
+@itemx -mips4
+@itemx -mips5
+@itemx -mips32
+@itemx -mips32r2
+@itemx -mips32r3
+@itemx -mips32r5
+@itemx -mips32r6
+@itemx -mips64
+@itemx -mips64r2
+@itemx -mips64r3
+@itemx -mips64r5
+@itemx -mips64r6
+Generate code for a particular MIPS Instruction Set Architecture level.
+@samp{-mips1} is an alias for @samp{-march=r3000}, @samp{-mips2} is an
+alias for @samp{-march=r6000}, @samp{-mips3} is an alias for
+@samp{-march=r4000} and @samp{-mips4} is an alias for @samp{-march=r8000}.
+@samp{-mips5}, @samp{-mips32}, @samp{-mips32r2}, @samp{-mips32r3},
+@samp{-mips32r5}, @samp{-mips32r6}, @samp{-mips64}, @samp{-mips64r2},
+@samp{-mips64r3}, @samp{-mips64r5}, and @samp{-mips64r6} correspond to generic
+MIPS V, MIPS32, MIPS32 Release 2, MIPS32 Release 3, MIPS32 Release 5, MIPS32
+Release 6, MIPS64, MIPS64 Release 2, MIPS64 Release 3, MIPS64 Release 5, and
+MIPS64 Release 6 ISA processors, respectively.
+
+@item -march=@var{cpu}
+Generate code for a particular MIPS CPU.
+
+@item -mtune=@var{cpu}
+Schedule and tune for a particular MIPS CPU.
+
+@item -mfix7000
+@itemx -mno-fix7000
+Cause nops to be inserted if the read of the destination register
+of an mfhi or mflo instruction occurs in the following two instructions.
+
+@item -mfix-rm7000
+@itemx -mno-fix-rm7000
+Cause nops to be inserted if a dmult or dmultu instruction is
+followed by a load instruction.
+
+@item -mdebug
+@itemx -no-mdebug
+Cause stabs-style debugging output to go into an ECOFF-style .mdebug
+section instead of the standard ELF .stabs sections.
+
+@item -mpdr
+@itemx -mno-pdr
+Control generation of @code{.pdr} sections.
+
+@item -mgp32
+@itemx -mfp32
+The register sizes are normally inferred from the ISA and ABI, but these
+flags force a certain group of registers to be treated as 32 bits wide at
+all times. @samp{-mgp32} controls the size of general-purpose registers
+and @samp{-mfp32} controls the size of floating-point registers.
+
+@item -mgp64
+@itemx -mfp64
+The register sizes are normally inferred from the ISA and ABI, but these
+flags force a certain group of registers to be treated as 64 bits wide at
+all times. @samp{-mgp64} controls the size of general-purpose registers
+and @samp{-mfp64} controls the size of floating-point registers.
+
+@item -mfpxx
+The register sizes are normally inferred from the ISA and ABI, but using
+this flag in combination with @samp{-mabi=32} enables an ABI variant
+which will operate correctly with floating-point registers which are
+32 or 64 bits wide.
+
+@item -modd-spreg
+@itemx -mno-odd-spreg
+Enable use of floating-point operations on odd-numbered single-precision
+registers when supported by the ISA. @samp{-mfpxx} implies
+@samp{-mno-odd-spreg}, otherwise the default is @samp{-modd-spreg}.
+
+@item -mips16
+@itemx -no-mips16
+Generate code for the MIPS 16 processor. This is equivalent to putting
+@code{.module mips16} at the start of the assembly file. @samp{-no-mips16}
+turns off this option.
+
+@item -mmips16e2
+@itemx -mno-mips16e2
+Enable the use of MIPS16e2 instructions in MIPS16 mode. This is equivalent
+to putting @code{.module mips16e2} at the start of the assembly file.
+@samp{-mno-mips16e2} turns off this option.
+
+@item -mmicromips
+@itemx -mno-micromips
+Generate code for the microMIPS processor. This is equivalent to putting
+@code{.module micromips} at the start of the assembly file.
+@samp{-mno-micromips} turns off this option. This is equivalent to putting
+@code{.module nomicromips} at the start of the assembly file.
+
+@item -msmartmips
+@itemx -mno-smartmips
+Enables the SmartMIPS extension to the MIPS32 instruction set. This is
+equivalent to putting @code{.module smartmips} at the start of the assembly
+file. @samp{-mno-smartmips} turns off this option.
+
+@item -mips3d
+@itemx -no-mips3d
+Generate code for the MIPS-3D Application Specific Extension.
+This tells the assembler to accept MIPS-3D instructions.
+@samp{-no-mips3d} turns off this option.
+
+@item -mdmx
+@itemx -no-mdmx
+Generate code for the MDMX Application Specific Extension.
+This tells the assembler to accept MDMX instructions.
+@samp{-no-mdmx} turns off this option.
+
+@item -mdsp
+@itemx -mno-dsp
+Generate code for the DSP Release 1 Application Specific Extension.
+This tells the assembler to accept DSP Release 1 instructions.
+@samp{-mno-dsp} turns off this option.
+
+@item -mdspr2
+@itemx -mno-dspr2
+Generate code for the DSP Release 2 Application Specific Extension.
+This option implies @samp{-mdsp}.
+This tells the assembler to accept DSP Release 2 instructions.
+@samp{-mno-dspr2} turns off this option.
+
+@item -mdspr3
+@itemx -mno-dspr3
+Generate code for the DSP Release 3 Application Specific Extension.
+This option implies @samp{-mdsp} and @samp{-mdspr2}.
+This tells the assembler to accept DSP Release 3 instructions.
+@samp{-mno-dspr3} turns off this option.
+
+@item -mmsa
+@itemx -mno-msa
+Generate code for the MIPS SIMD Architecture Extension.
+This tells the assembler to accept MSA instructions.
+@samp{-mno-msa} turns off this option.
+
+@item -mxpa
+@itemx -mno-xpa
+Generate code for the MIPS eXtended Physical Address (XPA) Extension.
+This tells the assembler to accept XPA instructions.
+@samp{-mno-xpa} turns off this option.
+
+@item -mmt
+@itemx -mno-mt
+Generate code for the MT Application Specific Extension.
+This tells the assembler to accept MT instructions.
+@samp{-mno-mt} turns off this option.
+
+@item -mmcu
+@itemx -mno-mcu
+Generate code for the MCU Application Specific Extension.
+This tells the assembler to accept MCU instructions.
+@samp{-mno-mcu} turns off this option.
+
+@item -mcrc
+@itemx -mno-crc
+Generate code for the MIPS cyclic redundancy check (CRC) Application
+Specific Extension. This tells the assembler to accept CRC instructions.
+@samp{-mno-crc} turns off this option.
+
+@item -mginv
+@itemx -mno-ginv
+Generate code for the Global INValidate (GINV) Application Specific
+Extension. This tells the assembler to accept GINV instructions.
+@samp{-mno-ginv} turns off this option.
+
+@item -minsn32
+@itemx -mno-insn32
+Only use 32-bit instruction encodings when generating code for the
+microMIPS processor. This option inhibits the use of any 16-bit
+instructions. This is equivalent to putting @code{.set insn32} at
+the start of the assembly file. @samp{-mno-insn32} turns off this
+option. This is equivalent to putting @code{.set noinsn32} at the
+start of the assembly file. By default @samp{-mno-insn32} is
+selected, allowing all instructions to be used.
+
+@item --construct-floats
+@itemx --no-construct-floats
+The @samp{--no-construct-floats} option disables the construction of
+double width floating point constants by loading the two halves of the
+value into the two single width floating point registers that make up
+the double width register. By default @samp{--construct-floats} is
+selected, allowing construction of these floating point constants.
+
+@item --relax-branch
+@itemx --no-relax-branch
+The @samp{--relax-branch} option enables the relaxation of out-of-range
+branches. By default @samp{--no-relax-branch} is selected, causing any
+out-of-range branches to produce an error.
+
+@item -mignore-branch-isa
+@itemx -mno-ignore-branch-isa
+Ignore branch checks for invalid transitions between ISA modes. The
+semantics of branches does not provide for an ISA mode switch, so in
+most cases the ISA mode a branch has been encoded for has to be the
+same as the ISA mode of the branch's target label. Therefore GAS has
+checks implemented that verify in branch assembly that the two ISA
+modes match. @samp{-mignore-branch-isa} disables these checks. By
+default @samp{-mno-ignore-branch-isa} is selected, causing any invalid
+branch requiring a transition between ISA modes to produce an error.
+
+@item -mnan=@var{encoding}
+Select between the IEEE 754-2008 (@option{-mnan=2008}) or the legacy
+(@option{-mnan=legacy}) NaN encoding format. The latter is the default.
+
+@cindex emulation
+@item --emulation=@var{name}
+This option was formerly used to switch between ELF and ECOFF output
+on targets like IRIX 5 that supported both. MIPS ECOFF support was
+removed in GAS 2.24, so the option now serves little purpose.
+It is retained for backwards compatibility.
+
+The available configuration names are: @samp{mipself}, @samp{mipslelf} and
+@samp{mipsbelf}. Choosing @samp{mipself} now has no effect, since the output
+is always ELF. @samp{mipslelf} and @samp{mipsbelf} select little- and
+big-endian output respectively, but @samp{-EL} and @samp{-EB} are now the
+preferred options instead.
+
+@item -nocpp
+@command{@value{AS}} ignores this option. It is accepted for compatibility with
+the native tools.
+
+@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.
+
+@item -n
+When this option is used, @command{@value{AS}} will issue a warning every
+time it generates a nop instruction from a macro.
+@end table
+@c man end
+@end ifset
+
+@ifset MCORE
+The following options are available when @value{AS} is configured for
+an MCore processor.
+
+@table @gcctabopt
+@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 overridden by the @samp{-sifilter} command line option.
+
+@item -relax
+Alter jump instructions for long displacements.
+
+@item -mcpu=[210|340]
+Select the cpu type on the target hardware. This controls which instructions
+can be assembled.
+
+@item -EB
+Assemble for a big endian target.
+
+@item -EL
+Assemble for a little endian target.
+
+@end table
+@end ifset
+@c man end
+
+@ifset METAG
+
+@ifclear man
+@xref{Meta Options}, for the options available when @value{AS} is configured
+for a Meta processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for a
+Meta processor.
+@c man end
+@c man begin INCLUDE
+@include c-metag.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
+@c man begin OPTIONS
+@ifset MMIX
+See the info pages for documentation of the MMIX-specific options.
+@end ifset
+
+@ifset NDS32
+
+@ifclear man
+@xref{NDS32 Options}, for the options available when @value{AS} is configured
+for a NDS32 processor.
+@end ifclear
+@c ended inside the included file
+@end ifset
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for a
+NDS32 processor.
+@c man end
+@c man begin INCLUDE
+@include c-nds32.texi
+@c ended inside the included file
+@end ifset
+
+@c man end
+@ifset PPC
+
+@ifclear man
+@xref{PowerPC-Opts}, for the options available when @value{AS} is configured
+for a PowerPC processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for a
+PowerPC processor.
+@c man end
+@c man begin INCLUDE
+@include c-ppc.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
+@ifset RISCV
+
+@ifclear man
+@xref{RISC-V-Options}, for the options available when @value{AS} is configured
+for a RISC-V processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for a
+RISC-V processor.
+@c man end
+@c man begin INCLUDE
+@include c-riscv.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
+@c man begin OPTIONS
+@ifset RX
+See the info pages for documentation of the RX-specific options.
+@end ifset
+
+@ifset S390
+The following options are available when @value{AS} is configured for the s390
+processor family.
+
+@table @gcctabopt
+@item -m31
+@itemx -m64
+Select the word size, either 31/32 bits or 64 bits.
+@item -mesa
+@item -mzarch
+Select the architecture mode, either the Enterprise System
+Architecture (esa) or the z/Architecture mode (zarch).
+@item -march=@var{processor}
+Specify which s390 processor variant is the target, @samp{g5} (or
+@samp{arch3}), @samp{g6}, @samp{z900} (or @samp{arch5}), @samp{z990} (or
+@samp{arch6}), @samp{z9-109}, @samp{z9-ec} (or @samp{arch7}), @samp{z10} (or
+@samp{arch8}), @samp{z196} (or @samp{arch9}), @samp{zEC12} (or @samp{arch10}),
+@samp{z13} (or @samp{arch11}), or @samp{z14} (or @samp{arch12}).
+@item -mregnames
+@itemx -mno-regnames
+Allow or disallow symbolic names for registers.
+@item -mwarn-areg-zero
+Warn whenever the operand for a base or index register has been specified
+but evaluates to zero.
+@end table
+@end ifset
+@c man end
+
+@ifset TIC6X
+
+@ifclear man
+@xref{TIC6X Options}, for the options available when @value{AS} is configured
+for a TMS320C6000 processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for a
+TMS320C6000 processor.
+@c man end
+@c man begin INCLUDE
+@include c-tic6x.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
+@ifset TILEGX
+
+@ifclear man
+@xref{TILE-Gx Options}, for the options available when @value{AS} is configured
+for a TILE-Gx processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for a TILE-Gx
+processor.
+@c man end
+@c man begin INCLUDE
+@include c-tilegx.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
+@ifset VISIUM
+
+@ifclear man
+@xref{Visium Options}, for the options available when @value{AS} is configured
+for a Visium processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following option is available when @value{AS} is configured for a Visium
+processor.
+@c man end
+@c man begin INCLUDE
+@include c-visium.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
+@ifset XTENSA
+
+@ifclear man
+@xref{Xtensa Options}, for the options available when @value{AS} is configured
+for an Xtensa processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for an
+Xtensa processor.
+@c man end
+@c man begin INCLUDE
+@include c-xtensa.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
+
+@c man begin OPTIONS
+
+@ifset Z80
+The following options are available when @value{AS} is configured for
+a Z80 family processor.
+@table @gcctabopt
+@item -z80
+Assemble for Z80 processor.
+@item -r800
+Assemble for R800 processor.
+@item -ignore-undocumented-instructions
+@itemx -Wnud
+Assemble undocumented Z80 instructions that also work on R800 without warning.
+@item -ignore-unportable-instructions
+@itemx -Wnup
+Assemble all undocumented Z80 instructions without warning.
+@item -warn-undocumented-instructions
+@itemx -Wud
+Issue a warning for undocumented Z80 instructions that also work on R800.
+@item -warn-unportable-instructions
+@itemx -Wup
+Issue a warning for undocumented Z80 instructions that do not work on R800.
+@item -forbid-undocumented-instructions
+@itemx -Fud
+Treat all undocumented instructions as errors.
+@item -forbid-unportable-instructions
+@itemx -Fup
+Treat undocumented Z80 instructions that do not work on R800 as errors.
+@end table
+@end ifset
+
+@c man end
+
+@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} @command{@value{AS}}. We cover the syntax expected in source files, including
+notation for symbols, constants, and expressions; the directives that
+@command{@value{AS}} understands; and of course how to invoke @command{@value{AS}}.
+
+@ifclear GENERIC
+We also cover special features in the @value{TARGET}
+configuration of @command{@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}. For the H8/300H, see @cite{H8/300H Series
+Programming Manual} (Renesas).
+@end ifset
+@ifset SH
+For information on the Renesas (formerly Hitachi) / SuperH SH machine instruction set,
+see @cite{SH-Microcomputer User's Manual} (Renesas) or
+@cite{SH-4 32-bit CPU Core Architecture} (SuperH) and
+@cite{SuperH (SH) 64-Bit RISC Series} (SuperH).
+@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.
+
+@command{@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
+@command{@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
+
+@c man begin DESCRIPTION
+
+@sc{gnu} @command{as} is really a family of assemblers.
+@ifclear GENERIC
+This manual describes @command{@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
+@command{@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 @command{@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 @command{@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
+
+@c man end
+
+Unlike older assemblers, @command{@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
+For the @value{TARGET} target, @command{@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 HPPA
+On the @value{TARGET}, @command{@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 @command{@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 @command{@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
+@command{@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 @command{@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.
+
+@c man begin DESCRIPTION
+Each time you run @command{@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 @command{@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 @command{@value{AS}} no file names it attempts to read one input file
+from the @command{@value{AS}} standard input, which is normally your terminal. You
+may have to type @key{ctl-D} to tell @command{@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, @command{@value{AS}} produces a small, empty object
+file.
+
+@c man end
+
+@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 @command{@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 @command{@value{AS}} source
+is itself synthesized from other files. @command{@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 @command{@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 @code{a.out}.
+You can give it another name by using the @option{-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
+
+@c man begin DESCRIPTION
+
+@cindex error messages
+@cindex warning messages
+@cindex messages from assembler
+@command{@value{AS}} may write warnings and error messages to the standard error
+file (usually your terminal). This should not happen when a compiler
+runs @command{@value{AS}} automatically. Warnings report an assumption made so
+that @command{@value{AS}} could keep assembling a flawed program; errors report a
+grave problem that stops the assembly.
+
+@c man end
+
+@cindex format of warning messages
+Warning messages have the format
+
+@smallexample
+file_name:@b{NNN}:Warning Message Text
+@end smallexample
+
+@noindent
+@cindex file names and line numbers, in warnings/errors
+(where @b{NNN} is a line number). If both a logical file name
+(@pxref{File,,@code{.file}}) and a logical line number
+@ifset GENERIC
+(@pxref{Line,,@code{.line}})
+@end ifset
+have been given then they will be used, otherwise the file name and line number
+in the current assembler source file will be used. The message text is
+intended to be self explanatory (in the grand Unix tradition).
+
+Note the file name must be set via the logical version of the @code{.file}
+directive, not the DWARF2 version of the @code{.file} directive. For example:
+
+@smallexample
+ .file 2 "bar.c"
+ error_assembler_source
+ .file "foo.c"
+ .line 30
+ error_c_source
+@end smallexample
+
+produces this output:
+
+@smallexample
+ Assembler messages:
+ asm.s:2: Error: no such instruction: `error_assembler_source'
+ foo.c:31: Error: no such instruction: `error_c_source'
+@end smallexample
+
+@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; see @ref{Machine Dependencies},
+for options specific
+@ifclear GENERIC
+to the @value{TARGET} target.
+@end ifclear
+@ifset GENERIC
+to particular machine architectures.
+@end ifset
+
+@c man begin DESCRIPTION
+
+If you are invoking @command{@value{AS}} via the @sc{gnu} C compiler,
+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 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.)
+
+@c man end
+
+@menu
+* a:: -a[cdghlns] enable listings
+* alternate:: --alternate enable alternate macro syntax
+* 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 symbols
+* listing:: --listing-XXX to configure listing output
+* M:: -M or --mri to assemble in MRI compatibility mode
+* MD:: --MD for dependency tracking
+* no-pad-sections:: --no-pad-sections to stop section padding
+* 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, --no-warn, --warn, --fatal-warnings to control warnings
+* Z:: -Z to make object file even after errors
+@end menu
+
+@node a
+@section Enable Listings: @option{-a[cdghlns]}
+
+@kindex -a
+@kindex -ac
+@kindex -ad
+@kindex -ag
+@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{-ag} option to print a first section with general assembly
+information, like @value{AS} version, switches passed, or time stamp.
+
+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}.
+
+Note if the assembler source is coming from the standard input (e.g.,
+because it
+is being created by @code{@value{GCC}} and the @samp{-pipe} command line switch
+is being used) then the listing will not contain any comments or preprocessor
+directives. This is because the listing code buffers input source lines from
+stdin only after they have been preprocessed by the assembler. This reduces
+memory usage and makes the code more efficient.
+
+@node alternate
+@section @option{--alternate}
+
+@kindex --alternate
+Begin in alternate macro mode, see @ref{Altmacro,,@code{.altmacro}}.
+
+@node D
+@section @option{-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
+@command{@value{AS}}.
+
+@node f
+@section Work Faster: @option{-f}
+
+@kindex -f
+@cindex trusted compiler
+@cindex faster processing (@option{-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), @command{@value{AS}} does
+not work correctly.
+@end quotation
+
+@node I
+@section @code{.include} Search Path: @option{-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
+@command{@value{AS}} searches for files specified in @code{.include}
+directives (@pxref{Include,,@code{.include}}). You may use @option{-I} as
+many times as necessary to include a variety of paths. The current
+working directory is always searched first; after that, @command{@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: @option{-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
+@command{@value{AS}} sometimes alters the code emitted for directives of the
+form @samp{.word @var{sym1}-@var{sym2}}. @xref{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 Symbols: @option{-L}
+
+@kindex -L
+@cindex local symbols, retaining in output
+Symbols beginning with system-specific local label prefixes, typically
+@samp{.L} for ELF systems or @samp{L} for traditional a.out systems, are
+called @dfn{local symbols}. @xref{Symbol Names}. Normally you do not see
+such symbols when debugging, because they are intended for the use of
+programs (like compilers) that compose assembler programs, not for your
+notice. Normally both @command{@value{AS}} and @code{@value{LD}} discard
+such symbols, so you do not normally debug with them.
+
+This option tells @command{@value{AS}} to retain those local symbols
+in the object file. Usually if you do this you also tell the linker
+@code{@value{LD}} to preserve those symbols.
+
+@node listing
+@section Configuring listing output: @option{--listing}
+
+The listing feature of the assembler can be enabled via the command line switch
+@samp{-a} (@pxref{a}). This feature combines the input source file(s) with a
+hex dump of the corresponding locations in the output object file, and displays
+them as a listing file. The format of this listing can be controlled by
+directives inside the assembler source (i.e., @code{.list} (@pxref{List}),
+@code{.title} (@pxref{Title}), @code{.sbttl} (@pxref{Sbttl}),
+@code{.psize} (@pxref{Psize}), and
+@code{.eject} (@pxref{Eject}) and also by the following switches:
+
+@table @gcctabopt
+@item --listing-lhs-width=@samp{number}
+@kindex --listing-lhs-width
+@cindex Width of first line disassembly output
+Sets the maximum width, in words, of the first line of the hex byte dump. This
+dump appears on the left hand side of the listing output.
+
+@item --listing-lhs-width2=@samp{number}
+@kindex --listing-lhs-width2
+@cindex Width of continuation lines of disassembly output
+Sets the maximum width, in words, of any further lines of the hex byte dump for
+a given input source line. If this value is not specified, it defaults to being
+the same as the value specified for @samp{--listing-lhs-width}. If neither
+switch is used the default is to one.
+
+@item --listing-rhs-width=@samp{number}
+@kindex --listing-rhs-width
+@cindex Width of source line output
+Sets the maximum width, in characters, of the source line that is displayed
+alongside the hex dump. The default value for this parameter is 100. The
+source line is displayed on the right hand side of the listing output.
+
+@item --listing-cont-lines=@samp{number}
+@kindex --listing-cont-lines
+@cindex Maximum number of continuation lines
+Sets the maximum number of continuation lines of hex dump that will be
+displayed for a given single line of source input. The default value is 4.
+@end table
+
+@node M
+@section Assemble in MRI Compatibility Mode: @option{-M}
+
+@kindex -M
+@cindex MRI compatibility mode
+The @option{-M} or @option{--mri} option selects MRI compatibility mode. This
+changes the syntax and pseudo-op handling of @command{@value{AS}} to make it
+compatible with the @code{ASM68K} 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 @command{@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. @command{@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 @option{-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 @command{@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
+@command{@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. @command{@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.
+
+@end itemize
+
+@node MD
+@section Dependency Tracking: @option{--MD}
+
+@kindex --MD
+@cindex dependency tracking
+@cindex make rules
+
+@command{@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 no-pad-sections
+@section Output Section Padding
+@kindex --no-pad-sections
+@cindex output section padding
+Normally the assembler will pad the end of each output section up to its
+alignment boundary. But this can waste space, which can be significant on
+memory constrained targets. So the @option{--no-pad-sections} option will
+disable this behaviour.
+
+@node o
+@section Name the Object File: @option{-o}
+
+@kindex -o
+@cindex naming object file
+@cindex object file name
+There is always one object file output when you run @command{@value{AS}}. By
+default it has the name @file{a.out}.
+You use this option (which takes exactly one filename) to give the
+object file a different name.
+
+Whatever the object file is called, @command{@value{AS}} overwrites any
+existing file of the same name.
+
+@node R
+@section Join Data and Text Sections: @option{-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
+@option{-R} tells @command{@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 @option{-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 @command{@value{AS}}. In future, @option{-R} may work this way.
+
+@ifset COFF-ELF
+When @command{@value{AS}} is configured for COFF or ELF output,
+this option is only useful if you use sections named @samp{.text} and
+@samp{.data}.
+@end ifset
+
+@ifset HPPA
+@option{-R} is not supported for any of the HPPA targets. Using
+@option{-R} generates a warning from @command{@value{AS}}.
+@end ifset
+
+@node statistics
+@section Display Assembly Statistics: @option{--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
+@command{@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: @option{--traditional-format}
+
+@kindex --traditional-format
+For some targets, the output of @command{@value{AS}} is different in some ways
+from the output of some existing assembler. This switch requests
+@command{@value{AS}} to use the traditional format instead.
+
+For example, it disables the exception frame optimizations which
+@command{@value{AS}} normally does by default on @code{@value{GCC}} output.
+
+@node v
+@section Announce Version: @option{-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 Control Warnings: @option{-W}, @option{--warn}, @option{--no-warn}, @option{--fatal-warnings}
+
+@command{@value{AS}} should never give a warning or error message when
+assembling compiler output. But programs written by people often
+cause @command{@value{AS}} to give a warning that a particular assumption was
+made. All such warnings are directed to the standard error file.
+
+@kindex -W
+@kindex --no-warn
+@cindex suppressing warnings
+@cindex warnings, suppressing
+If you use the @option{-W} and @option{--no-warn} options, no warnings are issued.
+This only affects the warning messages: it does not change any particular of
+how @command{@value{AS}} assembles your file. Errors, which stop the assembly,
+are still reported.
+
+@kindex --fatal-warnings
+@cindex errors, caused by warnings
+@cindex warnings, causing error
+If you use the @option{--fatal-warnings} option, @command{@value{AS}} considers
+files that generate warnings to be in error.
+
+@kindex --warn
+@cindex warnings, switching on
+You can switch these options off again by specifying @option{--warn}, which
+causes warnings to be output as usual.
+
+@node Z
+@section Generate Object File in Spite of Errors: @option{-Z}
+@cindex object file, after errors
+@cindex errors, continuing after
+After an error message, @command{@value{AS}} normally produces no output. If for
+some reason you are interested in object file output even after
+@command{@value{AS}} gives an error message on your program, use the @samp{-Z}
+option. If there are any errors, @command{@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. @command{@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 @command{@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 @command{@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 @command{@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 a @dfn{line comment} character up to the next newline is
+considered a comment and is ignored. The line comment character is target
+specific, and some targets multiple comment characters. Some targets also have
+line comment characters that only work if they are the first character on a
+line. Some targets use a sequence of two characters to introduce a line
+comment. Some targets can also change their line comment characters depending
+upon command line options that have been used. For more details see the
+@emph{Syntax} section in the documentation for individual targets.
+
+If the line comment character is the hash sign (@samp{#}) then it still has the
+special ability to enable and disable preprocessing (@pxref{Preprocessing}) and
+to specify logical line numbers:
+
+@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 @command{@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. Multibyte characters
+are supported. 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}.
+
+Symbol names may also be enclosed in double quote @code{"} characters. In such
+cases any characters are allowed, except for the NUL character. If a double
+quote character is to be included in the symbol name it must be preceeded by a
+backslash @code{\} character.
+@cindex length of symbols
+
+@node Statements
+@section Statements
+
+@cindex statements, structure of
+@cindex line separator character
+@cindex statement separator character
+
+A @dfn{statement} ends at a newline character (@samp{\n}) or a
+@dfn{line separator character}. The line separator character is target
+specific and described in the @emph{Syntax} section of each
+target's documentation. Not all targets support a line separator character.
+The newline or line separator character is considered to be part of the
+preceding statement. Newlines and separators within character constants are an
+exception: they do not end statements.
+
+@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 @command{@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
+@command{@value{AS}} to interpret the second character literally as a backslash
+(which prevents @command{@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
+@c NOTE: Cindex entries must not start with a backlash character.
+@c NOTE: This confuses the pdf2texi script when it is creating the
+@c NOTE: index based upon the first character and so it generates:
+@c NOTE: \initial {\\}
+@c NOTE: which then results in the error message:
+@c NOTE: Argument of \\ has an extra }.
+@c NOTE: So in the index entries below a space character has been
+@c NOTE: prepended to avoid this problem.
+@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 backslash-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{backslash-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 @command{@value{AS}} has no
+other interpretation, so @command{@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. Some backslash escapes apply to characters, @code{\b},
+@code{\f}, @code{\n}, @code{\r}, @code{\t}, and @code{\"} with the same meaning
+as for strings, plus @code{\'} for a single quote. 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 H8
+(or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
+Renesas SH)
+@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. @command{@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
+@command{@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
+@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
+@command{@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 @command{@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 @command{@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 and Renesas / SuperH SH 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 HPPA architecture, the letter must be @samp{E} (upper case only).
+@end ifset
+@ifclear GENERIC
+@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
+@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.
+
+@command{@value{AS}} does all processing using integers. Flonums are computed
+independently of any floating point hardware in the computer running
+@command{@value{AS}}.
+
+@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 @command{@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 @command{@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 for the Renesas / SuperH SH,
+@command{@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 @command{@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-ELF
+@ifset GENERIC
+When it generates COFF or ELF output,
+@end ifset
+@command{@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 @command{@value{AS}} generates SOM or ELF output for the HPPA,
+@end ifset
+@command{@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, @command{@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, @command{@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 @command{@value{AS}} ever uses is expressed as
+@display
+(@var{section}) + (@var{offset into section})
+@end display
+@noindent
+Further, most expressions @command{@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 @command{@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-ELF
+@cindex named sections
+@cindex sections, named
+@item named sections
+@end ifset
+@ifset aout
+@cindex text section
+@cindex data section
+@itemx text section
+@itemx data section
+@end ifset
+These sections hold your program. @command{@value{AS}} and @code{@value{LD}} treat them as
+separate but equal sections. Anything you can say of one section is
+true of another.
+@c @ifset aout
+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.
+@c @end ifset
+
+@cindex bss section
+@item bss section
+This section contains zeroed bytes when your program begins running. It
+is used to hold uninitialized 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-ELF
+The example uses the traditional section names @samp{.text} and @samp{.data}.
+@end ifset
+Memory addresses are on the horizontal axis.
+
+@c TEXI2ROFF-KILL
+@ifnottex
+@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 ifnottex
+@need 5000
+@tex
+\bigskip
+\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 @command{@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 @command{@value{AS}}
+warning messages, so it might be helpful to have an idea of their
+meanings to @command{@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
+Assembled bytes
+@ifset COFF-ELF
+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
+data in named sections
+@end ifclear
+@ifset aout
+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. @command{@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 @command{@value{AS}}.)
+@end ifset
+@ifclear GENERIC
+@ifset H8
+On the H8/300 platform, each subsection is zero-padded to a word
+boundary (two bytes).
+The same is true on the Renesas SH.
+@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
+@ifset ELF
+@ifset GENERIC
+When generating ELF output, you
+@end ifset
+@ifclear GENERIC
+You
+@end ifclear
+can also use the @code{.subsection} directive (@pxref{SubSection})
+to specify a subsection: @samp{.subsection @var{expression}}.
+@end ifset
+@var{Expression} should be an absolute expression
+(@pxref{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 @command{@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 @ref{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:} @command{@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 @command{@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}}. In the same way, using a double
+equals sign @samp{=}@samp{=} here represents an equivalent of the
+@code{.eqv} directive. @xref{Eqv,,@code{.eqv}}.
+
+@ifset Blackfin
+Blackfin does not support symbol assignment with @samp{=}.
+@end ifset
+
+@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 for a
+particular target machine), and underscores.
+@end ifclear
+@ifset SPECIAL-SYMS
+@ifset H8
+Symbol names begin with a letter or with one of @samp{._}. On the
+Renesas SH 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}.
+
+Symbol names do not start with a digit. An exception to this rule is made for
+Local Labels. See below.
+
+Multibyte characters are supported. To generate a symbol name containing
+multibyte characters enclose it within double quotes and use escape codes. cf
+@xref{Strings}. Generating a multibyte symbol name from a label is not
+currently supported.
+
+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
+A local symbol is any symbol beginning with certain local label prefixes.
+By default, the local label prefix is @samp{.L} for ELF systems or
+@samp{L} for traditional a.out systems, but each target may have its own
+set of local label prefixes.
+@ifset HPPA
+On the HPPA local symbols begin with @samp{L$}.
+@end ifset
+
+Local symbols are defined and used within the assembler, but they are
+normally not saved in object files. Thus, they are not visible when debugging.
+You may use the @samp{-L} option (@pxref{L, ,Include Local Symbols})
+to retain the local symbols in the object files.
+
+@subheading Local Labels
+
+@cindex local labels
+@cindex temporary symbol names
+@cindex symbol names, temporary
+Local labels are different from local symbols. Local labels help compilers and
+programmers use names temporarily. They create symbols which are guaranteed to
+be unique over the entire scope of the input source code and which can be
+referred to by a simple notation. To define a local label, write a label of
+the form @samp{@b{N}:} (where @b{N} represents any non-negative integer).
+To refer to the most recent previous definition of that label write
+@samp{@b{N}b}, using the same number as when you defined the label. To refer
+to the next definition of a local label, write @samp{@b{N}f}. The @samp{b}
+stands for ``backwards'' and the @samp{f} stands for ``forwards''.
+
+There is no restriction on how you can use these labels, and you can reuse them
+too. So that it is possible to repeatedly define the same local label (using
+the same number @samp{@b{N}}), although you can only refer to the most recently
+defined local label of that number (for a backwards reference) or the next
+definition of a specific local label for a forward reference. It is also worth
+noting that the first 10 local labels (@samp{@b{0:}}@dots{}@samp{@b{9:}}) are
+implemented in a slightly more efficient manner than the others.
+
+Here is an example:
+
+@smallexample
+1: branch 1f
+2: branch 1b
+1: branch 2f
+2: branch 1b
+@end smallexample
+
+Which is the equivalent of:
+
+@smallexample
+label_1: branch label_3
+label_2: branch label_1
+label_3: branch label_4
+label_4: branch label_3
+@end smallexample
+
+Local label names are only a notational device. They are immediately
+transformed into more conventional symbol names before the assembler uses them.
+The symbol names are stored in the symbol table, appear in error messages, and
+are optionally emitted to the object file. The names are constructed using
+these parts:
+
+@table @code
+@item @emph{local label prefix}
+All local symbols begin with the system-specific local label prefix.
+Normally both @command{@value{AS}} and @code{@value{LD}} forget symbols
+that start with the local label prefix. These labels are
+used for symbols you are never intended to see. If you use the
+@samp{-L} option then @command{@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{number}
+This is the number that was used in the local label definition. So if the
+label is written @samp{55:} then the number is @samp{55}.
+
+@item @kbd{C-B}
+This unusual character is included so you do not accidentally invent a symbol
+of the same name. The character has ASCII value of @samp{\002} (control-B).
+
+@item @emph{ordinal number}
+This is a serial number to keep the labels distinct. The first definition of
+@samp{0:} gets the number @samp{1}. The 15th definition of @samp{0:} gets the
+number @samp{15}, and so on. Likewise the first definition of @samp{1:} gets
+the number @samp{1} and its 15th definition gets @samp{15} as well.
+@end table
+
+So for example, the first @code{1:} may be named @code{.L1@kbd{C-B}1}, and
+the 44th @code{3:} may be named @code{.L3@kbd{C-B}44}.
+
+@subheading Dollar Local Labels
+@cindex dollar local symbols
+
+On some targets @code{@value{AS}} also supports an even more local form of
+local labels called dollar labels. These labels go out of scope (i.e., they
+become undefined) as soon as a non-local label is defined. Thus they remain
+valid for only a small region of the input source code. Normal local labels,
+by contrast, remain in scope for the entire file, or until they are redefined
+by another occurrence of the same local label.
+
+Dollar labels are defined in exactly the same way as ordinary local labels,
+except that they have a dollar sign suffix to their numeric value, e.g.,
+@samp{@b{55$:}}.
+
+They can also be distinguished from ordinary local labels by their transformed
+names which use ASCII character @samp{\001} (control-A) as the magic character
+to distinguish them from ordinary labels. For example, the fifth definition of
+@samp{6$} may be named @samp{.L6@kbd{C-A}5}.
+
+@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
+@command{@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.
+@ifclear no-space-dir
+Thus, the expression @samp{.=.+4} is the same as saying
+@samp{.space 4}.
+@end ifclear
+
+@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, @command{@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
+* a.out Symbols:: Symbol Attributes: @code{a.out}
+@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
+@node a.out Symbols
+@subsection Symbol Attributes: @code{a.out}
+
+@cindex @code{a.out} symbol attributes
+@cindex symbol attributes, @code{a.out}
+
+@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
+@command{@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 @command{@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 @command{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
+@code{.size}, @code{.tag}, and @code{.weak} 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 @command{@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.
+@command{@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 @command{@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 @command{@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
+@command{@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 @option{-}, 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 <<
+@dfn{Shift Left}. Same as the C operator @samp{<<}.
+
+@item >>
+@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
+Low 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 ?
+
+@cindex comparison expressions
+@cindex expressions, comparison
+@item ==
+@dfn{Is Equal To}
+@item <>
+@itemx !=
+@dfn{Is Not Equal To}
+@item <
+@dfn{Is Less Than}
+@item >
+@dfn{Is Greater Than}
+@item >=
+@dfn{Is Greater Than Or Equal To}
+@item <=
+@dfn{Is Less Than Or Equal To}
+
+The comparison operators can be used as infix operators. A true results has a
+value of -1 whereas a false result has a value of 0. Note, these operators
+perform signed comparisons.
+@end table
+
+@item Lowest Precedence
+
+@table @code
+@item &&
+@dfn{Logical And}.
+
+@item ||
+@dfn{Logical Or}.
+
+These two logical operations can be used to combine the results of sub
+expressions. Note, unlike the comparison operators a true result returns a
+value of 1 but a false results does still return 0. Also note that the logical
+or operator has a slightly lower precedence than logical and.
+
+@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 names are case insensitive for most targets, and usually written
+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 (COFF):: @code{.ABORT}
+@end ifset
+
+* Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
+* Altmacro:: @code{.altmacro}
+* Ascii:: @code{.ascii "@var{string}"}@dots{}
+* Asciz:: @code{.asciz "@var{string}"}@dots{}
+* Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}}
+* Bundle directives:: @code{.bundle_align_mode @var{abs-expr}}, etc
+* Byte:: @code{.byte @var{expressions}}
+* CFI directives:: @code{.cfi_startproc [simple]}, @code{.cfi_endproc}, etc.
+* Comm:: @code{.comm @var{symbol} , @var{length} }
+* Data:: @code{.data @var{subsection}}
+* Dc:: @code{.dc[@var{size}] @var{expressions}}
+* Dcb:: @code{.dcb[@var{size}] @var{number} [,@var{fill}]}
+* Ds:: @code{.ds[@var{size}] @var{number} [,@var{fill}]}
+@ifset COFF
+* Def:: @code{.def @var{name}}
+@end ifset
+@ifset aout
+* 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}
+* Elseif:: @code{.elseif}
+* 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}}
+* Eqv:: @code{.eqv @var{symbol}, @var{expression}}
+* Err:: @code{.err}
+* Error:: @code{.error @var{string}}
+* Exitm:: @code{.exitm}
+* Extern:: @code{.extern}
+* Fail:: @code{.fail}
+* File:: @code{.file}
+* 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}}
+@ifset ELF
+* Gnu_attribute:: @code{.gnu_attribute @var{tag},@var{value}}
+* Hidden:: @code{.hidden @var{names}}
+@end ifset
+
+* hword:: @code{.hword @var{expressions}}
+* Ident:: @code{.ident}
+* If:: @code{.if @var{absolute expression}}
+* Incbin:: @code{.incbin "@var{file}"[,@var{skip}[,@var{count}]]}
+* Include:: @code{.include "@var{file}"}
+* Int:: @code{.int @var{expressions}}
+@ifset ELF
+* Internal:: @code{.internal @var{names}}
+@end ifset
+
+* 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
+
+* Linkonce:: @code{.linkonce [@var{type}]}
+* List:: @code{.list}
+* Ln:: @code{.ln @var{line-number}}
+* Loc:: @code{.loc @var{fileno} @var{lineno}}
+* Loc_mark_labels:: @code{.loc_mark_labels @var{enable}}
+@ifset ELF
+* Local:: @code{.local @var{names}}
+@end ifset
+
+* 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}}
+* Noaltmacro:: @code{.noaltmacro}
+* Nolist:: @code{.nolist}
+* Nops:: @code{.nops @var{size}[, @var{control}]}
+* Octa:: @code{.octa @var{bignums}}
+* Offset:: @code{.offset @var{loc}}
+* Org:: @code{.org @var{new-lc}, @var{fill}}
+* P2align:: @code{.p2align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
+@ifset ELF
+* PopSection:: @code{.popsection}
+* Previous:: @code{.previous}
+@end ifset
+
+* Print:: @code{.print @var{string}}
+@ifset ELF
+* Protected:: @code{.protected @var{names}}
+@end ifset
+
+* Psize:: @code{.psize @var{lines}, @var{columns}}
+* Purgem:: @code{.purgem @var{name}}
+@ifset ELF
+* PushSection:: @code{.pushsection @var{name}}
+@end ifset
+
+* Quad:: @code{.quad @var{bignums}}
+* Reloc:: @code{.reloc @var{offset}, @var{reloc_name}[, @var{expression}]}
+* Rept:: @code{.rept @var{count}}
+* Sbttl:: @code{.sbttl "@var{subheading}"}
+@ifset COFF
+* Scl:: @code{.scl @var{class}}
+@end ifset
+@ifset COFF-ELF
+* Section:: @code{.section @var{name}[, @var{flags}]}
+@end ifset
+
+* Set:: @code{.set @var{symbol}, @var{expression}}
+* Short:: @code{.short @var{expressions}}
+* Single:: @code{.single @var{flonums}}
+@ifset COFF-ELF
+* Size:: @code{.size [@var{name} , @var{expression}]}
+@end ifset
+@ifclear no-space-dir
+* Skip:: @code{.skip @var{size} [,@var{fill}]}
+@end ifclear
+
+* Sleb128:: @code{.sleb128 @var{expressions}}
+@ifclear no-space-dir
+* Space:: @code{.space @var{size} [,@var{fill}]}
+@end ifclear
+@ifset have-stabs
+* Stab:: @code{.stabd, .stabn, .stabs}
+@end ifset
+
+* String:: @code{.string "@var{str}"}, @code{.string8 "@var{str}"}, @code{.string16 "@var{str}"}, @code{.string32 "@var{str}"}, @code{.string64 "@var{str}"}
+* Struct:: @code{.struct @var{expression}}
+@ifset ELF
+* SubSection:: @code{.subsection}
+* 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-ELF
+* Type:: @code{.type <@var{int} | @var{name} , @var{type description}>}
+@end ifset
+
+* Uleb128:: @code{.uleb128 @var{expressions}}
+@ifset COFF
+* Val:: @code{.val @var{addr}}
+@end ifset
+
+@ifset ELF
+* Version:: @code{.version "@var{string}"}
+* VTableEntry:: @code{.vtable_entry @var{table}, @var{offset}}
+* VTableInherit:: @code{.vtable_inherit @var{child}, @var{parent}}
+@end ifset
+
+* Warning:: @code{.warning @var{string}}
+* Weak:: @code{.weak @var{names}}
+* Weakref:: @code{.weakref @var{alias}, @var{symbol}}
+* Word:: @code{.word @var{expressions}}
+@ifclear no-space-dir
+* Zero:: @code{.zero @var{size}}
+@end ifclear
+@ifset ELF
+* 2byte:: @code{.2byte @var{expressions}}
+* 4byte:: @code{.4byte @var{expressions}}
+* 8byte:: @code{.8byte @var{bignums}}
+@end ifset
+* 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 @command{@value{AS}} to
+quit also. One day @code{.abort} will not be supported.
+
+@ifset COFF
+@node ABORT (COFF)
+@section @code{.ABORT} (COFF)
+
+@cindex @code{ABORT} directive
+When producing COFF output, @command{@value{AS}} accepts this directive as a
+synonym for @samp{.abort}.
+
+@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 most 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 arc, hppa, i386 using ELF, iq2000, m68k, or1k,
+s390, sparc, tic4x, tic80 and xtensa, 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 the tic54x, the
+first expression is the alignment request in words.
+
+For other systems, including ppc, i386 using a.out format, arm and
+strongarm, 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 Altmacro
+@section @code{.altmacro}
+Enable alternate macro mode, enabling:
+
+@ftable @code
+@item LOCAL @var{name} [ , @dots{} ]
+One additional directive, @code{LOCAL}, is available. It is used to
+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.
+
+@item String delimiters
+You can write strings delimited in these other ways besides
+@code{"@var{string}"}:
+
+@table @code
+@item '@var{string}'
+You can delimit strings with single-quote characters.
+
+@item <@var{string}>
+You can delimit strings with matching angle brackets.
+@end table
+
+@item single-character string escape
+To include any single character literally in a string (even if the
+character would otherwise have some special meaning), you can prefix the
+character with @samp{!} (an exclamation mark). For example, you can
+write @samp{<4.3 !> 5.4!!>} to get the literal text @samp{4.3 > 5.4!}.
+
+@item Expression results as strings
+You can write @samp{%@var{expr}} to evaluate the expression @var{expr}
+and use the result as a string.
+@end ftable
+
+@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 most 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 Bundle directives
+@section Bundle directives
+@subsection @code{.bundle_align_mode @var{abs-expr}}
+@cindex @code{bundle_align_mode} directive
+@cindex bundle
+@cindex instruction bundle
+@cindex aligned instruction bundle
+@code{.bundle_align_mode} enables or disables @dfn{aligned instruction
+bundle} mode. In this mode, sequences of adjacent instructions are grouped
+into fixed-sized @dfn{bundles}. If the argument is zero, this mode is
+disabled (which is the default state). If the argument it not zero, it
+gives the size of an instruction bundle as a power of two (as for the
+@code{.p2align} directive, @pxref{P2align}).
+
+For some targets, it's an ABI requirement that no instruction may span a
+certain aligned boundary. A @dfn{bundle} is simply a sequence of
+instructions that starts on an aligned boundary. For example, if
+@var{abs-expr} is @code{5} then the bundle size is 32, so each aligned
+chunk of 32 bytes is a bundle. When aligned instruction bundle mode is in
+effect, no single instruction may span a boundary between bundles. If an
+instruction would start too close to the end of a bundle for the length of
+that particular instruction to fit within the bundle, then the space at the
+end of that bundle is filled with no-op instructions so the instruction
+starts in the next bundle. As a corollary, it's an error if any single
+instruction's encoding is longer than the bundle size.
+
+@subsection @code{.bundle_lock} and @code{.bundle_unlock}
+@cindex @code{bundle_lock} directive
+@cindex @code{bundle_unlock} directive
+The @code{.bundle_lock} and directive @code{.bundle_unlock} directives
+allow explicit control over instruction bundle padding. These directives
+are only valid when @code{.bundle_align_mode} has been used to enable
+aligned instruction bundle mode. It's an error if they appear when
+@code{.bundle_align_mode} has not been used at all, or when the last
+directive was @w{@code{.bundle_align_mode 0}}.
+
+@cindex bundle-locked
+For some targets, it's an ABI requirement that certain instructions may
+appear only as part of specified permissible sequences of multiple
+instructions, all within the same bundle. A pair of @code{.bundle_lock}
+and @code{.bundle_unlock} directives define a @dfn{bundle-locked}
+instruction sequence. For purposes of aligned instruction bundle mode, a
+sequence starting with @code{.bundle_lock} and ending with
+@code{.bundle_unlock} is treated as a single instruction. That is, the
+entire sequence must fit into a single bundle and may not span a bundle
+boundary. If necessary, no-op instructions will be inserted before the
+first instruction of the sequence so that the whole sequence starts on an
+aligned bundle boundary. It's an error if the sequence is longer than the
+bundle size.
+
+For convenience when using @code{.bundle_lock} and @code{.bundle_unlock}
+inside assembler macros (@pxref{Macro}), bundle-locked sequences may be
+nested. That is, a second @code{.bundle_lock} directive before the next
+@code{.bundle_unlock} directive has no effect except that it must be
+matched by another closing @code{.bundle_unlock} so that there is the
+same number of @code{.bundle_lock} and @code{.bundle_unlock} directives.
+
+@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 CFI directives
+@section CFI directives
+@subsection @code{.cfi_sections @var{section_list}}
+@cindex @code{cfi_sections} directive
+@code{.cfi_sections} may be used to specify whether CFI directives
+should emit @code{.eh_frame} section and/or @code{.debug_frame} section.
+If @var{section_list} is @code{.eh_frame}, @code{.eh_frame} is emitted,
+if @var{section_list} is @code{.debug_frame}, @code{.debug_frame} is emitted.
+To emit both use @code{.eh_frame, .debug_frame}. The default if this
+directive is not used is @code{.cfi_sections .eh_frame}.
+
+On targets that support compact unwinding tables these can be generated
+by specifying @code{.eh_frame_entry} instead of @code{.eh_frame}.
+
+Some targets may support an additional name, such as @code{.c6xabi.exidx}
+which is used by the @value{TIC6X} target.
+
+The @code{.cfi_sections} directive can be repeated, with the same or different
+arguments, provided that CFI generation has not yet started. Once CFI
+generation has started however the section list is fixed and any attempts to
+redefine it will result in an error.
+
+@subsection @code{.cfi_startproc [simple]}
+@cindex @code{cfi_startproc} directive
+@code{.cfi_startproc} is used at the beginning of each function that
+should have an entry in @code{.eh_frame}. It initializes some internal
+data structures. Don't forget to close the function by
+@code{.cfi_endproc}.
+
+Unless @code{.cfi_startproc} is used along with parameter @code{simple}
+it also emits some architecture dependent initial CFI instructions.
+
+@subsection @code{.cfi_endproc}
+@cindex @code{cfi_endproc} directive
+@code{.cfi_endproc} is used at the end of a function where it closes its
+unwind entry previously opened by
+@code{.cfi_startproc}, and emits it to @code{.eh_frame}.
+
+@subsection @code{.cfi_personality @var{encoding} [, @var{exp}]}
+@cindex @code{cfi_personality} directive
+@code{.cfi_personality} defines personality routine and its encoding.
+@var{encoding} must be a constant determining how the personality
+should be encoded. If it is 255 (@code{DW_EH_PE_omit}), second
+argument is not present, otherwise second argument should be
+a constant or a symbol name. When using indirect encodings,
+the symbol provided should be the location where personality
+can be loaded from, not the personality routine itself.
+The default after @code{.cfi_startproc} is @code{.cfi_personality 0xff},
+no personality routine.
+
+@subsection @code{.cfi_personality_id @var{id}}
+@cindex @code{cfi_personality_id} directive
+@code{cfi_personality_id} defines a personality routine by its index as
+defined in a compact unwinding format.
+Only valid when generating compact EH frames (i.e.
+with @code{.cfi_sections eh_frame_entry}.
+
+@subsection @code{.cfi_fde_data [@var{opcode1} [, @dots{}]]}
+@cindex @code{cfi_fde_data} directive
+@code{cfi_fde_data} is used to describe the compact unwind opcodes to be
+used for the current function. These are emitted inline in the
+@code{.eh_frame_entry} section if small enough and there is no LSDA, or
+in the @code{.gnu.extab} section otherwise.
+Only valid when generating compact EH frames (i.e.
+with @code{.cfi_sections eh_frame_entry}.
+
+@subsection @code{.cfi_lsda @var{encoding} [, @var{exp}]}
+@code{.cfi_lsda} defines LSDA and its encoding.
+@var{encoding} must be a constant determining how the LSDA
+should be encoded. If it is 255 (@code{DW_EH_PE_omit}), the second
+argument is not present, otherwise the second argument should be a constant
+or a symbol name. The default after @code{.cfi_startproc} is @code{.cfi_lsda 0xff},
+meaning that no LSDA is present.
+
+@subsection @code{.cfi_inline_lsda} [@var{align}]
+@code{.cfi_inline_lsda} marks the start of a LSDA data section and
+switches to the corresponding @code{.gnu.extab} section.
+Must be preceded by a CFI block containing a @code{.cfi_lsda} directive.
+Only valid when generating compact EH frames (i.e.
+with @code{.cfi_sections eh_frame_entry}.
+
+The table header and unwinding opcodes will be generated at this point,
+so that they are immediately followed by the LSDA data. The symbol
+referenced by the @code{.cfi_lsda} directive should still be defined
+in case a fallback FDE based encoding is used. The LSDA data is terminated
+by a section directive.
+
+The optional @var{align} argument specifies the alignment required.
+The alignment is specified as a power of two, as with the
+@code{.p2align} directive.
+
+@subsection @code{.cfi_def_cfa @var{register}, @var{offset}}
+@code{.cfi_def_cfa} defines a rule for computing CFA as: @i{take
+address from @var{register} and add @var{offset} to it}.
+
+@subsection @code{.cfi_def_cfa_register @var{register}}
+@code{.cfi_def_cfa_register} modifies a rule for computing CFA. From
+now on @var{register} will be used instead of the old one. Offset
+remains the same.
+
+@subsection @code{.cfi_def_cfa_offset @var{offset}}
+@code{.cfi_def_cfa_offset} modifies a rule for computing CFA. Register
+remains the same, but @var{offset} is new. Note that it is the
+absolute offset that will be added to a defined register to compute
+CFA address.
+
+@subsection @code{.cfi_adjust_cfa_offset @var{offset}}
+Same as @code{.cfi_def_cfa_offset} but @var{offset} is a relative
+value that is added/subtracted from the previous offset.
+
+@subsection @code{.cfi_offset @var{register}, @var{offset}}
+Previous value of @var{register} is saved at offset @var{offset} from
+CFA.
+
+@subsection @code{.cfi_val_offset @var{register}, @var{offset}}
+Previous value of @var{register} is CFA + @var{offset}.
+
+@subsection @code{.cfi_rel_offset @var{register}, @var{offset}}
+Previous value of @var{register} is saved at offset @var{offset} from
+the current CFA register. This is transformed to @code{.cfi_offset}
+using the known displacement of the CFA register from the CFA.
+This is often easier to use, because the number will match the
+code it's annotating.
+
+@subsection @code{.cfi_register @var{register1}, @var{register2}}
+Previous value of @var{register1} is saved in register @var{register2}.
+
+@subsection @code{.cfi_restore @var{register}}
+@code{.cfi_restore} says that the rule for @var{register} is now the
+same as it was at the beginning of the function, after all initial
+instruction added by @code{.cfi_startproc} were executed.
+
+@subsection @code{.cfi_undefined @var{register}}
+From now on the previous value of @var{register} can't be restored anymore.
+
+@subsection @code{.cfi_same_value @var{register}}
+Current value of @var{register} is the same like in the previous frame,
+i.e. no restoration needed.
+
+@subsection @code{.cfi_remember_state} and @code{.cfi_restore_state}
+@code{.cfi_remember_state} pushes the set of rules for every register onto an
+implicit stack, while @code{.cfi_restore_state} pops them off the stack and
+places them in the current row. This is useful for situations where you have
+multiple @code{.cfi_*} directives that need to be undone due to the control
+flow of the program. For example, we could have something like this (assuming
+the CFA is the value of @code{rbp}):
+
+@smallexample
+ je label
+ popq %rbx
+ .cfi_restore %rbx
+ popq %r12
+ .cfi_restore %r12
+ popq %rbp
+ .cfi_restore %rbp
+ .cfi_def_cfa %rsp, 8
+ ret
+label:
+ /* Do something else */
+@end smallexample
+
+Here, we want the @code{.cfi} directives to affect only the rows corresponding
+to the instructions before @code{label}. This means we'd have to add multiple
+@code{.cfi} directives after @code{label} to recreate the original save
+locations of the registers, as well as setting the CFA back to the value of
+@code{rbp}. This would be clumsy, and result in a larger binary size. Instead,
+we can write:
+
+@smallexample
+ je label
+ popq %rbx
+ .cfi_remember_state
+ .cfi_restore %rbx
+ popq %r12
+ .cfi_restore %r12
+ popq %rbp
+ .cfi_restore %rbp
+ .cfi_def_cfa %rsp, 8
+ ret
+label:
+ .cfi_restore_state
+ /* Do something else */
+@end smallexample
+
+That way, the rules for the instructions after @code{label} will be the same
+as before the first @code{.cfi_restore} without having to use multiple
+@code{.cfi} directives.
+
+@subsection @code{.cfi_return_column @var{register}}
+Change return column @var{register}, i.e. the return address is either
+directly in @var{register} or can be accessed by rules for @var{register}.
+
+@subsection @code{.cfi_signal_frame}
+Mark current function as signal trampoline.
+
+@subsection @code{.cfi_window_save}
+SPARC register window has been saved.
+
+@subsection @code{.cfi_escape} @var{expression}[, @dots{}]
+Allows the user to add arbitrary bytes to the unwind info. One
+might use this to add OS-specific CFI opcodes, or generic CFI
+opcodes that GAS does not yet support.
+
+@subsection @code{.cfi_val_encoded_addr @var{register}, @var{encoding}, @var{label}}
+The current value of @var{register} is @var{label}. The value of @var{label}
+will be encoded in the output file according to @var{encoding}; see the
+description of @code{.cfi_personality} for details on this encoding.
+
+The usefulness of equating a register to a fixed label is probably
+limited to the return address register. Here, it can be useful to
+mark a code segment that has only one return address which is reached
+by a direct branch and no copy of the return address exists in memory
+or another register.
+
+@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 COFF-ELF
+When using ELF or (as a GNU extension) PE, the @code{.comm} directive takes
+an optional third argument. This is the desired alignment of the symbol,
+specified for ELF as a byte boundary (for example, an alignment of 16 means
+that the least significant 4 bits of the address should be zero), and for PE
+as a power of two (for example, an alignment of 5 means aligned to a 32-byte
+boundary). 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, @command{@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 on ELF, or the default section alignment of 4 on PE@footnote{This
+is not the same as the executable image file alignment controlled by @code{@value{LD}}'s
+@samp{--section-alignment} option; image file sections in PE are aligned to
+multiples of 4096, which is far too large an alignment for ordinary variables.
+It is rather the default alignment for (non-debug) sections within object
+(@samp{*.o}) files, which are less strictly aligned.}.
+@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 @command{@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.
+
+@node Dc
+@section @code{.dc[@var{size}] @var{expressions}}
+@cindex @code{dc} directive
+
+The @code{.dc} directive expects zero or more @var{expressions} separated by
+commas. These expressions are evaluated and their values inserted into the
+current section. The size of the emitted value depends upon the suffix to the
+@code{.dc} directive:
+
+@table @code
+@item @samp{.a}
+Emits N-bit values, where N is the size of an address on the target system.
+@item @samp{.b}
+Emits 8-bit values.
+@item @samp{.d}
+Emits double precision floating-point values.
+@item @samp{.l}
+Emits 32-bit values.
+@item @samp{.s}
+Emits single precision floating-point values.
+@item @samp{.w}
+Emits 16-bit values.
+Note - this is true even on targets where the @code{.word} directive would emit
+32-bit values.
+@item @samp{.x}
+Emits long double precision floating-point values.
+@end table
+
+If no suffix is used then @samp{.w} is assumed.
+
+The byte ordering is target dependent, as is the size and format of floating
+point values.
+
+@node Dcb
+@section @code{.dcb[@var{size}] @var{number} [,@var{fill}]}
+@cindex @code{dcb} directive
+This directive emits @var{number} copies of @var{fill}, each of @var{size}
+bytes. Both @var{number} and @var{fill} are absolute expressions. If the
+comma and @var{fill} are omitted, @var{fill} is assumed to be zero. The
+@var{size} suffix, if present, must be one of:
+
+@table @code
+@item @samp{.b}
+Emits single byte values.
+@item @samp{.d}
+Emits double-precision floating point values.
+@item @samp{.l}
+Emits 4-byte values.
+@item @samp{.s}
+Emits single-precision floating point values.
+@item @samp{.w}
+Emits 2-byte values.
+@item @samp{.x}
+Emits long double-precision floating point values.
+@end table
+
+If the @var{size} suffix is omitted then @samp{.w} is assumed.
+
+The byte ordering is target dependent, as is the size and format of floating
+point values.
+
+@node Ds
+@section @code{.ds[@var{size}] @var{number} [,@var{fill}]}
+@cindex @code{ds} directive
+This directive emits @var{number} copies of @var{fill}, each of @var{size}
+bytes. Both @var{number} and @var{fill} are absolute expressions. If the
+comma and @var{fill} are omitted, @var{fill} is assumed to be zero. The
+@var{size} suffix, if present, must be one of:
+
+@table @code
+@item @samp{.b}
+Emits single byte values.
+@item @samp{.d}
+Emits 8-byte values.
+@item @samp{.l}
+Emits 4-byte values.
+@item @samp{.p}
+Emits 12-byte values.
+@item @samp{.s}
+Emits 4-byte values.
+@item @samp{.w}
+Emits 2-byte values.
+@item @samp{.x}
+Emits 12-byte values.
+@end table
+
+Note - unlike the @code{.dcb} directive the @samp{.d}, @samp{.s} and @samp{.x}
+suffixes do not indicate that floating-point values are to be inserted.
+
+If the @var{size} suffix is omitted then @samp{.w} is assumed.
+
+The byte ordering is target dependent.
+
+
+@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.
+@end ifset
+
+@ifset aout
+@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 @command{@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, @command{@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.
+@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
+@command{@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 @command{@value{AS}} support for conditional
+assembly; see @ref{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 Elseif
+@section @code{.elseif}
+
+@cindex @code{elseif} directive
+@code{.elseif} is part of the @command{@value{AS}} support for conditional
+assembly; see @ref{If,,@code{.if}}. It is shorthand for beginning a new
+@code{.if} block that would otherwise fill the entire @code{.else} section.
+
+@node End
+@section @code{.end}
+
+@cindex @code{end} directive
+@code{.end} marks the end of the assembly file. @command{@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}.
+@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 @command{@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}; see @ref{Set,,@code{.set}}.
+
+@ifset HPPA
+The syntax for @code{equ} on the HPPA is
+@samp{@var{symbol} .equ @var{expression}}.
+@end ifset
+
+@ifset Z80
+The syntax for @code{equ} on the Z80 is
+@samp{@var{symbol} equ @var{expression}}.
+On the Z80 it is an error if @var{symbol} is already defined,
+but the symbol is not protected from later redefinition.
+Compare @ref{Equiv}.
+@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. Note a
+symbol which has been referenced but not actually defined is considered to be
+undefined.
+
+Except for the contents of the error message, this is roughly equivalent to
+@smallexample
+.ifdef SYM
+.err
+.endif
+.equ SYM,VAL
+@end smallexample
+plus it protects the symbol from later redefinition.
+
+@node Eqv
+@section @code{.eqv @var{symbol}, @var{expression}}
+@cindex @code{eqv} directive
+The @code{.eqv} directive is like @code{.equiv}, but no attempt is made to
+evaluate the expression or any part of it immediately. Instead each time
+the resulting symbol is used in an expression, a snapshot of its current
+value is taken.
+
+@node Err
+@section @code{.err}
+@cindex @code{err} directive
+If @command{@value{AS}} assembles a @code{.err} directive, it will print an error
+message and, unless the @option{-Z} option was used, it will not generate an
+object file. This can be used to signal an error in conditionally compiled code.
+
+@node Error
+@section @code{.error "@var{string}"}
+@cindex error directive
+
+Similarly to @code{.err}, this directive emits an error, but you can specify a
+string that will be emitted as the error message. If you don't specify the
+message, it defaults to @code{".error directive invoked in source file"}.
+@xref{Errors, ,Error and Warning Messages}.
+
+@smallexample
+ .error "This code has not been assembled and tested."
+@end smallexample
+
+@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. @command{@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, @command{@value{AS}} will print a warning message. If the value is less
+than 500, @command{@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.
+
+@node File
+@section @code{.file}
+@cindex @code{file} directive
+
+@ifclear no-file-dir
+There are two different versions of the @code{.file} directive. Targets
+that support DWARF2 line number information use the DWARF2 version of
+@code{.file}. Other targets use the default version.
+
+@subheading Default Version
+
+@cindex logical file name
+@cindex file name, logical
+This version of the @code{.file} directive tells @command{@value{AS}} that we
+are about to start a new logical file. The syntax is:
+
+@smallexample
+.file @var{string}
+@end smallexample
+
+@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 @command{@value{AS}} programs.
+
+@subheading DWARF2 Version
+@end ifclear
+
+When emitting DWARF2 line number information, @code{.file} assigns filenames
+to the @code{.debug_line} file name table. The syntax is:
+
+@smallexample
+.file @var{fileno} @var{filename}
+@end smallexample
+
+The @var{fileno} operand should be a unique positive integer to use as the
+index of the entry in the table. The @var{filename} operand is a C string
+literal.
+
+The detail of filename indices is exposed to the user because the filename
+table is shared with the @code{.debug_info} section of the DWARF2 debugging
+information, and thus the user must know the exact indices that table
+entries will have.
+
+@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{repeat}, @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 @command{@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
+@command{@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
+
+@ifset ELF
+@node Gnu_attribute
+@section @code{.gnu_attribute @var{tag},@var{value}}
+Record a @sc{gnu} object attribute for this file. @xref{Object Attributes}.
+
+@node Hidden
+@section @code{.hidden @var{names}}
+
+@cindex @code{hidden} directive
+@cindex visibility
+This is one of the ELF visibility directives. The other two are
+@code{.internal} (@pxref{Internal,,@code{.internal}}) and
+@code{.protected} (@pxref{Protected,,@code{.protected}}).
+
+This directive overrides the named symbols default visibility (which is set by
+their binding: local, global or weak). The directive sets the visibility to
+@code{hidden} which means that the symbols are not visible to other components.
+Such symbols are always considered to be @code{protected} as well.
+@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. The
+behavior of this directive varies depending on the target. When using the
+a.out object file format, @command{@value{AS}} simply accepts the directive for
+source-file compatibility with existing assemblers, but does not emit anything
+for it. When using COFF, comments are emitted to the @code{.comment} or
+@code{.rdata} section, depending on the target. When using ELF, comments are
+emitted to the @code{.comment} section.
+
+@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}}).
+If you have several conditions to check, @code{.elseif} may be used to avoid
+nesting blocks if/else within each subsequent @code{.else} block.
+
+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. Note a symbol which has been referenced but not yet defined
+is considered to be undefined.
+
+@cindex @code{ifb} directive
+@item .ifb @var{text}
+Assembles the following section of code if the operand is blank (empty).
+
+@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{ifnb} directive
+@item .ifnb @var{text}
+Like @code{.ifb}, but the sense of the test is reversed: this assembles the
+following section of code if the operand is non-blank (non-empty).
+
+@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. Note a symbol
+which has been referenced but not yet defined is considered to be undefined.
+
+@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 Incbin
+@section @code{.incbin "@var{file}"[,@var{skip}[,@var{count}]]}
+
+@cindex @code{incbin} directive
+@cindex binary files, including
+The @code{incbin} directive includes @var{file} verbatim at the current
+location. 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}.
+
+The @var{skip} argument skips a number of bytes from the start of the
+@var{file}. The @var{count} argument indicates the maximum number of bytes to
+read. Note that the data is not aligned in any way, so it is the user's
+responsibility to make sure that proper alignment is provided both before and
+after the @code{incbin} directive.
+
+@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 most forms of the H8/300, @code{.int} emits 16-bit
+integers. On the H8/300H and the Renesas SH, however, @code{.int} emits
+32-bit integers.
+@end ifset
+@end ifclear
+
+@ifset ELF
+@node Internal
+@section @code{.internal @var{names}}
+
+@cindex @code{internal} directive
+@cindex visibility
+This is one of the ELF visibility directives. The other two are
+@code{.hidden} (@pxref{Hidden,,@code{.hidden}}) and
+@code{.protected} (@pxref{Protected,,@code{.protected}}).
+
+This directive overrides the named symbols default visibility (which is set by
+their binding: local, global or weak). The directive sets the visibility to
+@code{internal} which means that the symbols are considered to be @code{hidden}
+(i.e., not visible to other components), and that some extra, processor specific
+processing must also be performed upon the symbols as well.
+@end ifset
+
+@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
+
+For some caveats with the spelling of @var{symbol}, see also @ref{Macro}.
+
+@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
+
+For some caveats with the spelling of @var{symbol}, see also the discussion
+at @xref{Macro}.
+
+@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)
+@command{@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
+@cindex logical line number
+@ifset aout
+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
+@command{@value{AS}} will no longer support this directive: it is recognized only
+for compatibility with existing assembler programs.
+@end ifset
+
+Even though this is a directive associated with the @code{a.out} or
+@code{b.out} object-code formats, @command{@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 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 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 @command{@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.
+@end ifset
+
+@node Loc
+@section @code{.loc @var{fileno} @var{lineno} [@var{column}] [@var{options}]}
+@cindex @code{loc} directive
+When emitting DWARF2 line number information,
+the @code{.loc} directive will add a row to the @code{.debug_line} line
+number matrix corresponding to the immediately following assembly
+instruction. The @var{fileno}, @var{lineno}, and optional @var{column}
+arguments will be applied to the @code{.debug_line} state machine before
+the row is added.
+
+The @var{options} are a sequence of the following tokens in any order:
+
+@table @code
+@item basic_block
+This option will set the @code{basic_block} register in the
+@code{.debug_line} state machine to @code{true}.
+
+@item prologue_end
+This option will set the @code{prologue_end} register in the
+@code{.debug_line} state machine to @code{true}.
+
+@item epilogue_begin
+This option will set the @code{epilogue_begin} register in the
+@code{.debug_line} state machine to @code{true}.
+
+@item is_stmt @var{value}
+This option will set the @code{is_stmt} register in the
+@code{.debug_line} state machine to @code{value}, which must be
+either 0 or 1.
+
+@item isa @var{value}
+This directive will set the @code{isa} register in the @code{.debug_line}
+state machine to @var{value}, which must be an unsigned integer.
+
+@item discriminator @var{value}
+This directive will set the @code{discriminator} register in the @code{.debug_line}
+state machine to @var{value}, which must be an unsigned integer.
+
+@item view @var{value}
+This option causes a row to be added to @code{.debug_line} in reference to the
+current address (which might not be the same as that of the following assembly
+instruction), and to associate @var{value} with the @code{view} register in the
+@code{.debug_line} state machine. If @var{value} is a label, both the
+@code{view} register and the label are set to the number of prior @code{.loc}
+directives at the same program location. If @var{value} is the literal
+@code{0}, the @code{view} register is set to zero, and the assembler asserts
+that there aren't any prior @code{.loc} directives at the same program
+location. If @var{value} is the literal @code{-0}, the assembler arrange for
+the @code{view} register to be reset in this row, even if there are prior
+@code{.loc} directives at the same program location.
+
+@end table
+
+@node Loc_mark_labels
+@section @code{.loc_mark_labels @var{enable}}
+@cindex @code{loc_mark_labels} directive
+When emitting DWARF2 line number information,
+the @code{.loc_mark_labels} directive makes the assembler emit an entry
+to the @code{.debug_line} line number matrix with the @code{basic_block}
+register in the state machine set whenever a code label is seen.
+The @var{enable} argument should be either 1 or 0, to enable or disable
+this function respectively.
+
+@ifset ELF
+@node Local
+@section @code{.local @var{names}}
+
+@cindex @code{local} directive
+This directive, which is available for ELF targets, marks each symbol in
+the comma-separated list of @code{names} as a local symbol so that it
+will not be externally visible. If the symbols do not already exist,
+they will be created.
+
+For targets where the @code{.lcomm} directive (@pxref{Lcomm}) does not
+accept an alignment argument, which is the case for most ELF targets,
+the @code{.local} directive can be used in combination with @code{.comm}
+(@pxref{Comm}) to define aligned local common data.
+@end ifset
+
+@node Long
+@section @code{.long @var{expressions}}
+
+@cindex @code{long} directive
+@code{.long} is the same as @samp{.int}. @xref{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 qualify the macro argument to
+indicate whether all invocations must specify a non-blank value (through
+@samp{:@code{req}}), or whether it takes all of the remaining arguments
+(through @samp{:@code{vararg}}). You can supply a default value for any
+macro argument by following the name with @samp{=@var{deflt}}. You
+cannot define two macros with the same @var{macname} unless it has been
+subject to the @code{.purgem} directive (@pxref{Purgem}) between the two
+definitions. 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}).
+
+@item .macro m p1:req, p2=0, p3:vararg
+Begin the definition of a macro called @code{m}, with at least three
+arguments. The first argument must always have a value specified, but
+not the second, which instead has a default value. The third formal
+will get assigned all remaining arguments specified at invocation time.
+
+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}.
+
+@end table
+
+Note that since each of the @var{macargs} can be an identifier exactly
+as any other one permitted by the target architecture, there may be
+occasional problems if the target hand-crafts special meanings to certain
+characters when they occur in a special position. For example, if the colon
+(@code{:}) is generally permitted to be part of a symbol name, but the
+architecture specific code special-cases it when occurring as the final
+character of a symbol (to denote a label), then the macro parameter
+replacement code will have no way of knowing that and consider the whole
+construct (including the colon) an identifier, and check only this
+identifier for being the subject to parameter substitution. So for example
+this macro definition:
+
+@example
+ .macro label l
+\l:
+ .endm
+@end example
+
+might not work as expected. Invoking @samp{label foo} might not create a label
+called @samp{foo} but instead just insert the text @samp{\l:} into the
+assembler source, probably generating an error about an unrecognised
+identifier.
+
+Similarly problems might occur with the period character (@samp{.})
+which is often allowed inside opcode names (and hence identifier names). So
+for example constructing a macro to build an opcode from a base name and a
+length specifier like this:
+
+@example
+ .macro opcode base length
+ \base.\length
+ .endm
+@end example
+
+and invoking it as @samp{opcode store l} will not create a @samp{store.l}
+instruction but instead generate some kind of error as the assembler tries to
+interpret the text @samp{\base.\length}.
+
+There are several possible ways around this problem:
+
+@table @code
+@item Insert white space
+If it is possible to use white space characters then this is the simplest
+solution. eg:
+
+@example
+ .macro label l
+\l :
+ .endm
+@end example
+
+@item Use @samp{\()}
+The string @samp{\()} can be used to separate the end of a macro argument from
+the following text. eg:
+
+@example
+ .macro opcode base length
+ \base\().\length
+ .endm
+@end example
+
+@item Use the alternate macro syntax mode
+In the alternative macro syntax mode the ampersand character (@samp{&}) can be
+used as a separator. eg:
+
+@example
+ .altmacro
+ .macro label l
+l&:
+ .endm
+@end example
+@end table
+
+Note: this problem of correctly identifying string parameters to pseudo ops
+also applies to the identifiers used in @code{.irp} (@pxref{Irp})
+and @code{.irpc} (@pxref{Irpc}) as well.
+
+@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 \@@
+@command{@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}.
+
+@item LOCAL @var{name} [ , @dots{} ]
+@emph{Warning: @code{LOCAL} is only available if you select ``alternate
+macro syntax'' with @samp{--alternate} or @code{.altmacro}.}
+@xref{Altmacro,,@code{.altmacro}}.
+@end ftable
+
+@node MRI
+@section @code{.mri @var{val}}
+
+@cindex @code{mri} directive
+@cindex MRI mode, temporarily
+If @var{val} is non-zero, this tells @command{@value{AS}} to enter MRI mode. If
+@var{val} is zero, this tells @command{@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 Noaltmacro
+@section @code{.noaltmacro}
+Disable alternate macro mode. @xref{Altmacro}.
+
+@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 Nops
+@section @code{.nops @var{size}[, @var{control}]}
+
+@cindex @code{nops} directive
+@cindex filling memory with no-op instructions
+This directive emits @var{size} bytes filled with no-op instructions.
+@var{size} is absolute expression, which must be a positve value.
+@var{control} controls how no-op instructions should be generated. If
+the comma and @var{control} are omitted, @var{control} is assumed to be
+zero.
+
+Note: For Intel 80386 and AMD x86-64 targets, @var{control} specifies
+the size limit of a no-op instruction. The valid values of @var{control}
+are between 0 and 4 in 16-bit mode, between 0 and 7 when tuning for
+older processors in 32-bit mode, between 0 and 11 in 64-bit mode or when
+tuning for newer processors in 32-bit mode. When 0 is used, the no-op
+instruction size limit is set to the maximum supported size.
+
+@node Octa
+@section @code{.octa @var{bignums}}
+
+@c FIXME: double size emitted for "octa" on some? 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 Offset
+@section @code{.offset @var{loc}}
+
+@cindex @code{offset} directive
+Set the location counter to @var{loc} in the absolute section. @var{loc} must
+be an absolute expression. This directive may be useful for defining
+symbols with absolute values. Do not confuse it with the @code{.org}
+directive.
+
+@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,
+@command{@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 @command{@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 most 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.
+
+@ifset ELF
+@node PopSection
+@section @code{.popsection}
+
+@cindex @code{popsection} directive
+@cindex Section Stack
+This is one of the ELF section stack manipulation directives. The others are
+@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}),
+@code{.pushsection} (@pxref{PushSection}), and @code{.previous}
+(@pxref{Previous}).
+
+This directive replaces the current section (and subsection) with the top
+section (and subsection) on the section stack. This section is popped off the
+stack.
+@end ifset
+
+@ifset ELF
+@node Previous
+@section @code{.previous}
+
+@cindex @code{previous} directive
+@cindex Section Stack
+This is one of the ELF section stack manipulation directives. The others are
+@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}),
+@code{.pushsection} (@pxref{PushSection}), and @code{.popsection}
+(@pxref{PopSection}).
+
+This directive swaps the current section (and subsection) with most recently
+referenced section/subsection pair prior to this one. Multiple
+@code{.previous} directives in a row will flip between two sections (and their
+subsections). For example:
+
+@smallexample
+.section A
+ .subsection 1
+ .word 0x1234
+ .subsection 2
+ .word 0x5678
+.previous
+ .word 0x9abc
+@end smallexample
+
+Will place 0x1234 and 0x9abc into subsection 1 and 0x5678 into subsection 2 of
+section A. Whilst:
+
+@smallexample
+.section A
+.subsection 1
+ # Now in section A subsection 1
+ .word 0x1234
+.section B
+.subsection 0
+ # Now in section B subsection 0
+ .word 0x5678
+.subsection 1
+ # Now in section B subsection 1
+ .word 0x9abc
+.previous
+ # Now in section B subsection 0
+ .word 0xdef0
+@end smallexample
+
+Will place 0x1234 into section A, 0x5678 and 0xdef0 into subsection 0 of
+section B and 0x9abc into subsection 1 of section B.
+
+In terms of the section stack, this directive swaps the current section with
+the top section on the section stack.
+@end ifset
+
+@node Print
+@section @code{.print @var{string}}
+
+@cindex @code{print} directive
+@command{@value{AS}} will print @var{string} on the standard output during
+assembly. You must put @var{string} in double quotes.
+
+@ifset ELF
+@node Protected
+@section @code{.protected @var{names}}
+
+@cindex @code{protected} directive
+@cindex visibility
+This is one of the ELF visibility directives. The other two are
+@code{.hidden} (@pxref{Hidden}) and @code{.internal} (@pxref{Internal}).
+
+This directive overrides the named symbols default visibility (which is set by
+their binding: local, global or weak). The directive sets the visibility to
+@code{protected} which means that any references to the symbols from within the
+components that defines them must be resolved to the definition in that
+component, even if a definition in another component would normally preempt
+this.
+@end ifset
+
+@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.
+
+@command{@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}.
+
+@ifset ELF
+@node PushSection
+@section @code{.pushsection @var{name} [, @var{subsection}] [, "@var{flags}"[, @@@var{type}[,@var{arguments}]]]}
+
+@cindex @code{pushsection} directive
+@cindex Section Stack
+This is one of the ELF section stack manipulation directives. The others are
+@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}),
+@code{.popsection} (@pxref{PopSection}), and @code{.previous}
+(@pxref{Previous}).
+
+This directive pushes the current section (and subsection) onto the
+top of the section stack, and then replaces the current section and
+subsection with @code{name} and @code{subsection}. The optional
+@code{flags}, @code{type} and @code{arguments} are treated the same
+as in the @code{.section} (@pxref{Section}) directive.
+@end ifset
+
+@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 Reloc
+@section @code{.reloc @var{offset}, @var{reloc_name}[, @var{expression}]}
+
+@cindex @code{reloc} directive
+Generate a relocation at @var{offset} of type @var{reloc_name} with value
+@var{expression}. If @var{offset} is a number, the relocation is generated in
+the current section. If @var{offset} is an expression that resolves to a
+symbol plus offset, the relocation is generated in the given symbol's section.
+@var{expression}, if present, must resolve to a symbol plus addend or to an
+absolute value, but note that not all targets support an addend. e.g. ELF REL
+targets such as i386 store an addend in the section contents rather than in the
+relocation. This low level interface does not support addends stored in the
+section.
+
+@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
+
+A count of zero is allowed, but nothing is generated. Negative counts are not
+allowed and if encountered will be treated as if they were zero.
+
+@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.
+@end ifset
+
+@ifset COFF-ELF
+@node Section
+@section @code{.section @var{name}}
+
+@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
+@ifset ELF
+@c only print the extra heading if both COFF and ELF are set
+@subheading COFF Version
+@end ifset
+
+@cindex @code{section} directive (COFF version)
+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{subsection}]
+@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 e
+exclude section from linking
+@item r
+read-only section
+@item x
+executable section
+@item s
+shared section (meaningful for PE targets)
+@item a
+ignored. (For compatibility with the ELF version)
+@item y
+section is not readable (meaningful for PE targets)
+@item 0-9
+single-digit power-of-two section alignment (GNU extension)
+@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. Note the @code{n} and @code{w} flags remove attributes
+from the section, rather than adding them, so if they are used on their own it
+will be as if no flags had been specified at all.
+
+If the optional argument to the @code{.section} directive is not quoted, it is
+taken as a subsection number (@pxref{Sub-Sections}).
+@end ifset
+
+@ifset ELF
+@ifset COFF
+@c only print the extra heading if both COFF and ELF are set
+@subheading ELF Version
+@end ifset
+
+@cindex Section Stack
+This is one of the ELF section stack manipulation directives. The others are
+@code{.subsection} (@pxref{SubSection}), @code{.pushsection}
+(@pxref{PushSection}), @code{.popsection} (@pxref{PopSection}), and
+@code{.previous} (@pxref{Previous}).
+
+@cindex @code{section} directive (ELF version)
+For ELF targets, the @code{.section} directive is used like this:
+
+@smallexample
+.section @var{name} [, "@var{flags}"[, @@@var{type}[,@var{flag_specific_arguments}]]]
+@end smallexample
+
+@anchor{Section Name Substitutions}
+@kindex --sectname-subst
+@cindex section name substitution
+If the @samp{--sectname-subst} command-line option is provided, the @var{name}
+argument may contain a substitution sequence. Only @code{%S} is supported
+at the moment, and substitutes the current section name. For example:
+
+@smallexample
+.macro exception_code
+.section %S.exception
+[exception code here]
+.previous
+.endm
+
+.text
+[code]
+exception_code
+[...]
+
+.section .init
+[init code]
+exception_code
+[...]
+@end smallexample
+
+The two @code{exception_code} invocations above would create the
+@code{.text.exception} and @code{.init.exception} sections respectively.
+This is useful e.g. to discriminate between ancillary sections that are
+tied to setup code to be discarded after use from ancillary sections that
+need to stay resident without having to define multiple @code{exception_code}
+macros just for that purpose.
+
+The optional @var{flags} argument is a quoted string which may contain any
+combination of the following characters:
+
+@table @code
+@item a
+section is allocatable
+@item d
+section is a GNU_MBIND section
+@item e
+section is excluded from executable and shared library.
+@item w
+section is writable
+@item x
+section is executable
+@item M
+section is mergeable
+@item S
+section contains zero terminated strings
+@item G
+section is a member of a section group
+@item T
+section is used for thread-local-storage
+@item ?
+section is a member of the previously-current section's group, if any
+@item @code{<number>}
+a numeric value indicating the bits to be set in the ELF section header's flags
+field. Note - if one or more of the alphabetic characters described above is
+also included in the flags field, their bit values will be ORed into the
+resulting value.
+@item @code{<target specific>}
+some targets extend this list with their own flag characters
+@end table
+
+Note - once a section's flags have been set they cannot be changed. There are
+a few exceptions to this rule however. Processor and application specific
+flags can be added to an already defined section. The @code{.interp},
+@code{.strtab} and @code{.symtab} sections can have the allocate flag
+(@code{a}) set after they are initially defined, and the @code{.note-GNU-stack}
+section may have the executable (@code{x}) flag added.
+
+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)
+@item @@note
+section contains data which is used by things other than the program
+@item @@init_array
+section contains an array of pointers to init functions
+@item @@fini_array
+section contains an array of pointers to finish functions
+@item @@preinit_array
+section contains an array of pointers to pre-init functions
+@item @@@code{<number>}
+a numeric value to be set as the ELF section header's type field.
+@item @@@code{<target specific>}
+some targets extend this list with their own types
+@end table
+
+Many targets only support the first three section types. The type may be
+enclosed in double quotes if necessary.
+
+Note on targets where the @code{@@} character is the start of a comment (eg
+ARM) then another character is used instead. For example the ARM port uses the
+@code{%} character.
+
+Note - some sections, eg @code{.text} and @code{.data} are considered to be
+special and have fixed types. Any attempt to declare them with a different
+type will generate an error from the assembler.
+
+If @var{flags} contains the @code{M} symbol then the @var{type} argument must
+be specified as well as an extra argument---@var{entsize}---like this:
+
+@smallexample
+.section @var{name} , "@var{flags}"M, @@@var{type}, @var{entsize}
+@end smallexample
+
+Sections with the @code{M} flag but not @code{S} flag must contain fixed size
+constants, each @var{entsize} octets long. Sections with both @code{M} and
+@code{S} must contain zero terminated strings where each character is
+@var{entsize} bytes long. The linker may remove duplicates within sections with
+the same name, same entity size and same flags. @var{entsize} must be an
+absolute expression. For sections with both @code{M} and @code{S}, a string
+which is a suffix of a larger string is considered a duplicate. Thus
+@code{"def"} will be merged with @code{"abcdef"}; A reference to the first
+@code{"def"} will be changed to a reference to @code{"abcdef"+3}.
+
+If @var{flags} contains the @code{G} symbol then the @var{type} argument must
+be present along with an additional field like this:
+
+@smallexample
+.section @var{name} , "@var{flags}"G, @@@var{type}, @var{GroupName}[, @var{linkage}]
+@end smallexample
+
+The @var{GroupName} field specifies the name of the section group to which this
+particular section belongs. The optional linkage field can contain:
+
+@table @code
+@item comdat
+indicates that only one copy of this section should be retained
+@item .gnu.linkonce
+an alias for comdat
+@end table
+
+Note: if both the @var{M} and @var{G} flags are present then the fields for
+the Merge flag should come first, like this:
+
+@smallexample
+.section @var{name} , "@var{flags}"MG, @@@var{type}, @var{entsize}, @var{GroupName}[, @var{linkage}]
+@end smallexample
+
+If @var{flags} contains the @code{?} symbol then it may not also contain the
+@code{G} symbol and the @var{GroupName} or @var{linkage} fields should not be
+present. Instead, @code{?} says to consider the section that's current before
+this directive. If that section used @code{G}, then the new section will use
+@code{G} with those same @var{GroupName} and @var{linkage} fields implicitly.
+If not, then the @code{?} symbol has no effect.
+
+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
+@item #exclude
+section is excluded from executable and shared library.
+@item #tls
+section is used for thread local storage
+@end table
+
+This directive replaces the current section and subsection. See the
+contents of the gas testsuite directory @code{gas/testsuite/gas/elf} for
+some examples of how this directive and the other section stack directives
+work.
+@end ifset
+@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 provided that the
+values given to the symbol are constants. Values that are based on expressions
+involving other symbols are allowed, but some targets may restrict this to only
+being done once per assembly. This is because those targets do not set the
+addresses of symbols at assembly time, but rather delay the assignment until a
+final link is performed. This allows the linker a chance to change the code in
+the files, changing the location of, and the relative distance between, various
+different symbols.
+
+If you @code{.set} a global symbol, the value stored in the object
+file is the last value stored into it.
+
+@ifset Z80
+On Z80 @code{set} is a real instruction, use
+@samp{@var{symbol} defl @var{expression}} instead.
+@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. @xref{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
+@command{@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-ELF
+@node Size
+@section @code{.size}
+
+This directive is used to set the size associated with a symbol.
+
+@ifset COFF
+@ifset ELF
+@c only print the extra heading if both COFF and ELF are set
+@subheading COFF Version
+@end ifset
+
+@cindex @code{size} directive (COFF version)
+For COFF targets, the @code{.size} directive is only permitted inside
+@code{.def}/@code{.endef} pairs. It is used like this:
+
+@smallexample
+.size @var{expression}
+@end smallexample
+
+@end ifset
+
+@ifset ELF
+@ifset COFF
+@c only print the extra heading if both COFF and ELF are set
+@subheading ELF Version
+@end ifset
+
+@cindex @code{size} directive (ELF version)
+For ELF targets, the @code{.size} directive is used like this:
+
+@smallexample
+.size @var{name} , @var{expression}
+@end smallexample
+
+This directive sets the size associated with a symbol @var{name}.
+The size in bytes is computed from @var{expression} which can make use of label
+arithmetic. This directive is typically used to set the size of function
+symbols.
+@end ifset
+@end ifset
+
+@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}.
+@end ifclear
+
+@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 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 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 @command{@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}", @code{.string8} "@var{str}", @code{.string16}
+"@var{str}", @code{.string32} "@var{str}", @code{.string64} "@var{str}"
+
+@cindex string, copying to object file
+@cindex string8, copying to object file
+@cindex string16, copying to object file
+@cindex string32, copying to object file
+@cindex string64, copying to object file
+@cindex @code{string} directive
+@cindex @code{string8} directive
+@cindex @code{string16} directive
+@cindex @code{string32} directive
+@cindex @code{string64} 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}.
+
+The variants @code{string16}, @code{string32} and @code{string64} differ from
+the @code{string} pseudo opcode in that each 8-bit character from @var{str} is
+copied and expanded to 16, 32 or 64 bits respectively. The expanded characters
+are stored in target endianness byte order.
+
+Example:
+@smallexample
+ .string32 "BYE"
+expands to:
+ .string "B\0\0\0Y\0\0\0E\0\0\0" /* On little endian targets. */
+ .string "\0\0\0B\0\0\0Y\0\0\0E" /* On big endian targets. */
+@end smallexample
+
+
+@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 SubSection
+@section @code{.subsection @var{name}}
+
+@cindex @code{subsection} directive
+@cindex Section Stack
+This is one of the ELF section stack manipulation directives. The others are
+@code{.section} (@pxref{Section}), @code{.pushsection} (@pxref{PushSection}),
+@code{.popsection} (@pxref{PopSection}), and @code{.previous}
+(@pxref{Previous}).
+
+This directive replaces the current subsection with @code{name}. The current
+section is not changed. The replaced subsection is put onto the section stack
+in place of the then current top of stack subsection.
+@end ifset
+
+@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 can be used like this:
+@smallexample
+.symver @var{name}, @var{name2@@nodename}
+@end smallexample
+If the symbol @var{name} is defined within the file
+being assembled, the @code{.symver} 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.
+
+If the symbol @var{name} is not defined within the file being assembled, all
+references to @var{name} will be changed to @var{name2@@nodename}. If no
+reference to @var{name} is made, @var{name2@@nodename} will be removed from the
+symbol table.
+
+Another usage of the @code{.symver} directive is:
+@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. It is similar to @var{name2@@nodename}. The
+difference is @var{name2@@@@nodename} will also be used to resolve
+references to @var{name2} by the linker.
+
+The third usage of the @code{.symver} directive is:
+@smallexample
+.symver @var{name}, @var{name2@@@@@@nodename}
+@end smallexample
+When @var{name} is not defined within the
+file being assembled, it is treated as @var{name2@@nodename}. When
+@var{name} is defined within the file being assembled, the symbol
+name, @var{name}, will be changed to @var{name2@@@@nodename}.
+@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.
+@end ifset
+
+@node Text
+@section @code{.text @var{subsection}}
+
+@cindex @code{text} directive
+Tells @command{@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-ELF
+@node Type
+@section @code{.type}
+
+This directive is used to set the type of a symbol.
+
+@ifset COFF
+@ifset ELF
+@c only print the extra heading if both COFF and ELF are set
+@subheading COFF Version
+@end ifset
+
+@cindex COFF symbol type
+@cindex symbol type, COFF
+@cindex @code{type} directive (COFF version)
+For COFF targets, this directive is permitted only within
+@code{.def}/@code{.endef} pairs. It is used like this:
+
+@smallexample
+.type @var{int}
+@end smallexample
+
+This records the integer @var{int} as the type attribute of a symbol table
+entry.
+
+@end ifset
+
+@ifset ELF
+@ifset COFF
+@c only print the extra heading if both COFF and ELF are set
+@subheading ELF Version
+@end ifset
+
+@cindex ELF symbol type
+@cindex symbol type, ELF
+@cindex @code{type} directive (ELF version)
+For ELF targets, the @code{.type} directive is used like this:
+
+@smallexample
+.type @var{name} , @var{type description}
+@end smallexample
+
+This sets the type of symbol @var{name} to be either a
+function symbol or an object symbol. There are five different syntaxes
+supported for the @var{type description} field, in order to provide
+compatibility with various other assemblers.
+
+Because some of the characters used in these syntaxes (such as @samp{@@} and
+@samp{#}) are comment characters for some architectures, some of the syntaxes
+below do not work on all architectures. The first variant will be accepted by
+the GNU assembler on all architectures so that variant should be used for
+maximum portability, if you do not need to assemble your code with other
+assemblers.
+
+The syntaxes supported are:
+
+@smallexample
+ .type <name> STT_<TYPE_IN_UPPER_CASE>
+ .type <name>,#<type>
+ .type <name>,@@<type>
+ .type <name>,%<type>
+ .type <name>,"<type>"
+@end smallexample
+
+The types supported are:
+
+@table @gcctabopt
+@item STT_FUNC
+@itemx function
+Mark the symbol as being a function name.
+
+@item STT_GNU_IFUNC
+@itemx gnu_indirect_function
+Mark the symbol as an indirect function when evaluated during reloc
+processing. (This is only supported on assemblers targeting GNU systems).
+
+@item STT_OBJECT
+@itemx object
+Mark the symbol as being a data object.
+
+@item STT_TLS
+@itemx tls_object
+Mark the symbol as being a thread-local data object.
+
+@item STT_COMMON
+@itemx common
+Mark the symbol as being a common data object.
+
+@item STT_NOTYPE
+@itemx notype
+Does not mark the symbol in any way. It is supported just for completeness.
+
+@item gnu_unique_object
+Marks the symbol as being a globally unique data object. The dynamic linker
+will make sure that in the entire process there is just one symbol with this
+name and type in use. (This is only supported on assemblers targeting GNU
+systems).
+
+@end table
+
+Note: Some targets support extra types in addition to those listed above.
+
+@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}}.
+
+@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.
+@end ifset
+
+@ifset ELF
+@node Version
+@section @code{.version "@var{string}"}
+
+@cindex @code{version} directive
+This directive creates a @code{.note} section and places into it an ELF
+formatted note of type NT_VERSION. The note's name is set to @code{string}.
+@end ifset
+
+@ifset ELF
+@node VTableEntry
+@section @code{.vtable_entry @var{table}, @var{offset}}
+
+@cindex @code{vtable_entry} directive
+This directive finds or creates a symbol @code{table} and creates a
+@code{VTABLE_ENTRY} relocation for it with an addend of @code{offset}.
+
+@node VTableInherit
+@section @code{.vtable_inherit @var{child}, @var{parent}}
+
+@cindex @code{vtable_inherit} directive
+This directive finds the symbol @code{child} and finds or creates the symbol
+@code{parent} and then creates a @code{VTABLE_INHERIT} relocation for the
+parent whose addend is the value of the child symbol. As a special case the
+parent name of @code{0} is treated as referring to the @code{*ABS*} section.
+@end ifset
+
+@node Warning
+@section @code{.warning "@var{string}"}
+@cindex warning directive
+Similar to the directive @code{.error}
+(@pxref{Error,,@code{.error "@var{string}"}}), but just emits a warning.
+
+@node Weak
+@section @code{.weak @var{names}}
+
+@cindex @code{weak} directive
+This directive sets the weak attribute on the comma separated list of symbol
+@code{names}. If the symbols do not already exist, they will be created.
+
+On COFF targets other than PE, weak symbols are a GNU extension. This
+directive sets the weak attribute on the comma separated list of symbol
+@code{names}. If the symbols do not already exist, they will be created.
+
+On the PE target, weak symbols are supported natively as weak aliases.
+When a weak symbol is created that is not an alias, GAS creates an
+alternate symbol to hold the default value.
+
+@node Weakref
+@section @code{.weakref @var{alias}, @var{target}}
+
+@cindex @code{weakref} directive
+This directive creates an alias to the target symbol that enables the symbol to
+be referenced with weak-symbol semantics, but without actually making it weak.
+If direct references or definitions of the symbol are present, then the symbol
+will not be weak, but if all references to it are through weak references, the
+symbol will be marked as weak in the symbol table.
+
+The effect is equivalent to moving all references to the alias to a separate
+assembly source file, renaming the alias to the symbol in it, declaring the
+symbol as weak there, and running a reloadable link to merge the object files
+resulting from the assembly of the new source file and the old source file that
+had the references to the alias removed.
+
+The alias itself never makes to the symbol table, and is entirely handled
+within the assembler.
+
+@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, @command{@value{AS}} emits a 32-bit number.
+@end ifset
+@ifset W16
+For each expression, @command{@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 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,
+@command{@value{AS}} occasionally 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 @command{@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, @command{@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 @command{@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
+
+@ifclear no-space-dir
+@node Zero
+@section @code{.zero @var{size}}
+
+@cindex @code{zero} directive
+@cindex filling memory with zero bytes
+This directive emits @var{size} 0-valued bytes. @var{size} must be an absolute
+expression. This directive is actually an alias for the @samp{.skip} directive
+so in can take an optional second argument of the value to store in the bytes
+instead of zero. Using @samp{.zero} in this way would be confusing however.
+@end ifclear
+
+@ifset ELF
+@node 2byte
+@section @code{.2byte @var{expression} [, @var{expression}]*}
+@cindex @code{2byte} directive
+@cindex two-byte integer
+@cindex integer, 2-byte
+
+This directive expects zero or more expressions, separated by commas. If there
+are no expressions then the directive does nothing. Otherwise each expression
+is evaluated in turn and placed in the next two bytes of the current output
+section, using the endian model of the target. If an expression will not fit
+in two bytes, a warning message is displayed and the least significant two
+bytes of the expression's value are used. If an expression cannot be evaluated
+at assembly time then relocations will be generated in order to compute the
+value at link time.
+
+This directive does not apply any alignment before or after inserting the
+values. As a result of this, if relocations are generated, they may be
+different from those used for inserting values with a guaranteed alignment.
+
+This directive is only available for ELF targets,
+
+@node 4byte
+@section @code{.4byte @var{expression} [, @var{expression}]*}
+@cindex @code{4byte} directive
+@cindex four-byte integer
+@cindex integer, 4-byte
+
+Like the @option{.2byte} directive, except that it inserts unaligned, four byte
+long values into the output.
+
+@node 8byte
+@section @code{.8byte @var{expression} [, @var{expression}]*}
+@cindex @code{8byte} directive
+@cindex eight-byte integer
+@cindex integer, 8-byte
+
+Like the @option{.2byte} directive, except that it inserts unaligned, eight
+byte long bignum values into the output.
+
+@end ifset
+
+@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 ELF
+@node Object Attributes
+@chapter Object Attributes
+@cindex object attributes
+
+@command{@value{AS}} assembles source files written for a specific architecture
+into object files for that architecture. But not all object files are alike.
+Many architectures support incompatible variations. For instance, floating
+point arguments might be passed in floating point registers if the object file
+requires hardware floating point support---or floating point arguments might be
+passed in integer registers if the object file supports processors with no
+hardware floating point unit. Or, if two objects are built for different
+generations of the same architecture, the combination may require the
+newer generation at run-time.
+
+This information is useful during and after linking. At link time,
+@command{@value{LD}} can warn about incompatible object files. After link
+time, tools like @command{gdb} can use it to process the linked file
+correctly.
+
+Compatibility information is recorded as a series of object attributes. Each
+attribute has a @dfn{vendor}, @dfn{tag}, and @dfn{value}. The vendor is a
+string, and indicates who sets the meaning of the tag. The tag is an integer,
+and indicates what property the attribute describes. The value may be a string
+or an integer, and indicates how the property affects this object. Missing
+attributes are the same as attributes with a zero value or empty string value.
+
+Object attributes were developed as part of the ABI for the ARM Architecture.
+The file format is documented in @cite{ELF for the ARM Architecture}.
+
+@menu
+* GNU Object Attributes:: @sc{gnu} Object Attributes
+* Defining New Object Attributes:: Defining New Object Attributes
+@end menu
+
+@node GNU Object Attributes
+@section @sc{gnu} Object Attributes
+
+The @code{.gnu_attribute} directive records an object attribute
+with vendor @samp{gnu}.
+
+Except for @samp{Tag_compatibility}, which has both an integer and a string for
+its value, @sc{gnu} attributes have a string value if the tag number is odd and
+an integer value if the tag number is even. The second bit (@code{@var{tag} &
+2} is set for architecture-independent attributes and clear for
+architecture-dependent ones.
+
+@subsection Common @sc{gnu} attributes
+
+These attributes are valid on all architectures.
+
+@table @r
+@item Tag_compatibility (32)
+The compatibility attribute takes an integer flag value and a vendor name. If
+the flag value is 0, the file is compatible with other toolchains. If it is 1,
+then the file is only compatible with the named toolchain. If it is greater
+than 1, the file can only be processed by other toolchains under some private
+arrangement indicated by the flag value and the vendor name.
+@end table
+
+@subsection MIPS Attributes
+
+@table @r
+@item Tag_GNU_MIPS_ABI_FP (4)
+The floating-point ABI used by this object file. The value will be:
+
+@itemize @bullet
+@item
+0 for files not affected by the floating-point ABI.
+@item
+1 for files using the hardware floating-point ABI with a standard
+double-precision FPU.
+@item
+2 for files using the hardware floating-point ABI with a single-precision FPU.
+@item
+3 for files using the software floating-point ABI.
+@item
+4 for files using the deprecated hardware floating-point ABI which used 64-bit
+floating-point registers, 32-bit general-purpose registers and increased the
+number of callee-saved floating-point registers.
+@item
+5 for files using the hardware floating-point ABI with a double-precision FPU
+with either 32-bit or 64-bit floating-point registers and 32-bit
+general-purpose registers.
+@item
+6 for files using the hardware floating-point ABI with 64-bit floating-point
+registers and 32-bit general-purpose registers.
+@item
+7 for files using the hardware floating-point ABI with 64-bit floating-point
+registers, 32-bit general-purpose registers and a rule that forbids the
+direct use of odd-numbered single-precision floating-point registers.
+@end itemize
+@end table
+
+@subsection PowerPC Attributes
+
+@table @r
+@item Tag_GNU_Power_ABI_FP (4)
+The floating-point ABI used by this object file. The value will be:
+
+@itemize @bullet
+@item
+0 for files not affected by the floating-point ABI.
+@item
+1 for files using double-precision hardware floating-point ABI.
+@item
+2 for files using the software floating-point ABI.
+@item
+3 for files using single-precision hardware floating-point ABI.
+@end itemize
+
+@item Tag_GNU_Power_ABI_Vector (8)
+The vector ABI used by this object file. The value will be:
+
+@itemize @bullet
+@item
+0 for files not affected by the vector ABI.
+@item
+1 for files using general purpose registers to pass vectors.
+@item
+2 for files using AltiVec registers to pass vectors.
+@item
+3 for files using SPE registers to pass vectors.
+@end itemize
+@end table
+
+@subsection IBM z Systems Attributes
+
+@table @r
+@item Tag_GNU_S390_ABI_Vector (8)
+The vector ABI used by this object file. The value will be:
+
+@itemize @bullet
+@item
+0 for files not affected by the vector ABI.
+@item
+1 for files using software vector ABI.
+@item
+2 for files using hardware vector ABI.
+@end itemize
+@end table
+
+@node Defining New Object Attributes
+@section Defining New Object Attributes
+
+If you want to define a new @sc{gnu} object attribute, here are the places you
+will need to modify. New attributes should be discussed on the @samp{binutils}
+mailing list.
+
+@itemize @bullet
+@item
+This manual, which is the official register of attributes.
+@item
+The header for your architecture @file{include/elf}, to define the tag.
+@item
+The @file{bfd} support file for your architecture, to merge the attribute
+and issue any appropriate link warnings.
+@item
+Test cases in @file{ld/testsuite} for merging and link warnings.
+@item
+@file{binutils/readelf.c} to display your attribute.
+@item
+GCC, if you want the compiler to mark the attribute automatically.
+@end itemize
+
+@end ifset
+
+@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 @command{@value{AS}} runs. Floating point representations
+vary as well, and @command{@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
+@command{@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 AARCH64
+* AArch64-Dependent:: AArch64 Dependent Features
+@end ifset
+@ifset ALPHA
+* Alpha-Dependent:: Alpha Dependent Features
+@end ifset
+@ifset ARC
+* ARC-Dependent:: ARC Dependent Features
+@end ifset
+@ifset ARM
+* ARM-Dependent:: ARM Dependent Features
+@end ifset
+@ifset AVR
+* AVR-Dependent:: AVR Dependent Features
+@end ifset
+@ifset Blackfin
+* Blackfin-Dependent:: Blackfin Dependent Features
+@end ifset
+@ifset CR16
+* CR16-Dependent:: CR16 Dependent Features
+@end ifset
+@ifset CRIS
+* CRIS-Dependent:: CRIS Dependent Features
+@end ifset
+@ifset D10V
+* D10V-Dependent:: D10V Dependent Features
+@end ifset
+@ifset D30V
+* D30V-Dependent:: D30V Dependent Features
+@end ifset
+@ifset EPIPHANY
+* Epiphany-Dependent:: EPIPHANY Dependent Features
+@end ifset
+@ifset H8/300
+* H8/300-Dependent:: Renesas H8/300 Dependent Features
+@end ifset
+@ifset HPPA
+* HPPA-Dependent:: HPPA Dependent Features
+@end ifset
+@ifset I80386
+* i386-Dependent:: Intel 80386 and AMD x86-64 Dependent Features
+@end ifset
+@ifset IA64
+* IA-64-Dependent:: Intel IA-64 Dependent Features
+@end ifset
+@ifset IP2K
+* IP2K-Dependent:: IP2K Dependent Features
+@end ifset
+@ifset LM32
+* LM32-Dependent:: LM32 Dependent Features
+@end ifset
+@ifset M32C
+* M32C-Dependent:: M32C Dependent Features
+@end ifset
+@ifset M32R
+* M32R-Dependent:: M32R Dependent Features
+@end ifset
+@ifset M680X0
+* M68K-Dependent:: M680x0 Dependent Features
+@end ifset
+@ifset M68HC11
+* M68HC11-Dependent:: M68HC11 and 68HC12 Dependent Features
+@end ifset
+@ifset S12Z
+* S12Z-Dependent:: S12Z Dependent Features
+@end ifset
+@ifset METAG
+* Meta-Dependent :: Meta Dependent Features
+@end ifset
+@ifset MICROBLAZE
+* MicroBlaze-Dependent:: MICROBLAZE Dependent Features
+@end ifset
+@ifset MIPS
+* MIPS-Dependent:: MIPS Dependent Features
+@end ifset
+@ifset MMIX
+* MMIX-Dependent:: MMIX Dependent Features
+@end ifset
+@ifset MSP430
+* MSP430-Dependent:: MSP430 Dependent Features
+@end ifset
+@ifset NDS32
+* NDS32-Dependent:: Andes NDS32 Dependent Features
+@end ifset
+@ifset NIOSII
+* NiosII-Dependent:: Altera Nios II Dependent Features
+@end ifset
+@ifset NS32K
+* NS32K-Dependent:: NS32K Dependent Features
+@end ifset
+@ifset PDP11
+* PDP-11-Dependent:: PDP-11 Dependent Features
+@end ifset
+@ifset PJ
+* PJ-Dependent:: picoJava Dependent Features
+@end ifset
+@ifset PPC
+* PPC-Dependent:: PowerPC Dependent Features
+@end ifset
+@ifset PRU
+* PRU-Dependent:: PRU Dependent Features
+@end ifset
+@ifset RISCV
+* RISC-V-Dependent:: RISC-V Dependent Features
+@end ifset
+@ifset RL78
+* RL78-Dependent:: RL78 Dependent Features
+@end ifset
+@ifset RX
+* RX-Dependent:: RX Dependent Features
+@end ifset
+@ifset S390
+* S/390-Dependent:: IBM S/390 Dependent Features
+@end ifset
+@ifset SCORE
+* SCORE-Dependent:: SCORE Dependent Features
+@end ifset
+@ifset SH
+* SH-Dependent:: Renesas / SuperH SH Dependent Features
+@end ifset
+@ifset SPARC
+* Sparc-Dependent:: SPARC Dependent Features
+@end ifset
+@ifset TIC54X
+* TIC54X-Dependent:: TI TMS320C54x Dependent Features
+@end ifset
+@ifset TIC6X
+* TIC6X-Dependent :: TI TMS320C6x Dependent Features
+@end ifset
+@ifset TILEGX
+* TILE-Gx-Dependent :: Tilera TILE-Gx Dependent Features
+@end ifset
+@ifset TILEPRO
+* TILEPro-Dependent :: Tilera TILEPro Dependent Features
+@end ifset
+@ifset V850
+* V850-Dependent:: V850 Dependent Features
+@end ifset
+@ifset VAX
+* Vax-Dependent:: VAX Dependent Features
+@end ifset
+@ifset VISIUM
+* Visium-Dependent:: Visium Dependent Features
+@end ifset
+@ifset WASM32
+* WebAssembly-Dependent:: WebAssembly Dependent Features
+@end ifset
+@ifset XGATE
+* XGATE-Dependent:: XGATE Dependent Features
+@end ifset
+@ifset XSTORMY16
+* XSTORMY16-Dependent:: XStormy16 Dependent Features
+@end ifset
+@ifset XTENSA
+* Xtensa-Dependent:: Xtensa Dependent Features
+@end ifset
+@ifset Z80
+* Z80-Dependent:: Z80 Dependent Features
+@end ifset
+@ifset Z8000
+* Z8000-Dependent:: Z8000 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 AARCH64
+@include c-aarch64.texi
+@end ifset
+
+@ifset ALPHA
+@include c-alpha.texi
+@end ifset
+
+@ifset ARC
+@include c-arc.texi
+@end ifset
+
+@ifset ARM
+@include c-arm.texi
+@end ifset
+
+@ifset AVR
+@include c-avr.texi
+@end ifset
+
+@ifset Blackfin
+@include c-bfin.texi
+@end ifset
+
+@ifset CR16
+@include c-cr16.texi
+@end ifset
+
+@ifset CRIS
+@include c-cris.texi
+@end ifset
+
+@ifset Renesas-all
+@ifclear GENERIC
+@node Machine Dependencies
+@chapter Machine Dependent Features
+
+The machine instruction sets are different on each Renesas chip family,
+and there are also some syntax differences among the families. This
+chapter describes the specific @command{@value{AS}} features for each
+family.
+
+@menu
+* H8/300-Dependent:: Renesas H8/300 Dependent Features
+* SH-Dependent:: Renesas 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 EPIPHANY
+@include c-epiphany.texi
+@end ifset
+
+@ifset H8/300
+@include c-h8300.texi
+@end ifset
+
+@ifset HPPA
+@include c-hppa.texi
+@end ifset
+
+@ifset I80386
+@include c-i386.texi
+@end ifset
+
+@ifset IA64
+@include c-ia64.texi
+@end ifset
+
+@ifset IP2K
+@include c-ip2k.texi
+@end ifset
+
+@ifset LM32
+@include c-lm32.texi
+@end ifset
+
+@ifset M32C
+@include c-m32c.texi
+@end ifset
+
+@ifset M32R
+@include c-m32r.texi
+@end ifset
+
+@ifset M680X0
+@include c-m68k.texi
+@end ifset
+
+@ifset M68HC11
+@include c-m68hc11.texi
+@end ifset
+
+@ifset S12Z
+@include c-s12z.texi
+@end ifset
+
+@ifset METAG
+@include c-metag.texi
+@end ifset
+
+@ifset MICROBLAZE
+@include c-microblaze.texi
+@end ifset
+
+@ifset MIPS
+@include c-mips.texi
+@end ifset
+
+@ifset MMIX
+@include c-mmix.texi
+@end ifset
+
+@ifset MSP430
+@include c-msp430.texi
+@end ifset
+
+@ifset NDS32
+@include c-nds32.texi
+@end ifset
+
+@ifset NIOSII
+@include c-nios2.texi
+@end ifset
+
+@ifset NS32K
+@include c-ns32k.texi
+@end ifset
+
+@ifset PDP11
+@include c-pdp11.texi
+@end ifset
+
+@ifset PJ
+@include c-pj.texi
+@end ifset
+
+@ifset PPC
+@include c-ppc.texi
+@end ifset
+
+@ifset PRU
+@include c-pru.texi
+@end ifset
+
+@ifset RISCV
+@include c-riscv.texi
+@end ifset
+
+@ifset RL78
+@include c-rl78.texi
+@end ifset
+
+@ifset RX
+@include c-rx.texi
+@end ifset
+
+@ifset S390
+@include c-s390.texi
+@end ifset
+
+@ifset SCORE
+@include c-score.texi
+@end ifset
+
+@ifset SH
+@include c-sh.texi
+@end ifset
+
+@ifset SPARC
+@include c-sparc.texi
+@end ifset
+
+@ifset TIC54X
+@include c-tic54x.texi
+@end ifset
+
+@ifset TIC6X
+@include c-tic6x.texi
+@end ifset
+
+@ifset TILEGX
+@include c-tilegx.texi
+@end ifset
+
+@ifset TILEPRO
+@include c-tilepro.texi
+@end ifset
+
+@ifset V850
+@include c-v850.texi
+@end ifset
+
+@ifset VAX
+@include c-vax.texi
+@end ifset
+
+@ifset VISIUM
+@include c-visium.texi
+@end ifset
+
+@ifset WASM32
+@include c-wasm32.texi
+@end ifset
+
+@ifset XGATE
+@include c-xgate.texi
+@end ifset
+
+@ifset XSTORMY16
+@include c-xstormy16.texi
+@end ifset
+
+@ifset XTENSA
+@include c-xtensa.texi
+@end ifset
+
+@ifset Z80
+@include c-z80.texi
+@end ifset
+
+@ifset Z8000
+@include c-z8k.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 @command{@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 @command{@value{AS}} work better.
+Bug reports are your contribution to the maintenance of @command{@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
+@command{@value{AS}} bug. Reliable assemblers never crash.
+
+@cindex error on valid input
+@item
+If @command{@value{AS}} produces an error message for valid input, that is a bug.
+
+@cindex invalid input
+@item
+If @command{@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 @command{@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 @command{@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.
+
+@ifset BUGURL
+In any event, we also recommend that you send bug reports for @command{@value{AS}}
+to @value{BUGURL}.
+@end ifset
+
+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?'' This cannot help us fix a bug, so it is basically useless. We
+respond by asking for enough details to enable us to investigate.
+You might as well expedite matters by sending them to begin with.
+
+To enable us to fix the bug, you should include all these things:
+
+@itemize @bullet
+@item
+The version of @command{@value{AS}}. @command{@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 @command{@value{AS}}.
+
+@item
+Any patches you may have applied to the @command{@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 @command{@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
+@command{@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 @command{@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
+@command{@value{AS}} is out of sync, 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 @command{@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 @command{@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 @command{@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 GAS 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 (October 2012),
+the maintainer is Nick Clifton (email address @code{nickc@@redhat.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 Renesas H8/300 processors (tc-z8k,
+tc-h8300), 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 GAS 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).
+
+Linas Vepstas added GAS support for the ESA/390 ``IBM 370'' architecture.
+
+Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD
+support for openVMS/Alpha.
+
+Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic*
+flavors.
+
+David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica,
+Inc.@: added support for Xtensa processors.
+
+Several engineers at Cygnus Support have also provided many small bug fixes and
+configuration enhancements.
+
+Jon Beniston added support for the Lattice Mico32 architecture.
+
+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 GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include fdl.texi
+
+@node AS Index
+@unnumbered AS Index
+
+@printindex cp
+
+@bye
+@c Local Variables:
+@c fill-column: 79
+@c End: