diff options
Diffstat (limited to 'gas/doc/as.texi')
| -rw-r--r-- | gas/doc/as.texi | 8249 |
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: |