From bbb0fbde9a8292087cbfa87740d2202e832a16a9 Mon Sep 17 00:00:00 2001 From: Baptiste Daroussin Date: Sun, 4 Jan 2015 00:58:30 +0000 Subject: [PATCH] Add pregenerated documentation for as(1) and ld(1) --- contrib/binutils/bfd/doc/bfdver.texi | 1 + contrib/binutils/gas/doc/as.txt | 13924 +++++++++++++++++++++++ contrib/binutils/gas/doc/asconfig.texi | 90 + contrib/binutils/ld/configdoc.texi | 25 + contrib/binutils/ld/ld.txt | 6564 +++++++++++ etc/mtree/BSD.usr.dist | 2 + gnu/usr.bin/binutils/Makefile | 3 +- gnu/usr.bin/binutils/doc/Makefile | 12 + 8 files changed, 20620 insertions(+), 1 deletion(-) create mode 100644 contrib/binutils/bfd/doc/bfdver.texi create mode 100644 contrib/binutils/gas/doc/as.txt create mode 100644 contrib/binutils/gas/doc/asconfig.texi create mode 100644 contrib/binutils/ld/configdoc.texi create mode 100644 contrib/binutils/ld/ld.txt create mode 100644 gnu/usr.bin/binutils/doc/Makefile diff --git a/contrib/binutils/bfd/doc/bfdver.texi b/contrib/binutils/bfd/doc/bfdver.texi new file mode 100644 index 000000000000..eaf58f49ca72 --- /dev/null +++ b/contrib/binutils/bfd/doc/bfdver.texi @@ -0,0 +1 @@ +@set VERSION "2.17.50 [FreeBSD] 2007-07-03" diff --git a/contrib/binutils/gas/doc/as.txt b/contrib/binutils/gas/doc/as.txt new file mode 100644 index 000000000000..91334b842db9 --- /dev/null +++ b/contrib/binutils/gas/doc/as.txt @@ -0,0 +1,13924 @@ +START-INFO-DIR-ENTRY +* As: (as). The GNU assembler. +* Gas: (as). The GNU assembler. +END-INFO-DIR-ENTRY + +Using as +1 Overview + 1.1 Structure of this Manual + 1.2 The GNU Assembler + 1.3 Object File Formats + 1.4 Command Line + 1.5 Input Files + 1.6 Output (Object) File + 1.7 Error and Warning Messages +2 Command-Line Options + 2.1 Enable Listings: '-a[cdhlns]' + 2.2 '--alternate' + 2.3 '-D' + 2.4 Work Faster: '-f' + 2.5 '.include' Search Path: '-I' PATH + 2.6 Difference Tables: '-K' + 2.7 Include Local Symbols: '-L' + 2.8 Configuring listing output: '--listing' + 2.9 Assemble in MRI Compatibility Mode: '-M' + 2.10 Dependency Tracking: '--MD' + 2.11 Name the Object File: '-o' + 2.12 Join Data and Text Sections: '-R' + 2.13 Display Assembly Statistics: '--statistics' + 2.14 Compatible Output: '--traditional-format' + 2.15 Announce Version: '-v' + 2.16 Control Warnings: '-W', '--warn', '--no-warn', '--fatal-warnings' + 2.17 Generate Object File in Spite of Errors: '-Z' +3 Syntax + 3.1 Preprocessing + 3.2 Whitespace + 3.3 Comments + 3.4 Symbols + 3.5 Statements + 3.6 Constants + 3.6.1 Character Constants + 3.6.1.1 Strings + 3.6.1.2 Characters + 3.6.2 Number Constants + 3.6.2.1 Integers + 3.6.2.2 Bignums + 3.6.2.3 Flonums +4 Sections and Relocation + 4.1 Background + 4.2 Linker Sections + 4.3 Assembler Internal Sections + 4.4 Sub-Sections + 4.5 bss Section +5 Symbols + 5.1 Labels + 5.2 Giving Symbols Other Values + 5.3 Symbol Names + 5.4 The Special Dot Symbol + 5.5 Symbol Attributes + 5.5.1 Value + 5.5.2 Type +6 Expressions + 6.1 Empty Expressions + 6.2 Integer Expressions + 6.2.1 Arguments + 6.2.2 Operators + 6.2.3 Prefix Operator + 6.2.4 Infix Operators +7 Assembler Directives + 7.1 '.abort' + 7.2 '.align ABS-EXPR, ABS-EXPR, ABS-EXPR' + 7.3 '.ascii "STRING"'... + 7.4 '.asciz "STRING"'... + 7.5 '.balign[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' + 7.6 '.byte EXPRESSIONS' + 7.7 '.comm SYMBOL , LENGTH ' + 7.8 '.cfi_startproc [simple]' + 7.9 '.cfi_endproc' + 7.10 '.cfi_personality ENCODING [, EXP]' + 7.11 '.cfi_lsda ENCODING [, EXP]' + 7.12 '.cfi_def_cfa REGISTER, OFFSET' + 7.13 '.cfi_def_cfa_register REGISTER' + 7.14 '.cfi_def_cfa_offset OFFSET' + 7.15 '.cfi_adjust_cfa_offset OFFSET' + 7.16 '.cfi_offset REGISTER, OFFSET' + 7.17 '.cfi_rel_offset REGISTER, OFFSET' + 7.18 '.cfi_register REGISTER1, REGISTER2' + 7.19 '.cfi_restore REGISTER' + 7.20 '.cfi_undefined REGISTER' + 7.21 '.cfi_same_value REGISTER' + 7.22 '.cfi_remember_state', + 7.23 '.cfi_return_column REGISTER' + 7.24 '.cfi_signal_frame' + 7.25 '.cfi_window_save' + 7.26 '.cfi_escape' EXPRESSION[, ...] + 7.27 '.file FILENO FILENAME' + 7.28 '.loc FILENO LINENO [COLUMN] [OPTIONS]' + 7.29 '.loc_mark_blocks ENABLE' + 7.30 '.data SUBSECTION' + 7.31 '.double FLONUMS' + 7.32 '.eject' + 7.33 '.else' + 7.34 '.elseif' + 7.35 '.end' + 7.36 '.endfunc' + 7.37 '.endif' + 7.38 '.equ SYMBOL, EXPRESSION' + 7.39 '.equiv SYMBOL, EXPRESSION' + 7.40 '.eqv SYMBOL, EXPRESSION' + 7.41 '.err' + 7.42 '.error "STRING"' + 7.43 '.exitm' + 7.44 '.extern' + 7.45 '.fail EXPRESSION' + 7.46 '.file STRING' + 7.47 '.fill REPEAT , SIZE , VALUE' + 7.48 '.float FLONUMS' + 7.49 '.func NAME[,LABEL]' + 7.50 '.global SYMBOL', '.globl SYMBOL' + 7.51 '.hidden NAMES' + 7.52 '.hword EXPRESSIONS' + 7.53 '.ident' + 7.54 '.if ABSOLUTE EXPRESSION' + 7.55 '.incbin "FILE"[,SKIP[,COUNT]]' + 7.56 '.include "FILE"' + 7.57 '.int EXPRESSIONS' + 7.58 '.internal NAMES' + 7.59 '.irp SYMBOL,VALUES'... + 7.60 '.irpc SYMBOL,VALUES'... + 7.61 '.lcomm SYMBOL , LENGTH' + 7.62 '.lflags' + 7.63 '.line LINE-NUMBER' + 7.64 '.linkonce [TYPE]' + 7.65 '.ln LINE-NUMBER' + 7.66 '.mri VAL' + 7.67 '.list' + 7.68 '.long EXPRESSIONS' + 7.69 '.macro' + 7.70 '.altmacro' + 7.71 '.noaltmacro' + 7.72 '.nolist' + 7.73 '.octa BIGNUMS' + 7.74 '.org NEW-LC , FILL' + 7.75 '.p2align[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' + 7.76 '.previous' + 7.77 '.popsection' + 7.78 '.print STRING' + 7.79 '.protected NAMES' + 7.80 '.psize LINES , COLUMNS' + 7.81 '.purgem NAME' + 7.82 '.pushsection NAME , SUBSECTION' + 7.83 '.quad BIGNUMS' + 7.84 '.reloc OFFSET, RELOC_NAME[, EXPRESSION]' + 7.85 '.rept COUNT' + 7.86 '.sbttl "SUBHEADING"' + 7.87 '.section NAME' + 7.88 '.set SYMBOL, EXPRESSION' + 7.89 '.short EXPRESSIONS' + 7.90 '.single FLONUMS' + 7.91 '.size' + 7.92 '.sleb128 EXPRESSIONS' + 7.93 '.skip SIZE , FILL' + 7.94 '.space SIZE , FILL' + 7.95 '.stabd, .stabn, .stabs' + 7.96 '.string' "STR" + 7.97 '.struct EXPRESSION' + 7.98 '.subsection NAME' + 7.99 '.symver' + 7.100 '.text SUBSECTION' + 7.101 '.title "HEADING"' + 7.102 '.type' + 7.103 '.uleb128 EXPRESSIONS' + 7.104 '.version "STRING"' + 7.105 '.vtable_entry TABLE, OFFSET' + 7.106 '.vtable_inherit CHILD, PARENT' + 7.107 '.warning "STRING"' + 7.108 '.weak NAMES' + 7.109 '.weakref ALIAS, TARGET' + 7.110 '.word EXPRESSIONS' + 7.111 Deprecated Directives +8 ARM Dependent Features + 8.1 Options + 8.2 Syntax + 8.2.1 Special Characters + 8.2.2 Register Names + 8.2.3 ARM relocation generation + 8.3 Floating Point + 8.4 ARM Machine Directives + 8.5 Opcodes + 8.6 Mapping Symbols +9 80386 Dependent Features + 9.1 Options + 9.2 AT&T Syntax versus Intel Syntax + 9.3 Instruction Naming + 9.4 Register Naming + 9.5 Instruction Prefixes + 9.6 Memory References + 9.7 Handling of Jump Instructions + 9.8 Floating Point + 9.9 Intel's MMX and AMD's 3DNow! SIMD Operations + 9.10 Writing 16-bit Code + 9.11 AT&T Syntax bugs + 9.12 Specifying CPU Architecture + 9.13 Notes +10 IA-64 Dependent Features + 10.1 Options + 10.2 Syntax + 10.2.1 Special Characters + 10.2.2 Register Names + 10.2.3 IA-64 Processor-Status-Register (PSR) Bit Names + 10.3 Opcodes +11 MIPS Dependent Features + 11.1 Assembler options + 11.2 MIPS ECOFF object code + 11.3 Directives for debugging information + 11.4 Directives to override the size of symbols + 11.5 Directives to override the ISA level + 11.6 Directives for extending MIPS 16 bit instructions + 11.7 Directive to mark data as an instruction + 11.8 Directives to save and restore options + 11.9 Directives to control generation of MIPS ASE instructions +12 PowerPC Dependent Features + 12.1 Options + 12.2 PowerPC Assembler Directives +13 SPARC Dependent Features + 13.1 Options + 13.2 Enforcing aligned data + 13.3 Floating Point + 13.4 Sparc Machine Directives +14 Reporting Bugs + 14.1 Have You Found a Bug? + 14.2 How to Report Bugs +15 Acknowledgements +Appendix A GNU Free Documentation License + ADDENDUM: How to use this License for your documents +AS Index +Using as +******** + +This file is a user guide to the GNU assembler 'as' version "2.17.50 +[FreeBSD] 2007-07-03". This version of the file describes 'as' +configured to generate code for machine specific architectures. + + 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". + +1 Overview +********** + +Here is a brief summary of how to invoke 'as'. For details, see *note +Command-Line Options: Invoking. + + as [-a[cdhlns][=FILE]] [-alternate] [-D] + [-defsym SYM=VAL] [-f] [-g] [-gstabs] + [-gstabs+] [-gdwarf-2] [-help] [-I DIR] [-J] + [-K] [-L] [-listing-lhs-width=NUM] + [-listing-lhs-width2=NUM] [-listing-rhs-width=NUM] + [-listing-cont-lines=NUM] [-keep-locals] [-o + OBJFILE] [-R] [-reduce-memory-overheads] [-statistics] + [-v] [-version] [-version] [-W] [-warn] + [-fatal-warnings] [-w] [-x] [-Z] [@FILE] + [-target-help] [TARGET-OPTIONS] + [-|FILES ...] + + _Target ARM options:_ + [-mcpu=PROCESSOR[+EXTENSION...]] + [-march=ARCHITECTURE[+EXTENSION...]] + [-mfpu=FLOATING-POINT-FORMAT] + [-mfloat-abi=ABI] + [-meabi=VER] + [-mthumb] + [-EB|-EL] + [-mapcs-32|-mapcs-26|-mapcs-float| + -mapcs-reentrant] + [-mthumb-interwork] [-k] + + _Target i386 options:_ + [-32|-64] [-n] + [-march=CPU] [-mtune=CPU] + + _Target IA-64 options:_ + [-mconstant-gp|-mauto-pic] + [-milp32|-milp64|-mlp64|-mp64] + [-mle|mbe] + [-mtune=itanium1|-mtune=itanium2] + [-munwind-check=warning|-munwind-check=error] + [-mhint.b=ok|-mhint.b=warning|-mhint.b=error] + [-x|-xexplicit] [-xauto] [-xdebug] + + _Target MIPS options:_ + [-nocpp] [-EL] [-EB] [-O[OPTIMIZATION LEVEL]] + [-g[DEBUG LEVEL]] [-G NUM] [-KPIC] [-call_shared] + [-non_shared] [-xgot [-mvxworks-pic] + [-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32] + [-march=CPU] [-mtune=CPU] [-mips1] [-mips2] + [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2] + [-mips64] [-mips64r2] + [-construct-floats] [-no-construct-floats] + [-trap] [-no-break] [-break] [-no-trap] + [-mfix7000] [-mno-fix7000] + [-mips16] [-no-mips16] + [-msmartmips] [-mno-smartmips] + [-mips3d] [-no-mips3d] + [-mdmx] [-no-mdmx] + [-mdsp] [-mno-dsp] + [-mdspr2] [-mno-dspr2] + [-mmt] [-mno-mt] + [-mdebug] [-no-mdebug] + [-mpdr] [-mno-pdr] + + _Target PowerPC options:_ + [-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604| + -m403|-m405|-mppc64|-m620|-mppc64bridge|-mbooke| + -mbooke32|-mbooke64] + [-mcom|-many|-maltivec] [-memb] + [-mregnames|-mno-regnames] + [-mrelocatable|-mrelocatable-lib] + [-mlittle|-mlittle-endian|-mbig|-mbig-endian] + [-msolaris|-mno-solaris] + + _Target SPARC options:_ + [-Av6|-Av7|-Av8|-Asparclet|-Asparclite + -Av8plus|-Av8plusa|-Av9|-Av9a] + [-xarch=v8plus|-xarch=v8plusa] [-bump] + [-32|-64] + + + +'@FILE' + Read command-line options from FILE. The options read are inserted + in place of the original @FILE option. If FILE does not exist, or + cannot be read, then the option will be treated literally, and not + removed. + + Options in FILE are separated by whitespace. A whitespace + character may be included in an option by surrounding the entire + option in either single or double quotes. Any character (including + a backslash) may be included by prefixing the character to be + included with a backslash. The FILE may itself contain additional + @FILE options; any such options will be processed recursively. + +'-a[cdhlmns]' + Turn on listings, in any of a variety of ways: + + '-ac' + omit false conditionals + + '-ad' + omit debugging directives + + '-ah' + include high-level source + + '-al' + include assembly + + '-am' + include macro expansions + + '-an' + omit forms processing + + '-as' + include symbols + + '=file' + set the name of the listing file + + You may combine these options; for example, use '-aln' for assembly + listing without forms processing. The '=file' option, if used, + must be the last one. By itself, '-a' defaults to '-ahls'. + +'--alternate' + Begin in alternate macro mode. *Note '.altmacro': Altmacro. + +'-D' + Ignored. This option is accepted for script compatibility with + calls to other assemblers. + +'--defsym SYM=VALUE' + Define the symbol SYM to be VALUE before assembling the input file. + VALUE must be an integer constant. As in C, a leading '0x' + indicates a hexadecimal value, and a leading '0' indicates an octal + value. The value of the symbol can be overridden inside a source + file via the use of a '.set' pseudo-op. + +'-f' + "fast"--skip whitespace and comment preprocessing (assume source is + compiler output). + +'-g' +'--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. + +'--gstabs' + Generate stabs debugging information for each assembler line. This + may help debugging assembler code, if the debugger can handle it. + +'--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. + +'--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. + +'--help' + Print a summary of the command line options and exit. + +'--target-help' + Print a summary of all target specific options and exit. + +'-I DIR' + Add directory DIR to the search list for '.include' directives. + +'-J' + Don't warn about signed overflow. + +'-K' + This option is accepted but has no effect on the machine specific + family. + +'-L' +'--keep-locals' + Keep (in the symbol table) local symbols. These symbols start with + system-specific local label prefixes, typically '.L' for ELF + systems or 'L' for traditional a.out systems. *Note Symbol + Names::. + +'--listing-lhs-width=NUMBER' + Set the maximum width, in words, of the output data column for an + assembler listing to NUMBER. + +'--listing-lhs-width2=NUMBER' + Set the maximum width, in words, of the output data column for + continuation lines in an assembler listing to NUMBER. + +'--listing-rhs-width=NUMBER' + Set the maximum width of an input source line, as displayed in a + listing, to NUMBER bytes. + +'--listing-cont-lines=NUMBER' + Set the maximum number of lines printed in a listing for a single + line of input to NUMBER + 1. + +'-o OBJFILE' + Name the object-file output from 'as' OBJFILE. + +'-R' + Fold the data section into the text section. + + Set the default size of GAS's hash tables to a prime number close + to 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. + +'--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 '--hash-size=4051', but in the future it may have other + effects as well. + +'--statistics' + Print the maximum space (in bytes) and total time (in seconds) used + by assembly. + +'--strip-local-absolute' + Remove local absolute symbols from the outgoing symbol table. + +'-v' +'-version' + Print the 'as' version. + +'--version' + Print the 'as' version and exit. + +'-W' +'--no-warn' + Suppress warning messages. + +'--fatal-warnings' + Treat warnings as errors. + +'--warn' + Don't suppress warning messages or treat them as errors. + +'-w' + Ignored. + +'-x' + Ignored. + +'-Z' + Generate an object file even after errors. + +'-- | FILES ...' + Standard input, or source files to assemble. + + The following options are available when as is configured for the ARM +processor family. + +'-mcpu=PROCESSOR[+EXTENSION...]' + Specify which ARM processor variant is the target. +'-march=ARCHITECTURE[+EXTENSION...]' + Specify which ARM architecture variant is used by the target. +'-mfpu=FLOATING-POINT-FORMAT' + Select which Floating Point architecture is the target. +'-mfloat-abi=ABI' + Select which floating point ABI is in use. +'-mthumb' + Enable Thumb only instruction decoding. +'-mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant' + Select which procedure calling convention is in use. +'-EB | -EL' + Select either big-endian (-EB) or little-endian (-EL) output. +'-mthumb-interwork' + Specify that the code has been generated with interworking between + Thumb and ARM code in mind. +'-k' + Specify that PIC code has been generated. + + The following options are available when 'as' is configured for the +SPARC architecture: + +'-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite' +'-Av8plus | -Av8plusa | -Av9 | -Av9a' + Explicitly select a variant of the SPARC architecture. + + '-Av8plus' and '-Av8plusa' select a 32 bit environment. '-Av9' and + '-Av9a' select a 64 bit environment. + + '-Av8plusa' and '-Av9a' enable the SPARC V9 instruction set with + UltraSPARC extensions. + +'-xarch=v8plus | -xarch=v8plusa' + For compatibility with the Solaris v9 assembler. These options are + equivalent to -Av8plus and -Av8plusa, respectively. + +'-bump' + Warn when the assembler switches to another architecture. + + The following options are available when as is configured for a MIPS +processor. + +'-G NUM' + This option sets the largest size of an object that can be + referenced implicitly with the 'gp' register. It is only accepted + for targets that use ECOFF format, such as a DECstation running + Ultrix. The default value is 8. + +'-EB' + Generate "big endian" format output. + +'-EL' + Generate "little endian" format output. + +'-mips1' +'-mips2' +'-mips3' +'-mips4' +'-mips5' +'-mips32' +'-mips32r2' +'-mips64' +'-mips64r2' + Generate code for a particular MIPS Instruction Set Architecture + level. '-mips1' is an alias for '-march=r3000', '-mips2' is an + alias for '-march=r6000', '-mips3' is an alias for '-march=r4000' + and '-mips4' is an alias for '-march=r8000'. '-mips5', '-mips32', + '-mips32r2', '-mips64', and '-mips64r2' correspond to generic 'MIPS + V', 'MIPS32', 'MIPS32 Release 2', 'MIPS64', and 'MIPS64 Release 2' + ISA processors, respectively. + +'-march=CPU' + Generate code for a particular MIPS cpu. + +'-mtune=CPU' + Schedule and tune for a particular MIPS cpu. + +'-mfix7000' +'-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. + +'-mdebug' +'-no-mdebug' + Cause stabs-style debugging output to go into an ECOFF-style + .mdebug section instead of the standard ELF .stabs sections. + +'-mpdr' +'-mno-pdr' + Control generation of '.pdr' sections. + +'-mgp32' +'-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. '-mgp32' controls the size of + general-purpose registers and '-mfp32' controls the size of + floating-point registers. + +'-mips16' +'-no-mips16' + Generate code for the MIPS 16 processor. This is equivalent to + putting '.set mips16' at the start of the assembly file. + '-no-mips16' turns off this option. + +'-msmartmips' +'-mno-smartmips' + Enables the SmartMIPS extension to the MIPS32 instruction set. + This is equivalent to putting '.set smartmips' at the start of the + assembly file. '-mno-smartmips' turns off this option. + +'-mips3d' +'-no-mips3d' + Generate code for the MIPS-3D Application Specific Extension. This + tells the assembler to accept MIPS-3D instructions. '-no-mips3d' + turns off this option. + +'-mdmx' +'-no-mdmx' + Generate code for the MDMX Application Specific Extension. This + tells the assembler to accept MDMX instructions. '-no-mdmx' turns + off this option. + +'-mdsp' +'-mno-dsp' + Generate code for the DSP Release 1 Application Specific Extension. + This tells the assembler to accept DSP Release 1 instructions. + '-mno-dsp' turns off this option. + +'-mdspr2' +'-mno-dspr2' + Generate code for the DSP Release 2 Application Specific Extension. + This option implies -mdsp. This tells the assembler to accept DSP + Release 2 instructions. '-mno-dspr2' turns off this option. + +'-mmt' +'-mno-mt' + Generate code for the MT Application Specific Extension. This + tells the assembler to accept MT instructions. '-mno-mt' turns off + this option. + +'--construct-floats' +'--no-construct-floats' + The '--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 '--construct-floats' + is selected, allowing construction of these floating point + constants. + +'--emulation=NAME' + This option causes 'as' to emulate 'as' configured for some other + target, in all respects, including output format (choosing between + ELF and ECOFF only), handling of pseudo-opcodes which may generate + debugging information or store symbol table information, and + default endianness. The available configuration names are: + 'mipsecoff', 'mipself', 'mipslecoff', 'mipsbecoff', 'mipslelf', + 'mipsbelf'. The first two do not alter the default endianness from + that of the primary target for which the assembler was configured; + the others change the default to little- or big-endian as indicated + by the 'b' or 'l' in the name. Using '-EB' or '-EL' will override + the endianness selection in any case. + + This option is currently supported only when the primary target + 'as' is configured for is a MIPS ELF or ECOFF target. Furthermore, + the primary target or others specified with '--enable-targets=...' + at configuration time must include support for the other format, if + both are to be available. For example, the Irix 5 configuration + includes support for both. + + Eventually, this option will support more configurations, with more + fine-grained control over the assembler's behavior, and will be + supported for more processors. + +'-nocpp' + 'as' ignores this option. It is accepted for compatibility with + the native tools. + +'--trap' +'--no-trap' +'--break' +'--no-break' + Control how to deal with multiplication overflow and division by + zero. '--trap' or '--no-break' (which are synonyms) take a trap + exception (and only work for Instruction Set Architecture level 2 + and higher); '--break' or '--no-trap' (also synonyms, and the + default) take a break exception. + +'-n' + When this option is used, 'as' will issue a warning every time it + generates a nop instruction from a macro. + +1.1 Structure of this Manual +============================ + +This manual is intended to describe what you need to know to use GNU +'as'. We cover the syntax expected in source files, including notation +for symbols, constants, and expressions; the directives that 'as' +understands; and of course how to invoke 'as'. + + We also cover special features in the machine specific configuration +of 'as', including assembler directives. + + On the other hand, this manual is _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 _not_ describe the instruction set, standard +mnemonics, registers or addressing modes that are standard to a +particular architecture. + +1.2 The GNU Assembler +===================== + +GNU 'as' is really a family of assemblers. This manual describes 'as', +a member of that family which is configured for the machine specific +architectures. If you use (or have used) the 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 "pseudo-ops") and assembler syntax. + + 'as' is primarily intended to assemble the output of the GNU C +compiler 'gcc' for use by the linker 'ld'. Nevertheless, we've tried to +make 'as' assemble correctly everything that other assemblers for the +same machine would assemble. + + Unlike older assemblers, 'as' is designed to assemble a source +program in one pass of the source file. This has a subtle impact on the +'.org' directive (*note '.org': Org.). + +1.3 Object File Formats +======================= + +The 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. *Note Symbol +Attributes: Symbol Attributes. For the machine specific target, 'as' is +configured to produce ELF format object files. + +1.4 Command Line +================ + +After the program name '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. + + '--' (two hyphens) by itself names the standard input file +explicitly, as one of the files for 'as' to assemble. + + Except for '--' any command line argument that begins with a hyphen +('-') is an option. Each option changes the behavior of 'as'. No +option changes the way another option works. An option is a '-' +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 (GNU standard). +These two command lines are equivalent: + + as -o my-object-file.o mumble.s + as -omy-object-file.o mumble.s + +1.5 Input Files +=============== + +We use the phrase "source program", abbreviated "source", to describe +the program input to one run of '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. + + The source program is a concatenation of the text in all the files, +in the order specified. + + Each time you run '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 '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 'as' no file names it attempts to read one input file +from the 'as' standard input, which is normally your terminal. You may +have to type to tell 'as' there is no more program to assemble. + + Use '--' if you need to explicitly name the standard input file in +your command line. + + If the source is empty, 'as' produces a small, empty object file. + +Filenames and Line-numbers +-------------------------- + +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. *Note Error and Warning Messages: Errors. + + "Physical files" are those files named in the command line given to +'as'. + + "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 'as' source +is itself synthesized from other files. 'as' understands the '#' +directives emitted by the 'gcc' preprocessor. See also *note '.file': +File. + +1.6 Output (Object) File +======================== + +Every time you run '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 'a.out'. You can give it another name +by using the '-o' option. Conventionally, object file names end with +'.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 'a.out' format.) + + The object file is meant for input to the linker 'ld'. It contains +assembled program code, information to help 'ld' integrate the assembled +program into a runnable file, and (optionally) symbolic information for +the debugger. + +1.7 Error and Warning Messages +============================== + +'as' may write warnings and error messages to the standard error file +(usually your terminal). This should not happen when a compiler runs +'as' automatically. Warnings report an assumption made so that 'as' +could keep assembling a flawed program; errors report a grave problem +that stops the assembly. + + Warning messages have the format + + file_name:NNN:Warning Message Text + +(where NNN is a line number). If a logical file name has been given +(*note '.file': File.) it is used for the filename, otherwise the name +of the current input file is used. If a logical line number was given +then it is used to calculate the number printed, otherwise the actual +line in the current source file is printed. The message text is +intended to be self explanatory (in the grand Unix tradition). + + Error messages have the format + file_name:NNN:FATAL:Error Message Text + 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. + +2 Command-Line Options +********************** + +This chapter describes command-line options available in _all_ versions +of the GNU assembler; see *note Machine Dependencies::, for options +specific to the machine specific target. + + If you are invoking 'as' via the GNU C compiler, you can use the +'-Wa' option to pass arguments through to the assembler. The assembler +arguments must be separated from each other (and the '-Wa') by commas. +For example: + + gcc -c -g -O -Wa,-alh,-L file.c + +This passes two options to the assembler: '-alh' (emit a listing to +standard output with high-level and assembly source) and '-L' (retain +local symbols in the symbol table). + + Usually you do not need to use this '-Wa' mechanism, since many +compiler command-line options are automatically passed to the assembler +by the compiler. (You can call the GNU compiler driver with the '-v' +option to see precisely what options it passes to each compilation pass, +including the assembler.) + +2.1 Enable Listings: '-a[cdhlns]' +================================= + +These options enable listing output from the assembler. By itself, '-a' +requests high-level, assembly, and symbols listing. You can use other +letters to select specific options for the list: '-ah' requests a +high-level language listing, '-al' requests an output-program assembly +listing, and '-as' requests a symbol table listing. High-level listings +require that a compiler debugging option like '-g' be used, and that +assembly listings ('-al') be requested also. + + Use the '-ac' option to omit false conditionals from a listing. Any +lines which are not assembled because of a false '.if' (or '.ifdef', or +any other conditional), or a true '.if' followed by an '.else', will be +omitted from the listing. + + Use the '-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 '.list', +'.nolist', '.psize', '.eject', '.title', and '.sbttl'. The '-an' option +turns off all forms processing. If you do not request listing output +with one of the '-a' options, the listing-control directives have no +effect. + + The letters after '-a' may be combined into one option, _e.g._, +'-aln'. + + Note if the assembler source is coming from the standard input (e.g., +because it is being created by 'gcc' and the '-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. + +2.2 '--alternate' +================= + +Begin in alternate macro mode, see *note '.altmacro': Altmacro. + +2.3 '-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 'as'. + +2.4 Work Faster: '-f' +===================== + +'-f' should only be used when assembling programs written by a (trusted) +compiler. '-f' stops the assembler from doing whitespace and comment +preprocessing on the input file(s) before assembling them. *Note +Preprocessing: Preprocessing. + + _Warning:_ if you use '-f' when the files actually need to be + preprocessed (if they contain comments, for example), 'as' does not + work correctly. + +2.5 '.include' Search Path: '-I' PATH +===================================== + +Use this option to add a PATH to the list of directories 'as' searches +for files specified in '.include' directives (*note '.include': +Include.). You may use '-I' as many times as necessary to include a +variety of paths. The current working directory is always searched +first; after that, 'as' searches any '-I' directories in the same order +as they were specified (left to right) on the command line. + +2.6 Difference Tables: '-K' +=========================== + +On the machine specific family, this option is allowed, but has no +effect. It is permitted for compatibility with the GNU assembler on +other platforms, where it can be used to warn when the assembler alters +the machine code generated for '.word' directives in difference tables. +The machine specific family does not have the addressing limitations +that sometimes lead to this alteration on other platforms. + +2.7 Include Local Symbols: '-L' +=============================== + +Symbols beginning with system-specific local label prefixes, typically +'.L' for ELF systems or 'L' for traditional a.out systems, are called +"local symbols". *Note 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 'as' and 'ld' discard such symbols, so you do not +normally debug with them. + + This option tells 'as' to retain those local symbols in the object +file. Usually if you do this you also tell the linker 'ld' to preserve +those symbols. + +2.8 Configuring listing output: '--listing' +=========================================== + +The listing feature of the assembler can be enabled via the command line +switch '-a' (*note 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., +'.list' (*note List::), '.title' (*note Title::), '.sbttl' (*note +Sbttl::), '.psize' (*note Psize::), and '.eject' (*note Eject::) and +also by the following switches: + +'--listing-lhs-width='number'' + 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. + +'--listing-lhs-width2='number'' + 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 + '--listing-lhs-width'. If neither switch is used the default is to + one. + +'--listing-rhs-width='number'' + 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. + +'--listing-cont-lines='number'' + 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. + +2.9 Assemble in MRI Compatibility Mode: '-M' +============================================ + +The '-M' or '--mri' option selects MRI compatibility mode. This changes +the syntax and pseudo-op handling of 'as' to make it compatible with the +'ASM68K' or the 'ASM960' (depending upon the configured target) +assembler from Microtec Research. The exact nature of the MRI syntax +will not be documented here; see the MRI manuals for more information. +Note in particular that the handling of macros and macro arguments is +somewhat different. The purpose of this option is to permit assembling +existing MRI assembler code using '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: + + * 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. '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. + + * 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. + + * 'END' pseudo-op specifying start address + + The MRI '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 '-e' option to the + linker, or in a linker script. + + * 'IDNT', '.ident' and 'NAME' pseudo-ops + + The MRI 'IDNT', '.ident' and 'NAME' pseudo-ops assign a module name + to the output file. This is not supported by other object file + formats. + + * 'ORG' pseudo-op + + The m68k MRI 'ORG' pseudo-op begins an absolute section at a given + address. This differs from the usual 'as' '.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. + + There are some other features of the MRI assembler which are not +supported by 'as', typically either because they are difficult or +because they seem of little consequence. Some of these may be supported +in future releases. + + * EBCDIC strings + + EBCDIC strings are not supported. + + * packed binary coded decimal + + Packed binary coded decimal is not supported. This means that the + 'DC.P' and 'DCB.P' pseudo-ops are not supported. + + * 'FEQU' pseudo-op + + The m68k 'FEQU' pseudo-op is not supported. + + * 'NOOBJ' pseudo-op + + The m68k 'NOOBJ' pseudo-op is not supported. + + * 'OPT' branch control options + + The m68k 'OPT' branch control options--'B', 'BRS', 'BRB', 'BRL', + and 'BRW'--are ignored. 'as' automatically relaxes all branches, + whether forward or backward, to an appropriate size, so these + options serve no purpose. + + * 'OPT' list control options + + The following m68k 'OPT' list control options are ignored: 'C', + 'CEX', 'CL', 'CRE', 'E', 'G', 'I', 'M', 'MEX', 'MC', 'MD', 'X'. + + * other 'OPT' options + + The following m68k 'OPT' options are ignored: 'NEST', 'O', 'OLD', + 'OP', 'P', 'PCO', 'PCR', 'PCS', 'R'. + + * 'OPT' 'D' option is default + + The m68k 'OPT' 'D' option is the default, unlike the MRI assembler. + 'OPT NOD' may be used to turn it off. + + * 'XREF' pseudo-op. + + The m68k 'XREF' pseudo-op is ignored. + + * '.debug' pseudo-op + + The i960 '.debug' pseudo-op is not supported. + + * '.extended' pseudo-op + + The i960 '.extended' pseudo-op is not supported. + + * '.list' pseudo-op. + + The various options of the i960 '.list' pseudo-op are not + supported. + + * '.optimize' pseudo-op + + The i960 '.optimize' pseudo-op is not supported. + + * '.output' pseudo-op + + The i960 '.output' pseudo-op is not supported. + + * '.setreal' pseudo-op + + The i960 '.setreal' pseudo-op is not supported. + +2.10 Dependency Tracking: '--MD' +================================ + +'as' can generate a dependency file for the file it creates. This file +consists of a single rule suitable for '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. + +2.11 Name the Object File: '-o' +=============================== + +There is always one object file output when you run 'as'. By default it +has the name '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, 'as' overwrites any existing file +of the same name. + +2.12 Join Data and Text Sections: '-R' +====================================== + +'-R' tells '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. (*Note +Sections and Relocation: Sections.) + + When you specify '-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 'as'. In future, '-R' may work this way. + + When 'as' is configured for COFF or ELF output, this option is only +useful if you use sections named '.text' and '.data'. + +2.13 Display Assembly Statistics: '--statistics' +================================================ + +Use '--statistics' to display two statistics about the resources used by +'as': the maximum amount of space allocated during the assembly (in +bytes), and the total execution time taken for the assembly (in CPU +seconds). + +2.14 Compatible Output: '--traditional-format' +============================================== + +For some targets, the output of 'as' is different in some ways from the +output of some existing assembler. This switch requests 'as' to use the +traditional format instead. + + For example, it disables the exception frame optimizations which 'as' +normally does by default on 'gcc' output. + +2.15 Announce Version: '-v' +=========================== + +You can find out what version of as is running by including the option +'-v' (which you can also spell as '-version') on the command line. + +2.16 Control Warnings: '-W', '--warn', '--no-warn', '--fatal-warnings' +====================================================================== + +'as' should never give a warning or error message when assembling +compiler output. But programs written by people often cause 'as' to +give a warning that a particular assumption was made. All such warnings +are directed to the standard error file. + + If you use the '-W' and '--no-warn' options, no warnings are issued. +This only affects the warning messages: it does not change any +particular of how 'as' assembles your file. Errors, which stop the +assembly, are still reported. + + If you use the '--fatal-warnings' option, 'as' considers files that +generate warnings to be in error. + + You can switch these options off again by specifying '--warn', which +causes warnings to be output as usual. + +2.17 Generate Object File in Spite of Errors: '-Z' +================================================== + +After an error message, 'as' normally produces no output. If for some +reason you are interested in object file output even after 'as' gives an +error message on your program, use the '-Z' option. If there are any +errors, 'as' continues anyways, and writes an object file after a final +warning message of the form 'N errors, M warnings, generating bad object +file.' + +3 Syntax +******** + +This chapter describes the machine-independent syntax allowed in a +source file. 'as' syntax is similar to what many other assemblers use; +it is inspired by the BSD 4.2 assembler. + +3.1 Preprocessing +================= + +The 'as' internal preprocessor: + * 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. + + * removes all comments, replacing them with a single space, or an + appropriate number of newlines. + + * converts character constants into the appropriate numeric values. + + 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 '.include' directive (*note '.include': +Include.). You can use the GNU C compiler driver to get other "CPP" +style preprocessing by giving the input file a '.S' suffix. *Note +Options Controlling the Kind of Output: (gcc.info)Overall Options. + + Excess whitespace, comments, and character constants cannot be used +in the portions of the input text that are not preprocessed. + + If the first line of an input file is '#NO_APP' or if you use the +'-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 '#APP' +before the text that may contain whitespace or comments, and putting a +line that says '#NO_APP' after this text. This feature is mainly intend +to support 'asm' statements in compilers whose output is otherwise free +of comments and whitespace. + +3.2 Whitespace +============== + +"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 (*note Character Constants: +Characters.), any whitespace means the same as exactly one space. + +3.3 Comments +============ + +There are two ways of rendering comments to 'as'. In both cases the +comment is equivalent to one space. + + Anything from '/*' through the next '*/' is a comment. This means +you may not nest these comments. + + /* + 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. */ + + Anything from the "line comment" character to the next newline is +considered a comment and is ignored. The line comment character is '@' +on the ARM; '#' on the i386 and x86-64; '#' for Motorola PowerPC; '!' on +the SPARC; see *note Machine Dependencies::. + + To be compatible with past assemblers, lines that begin with '#' have +a special interpretation. Following the '#' should be an absolute +expression (*note Expressions::): the logical line number of the _next_ +line. Then a string (*note 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.) + + # This is an ordinary comment. + # 42-6 "new_file_name" # New logical file name + # This is logical line # 36. + This feature is deprecated, and may disappear from future versions of +'as'. + +3.4 Symbols +=========== + +A "symbol" is one or more characters chosen from the set of all letters +(both upper and lower case), digits and the three characters '_.$'. No +symbol may begin with a digit. Case is significant. There is no length +limit: all characters are significant. Symbols are delimited by +characters not in that set, or by the beginning of a file (since the +source program must end with a newline, the end of a file is not a +possible symbol delimiter). *Note Symbols::. + +3.5 Statements +============== + +A "statement" ends at a newline character ('\n') or at a semicolon +(';'). The newline or semicolon is considered part of the preceding +statement. Newlines and semicolons within character constants are an +exception: they do not end statements. + + It is an error to end any statement with end-of-file: the last +character of any input file should be a newline. + + An empty statement is allowed, and may include whitespace. It is +ignored. + + 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 '.' 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 "instruction": it +assembles into a machine language instruction. + + A label is a symbol immediately followed by a colon (':'). +Whitespace before a label or after a colon is permitted, but you may not +have whitespace between a label's symbol and its colon. *Note Labels::. + + label: .directive followed by something + another_label: # This is an empty statement. + instruction operand_1, operand_2, ... + +3.6 Constants +============= + +A constant is a number, written so that its value is known by +inspection, without knowing any context. Like this: + .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. + +3.6.1 Character Constants +------------------------- + +There are two kinds of character constants. A "character" stands for +one character in one byte and its value may be used in numeric +expressions. String constants (properly called string _literals_) are +potentially many bytes and their values may not be used in arithmetic +expressions. + +3.6.1.1 Strings +............... + +A "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 "escape" these characters: precede them with a +backslash '\' character. For example '\\' represents one backslash: the +first '\' is an escape which tells 'as' to interpret the second +character literally as a backslash (which prevents 'as' from recognizing +the second '\' as an escape character). The complete list of escapes +follows. + +'\b' + Mnemonic for backspace; for ASCII this is octal code 010. + +'\f' + Mnemonic for FormFeed; for ASCII this is octal code 014. + +'\n' + Mnemonic for newline; for ASCII this is octal code 012. + +'\r' + Mnemonic for carriage-Return; for ASCII this is octal code 015. + +'\t' + Mnemonic for horizontal Tab; for ASCII this is octal code 011. + +'\ DIGIT DIGIT 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, '\008' has the value 010, and '\009' the value + 011. + +'\x HEX-DIGITS...' + A hex character code. All trailing hex digits are combined. + Either upper or lower case 'x' works. + +'\\' + Represents one '\' character. + +'\"' + Represents one '"' character. Needed in strings to represent this + character, because an unescaped '"' would end the string. + +'\ ANYTHING-ELSE' + Any other character when escaped by '\' gives a warning, but + assembles as if the '\' 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 'as' has no + other interpretation, so 'as' knows it is giving you the wrong code + and warns you of the fact. + + 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. + +3.6.1.2 Characters +.................. + +A single character may be written as a single quote immediately followed +by that character. The same escapes apply to characters as to strings. +So if you want to write the character backslash, you must write ''\\' +where the first '\' escapes the second '\'. As you can see, the quote +is an acute accent, not a grave accent. A newline (or semicolon ';') +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. 'as' assumes your character code is ASCII: ''A' means +65, ''B' means 66, and so on. + +3.6.2 Number Constants +---------------------- + +'as' distinguishes three kinds of numbers according to how they are +stored in the target machine. _Integers_ are numbers that would fit +into an 'int' in the C language. _Bignums_ are integers, but they are +stored in more than 32 bits. _Flonums_ are floating point numbers, +described below. + +3.6.2.1 Integers +................ + +A binary integer is '0b' or '0B' followed by zero or more of the binary +digits '01'. + + An octal integer is '0' followed by zero or more of the octal digits +('01234567'). + + A decimal integer starts with a non-zero digit followed by zero or +more digits ('0123456789'). + + A hexadecimal integer is '0x' or '0X' followed by one or more +hexadecimal digits chosen from '0123456789abcdefABCDEF'. + + Integers have the usual values. To denote a negative integer, use +the prefix operator '-' discussed under expressions (*note Prefix +Operators: Prefix Ops.). + +3.6.2.2 Bignums +............... + +A "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. + +3.6.2.3 Flonums +............... + +A "flonum" represents a floating point number. The translation is +indirect: a decimal floating point number from the text is converted by +'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 +'as' specialized to that computer. + + A flonum is written by writing (in order) + * The digit '0'. + + * A letter, to tell 'as' the rest of the number is a flonum. + + * An optional sign: either '+' or '-'. + + * An optional "integer part": zero or more decimal digits. + + * An optional "fractional part": '.' followed by zero or more decimal + digits. + + * An optional exponent, consisting of: + + * An 'E' or 'e'. + * Optional sign: either '+' or '-'. + * One or more decimal digits. + + At least one of the integer part or the fractional part must be +present. The floating point number has the usual base-10 value. + + 'as' does all processing using integers. Flonums are computed +independently of any floating point hardware in the computer running +'as'. + +4 Sections and Relocation +************************* + +4.1 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. + + The linker 'ld' reads many object files (partial programs) and +combines their contents to form a runnable program. When 'as' emits an +object file, the partial program is assumed to start at address 0. '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 'as' uses sections. + + '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 _section_. Assigning +run-time addresses to sections is called "relocation". It includes the +task of adjusting mentions of object-file addresses so they refer to the +proper run-time addresses. + + An object file written by 'as' has at least three sections, any of +which may be empty. These are named "text", "data" and "bss" sections. + + 'as' can also generate whatever other named sections you specify +using the '.section' directive (*note '.section': Section.). If you do +not use any directives that place output in the '.text' or '.data' +sections, these sections still exist, but are empty. + + Within the object file, the text section starts at address '0', the +data section follows, and the bss section follows the data section. + + To let 'ld' know which data changes when the sections are relocated, +and how to change that data, 'as' also writes to the object file details +of the relocation needed. To perform relocation 'ld' must know, each +time an address in the object file is mentioned: + * Where in the object file is the beginning of this reference to an + address? + * How long (in bytes) is this reference? + * Which section does the address refer to? What is the numeric value + of + (ADDRESS) - (START-ADDRESS OF SECTION)? + * Is the reference to an address "Program-Counter relative"? + + In fact, every address 'as' ever uses is expressed as + (SECTION) + (OFFSET INTO SECTION) +Further, most expressions 'as' computes have this section-relative +nature. + + In this manual we use the notation {SECNAME N} to mean "offset N into +section SECNAME." + + Apart from text, data and bss sections you need to know about the +"absolute" section. When 'ld' mixes partial programs, addresses in the +absolute section remain unchanged. For example, address '{absolute 0}' +is "relocated" to run-time address 0 by 'ld'. Although the linker never +arranges two partial programs' data sections with overlapping addresses +after linking, _by definition_ their absolute sections must overlap. +Address '{absolute 239}' in one part of a program is always the same +address when the program is running as address '{absolute 239}' in any +other part of the program. + + The idea of sections is extended to the "undefined" section. Any +address whose section is unknown at assembly time is by definition +rendered {undefined U}--where 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 _undefined_. + + By analogy the word _section_ is used to describe groups of sections +in the linked program. 'ld' puts all partial programs' text sections in +contiguous addresses in the linked program. It is customary to refer to +the _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 'ld'; others are invented for use of +'as' and have no meaning except during assembly. + +4.2 Linker Sections +=================== + +'ld' deals with just four kinds of sections, summarized below. + +*named sections* + These sections hold your program. 'as' and 'ld' treat them as + separate but equal sections. Anything you can say of one section + is true of another. 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. + +*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. + +*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 'ld' + must not change when relocating. In this sense we speak of + absolute addresses being "unrelocatable": they do not change during + relocation. + +*undefined section* + This "section" is a catch-all for address references to objects not + in the preceding sections. + + An idealized example of three relocatable sections follows. The +example uses the traditional section names '.text' and '.data'. Memory +addresses are on the horizontal axis. + + +-----+----+--+ + 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 ... + +4.3 Assembler Internal Sections +=============================== + +These sections are meant only for the internal use of '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 'as' warning +messages, so it might be helpful to have an idea of their meanings to +'as'. These sections are used to permit the value of every expression +in your assembly language program to be a section-relative address. + +ASSEMBLER-INTERNAL-LOGIC-ERROR! + An internal assembler logic error has been found. This means there + is a bug in the assembler. + +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. + +4.4 Sub-Sections +================ + +You may have separate groups of data in named sections that you want to +end up near to each other in the object file, even though they are not +contiguous in the assembler source. 'as' allows you to use +"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 '.text 0' before each section of code being +output, and a '.text 1' before each group of constants being output. + + Subsections are optional. If you do not use subsections, everything +goes in subsection number zero. + + 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; +'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 '.text EXPRESSION' or a +'.data EXPRESSION' statement. You can also use the '.subsection' +directive (*note SubSection::) to specify a subsection: '.subsection +EXPRESSION'. EXPRESSION should be an absolute expression (*note +Expressions::). If you just say '.text' then '.text 0' is assumed. +Likewise '.data' means '.data 0'. Assembly begins in 'text 0'. For +instance: + .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 (*)." + + Each section has a "location counter" incremented by one for every +byte assembled into that section. Because subsections are merely a +convenience restricted to 'as' there is no concept of a subsection +location counter. There is no way to directly manipulate a location +counter--but the '.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 "active" location +counter. + +4.5 bss Section +=============== + +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 '.lcomm' pseudo-op defines a symbol in the bss section; see *note +'.lcomm': Lcomm. + + The '.comm' pseudo-op may be used to declare a common symbol, which +is another form of uninitialized symbol; see *note '.comm': Comm. + +5 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. + + _Warning:_ 'as' does not place symbols in the object file in the + same order they were declared. This may break some debuggers. + +5.1 Labels +========== + +A "label" is written as a symbol immediately followed by a colon ':'. +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. + +5.2 Giving Symbols Other Values +=============================== + +A symbol can be given an arbitrary value by writing a symbol, followed +by an equals sign '=', followed by an expression (*note Expressions::). +This is equivalent to using the '.set' directive. *Note '.set': Set. +In the same way, using a double equals sign '=''=' here represents an +equivalent of the '.eqv' directive. *Note '.eqv': Eqv. + +5.3 Symbol Names +================ + +Symbol names begin with a letter or with one of '._'. On most machines, +you can also use '$' in symbol names; exceptions are noted in *note +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. + + Case of letters is significant: 'foo' is a different symbol name than +'Foo'. + + Each symbol has exactly one name. Each name in an assembly language +program refers to exactly one symbol. You may use that symbol name any +number of times in a program. + +Local Symbol Names +------------------ + +A local symbol is any symbol beginning with certain local label +prefixes. By default, the local label prefix is '.L' for ELF systems or +'L' for traditional a.out systems, but each target may have its own set +of local label prefixes. + + 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 '-L' option (*note Include Local Symbols: +'-L': L.) to retain the local symbols in the object files. + +Local Labels +------------ + +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 'N:' +(where N represents any positive integer). To refer to the most recent +previous definition of that label write 'Nb', using the same number as +when you defined the label. To refer to the next definition of a local +label, write 'Nf'--the 'b' stands for "backwards" and the '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 '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 ('0:'...'9:') are implemented in a slightly more efficient manner +than the others. + + Here is an example: + + 1: branch 1f + 2: branch 1b + 1: branch 2f + 2: branch 1b + + Which is the equivalent of: + + label_1: branch label_3 + label_2: branch label_1 + label_3: branch label_4 + label_4: branch label_3 + + 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: + +'_local label prefix_' + All local symbols begin with the system-specific local label + prefix. Normally both 'as' and '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 '-L' option then 'as' + retains these symbols in the object file. If you also instruct + 'ld' to retain these symbols, you may use them in debugging. + +'NUMBER' + This is the number that was used in the local label definition. So + if the label is written '55:' then the number is '55'. + +'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 + '\002' (control-B). + +'_ordinal number_' + This is a serial number to keep the labels distinct. The first + definition of '0:' gets the number '1'. The 15th definition of + '0:' gets the number '15', and so on. Likewise the first + definition of '1:' gets the number '1' and its 15th definition gets + '15' as well. + + So for example, the first '1:' may be named '.L1C-B1', and the 44th +'3:' may be named '.L3C-B44'. + +Dollar Local Labels +------------------- + +'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 instead of being terminated by a colon, they are +terminated by a dollar sign, e.g., '55$'. + + They can also be distinguished from ordinary local labels by their +transformed names which use ASCII character '\001' (control-A) as the +magic character to distinguish them from ordinary labels. For example, +the fifth definition of '6$' may be named '.L6'C-A'5'. + +5.4 The Special Dot Symbol +========================== + +The special symbol '.' refers to the current address that 'as' is +assembling into. Thus, the expression 'melvin: .long .' defines +'melvin' to contain its own address. Assigning a value to '.' is +treated the same as a '.org' directive. Thus, the expression '.=.+4' is +the same as saying '.space 4'. + +5.5 Symbol Attributes +===================== + +Every symbol has, as well as its name, the attributes "Value" and +"Type". Depending on output format, symbols can also have auxiliary +attributes. The detailed definitions are in 'a.out.h'. + + If you use a symbol without defining it, '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. + +5.5.1 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 '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 +'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 '.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. + +5.5.2 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. + +6 Expressions +************* + +An "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 '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. 'as' aborts with an error message in this situation. + +6.1 Empty Expressions +===================== + +An empty expression has no value: it is just whitespace or null. +Wherever an absolute expression is required, you may omit the +expression, and 'as' assumes a value of (absolute) 0. This is +compatible with other assemblers. + +6.2 Integer Expressions +======================= + +An "integer expression" is one or more _arguments_ delimited by +_operators_. + +6.2.1 Arguments +--------------- + +"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 {SECTION NNN} where SECTION is one of +text, data, bss, absolute, or undefined. 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 'as' pretends these 32 +bits are an integer. You may write integer-manipulating instructions +that act on exotic constants, compatible with other assemblers. + + Subexpressions are a left parenthesis '(' followed by an integer +expression, followed by a right parenthesis ')'; or a prefix operator +followed by an argument. + +6.2.2 Operators +--------------- + +"Operators" are arithmetic functions, like '+' or '%'. Prefix operators +are followed by an argument. Infix operators appear between their +arguments. Operators may be preceded and/or followed by whitespace. + +6.2.3 Prefix Operator +--------------------- + +'as' has the following "prefix operators". They each take one argument, +which must be absolute. + +'-' + "Negation". Two's complement negation. +'~' + "Complementation". Bitwise not. + +6.2.4 Infix Operators +--------------------- + +"Infix operators" take two arguments, one on either side. Operators +have precedence, but operations with equal precedence are performed left +to right. Apart from '+' or '-', both arguments must be absolute, and +the result is absolute. + + 1. Highest Precedence + + '*' + "Multiplication". + + '/' + "Division". Truncation is the same as the C operator '/' + + '%' + "Remainder". + + '<<' + "Shift Left". Same as the C operator '<<'. + + '>>' + "Shift Right". Same as the C operator '>>'. + + 2. Intermediate precedence + + '|' + + "Bitwise Inclusive Or". + + '&' + "Bitwise And". + + '^' + "Bitwise Exclusive Or". + + '!' + "Bitwise Or Not". + + 3. Low Precedence + + '+' + "Addition". If either argument is absolute, the result has + the section of the other argument. You may not add together + arguments from different sections. + + '-' + "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. + + '==' + "Is Equal To" + '<>' + '!=' + "Is Not Equal To" + '<' + "Is Less Than" + '>' + "Is Greater Than" + '>=' + "Is Greater Than Or Equal To" + '<=' + "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. + + 4. Lowest Precedence + + '&&' + "Logical And". + + '||' + "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. + + In short, it's only meaningful to add or subtract the _offsets_ in an +address; you can only have a defined section in one of the two +arguments. + +7 Assembler Directives +********************** + +All assembler directives have names that begin with a period ('.'). The +rest of the name is letters, usually in lower case. + + This chapter discusses directives that are available regardless of +the target machine configuration for the GNU assembler. + +7.1 '.abort' +============ + +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 'as' to quit also. One day +'.abort' will not be supported. + +7.2 '.align ABS-EXPR, ABS-EXPR, ABS-EXPR' +========================================= + +Pad the location counter (in the current subsection) to a particular +storage boundary. The first expression (which must be absolute) is the +alignment required, as described below. + + The second expression (also absolute) gives the fill value to be +stored in the padding bytes. It (and the comma) may be omitted. If it +is omitted, the padding bytes are normally zero. However, on some +systems, if the section is marked as containing code and the fill value +is omitted, the space is filled with no-op instructions. + + The third expression is also absolute, and is also optional. If it +is present, it is the maximum number of bytes that should be skipped by +this alignment directive. If doing the alignment would require skipping +more bytes than the specified maximum, then the alignment is not done at +all. You can omit the fill value (the second argument) entirely by +simply using two commas after the required alignment; this can be useful +if you want the alignment to be filled with no-op instructions when +appropriate. + + The way the required alignment is specified varies from system to +system. For the arc, hppa, i386 using ELF, i860, iq2000, m68k, or32, +s390, sparc, tic4x, tic80 and xtensa, the first expression is the +alignment request in bytes. For example '.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 the i386 using a.out format, and the arm +and strongarm, it is the number of low-order zero bits the location +counter must have after advancement. For example '.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 '.balign' and '.p2align' directives, described later, which +have a consistent behavior across all architectures (but are specific to +GAS). + +7.3 '.ascii "STRING"'... +======================== + +'.ascii' expects zero or more string literals (*note Strings::) +separated by commas. It assembles each string (with no automatic +trailing zero byte) into consecutive addresses. + +7.4 '.asciz "STRING"'... +======================== + +'.asciz' is just like '.ascii', but each string is followed by a zero +byte. The "z" in '.asciz' stands for "zero". + +7.5 '.balign[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' +============================================== + +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 '.balign 8' advances the +location counter until it is a multiple of 8. If the location counter +is already a multiple of 8, no change is needed. + + The second expression (also absolute) gives the fill value to be +stored in the padding bytes. It (and the comma) may be omitted. If it +is omitted, the padding bytes are normally zero. However, on some +systems, if the section is marked as containing code and the fill value +is omitted, the space is filled with no-op instructions. + + The third expression is also absolute, and is also optional. If it +is present, it is the maximum number of bytes that should be skipped by +this alignment directive. If doing the alignment would require skipping +more bytes than the specified maximum, then the alignment is not done at +all. You can omit the fill value (the second argument) entirely by +simply using two commas after the required alignment; this can be useful +if you want the alignment to be filled with no-op instructions when +appropriate. + + The '.balignw' and '.balignl' directives are variants of the +'.balign' directive. The '.balignw' directive treats the fill pattern +as a two byte word value. The '.balignl' directives treats the fill +pattern as a four byte longword value. For example, '.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. + +7.6 '.byte EXPRESSIONS' +======================= + +'.byte' expects zero or more expressions, separated by commas. Each +expression is assembled into the next byte. + +7.7 '.comm SYMBOL , LENGTH ' +============================ + +'.comm' declares a common symbol named 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 'ld' does not see a +definition for the symbol-just one or more common symbols-then it will +allocate LENGTH bytes of uninitialized memory. LENGTH must be an +absolute expression. If '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. + + When using ELF, the '.comm' directive takes an optional third +argument. This is the desired alignment of the symbol, specified as a +byte boundary (for example, an alignment of 16 means that the least +significant 4 bits of the address should be zero). The alignment must +be an absolute expression, and it must be a power of two. If 'ld' +allocates uninitialized memory for the common symbol, it will use the +alignment when placing the symbol. If no alignment is specified, '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. + +7.8 '.cfi_startproc [simple]' +============================= + +'.cfi_startproc' is used at the beginning of each function that should +have an entry in '.eh_frame'. It initializes some internal data +structures. Don't forget to close the function by '.cfi_endproc'. + + Unless '.cfi_startproc' is used along with parameter 'simple' it also +emits some architecture dependent initial CFI instructions. + +7.9 '.cfi_endproc' +================== + +'.cfi_endproc' is used at the end of a function where it closes its +unwind entry previously opened by '.cfi_startproc', and emits it to +'.eh_frame'. + +7.10 '.cfi_personality ENCODING [, EXP]' +======================================== + +'.cfi_personality' defines personality routine and its encoding. +ENCODING must be a constant determining how the personality should be +encoded. If it is 255 ('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 '.cfi_startproc' is '.cfi_personality +0xff', no personality routine. + +7.11 '.cfi_lsda ENCODING [, EXP]' +================================= + +'.cfi_lsda' defines LSDA and its encoding. ENCODING must be a constant +determining how the LSDA should be encoded. If it is 255 +('DW_EH_PE_omit'), second argument is not present, otherwise second +argument should be a constant or a symbol name. The default after +'.cfi_startproc' is '.cfi_lsda 0xff', no LSDA. + +7.12 '.cfi_def_cfa REGISTER, OFFSET' +==================================== + +'.cfi_def_cfa' defines a rule for computing CFA as: take address from +REGISTER and add OFFSET to it. + +7.13 '.cfi_def_cfa_register REGISTER' +===================================== + +'.cfi_def_cfa_register' modifies a rule for computing CFA. From now on +REGISTER will be used instead of the old one. Offset remains the same. + +7.14 '.cfi_def_cfa_offset OFFSET' +================================= + +'.cfi_def_cfa_offset' modifies a rule for computing CFA. Register +remains the same, but OFFSET is new. Note that it is the absolute +offset that will be added to a defined register to compute CFA address. + +7.15 '.cfi_adjust_cfa_offset OFFSET' +==================================== + +Same as '.cfi_def_cfa_offset' but OFFSET is a relative value that is +added/substracted from the previous offset. + +7.16 '.cfi_offset REGISTER, OFFSET' +=================================== + +Previous value of REGISTER is saved at offset OFFSET from CFA. + +7.17 '.cfi_rel_offset REGISTER, OFFSET' +======================================= + +Previous value of REGISTER is saved at offset OFFSET from the current +CFA register. This is transformed to '.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. + +7.18 '.cfi_register REGISTER1, REGISTER2' +========================================= + +Previous value of REGISTER1 is saved in register REGISTER2. + +7.19 '.cfi_restore REGISTER' +============================ + +'.cfi_restore' says that the rule for REGISTER is now the same as it was +at the beginning of the function, after all initial instruction added by +'.cfi_startproc' were executed. + +7.20 '.cfi_undefined REGISTER' +============================== + +From now on the previous value of REGISTER can't be restored anymore. + +7.21 '.cfi_same_value REGISTER' +=============================== + +Current value of REGISTER is the same like in the previous frame, i.e. +no restoration needed. + +7.22 '.cfi_remember_state', +=========================== + +First save all current rules for all registers by '.cfi_remember_state', +then totally screw them up by subsequent '.cfi_*' directives and when +everything is hopelessly bad, use '.cfi_restore_state' to restore the +previous saved state. + +7.23 '.cfi_return_column REGISTER' +================================== + +Change return column REGISTER, i.e. the return address is either +directly in REGISTER or can be accessed by rules for REGISTER. + +7.24 '.cfi_signal_frame' +======================== + +Mark current function as signal trampoline. + +7.25 '.cfi_window_save' +======================= + +SPARC register window has been saved. + +7.26 '.cfi_escape' EXPRESSION[, ...] +==================================== + +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. + +7.27 '.file FILENO FILENAME' +============================ + +When emitting dwarf2 line number information '.file' assigns filenames +to the '.debug_line' file name table. The FILENO operand should be a +unique positive integer to use as the index of the entry in the table. +The 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 '.debug_info' section of the dwarf2 +debugging information, and thus the user must know the exact indices +that table entries will have. + +7.28 '.loc FILENO LINENO [COLUMN] [OPTIONS]' +============================================ + +The '.loc' directive will add row to the '.debug_line' line number +matrix corresponding to the immediately following assembly instruction. +The FILENO, LINENO, and optional COLUMN arguments will be applied to the +'.debug_line' state machine before the row is added. + + The OPTIONS are a sequence of the following tokens in any order: + +'basic_block' + This option will set the 'basic_block' register in the + '.debug_line' state machine to 'true'. + +'prologue_end' + This option will set the 'prologue_end' register in the + '.debug_line' state machine to 'true'. + +'epilogue_begin' + This option will set the 'epilogue_begin' register in the + '.debug_line' state machine to 'true'. + +'is_stmt VALUE' + This option will set the 'is_stmt' register in the '.debug_line' + state machine to 'value', which must be either 0 or 1. + +'isa VALUE' + This directive will set the 'isa' register in the '.debug_line' + state machine to VALUE, which must be an unsigned integer. + +7.29 '.loc_mark_blocks ENABLE' +============================== + +The '.loc_mark_blocks' directive makes the assembler emit an entry to +the '.debug_line' line number matrix with the 'basic_block' register in +the state machine set whenever a code label is seen. The ENABLE +argument should be either 1 or 0, to enable or disable this function +respectively. + +7.30 '.data SUBSECTION' +======================= + +'.data' tells 'as' to assemble the following statements onto the end of +the data subsection numbered SUBSECTION (which is an absolute +expression). If SUBSECTION is omitted, it defaults to zero. + +7.31 '.double FLONUMS' +====================== + +'.double' expects zero or more flonums, separated by commas. It +assembles floating point numbers. + +7.32 '.eject' +============= + +Force a page break at this point, when generating assembly listings. + +7.33 '.else' +============ + +'.else' is part of the 'as' support for conditional assembly; see *note +'.if': If. It marks the beginning of a section of code to be assembled +if the condition for the preceding '.if' was false. + +7.34 '.elseif' +============== + +'.elseif' is part of the 'as' support for conditional assembly; see +*note '.if': If. It is shorthand for beginning a new '.if' block that +would otherwise fill the entire '.else' section. + +7.35 '.end' +=========== + +'.end' marks the end of the assembly file. 'as' does not process +anything in the file past the '.end' directive. + +7.36 '.endfunc' +=============== + +'.endfunc' marks the end of a function specified with '.func'. + +7.37 '.endif' +============= + +'.endif' is part of the 'as' support for conditional assembly; it marks +the end of a block of code that is only assembled conditionally. *Note +'.if': If. + +7.38 '.equ SYMBOL, EXPRESSION' +============================== + +This directive sets the value of SYMBOL to EXPRESSION. It is synonymous +with '.set'; see *note '.set': Set. + +7.39 '.equiv SYMBOL, EXPRESSION' +================================ + +The '.equiv' directive is like '.equ' and '.set', except that the +assembler will signal an error if 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 + .ifdef SYM + .err + .endif + .equ SYM,VAL + plus it protects the symbol from later redefinition. + +7.40 '.eqv SYMBOL, EXPRESSION' +============================== + +The '.eqv' directive is like '.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. + +7.41 '.err' +=========== + +If 'as' assembles a '.err' directive, it will print an error message +and, unless the '-Z' option was used, it will not generate an object +file. This can be used to signal an error in conditionally compiled +code. + +7.42 '.error "STRING"' +====================== + +Similarly to '.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 '".error directive invoked in source +file"'. *Note Error and Warning Messages: Errors. + + .error "This code has not been assembled and tested." + +7.43 '.exitm' +============= + +Exit early from the current macro definition. *Note Macro::. + +7.44 '.extern' +============== + +'.extern' is accepted in the source program--for compatibility with +other assemblers--but it is ignored. 'as' treats all undefined symbols +as external. + +7.45 '.fail EXPRESSION' +======================= + +Generates an error or a warning. If the value of the EXPRESSION is 500 +or more, 'as' will print a warning message. If the value is less than +500, 'as' will print an error message. The message will include the +value of EXPRESSION. This can occasionally be useful inside complex +nested macros or conditional assembly. + +7.46 '.file STRING' +=================== + +'.file' tells 'as' that we are about to start a new logical file. +STRING is the new file name. In general, the filename is recognized +whether or not it is surrounded by quotes '"'; but if you wish to +specify an empty file name, you must give the quotes-'""'. This +statement may go away in future: it is only recognized to be compatible +with old 'as' programs. + +7.47 '.fill REPEAT , SIZE , VALUE' +================================== + +REPEAT, SIZE and VALUE are absolute expressions. This emits REPEAT +copies of SIZE bytes. REPEAT may be zero or more. 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 REPEAT +bytes is taken from an 8-byte number. The highest order 4 bytes are +zero. The lowest order 4 bytes are VALUE rendered in the byte-order of +an integer on the computer 'as' is assembling for. Each SIZE bytes in a +repetition is taken from the lowest order SIZE bytes of this number. +Again, this bizarre behavior is compatible with other people's +assemblers. + + SIZE and VALUE are optional. If the second comma and VALUE are +absent, VALUE is assumed zero. If the first comma and following tokens +are absent, SIZE is assumed to be 1. + +7.48 '.float FLONUMS' +===================== + +This directive assembles zero or more flonums, separated by commas. It +has the same effect as '.single'. + +7.49 '.func NAME[,LABEL]' +========================= + +'.func' emits debugging information to denote function NAME, and is +ignored unless the file is assembled with debugging enabled. Only +'--gstabs[+]' is currently supported. LABEL is the entry point of the +function and if omitted NAME prepended with the 'leading char' is used. +'leading char' is usually '_' or nothing, depending on the target. All +functions are currently defined to have 'void' return type. The +function must be terminated with '.endfunc'. + +7.50 '.global SYMBOL', '.globl SYMBOL' +====================================== + +'.global' makes the symbol visible to 'ld'. If you define SYMBOL in +your partial program, its value is made available to other partial +programs that are linked with it. Otherwise, SYMBOL takes its +attributes from a symbol of the same name from another file linked into +the same program. + + Both spellings ('.globl' and '.global') are accepted, for +compatibility with other assemblers. + +7.51 '.hidden NAMES' +==================== + +This is one of the ELF visibility directives. The other two are +'.internal' (*note '.internal': Internal.) and '.protected' (*note +'.protected': 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 'hidden' which means that the symbols are not visible to +other components. Such symbols are always considered to be 'protected' +as well. + +7.52 '.hword EXPRESSIONS' +========================= + +This expects zero or more EXPRESSIONS, and emits a 16 bit number for +each. + + This directive is a synonym for '.short'. + +7.53 '.ident' +============= + +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, '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 +'.comment' or '.rdata' section, depending on the target. When using +ELF, comments are emitted to the '.comment' section. + +7.54 '.if ABSOLUTE EXPRESSION' +============================== + +'.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 ABSOLUTE EXPRESSION) is non-zero. The end of the conditional +section of code must be marked by '.endif' (*note '.endif': Endif.); +optionally, you may include code for the alternative condition, flagged +by '.else' (*note '.else': Else.). If you have several conditions to +check, '.elseif' may be used to avoid nesting blocks if/else within each +subsequent '.else' block. + + The following variants of '.if' are also supported: +'.ifdef SYMBOL' + Assembles the following section of code if the specified SYMBOL has + been defined. Note a symbol which has been referenced but not yet + defined is considered to be undefined. + +'.ifb TEXT' + Assembles the following section of code if the operand is blank + (empty). + +'.ifc STRING1,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. + +'.ifeq ABSOLUTE EXPRESSION' + Assembles the following section of code if the argument is zero. + +'.ifeqs STRING1,STRING2' + Another form of '.ifc'. The strings must be quoted using double + quotes. + +'.ifge ABSOLUTE EXPRESSION' + Assembles the following section of code if the argument is greater + than or equal to zero. + +'.ifgt ABSOLUTE EXPRESSION' + Assembles the following section of code if the argument is greater + than zero. + +'.ifle ABSOLUTE EXPRESSION' + Assembles the following section of code if the argument is less + than or equal to zero. + +'.iflt ABSOLUTE EXPRESSION' + Assembles the following section of code if the argument is less + than zero. + +'.ifnb TEXT' + Like '.ifb', but the sense of the test is reversed: this assembles + the following section of code if the operand is non-blank + (non-empty). + +'.ifnc STRING1,STRING2.' + Like '.ifc', but the sense of the test is reversed: this assembles + the following section of code if the two strings are not the same. + +'.ifndef SYMBOL' +'.ifnotdef SYMBOL' + Assembles the following section of code if the specified 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. + +'.ifne ABSOLUTE EXPRESSION' + Assembles the following section of code if the argument is not + equal to zero (in other words, this is equivalent to '.if'). + +'.ifnes STRING1,STRING2' + Like '.ifeqs', but the sense of the test is reversed: this + assembles the following section of code if the two strings are not + the same. + +7.55 '.incbin "FILE"[,SKIP[,COUNT]]' +==================================== + +The 'incbin' directive includes FILE verbatim at the current location. +You can control the search paths used with the '-I' command-line option +(*note Command-Line Options: Invoking.). Quotation marks are required +around FILE. + + The SKIP argument skips a number of bytes from the start of the FILE. +The 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 'incbin' directive. + +7.56 '.include "FILE"' +====================== + +This directive provides a way to include supporting files at specified +points in your source program. The code from FILE is assembled as if it +followed the point of the '.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 '-I' command-line option (*note +Command-Line Options: Invoking.). Quotation marks are required around +FILE. + +7.57 '.int EXPRESSIONS' +======================= + +Expect zero or more 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. + +7.58 '.internal NAMES' +====================== + +This is one of the ELF visibility directives. The other two are +'.hidden' (*note '.hidden': Hidden.) and '.protected' (*note +'.protected': 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 'internal' which means that the symbols are considered to +be 'hidden' (i.e., not visible to other components), and that some +extra, processor specific processing must also be performed upon the +symbols as well. + +7.59 '.irp SYMBOL,VALUES'... +============================ + +Evaluate a sequence of statements assigning different values to SYMBOL. +The sequence of statements starts at the '.irp' directive, and is +terminated by an '.endr' directive. For each VALUE, SYMBOL is set to +VALUE, and the sequence of statements is assembled. If no VALUE is +listed, the sequence of statements is assembled once, with SYMBOL set to +the null string. To refer to SYMBOL within the sequence of statements, +use \SYMBOL. + + For example, assembling + + .irp param,1,2,3 + move d\param,sp@- + .endr + + is equivalent to assembling + + move d1,sp@- + move d2,sp@- + move d3,sp@- + + For some caveats with the spelling of SYMBOL, see also *note Macro::. + +7.60 '.irpc SYMBOL,VALUES'... +============================= + +Evaluate a sequence of statements assigning different values to SYMBOL. +The sequence of statements starts at the '.irpc' directive, and is +terminated by an '.endr' directive. For each character in VALUE, SYMBOL +is set to the character, and the sequence of statements is assembled. +If no VALUE is listed, the sequence of statements is assembled once, +with SYMBOL set to the null string. To refer to SYMBOL within the +sequence of statements, use \SYMBOL. + + For example, assembling + + .irpc param,123 + move d\param,sp@- + .endr + + is equivalent to assembling + + move d1,sp@- + move d2,sp@- + move d3,sp@- + + For some caveats with the spelling of SYMBOL, see also the discussion +at *Note Macro::. + +7.61 '.lcomm SYMBOL , LENGTH' +============================= + +Reserve LENGTH (an absolute expression) bytes for a local common denoted +by SYMBOL. The section and value of 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. SYMBOL is not declared global +(*note '.global': Global.), so is normally not visible to 'ld'. + +7.62 '.lflags' +============== + +'as' accepts this directive, for compatibility with other assemblers, +but ignores it. + +7.63 '.line LINE-NUMBER' +======================== + +Even though this is a directive associated with the 'a.out' or 'b.out' +object-code formats, 'as' still recognizes it when producing COFF +output, and treats '.line' as though it were the COFF '.ln' _if_ it is +found outside a '.def'/'.endef' pair. + + Inside a '.def', '.line' is, instead, one of the directives used by +compilers to generate auxiliary symbol information for debugging. + +7.64 '.linkonce [TYPE]' +======================= + +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 '.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 TYPE argument is optional. If specified, it must be one of the +following strings. For example: + .linkonce same_size + Not all types may be supported on all object file formats. + +'discard' + Silently discard duplicate sections. This is the default. + +'one_only' + Warn if there are duplicate sections, but still keep only one copy. + +'same_size' + Warn if any of the duplicates have different sizes. + +'same_contents' + Warn if any of the duplicates do not have exactly the same + contents. + +7.65 '.ln LINE-NUMBER' +====================== + +'.ln' is a synonym for '.line'. + +7.66 '.mri VAL' +=============== + +If VAL is non-zero, this tells 'as' to enter MRI mode. If VAL is zero, +this tells 'as' to exit MRI mode. This change affects code assembled +until the next '.mri' directive, or until the end of the file. *Note +MRI mode: M. + +7.67 '.list' +============ + +Control (in conjunction with the '.nolist' directive) whether or not +assembly listings are generated. These two directives maintain an +internal counter (which is zero initially). '.list' increments the +counter, and '.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 +'-a' command line option; *note Command-Line Options: Invoking.), the +initial value of the listing counter is one. + +7.68 '.long EXPRESSIONS' +======================== + +'.long' is the same as '.int'. *Note '.int': Int. + +7.69 '.macro' +============= + +The commands '.macro' and '.endm' allow you to define macros that +generate assembly output. For example, this definition specifies a +macro 'sum' that puts a sequence of numbers into memory: + + .macro sum from=0, to=5 + .long \from + .if \to-\from + sum "(\from+1)",\to + .endif + .endm + +With that definition, 'SUM 0,5' is equivalent to this assembly input: + + .long 0 + .long 1 + .long 2 + .long 3 + .long 4 + .long 5 + +'.macro MACNAME' +'.macro MACNAME MACARGS ...' + Begin the definition of a macro called 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 ':'req''), or whether it takes all of the + remaining arguments (through ':'vararg''). You can supply a + default value for any macro argument by following the name with + '=DEFLT'. You cannot define two macros with the same MACNAME + unless it has been subject to the '.purgem' directive (*note + Purgem::) between the two definitions. For example, these are all + valid '.macro' statements: + + '.macro comm' + Begin the definition of a macro called 'comm', which takes no + arguments. + + '.macro plus1 p, p1' + '.macro plus1 p p1' + Either statement begins the definition of a macro called + 'plus1', which takes two arguments; within the macro + definition, write '\p' or '\p1' to evaluate the arguments. + + '.macro reserve_str p1=0 p2' + Begin the definition of a macro called '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 'reserve_str A,B' (with '\p1' evaluating + to A and '\p2' evaluating to B), or as 'reserve_str ,B' (with + '\p1' evaluating as the default, in this case '0', and '\p2' + evaluating to B). + + '.macro m p1:req, p2=0, p3:vararg' + Begin the definition of a macro called '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, 'sum 9,17' is + equivalent to 'sum to=17, from=9'. + + Note that since each of the 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 (':') 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: + + .macro label l + \l: + .endm + + might not work as expected. Invoking 'label foo' might not create + a label called 'foo' but instead just insert the text '\l:' into + the assembler source, probably generating an error about an + unrecognised identifier. + + Similarly problems might occur with the period character ('.') + 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: + + .macro opcode base length + \base.\length + .endm + + and invoking it as 'opcode store l' will not create a 'store.l' + instruction but instead generate some kind of error as the + assembler tries to interpret the text '\base.\length'. + + There are several possible ways around this problem: + + 'Insert white space' + If it is possible to use white space characters then this is + the simplest solution. eg: + + .macro label l + \l : + .endm + + 'Use '\()'' + The string '\()' can be used to separate the end of a macro + argument from the following text. eg: + + .macro opcode base length + \base\().\length + .endm + + 'Use the alternate macro syntax mode' + In the alternative macro syntax mode the ampersand character + ('&') can be used as a separator. eg: + + .altmacro + .macro label l + l&: + .endm + + Note: this problem of correctly identifying string parameters to + pseudo ops also applies to the identifiers used in '.irp' (*note + Irp::) and '.irpc' (*note Irpc::) as well. + +'.endm' + Mark the end of a macro definition. + +'.exitm' + Exit early from the current macro definition. + +'\@' + 'as' maintains a counter of how many macros it has executed in this + pseudo-variable; you can copy that number to your output with '\@', + but _only within a macro definition_. + +'LOCAL NAME [ , ... ]' + _Warning: 'LOCAL' is only available if you select "alternate macro + syntax" with '--alternate' or '.altmacro'._ *Note '.altmacro': + Altmacro. + +7.70 '.altmacro' +================ + +Enable alternate macro mode, enabling: + +'LOCAL NAME [ , ... ]' + One additional directive, 'LOCAL', is available. It is used to + generate a string replacement for each of the NAME arguments, and + replace any instances of NAME in each macro expansion. The + replacement string is unique in the assembly, and different for + each separate macro expansion. 'LOCAL' allows you to write macros + that define symbols, without fear of conflict between separate + macro expansions. + +'String delimiters' + You can write strings delimited in these other ways besides + '"STRING"': + + ''STRING'' + You can delimit strings with single-quote characters. + + '' + You can delimit strings with matching angle brackets. + +'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 '!' (an exclamation mark). For example, + you can write '<4.3 !> 5.4!!>' to get the literal text '4.3 > + 5.4!'. + +'Expression results as strings' + You can write '%EXPR' to evaluate the expression EXPR and use the + result as a string. + +7.71 '.noaltmacro' +================== + +Disable alternate macro mode. *Note Altmacro::. + +7.72 '.nolist' +============== + +Control (in conjunction with the '.list' directive) whether or not +assembly listings are generated. These two directives maintain an +internal counter (which is zero initially). '.list' increments the +counter, and '.nolist' decrements it. Assembly listings are generated +whenever the counter is greater than zero. + +7.73 '.octa BIGNUMS' +==================== + +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 _octa_-word for 16 bytes. + +7.74 '.org NEW-LC , FILL' +========================= + +Advance the location counter of the current section to NEW-LC. NEW-LC +is either an absolute expression or an expression with the same section +as the current subsection. That is, you can't use '.org' to cross +sections: if NEW-LC has the wrong section, the '.org' directive is +ignored. To be compatible with former assemblers, if the section of +NEW-LC is absolute, 'as' issues a warning, then pretends the section of +NEW-LC is the same as the current subsection. + + '.org' may only increase the location counter, or leave it unchanged; +you cannot use '.org' to move the location counter backwards. + + Because 'as' tries to assemble programs in one pass, 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 FILL which should be an absolute +expression. If the comma and FILL are omitted, FILL defaults to zero. + +7.75 '.p2align[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' +================================================ + +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 '.p2align 3' advances the location counter +until it a multiple of 8. If the location counter is already a multiple +of 8, no change is needed. + + The second expression (also absolute) gives the fill value to be +stored in the padding bytes. It (and the comma) may be omitted. If it +is omitted, the padding bytes are normally zero. However, on some +systems, if the section is marked as containing code and the fill value +is omitted, the space is filled with no-op instructions. + + The third expression is also absolute, and is also optional. If it +is present, it is the maximum number of bytes that should be skipped by +this alignment directive. If doing the alignment would require skipping +more bytes than the specified maximum, then the alignment is not done at +all. You can omit the fill value (the second argument) entirely by +simply using two commas after the required alignment; this can be useful +if you want the alignment to be filled with no-op instructions when +appropriate. + + The '.p2alignw' and '.p2alignl' directives are variants of the +'.p2align' directive. The '.p2alignw' directive treats the fill pattern +as a two byte word value. The '.p2alignl' directives treats the fill +pattern as a four byte longword value. For example, '.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. + +7.76 '.previous' +================ + +This is one of the ELF section stack manipulation directives. The +others are '.section' (*note Section::), '.subsection' (*note +SubSection::), '.pushsection' (*note PushSection::), and '.popsection' +(*note PopSection::). + + This directive swaps the current section (and subsection) with most +recently referenced section (and subsection) prior to this one. +Multiple '.previous' directives in a row will flip between two sections +(and their subsections). + + In terms of the section stack, this directive swaps the current +section with the top section on the section stack. + +7.77 '.popsection' +================== + +This is one of the ELF section stack manipulation directives. The +others are '.section' (*note Section::), '.subsection' (*note +SubSection::), '.pushsection' (*note PushSection::), and '.previous' +(*note 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. + +7.78 '.print STRING' +==================== + +'as' will print STRING on the standard output during assembly. You must +put STRING in double quotes. + +7.79 '.protected NAMES' +======================= + +This is one of the ELF visibility directives. The other two are +'.hidden' (*note Hidden::) and '.internal' (*note 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 '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. + +7.80 '.psize LINES , COLUMNS' +============================= + +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 '.psize', listings use a default line-count of 60. +You may omit the comma and COLUMNS specification; the default width is +200 columns. + + 'as' generates formfeeds whenever the specified number of lines is +exceeded (or whenever you explicitly request one, using '.eject'). + + If you specify LINES as '0', no formfeeds are generated save those +explicitly specified with '.eject'. + +7.81 '.purgem NAME' +=================== + +Undefine the macro NAME, so that later uses of the string will not be +expanded. *Note Macro::. + +7.82 '.pushsection NAME , SUBSECTION' +===================================== + +This is one of the ELF section stack manipulation directives. The +others are '.section' (*note Section::), '.subsection' (*note +SubSection::), '.popsection' (*note PopSection::), and '.previous' +(*note 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 'name' and 'subsection'. + +7.83 '.quad BIGNUMS' +==================== + +'.quad' expects zero or more bignums, separated by commas. For each +bignum, it emits 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. + + The term "quad" comes from contexts in which a "word" is two bytes; +hence _quad_-word for 8 bytes. + +7.84 '.reloc OFFSET, RELOC_NAME[, EXPRESSION]' +============================================== + +Generate a relocation at OFFSET of type RELOC_NAME with value +EXPRESSION. If OFFSET is a number, the relocation is generated in the +current section. If OFFSET is an expression that resolves to a symbol +plus offset, the relocation is generated in the given symbol's section. +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. + +7.85 '.rept COUNT' +================== + +Repeat the sequence of lines between the '.rept' directive and the next +'.endr' directive COUNT times. + + For example, assembling + + .rept 3 + .long 0 + .endr + + is equivalent to assembling + + .long 0 + .long 0 + .long 0 + +7.86 '.sbttl "SUBHEADING"' +========================== + +Use 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. + +7.87 '.section NAME' +==================== + +Use the '.section' directive to assemble the following code into a +section named NAME. + + This directive is only supported for targets that actually support +arbitrarily named sections; on 'a.out' targets, for example, it is not +accepted, even with a standard 'a.out' section name. + + This is one of the ELF section stack manipulation directives. The +others are '.subsection' (*note SubSection::), '.pushsection' (*note +PushSection::), '.popsection' (*note PopSection::), and '.previous' +(*note Previous::). + + For ELF targets, the '.section' directive is used like this: + + .section NAME [, "FLAGS"[, @TYPE[,FLAG_SPECIFIC_ARGUMENTS]]] + + The optional FLAGS argument is a quoted string which may contain any +combination of the following characters: +'a' + section is allocatable +'w' + section is writable +'x' + section is executable +'M' + section is mergeable +'S' + section contains zero terminated strings +'G' + section is a member of a section group +'T' + section is used for thread-local-storage + + The optional TYPE argument may contain one of the following +constants: +'@progbits' + section contains data +'@nobits' + section does not contain data (i.e., section only occupies space) +'@note' + section contains data which is used by things other than the + program +'@init_array' + section contains an array of pointers to init functions +'@fini_array' + section contains an array of pointers to finish functions +'@preinit_array' + section contains an array of pointers to pre-init functions + + Many targets only support the first three section types. + + Note on targets where the '@' character is the start of a comment (eg +ARM) then another character is used instead. For example the ARM port +uses the '%' character. + + If FLAGS contains the 'M' symbol then the TYPE argument must be +specified as well as an extra argument--ENTSIZE--like this: + + .section NAME , "FLAGS"M, @TYPE, ENTSIZE + + Sections with the 'M' flag but not 'S' flag must contain fixed size +constants, each ENTSIZE octets long. Sections with both 'M' and 'S' +must contain zero terminated strings where each character is ENTSIZE +bytes long. The linker may remove duplicates within sections with the +same name, same entity size and same flags. ENTSIZE must be an absolute +expression. + + If FLAGS contains the 'G' symbol then the TYPE argument must be +present along with an additional field like this: + + .section NAME , "FLAGS"G, @TYPE, GROUPNAME[, LINKAGE] + + The GROUPNAME field specifies the name of the section group to which +this particular section belongs. The optional linkage field can +contain: +'comdat' + indicates that only one copy of this section should be retained +'.gnu.linkonce' + an alias for comdat + + Note: if both the M and G flags are present then the fields for the +Merge flag should come first, like this: + + .section NAME , "FLAGS"MG, @TYPE, ENTSIZE, GROUPNAME[, LINKAGE] + + 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 '.section' +directive for compatibility with the Solaris assembler: + + .section "NAME"[, FLAGS...] + + Note that the section name is quoted. There may be a sequence of +comma separated flags: +'#alloc' + section is allocatable +'#write' + section is writable +'#execinstr' + section is executable +'#tls' + section is used for thread local storage + + This directive replaces the current section and subsection. See the +contents of the gas testsuite directory 'gas/testsuite/gas/elf' for some +examples of how this directive and the other section stack directives +work. + +7.88 '.set SYMBOL, EXPRESSION' +============================== + +Set the value of SYMBOL to EXPRESSION. This changes SYMBOL's value and +type to conform to EXPRESSION. If SYMBOL was flagged as external, it +remains flagged (*note Symbol Attributes::). + + You may '.set' a symbol many times in the same assembly. + + If you '.set' a global symbol, the value stored in the object file is +the last value stored into it. + +7.89 '.short EXPRESSIONS' +========================= + +This expects zero or more EXPRESSIONS, and emits a 16 bit number for +each. + +7.90 '.single FLONUMS' +====================== + +This directive assembles zero or more flonums, separated by commas. It +has the same effect as '.float'. + +7.91 '.size' +============ + +This directive is used to set the size associated with a symbol. + + For ELF targets, the '.size' directive is used like this: + + .size NAME , EXPRESSION + + This directive sets the size associated with a symbol NAME. The size +in bytes is computed from EXPRESSION which can make use of label +arithmetic. This directive is typically used to set the size of +function symbols. + +7.92 '.sleb128 EXPRESSIONS' +=========================== + +SLEB128 stands for "signed little endian base 128." This is a compact, +variable length representation of numbers used by the DWARF symbolic +debugging format. *Note '.uleb128': Uleb128. + +7.93 '.skip SIZE , FILL' +======================== + +This directive emits SIZE bytes, each of value FILL. Both SIZE and FILL +are absolute expressions. If the comma and FILL are omitted, FILL is +assumed to be zero. This is the same as '.space'. + +7.94 '.space SIZE , FILL' +========================= + +This directive emits SIZE bytes, each of value FILL. Both SIZE and FILL +are absolute expressions. If the comma and FILL are omitted, FILL is +assumed to be zero. This is the same as '.skip'. + +7.95 '.stabd, .stabn, .stabs' +============================= + +There are three directives that begin '.stab'. All emit symbols (*note +Symbols::), for use by symbolic debuggers. The symbols are not entered +in the 'as' hash table: they cannot be referenced elsewhere in the +source file. Up to five fields are required: + +STRING + This is the symbol's name. It may contain any character except + '\000', so is more general than ordinary symbol names. Some + debuggers used to code arbitrarily complex structures into symbol + names using this field. + +TYPE + An absolute expression. The symbol's type is set to the low 8 bits + of this expression. Any bit pattern is permitted, but 'ld' and + debuggers choke on silly bit patterns. + +OTHER + An absolute expression. The symbol's "other" attribute is set to + the low 8 bits of this expression. + +DESC + An absolute expression. The symbol's descriptor is set to the low + 16 bits of this expression. + +VALUE + An absolute expression which becomes the symbol's value. + + If a warning is detected while reading a '.stabd', '.stabn', or +'.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! + +'.stabd TYPE , OTHER , 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 '.stabd' was assembled. + +'.stabn TYPE , OTHER , DESC , VALUE' + The name of the symbol is set to the empty string '""'. + +'.stabs STRING , TYPE , OTHER , DESC , VALUE' + All five fields are specified. + +7.96 '.string' "STR" +==================== + +Copy the characters in 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 *note Strings: Strings. + +7.97 '.struct EXPRESSION' +========================= + +Switch to the absolute section, and set the section offset to +EXPRESSION, which must be an absolute expression. You might use this as +follows: + .struct 0 + field1: + .struct field1 + 4 + field2: + .struct field2 + 4 + field3: + This would define the symbol 'field1' to have the value 0, the symbol +'field2' to have the value 4, and the symbol 'field3' to have the value +8. Assembly would be left in the absolute section, and you would need +to use a '.section' directive of some sort to change to some other +section before further assembly. + +7.98 '.subsection NAME' +======================= + +This is one of the ELF section stack manipulation directives. The +others are '.section' (*note Section::), '.pushsection' (*note +PushSection::), '.popsection' (*note PopSection::), and '.previous' +(*note Previous::). + + This directive replaces the current subsection with '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. + +7.99 '.symver' +============== + +Use the '.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 '.symver' directive can be used like this: + .symver NAME, NAME2@NODENAME + If the symbol NAME is defined within the file being assembled, the +'.symver' directive effectively creates a symbol alias with the name +NAME2@NODENAME, and in fact the main reason that we just don't try and +create a regular alias is that the @ character isn't permitted in symbol +names. The NAME2 part of the name is the actual name of the symbol by +which it will be externally referenced. The name 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 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 NODENAME should +correspond to the nodename of the symbol you are trying to override. + + If the symbol NAME is not defined within the file being assembled, +all references to NAME will be changed to NAME2@NODENAME. If no +reference to NAME is made, NAME2@NODENAME will be removed from the +symbol table. + + Another usage of the '.symver' directive is: + .symver NAME, NAME2@@NODENAME + In this case, the symbol NAME must exist and be defined within the +file being assembled. It is similar to NAME2@NODENAME. The difference +is NAME2@@NODENAME will also be used to resolve references to NAME2 by +the linker. + + The third usage of the '.symver' directive is: + .symver NAME, NAME2@@@NODENAME + When NAME is not defined within the file being assembled, it is +treated as NAME2@NODENAME. When NAME is defined within the file being +assembled, the symbol name, NAME, will be changed to NAME2@@NODENAME. + +7.100 '.text SUBSECTION' +======================== + +Tells 'as' to assemble the following statements onto the end of the text +subsection numbered SUBSECTION, which is an absolute expression. If +SUBSECTION is omitted, subsection number zero is used. + +7.101 '.title "HEADING"' +======================== + +Use 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. + +7.102 '.type' +============= + +This directive is used to set the type of a symbol. + + For ELF targets, the '.type' directive is used like this: + + .type NAME , TYPE DESCRIPTION + + This sets the type of symbol NAME to be either a function symbol or +an object symbol. There are five different syntaxes supported for the +TYPE DESCRIPTION field, in order to provide compatibility with various +other assemblers. + + Because some of the characters used in these syntaxes (such as '@' +and '#') 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: + + .type STT_FUNCTION + .type STT_OBJECT + + .type ,#function + .type ,#object + + .type ,@function + .type ,@object + + .type ,%function + .type ,%object + + .type ,"function" + .type ,"object" + +7.103 '.uleb128 EXPRESSIONS' +============================ + +ULEB128 stands for "unsigned little endian base 128." This is a +compact, variable length representation of numbers used by the DWARF +symbolic debugging format. *Note '.sleb128': Sleb128. + +7.104 '.version "STRING"' +========================= + +This directive creates a '.note' section and places into it an ELF +formatted note of type NT_VERSION. The note's name is set to 'string'. + +7.105 '.vtable_entry TABLE, OFFSET' +=================================== + +This directive finds or creates a symbol 'table' and creates a +'VTABLE_ENTRY' relocation for it with an addend of 'offset'. + +7.106 '.vtable_inherit CHILD, PARENT' +===================================== + +This directive finds the symbol 'child' and finds or creates the symbol +'parent' and then creates a 'VTABLE_INHERIT' relocation for the parent +whose addend is the value of the child symbol. As a special case the +parent name of '0' is treated as referring to the '*ABS*' section. + +7.107 '.warning "STRING"' +========================= + +Similar to the directive '.error' (*note '.error "STRING"': Error.), but +just emits a warning. + +7.108 '.weak NAMES' +=================== + +This directive sets the weak attribute on the comma separated list of +symbol '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 '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. + +7.109 '.weakref ALIAS, TARGET' +============================== + +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. + +7.110 '.word EXPRESSIONS' +========================= + +This directive expects zero or more EXPRESSIONS, of any section, +separated by commas. For each expression, 'as' emits a 32-bit number. + +7.111 Deprecated Directives +=========================== + +One day these directives won't work. They are included for +compatibility with older assemblers. +.abort +.line + +8 ARM Dependent Features +************************ + +8.1 Options +=========== + +'-mcpu=PROCESSOR[+EXTENSION...]' + This option specifies the target processor. The assembler will + issue an error message if an attempt is made to assemble an + instruction which will not execute on the target processor. The + following processor names are recognized: 'arm1', 'arm2', 'arm250', + 'arm3', 'arm6', 'arm60', 'arm600', 'arm610', 'arm620', 'arm7', + 'arm7m', 'arm7d', 'arm7dm', 'arm7di', 'arm7dmi', 'arm70', 'arm700', + 'arm700i', 'arm710', 'arm710t', 'arm720', 'arm720t', 'arm740t', + 'arm710c', 'arm7100', 'arm7500', 'arm7500fe', 'arm7t', 'arm7tdmi', + 'arm7tdmi-s', 'arm8', 'arm810', 'strongarm', 'strongarm1', + 'strongarm110', 'strongarm1100', 'strongarm1110', 'arm9', 'arm920', + 'arm920t', 'arm922t', 'arm940t', 'arm9tdmi', 'arm9e', 'arm926e', + 'arm926ej-s', 'arm946e-r0', 'arm946e', 'arm946e-s', 'arm966e-r0', + 'arm966e', 'arm966e-s', 'arm968e-s', 'arm10t', 'arm10tdmi', + 'arm10e', 'arm1020', 'arm1020t', 'arm1020e', 'arm1022e', + 'arm1026ej-s', 'arm1136j-s', 'arm1136jf-s', 'arm1156t2-s', + 'arm1156t2f-s', 'arm1176jz-s', 'arm1176jzf-s', 'mpcore', + 'mpcorenovfp', 'cortex-a8', 'cortex-r4', 'cortex-m3', 'ep9312' + (ARM920 with Cirrus Maverick coprocessor), 'i80200' (Intel XScale + processor) 'iwmmxt' (Intel(r) XScale processor with Wireless + MMX(tm) technology coprocessor) and 'xscale'. The special name + 'all' may be used to allow the assembler to accept instructions + valid for any ARM processor. + + In addition to the basic instruction set, the assembler can be told + to accept various extension mnemonics that extend the processor + using the co-processor instruction space. For example, + '-mcpu=arm920+maverick' is equivalent to specifying '-mcpu=ep9312'. + The following extensions are currently supported: '+maverick' + '+iwmmxt' and '+xscale'. + +'-march=ARCHITECTURE[+EXTENSION...]' + This option specifies the target architecture. The assembler will + issue an error message if an attempt is made to assemble an + instruction which will not execute on the target architecture. The + following architecture names are recognized: 'armv1', 'armv2', + 'armv2a', 'armv2s', 'armv3', 'armv3m', 'armv4', 'armv4xm', + 'armv4t', 'armv4txm', 'armv5', 'armv5t', 'armv5txm', 'armv5te', + 'armv5texp', 'armv6', 'armv6j', 'armv6k', 'armv6z', 'armv6zk', + 'armv7', 'armv7-a', 'armv7-r', 'armv7-m', 'iwmmxt' and 'xscale'. + If both '-mcpu' and '-march' are specified, the assembler will use + the setting for '-mcpu'. + + The architecture option can be extended with the same instruction + set extension options as the '-mcpu' option. + +'-mfpu=FLOATING-POINT-FORMAT' + + This option specifies the floating point format to assemble for. + The assembler will issue an error message if an attempt is made to + assemble an instruction which will not execute on the target + floating point unit. The following format options are recognized: + 'softfpa', 'fpe', 'fpe2', 'fpe3', 'fpa', 'fpa10', 'fpa11', + 'arm7500fe', 'softvfp', 'softvfp+vfp', 'vfp', 'vfp10', 'vfp10-r0', + 'vfp9', 'vfpxd', 'arm1020t', 'arm1020e', 'arm1136jf-s' and + 'maverick'. + + In addition to determining which instructions are assembled, this + option also affects the way in which the '.double' assembler + directive behaves when assembling little-endian code. + + The default is dependent on the processor selected. For + Architecture 5 or later, the default is to assembler for VFP + instructions; for earlier architectures the default is to assemble + for FPA instructions. + +'-mthumb' + This option specifies that the assembler should start assembling + Thumb instructions; that is, it should behave as though the file + starts with a '.code 16' directive. + +'-mthumb-interwork' + This option specifies that the output generated by the assembler + should be marked as supporting interworking. + +'-mapcs [26|32]' + This option specifies that the output generated by the assembler + should be marked as supporting the indicated version of the Arm + Procedure. Calling Standard. + +'-matpcs' + This option specifies that the output generated by the assembler + should be marked as supporting the Arm/Thumb Procedure Calling + Standard. If enabled this option will cause the assembler to + create an empty debugging section in the object file called + .arm.atpcs. Debuggers can use this to determine the ABI being used + by. + +'-mapcs-float' + This indicates the floating point variant of the APCS should be + used. In this variant floating point arguments are passed in FP + registers rather than integer registers. + +'-mapcs-reentrant' + This indicates that the reentrant variant of the APCS should be + used. This variant supports position independent code. + +'-mfloat-abi=ABI' + This option specifies that the output generated by the assembler + should be marked as using specified floating point ABI. The + following values are recognized: 'soft', 'softfp' and 'hard'. + +'-meabi=VER' + This option specifies which EABI version the produced object files + should conform to. The following values are recognized: 'gnu', '4' + and '5'. + +'-EB' + This option specifies that the output generated by the assembler + should be marked as being encoded for a big-endian processor. + +'-EL' + This option specifies that the output generated by the assembler + should be marked as being encoded for a little-endian processor. + +'-k' + This option specifies that the output of the assembler should be + marked as position-independent code (PIC). + +8.2 Syntax +========== + +8.2.1 Special Characters +------------------------ + +The presence of a '@' on a line indicates the start of a comment that +extends to the end of the current line. If a '#' appears as the first +character of a line, the whole line is treated as a comment. + + The ';' character can be used instead of a newline to separate +statements. + + Either '#' or '$' can be used to indicate immediate operands. + + *TODO* Explain about /data modifier on symbols. + +8.2.2 Register Names +-------------------- + +*TODO* Explain about ARM register naming, and the predefined names. + +8.2.3 ARM relocation generation +------------------------------- + +Specific data relocations can be generated by putting the relocation +name in parentheses after the symbol name. For example: + + .word foo(TARGET1) + + This will generate an 'R_ARM_TARGET1' relocation against the symbol +FOO. The following relocations are supported: 'GOT', 'GOTOFF', +'TARGET1', 'TARGET2', 'SBREL', 'TLSGD', 'TLSLDM', 'TLSLDO', 'GOTTPOFF' +and 'TPOFF'. + + For compatibility with older toolchains the assembler also accepts +'(PLT)' after branch targets. This will generate the deprecated +'R_ARM_PLT32' relocation. + + Relocations for 'MOVW' and 'MOVT' instructions can be generated by +prefixing the value with '#:lower16:' and '#:upper16' respectively. For +example to load the 32-bit address of foo into r0: + + MOVW r0, #:lower16:foo + MOVT r0, #:upper16:foo + +8.3 Floating Point +================== + +The ARM family uses IEEE floating-point numbers. + +8.4 ARM Machine Directives +========================== + +'.align EXPRESSION [, EXPRESSION]' + This is the generic .ALIGN directive. For the ARM however if the + first argument is zero (ie no alignment is needed) the assembler + will behave as if the argument had been 2 (ie pad to the next four + byte boundary). This is for compatibility with ARM's own + assembler. + +'NAME .req REGISTER NAME' + This creates an alias for REGISTER NAME called NAME. For example: + + foo .req r0 + +'.unreq ALIAS-NAME' + This undefines a register alias which was previously defined using + the 'req', 'dn' or 'qn' directives. For example: + + foo .req r0 + .unreq foo + + An error occurs if the name is undefined. Note - this pseudo op + can be used to delete builtin in register name aliases (eg 'r0'). + This should only be done if it is really necessary. + +'NAME .dn REGISTER NAME [.TYPE] [[INDEX]]' +'NAME .qn REGISTER NAME [.TYPE] [[INDEX]]' + + The 'dn' and 'qn' directives are used to create typed and/or + indexed register aliases for use in Advanced SIMD Extension (Neon) + instructions. The former should be used to create aliases of + double-precision registers, and the latter to create aliases of + quad-precision registers. + + If these directives are used to create typed aliases, those aliases + can be used in Neon instructions instead of writing types after the + mnemonic or after each operand. For example: + + x .dn d2.f32 + y .dn d3.f32 + z .dn d4.f32[1] + vmul x,y,z + + This is equivalent to writing the following: + + vmul.f32 d2,d3,d4[1] + + Aliases created using 'dn' or 'qn' can be destroyed using 'unreq'. + +'.code [16|32]' + This directive selects the instruction set being generated. The + value 16 selects Thumb, with the value 32 selecting ARM. + +'.thumb' + This performs the same action as .CODE 16. + +'.arm' + This performs the same action as .CODE 32. + +'.force_thumb' + This directive forces the selection of Thumb instructions, even if + the target processor does not support those instructions + +'.thumb_func' + This directive specifies that the following symbol is the name of a + Thumb encoded function. This information is necessary in order to + allow the assembler and linker to generate correct code for + interworking between Arm and Thumb instructions and should be used + even if interworking is not going to be performed. The presence of + this directive also implies '.thumb' + + This directive is not neccessary when generating EABI objects. On + these targets the encoding is implicit when generating Thumb code. + +'.thumb_set' + This performs the equivalent of a '.set' directive in that it + creates a symbol which is an alias for another symbol (possibly not + yet defined). This directive also has the added property in that + it marks the aliased symbol as being a thumb function entry point, + in the same way that the '.thumb_func' directive does. + +'.ltorg' + This directive causes the current contents of the literal pool to + be dumped into the current section (which is assumed to be the + .text section) at the current location (aligned to a word + boundary). 'GAS' maintains a separate literal pool for each + section and each sub-section. The '.ltorg' directive will only + affect the literal pool of the current section and sub-section. At + the end of assembly all remaining, un-empty literal pools will + automatically be dumped. + + Note - older versions of 'GAS' would dump the current literal pool + any time a section change occurred. This is no longer done, since + it prevents accurate control of the placement of literal pools. + +'.pool' + This is a synonym for .ltorg. + +'.unwind_fnstart' + Marks the start of a function with an unwind table entry. + +'.unwind_fnend' + Marks the end of a function with an unwind table entry. The unwind + index table entry is created when this directive is processed. + + If no personality routine has been specified then standard + personality routine 0 or 1 will be used, depending on the number of + unwind opcodes required. + +'.cantunwind' + Prevents unwinding through the current function. No personality + routine or exception table data is required or permitted. + +'.personality NAME' + Sets the personality routine for the current function to NAME. + +'.personalityindex INDEX' + Sets the personality routine for the current function to the EABI + standard routine number INDEX + +'.handlerdata' + Marks the end of the current function, and the start of the + exception table entry for that function. Anything between this + directive and the '.fnend' directive will be added to the exception + table entry. + + Must be preceded by a '.personality' or '.personalityindex' + directive. + +'.save REGLIST' + Generate unwinder annotations to restore the registers in REGLIST. + The format of REGLIST is the same as the corresponding + store-multiple instruction. + + _core registers_ + .save {r4, r5, r6, lr} + stmfd sp!, {r4, r5, r6, lr} + _FPA registers_ + .save f4, 2 + sfmfd f4, 2, [sp]! + _VFP registers_ + .save {d8, d9, d10} + fstmdx sp!, {d8, d9, d10} + _iWMMXt registers_ + .save {wr10, wr11} + wstrd wr11, [sp, #-8]! + wstrd wr10, [sp, #-8]! + or + .save wr11 + wstrd wr11, [sp, #-8]! + .save wr10 + wstrd wr10, [sp, #-8]! + +'.vsave VFP-REGLIST' + Generate unwinder annotations to restore the VFP registers in + VFP-REGLIST using FLDMD. Also works for VFPv3 registers that are to + be restored using VLDM. The format of VFP-REGLIST is the same as + the corresponding store-multiple instruction. + + _VFP registers_ + .vsave {d8, d9, d10} + fstmdd sp!, {d8, d9, d10} + _VFPv3 registers_ + .vsave {d15, d16, d17} + vstm sp!, {d15, d16, d17} + + Since FLDMX and FSTMX are now deprecated, this directive should be + used in favour of '.save' for saving VFP registers for ARMv6 and + above. + +'.pad #COUNT' + Generate unwinder annotations for a stack adjustment of COUNT + bytes. A positive value indicates the function prologue allocated + stack space by decrementing the stack pointer. + +'.movsp REG [, #OFFSET]' + Tell the unwinder that REG contains an offset from the current + stack pointer. If OFFSET is not specified then it is assumed to be + zero. + +'.setfp FPREG, SPREG [, #OFFSET]' + Make all unwinder annotations relaive to a frame pointer. Without + this the unwinder will use offsets from the stack pointer. + + The syntax of this directive is the same as the 'sub' or 'mov' + instruction used to set the frame pointer. SPREG must be either + 'sp' or mentioned in a previous '.movsp' directive. + + .movsp ip + mov ip, sp + ... + .setfp fp, ip, #4 + sub fp, ip, #4 + +'.raw OFFSET, BYTE1, ...' + Insert one of more arbitary unwind opcode bytes, which are known to + adjust the stack pointer by OFFSET bytes. + + For example '.unwind_raw 4, 0xb1, 0x01' is equivalent to '.save + {r0}' + +'.cpu NAME' + Select the target processor. Valid values for NAME are the same as + for the '-mcpu' commandline option. + +'.arch NAME' + Select the target architecture. Valid values for NAME are the same + as for the '-march' commandline option. + +'.object_arch NAME' + Override the architecture recorded in the EABI object attribute + section. Valid values for NAME are the same as for the '.arch' + directive. Typically this is useful when code uses runtime + detection of CPU features. + +'.fpu NAME' + Select the floating point unit to assemble for. Valid values for + NAME are the same as for the '-mfpu' commandline option. + +'.eabi_attribute TAG, VALUE' + Set the EABI object attribute number TAG to VALUE. The value is + either a 'number', '"string"', or 'number, "string"' depending on + the tag. + +8.5 Opcodes +=========== + +'as' implements all the standard ARM opcodes. It also implements +several pseudo opcodes, including several synthetic load instructions. + +'NOP' + nop + + This pseudo op will always evaluate to a legal ARM instruction that + does nothing. Currently it will evaluate to MOV r0, r0. + +'LDR' + ldr , = + + If expression evaluates to a numeric constant then a MOV or MVN + instruction will be used in place of the LDR instruction, if the + constant can be generated by either of these instructions. + Otherwise the constant will be placed into the nearest literal pool + (if it not already there) and a PC relative LDR instruction will be + generated. + +'ADR' + adr