diff options
| -rw-r--r-- | contrib/binutils/bfd/doc/bfdver.texi | 1 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/as.txt | 13924 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/asconfig.texi | 90 | ||||
| -rw-r--r-- | contrib/binutils/ld/configdoc.texi | 25 | ||||
| -rw-r--r-- | contrib/binutils/ld/ld.txt | 6564 | ||||
| -rw-r--r-- | etc/mtree/BSD.usr.dist | 2 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/Makefile | 3 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/doc/Makefile | 12 |
8 files changed, 20620 insertions, 1 deletions
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 <ctl-D> 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. + + '<STRING>' + 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 <name> STT_FUNCTION + .type <name> STT_OBJECT + + .type <name>,#function + .type <name>,#object + + .type <name>,@function + .type <name>,@object + + .type <name>,%function + .type <name>,%object + + .type <name>,"function" + .type <name>,"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 <register> , = <expression> + + 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 <register> <label> + + This instruction will load the address of LABEL into the indicated + register. The instruction will evaluate to a PC relative ADD or + SUB instruction depending upon where the label is located. If the + label is out of range, or if it is not defined in the same file + (and section) as the ADR instruction, then an error will be + generated. This instruction will not make use of the literal pool. + +'ADRL' + adrl <register> <label> + + This instruction will load the address of LABEL into the indicated + register. The instruction will evaluate to one or two PC relative + ADD or SUB instructions depending upon where the label is located. + If a second instruction is not needed a NOP instruction will be + generated in its place, so that this instruction is always 8 bytes + long. + + If the label is out of range, or if it is not defined in the same + file (and section) as the ADRL instruction, then an error will be + generated. This instruction will not make use of the literal pool. + + For information on the ARM or Thumb instruction sets, see 'ARM +Software Development Toolkit Reference Manual', Advanced RISC Machines +Ltd. + +8.6 Mapping Symbols +=================== + +The ARM ELF specification requires that special symbols be inserted into +object files to mark certain features: + +'$a' + At the start of a region of code containing ARM instructions. + +'$t' + At the start of a region of code containing THUMB instructions. + +'$d' + At the start of a region of data. + + The assembler will automatically insert these symbols for you - there +is no need to code them yourself. Support for tagging symbols ($b, $f, +$p and $m) which is also mentioned in the current ARM ELF specification +is not implemented. This is because they have been dropped from the new +EABI and so tools cannot rely upon their presence. + +9 80386 Dependent Features +************************** + +The i386 version 'as' supports both the original Intel 386 architecture +in both 16 and 32-bit mode as well as AMD x86-64 architecture extending +the Intel architecture to 64-bits. + +9.1 Options +=========== + +The i386 version of 'as' has a few machine dependent options: + +'--32 | --64' + Select the word size, either 32 bits or 64 bits. Selecting 32-bit + implies Intel i386 architecture, while 64-bit implies AMD x86-64 + architecture. + + These options are only available with the ELF object file format, + and require that the necessary BFD support has been included (on a + 32-bit platform you have to add -enable-64-bit-bfd to configure + enable 64-bit usage and use x86-64 as target platform). + +'-n' + By default, x86 GAS replaces multiple nop instructions used for + alignment within code sections with multi-byte nop instructions + such as leal 0(%esi,1),%esi. This switch disables the + optimization. + +'--divide' + On SVR4-derived platforms, the character '/' is treated as a + comment character, which means that it cannot be used in + expressions. The '--divide' option turns '/' into a normal + character. This does not disable '/' at the beginning of a line + starting a comment, or affect using '#' for starting a comment. + +'-march=CPU' + This option specifies an instruction set architecture for + generating instructions. The following architectures are + recognized: 'i8086', 'i186', 'i286', 'i386', 'i486', 'i586', + 'i686', 'pentium', 'pentiumpro', 'pentiumii', 'pentiumiii', + 'pentium4', 'prescott', 'nocona', 'core', 'core2', 'k6', 'k6_2', + 'athlon', 'sledgehammer', 'opteron', 'k8', 'generic32' and + 'generic64'. + + This option only affects instructions generated by the assembler. + The '.arch' directive will take precedent. + +'-mtune=CPU' + This option specifies a processor to optimize for. When used in + conjunction with the '-march' option, only instructions of the + processor specified by the '-march' option will be generated. + + Valid CPU values are identical to '-march=CPU'. + +9.2 AT&T Syntax versus Intel Syntax +=================================== + +'as' now supports assembly using Intel assembler syntax. +'.intel_syntax' selects Intel mode, and '.att_syntax' switches back to +the usual AT&T mode for compatibility with the output of 'gcc'. Either +of these directives may have an optional argument, 'prefix', or +'noprefix' specifying whether registers require a '%' prefix. AT&T +System V/386 assembler syntax is quite different from Intel syntax. We +mention these differences because almost all 80386 documents use Intel +syntax. Notable differences between the two syntaxes are: + + * AT&T immediate operands are preceded by '$'; Intel immediate + operands are undelimited (Intel 'push 4' is AT&T 'pushl $4'). AT&T + register operands are preceded by '%'; Intel register operands are + undelimited. AT&T absolute (as opposed to PC relative) jump/call + operands are prefixed by '*'; they are undelimited in Intel syntax. + + * AT&T and Intel syntax use the opposite order for source and + destination operands. Intel 'add eax, 4' is 'addl $4, %eax'. The + 'source, dest' convention is maintained for compatibility with + previous Unix assemblers. Note that instructions with more than + one source operand, such as the 'enter' instruction, do _not_ have + reversed order. *note i386-Bugs::. + + * In AT&T syntax the size of memory operands is determined from the + last character of the instruction mnemonic. Mnemonic suffixes of + 'b', 'w', 'l' and 'q' specify byte (8-bit), word (16-bit), long + (32-bit) and quadruple word (64-bit) memory references. Intel + syntax accomplishes this by prefixing memory operands (_not_ the + instruction mnemonics) with 'byte ptr', 'word ptr', 'dword ptr' and + 'qword ptr'. Thus, Intel 'mov al, byte ptr FOO' is 'movb FOO, %al' + in AT&T syntax. + + * Immediate form long jumps and calls are 'lcall/ljmp $SECTION, + $OFFSET' in AT&T syntax; the Intel syntax is 'call/jmp far + SECTION:OFFSET'. Also, the far return instruction is 'lret + $STACK-ADJUST' in AT&T syntax; Intel syntax is 'ret far + STACK-ADJUST'. + + * The AT&T assembler does not provide support for multiple section + programs. Unix style systems expect all programs to be single + sections. + +9.3 Instruction Naming +====================== + +Instruction mnemonics are suffixed with one character modifiers which +specify the size of operands. The letters 'b', 'w', 'l' and 'q' specify +byte, word, long and quadruple word operands. If no suffix is specified +by an instruction then 'as' tries to fill in the missing suffix based on +the destination register operand (the last one by convention). Thus, +'mov %ax, %bx' is equivalent to 'movw %ax, %bx'; also, 'mov $1, %bx' is +equivalent to 'movw $1, bx'. Note that this is incompatible with the +AT&T Unix assembler which assumes that a missing mnemonic suffix implies +long operand size. (This incompatibility does not affect compiler +output since compilers always explicitly specify the mnemonic suffix.) + + Almost all instructions have the same names in AT&T and Intel format. +There are a few exceptions. The sign extend and zero extend +instructions need two sizes to specify them. They need a size to +sign/zero extend _from_ and a size to zero extend _to_. This is +accomplished by using two instruction mnemonic suffixes in AT&T syntax. +Base names for sign extend and zero extend are 'movs...' and 'movz...' +in AT&T syntax ('movsx' and 'movzx' in Intel syntax). The instruction +mnemonic suffixes are tacked on to this base name, the _from_ suffix +before the _to_ suffix. Thus, 'movsbl %al, %edx' is AT&T syntax for +"move sign extend _from_ %al _to_ %edx." Possible suffixes, thus, are +'bl' (from byte to long), 'bw' (from byte to word), 'wl' (from word to +long), 'bq' (from byte to quadruple word), 'wq' (from word to quadruple +word), and 'lq' (from long to quadruple word). + + The Intel-syntax conversion instructions + + * 'cbw' -- sign-extend byte in '%al' to word in '%ax', + + * 'cwde' -- sign-extend word in '%ax' to long in '%eax', + + * 'cwd' -- sign-extend word in '%ax' to long in '%dx:%ax', + + * 'cdq' -- sign-extend dword in '%eax' to quad in '%edx:%eax', + + * 'cdqe' -- sign-extend dword in '%eax' to quad in '%rax' (x86-64 + only), + + * 'cqo' -- sign-extend quad in '%rax' to octuple in '%rdx:%rax' + (x86-64 only), + +are called 'cbtw', 'cwtl', 'cwtd', 'cltd', 'cltq', and 'cqto' in AT&T +naming. 'as' accepts either naming for these instructions. + + Far call/jump instructions are 'lcall' and 'ljmp' in AT&T syntax, but +are 'call far' and 'jump far' in Intel convention. + +9.4 Register Naming +=================== + +Register operands are always prefixed with '%'. The 80386 registers +consist of + + * the 8 32-bit registers '%eax' (the accumulator), '%ebx', '%ecx', + '%edx', '%edi', '%esi', '%ebp' (the frame pointer), and '%esp' (the + stack pointer). + + * the 8 16-bit low-ends of these: '%ax', '%bx', '%cx', '%dx', '%di', + '%si', '%bp', and '%sp'. + + * the 8 8-bit registers: '%ah', '%al', '%bh', '%bl', '%ch', '%cl', + '%dh', and '%dl' (These are the high-bytes and low-bytes of '%ax', + '%bx', '%cx', and '%dx') + + * the 6 section registers '%cs' (code section), '%ds' (data section), + '%ss' (stack section), '%es', '%fs', and '%gs'. + + * the 3 processor control registers '%cr0', '%cr2', and '%cr3'. + + * the 6 debug registers '%db0', '%db1', '%db2', '%db3', '%db6', and + '%db7'. + + * the 2 test registers '%tr6' and '%tr7'. + + * the 8 floating point register stack '%st' or equivalently '%st(0)', + '%st(1)', '%st(2)', '%st(3)', '%st(4)', '%st(5)', '%st(6)', and + '%st(7)'. These registers are overloaded by 8 MMX registers + '%mm0', '%mm1', '%mm2', '%mm3', '%mm4', '%mm5', '%mm6' and '%mm7'. + + * the 8 SSE registers registers '%xmm0', '%xmm1', '%xmm2', '%xmm3', + '%xmm4', '%xmm5', '%xmm6' and '%xmm7'. + + The AMD x86-64 architecture extends the register set by: + + * enhancing the 8 32-bit registers to 64-bit: '%rax' (the + accumulator), '%rbx', '%rcx', '%rdx', '%rdi', '%rsi', '%rbp' (the + frame pointer), '%rsp' (the stack pointer) + + * the 8 extended registers '%r8'-'%r15'. + + * the 8 32-bit low ends of the extended registers: '%r8d'-'%r15d' + + * the 8 16-bit low ends of the extended registers: '%r8w'-'%r15w' + + * the 8 8-bit low ends of the extended registers: '%r8b'-'%r15b' + + * the 4 8-bit registers: '%sil', '%dil', '%bpl', '%spl'. + + * the 8 debug registers: '%db8'-'%db15'. + + * the 8 SSE registers: '%xmm8'-'%xmm15'. + +9.5 Instruction Prefixes +======================== + +Instruction prefixes are used to modify the following instruction. They +are used to repeat string instructions, to provide section overrides, to +perform bus lock operations, and to change operand and address sizes. +(Most instructions that normally operate on 32-bit operands will use +16-bit operands if the instruction has an "operand size" prefix.) +Instruction prefixes are best written on the same line as the +instruction they act upon. For example, the 'scas' (scan string) +instruction is repeated with: + + repne scas %es:(%edi),%al + + You may also place prefixes on the lines immediately preceding the +instruction, but this circumvents checks that 'as' does with prefixes, +and will not work with all prefixes. + + Here is a list of instruction prefixes: + + * Section override prefixes 'cs', 'ds', 'ss', 'es', 'fs', 'gs'. + These are automatically added by specifying using the + SECTION:MEMORY-OPERAND form for memory references. + + * Operand/Address size prefixes 'data16' and 'addr16' change 32-bit + operands/addresses into 16-bit operands/addresses, while 'data32' + and 'addr32' change 16-bit ones (in a '.code16' section) into + 32-bit operands/addresses. These prefixes _must_ appear on the + same line of code as the instruction they modify. For example, in + a 16-bit '.code16' section, you might write: + + addr32 jmpl *(%ebx) + + * The bus lock prefix 'lock' inhibits interrupts during execution of + the instruction it precedes. (This is only valid with certain + instructions; see a 80386 manual for details). + + * The wait for coprocessor prefix 'wait' waits for the coprocessor to + complete the current instruction. This should never be needed for + the 80386/80387 combination. + + * The 'rep', 'repe', and 'repne' prefixes are added to string + instructions to make them repeat '%ecx' times ('%cx' times if the + current address size is 16-bits). + * The 'rex' family of prefixes is used by x86-64 to encode extensions + to i386 instruction set. The 'rex' prefix has four bits -- an + operand size overwrite ('64') used to change operand size from + 32-bit to 64-bit and X, Y and Z extensions bits used to extend the + register set. + + You may write the 'rex' prefixes directly. The 'rex64xyz' + instruction emits 'rex' prefix with all the bits set. By omitting + the '64', 'x', 'y' or 'z' you may write other prefixes as well. + Normally, there is no need to write the prefixes explicitly, since + gas will automatically generate them based on the instruction + operands. + +9.6 Memory References +===================== + +An Intel syntax indirect memory reference of the form + + SECTION:[BASE + INDEX*SCALE + DISP] + +is translated into the AT&T syntax + + SECTION:DISP(BASE, INDEX, SCALE) + +where BASE and INDEX are the optional 32-bit base and index registers, +DISP is the optional displacement, and SCALE, taking the values 1, 2, 4, +and 8, multiplies INDEX to calculate the address of the operand. If no +SCALE is specified, SCALE is taken to be 1. SECTION specifies the +optional section register for the memory operand, and may override the +default section register (see a 80386 manual for section register +defaults). Note that section overrides in AT&T syntax _must_ be +preceded by a '%'. If you specify a section override which coincides +with the default section register, 'as' does _not_ output any section +register override prefixes to assemble the given instruction. Thus, +section overrides can be specified to emphasize which section register +is used for a given memory operand. + + Here are some examples of Intel and AT&T style memory references: + +AT&T: '-4(%ebp)', Intel: '[ebp - 4]' + BASE is '%ebp'; DISP is '-4'. SECTION is missing, and the default + section is used ('%ss' for addressing with '%ebp' as the base + register). INDEX, SCALE are both missing. + +AT&T: 'foo(,%eax,4)', Intel: '[foo + eax*4]' + INDEX is '%eax' (scaled by a SCALE 4); DISP is 'foo'. All other + fields are missing. The section register here defaults to '%ds'. + +AT&T: 'foo(,1)'; Intel '[foo]' + This uses the value pointed to by 'foo' as a memory operand. Note + that BASE and INDEX are both missing, but there is only _one_ ','. + This is a syntactic exception. + +AT&T: '%gs:foo'; Intel 'gs:foo' + This selects the contents of the variable 'foo' with section + register SECTION being '%gs'. + + Absolute (as opposed to PC relative) call and jump operands must be +prefixed with '*'. If no '*' is specified, 'as' always chooses PC +relative addressing for jump/call labels. + + Any instruction that has a memory operand, but no register operand, +_must_ specify its size (byte, word, long, or quadruple) with an +instruction mnemonic suffix ('b', 'w', 'l' or 'q', respectively). + + The x86-64 architecture adds an RIP (instruction pointer relative) +addressing. This addressing mode is specified by using 'rip' as a base +register. Only constant offsets are valid. For example: + +AT&T: '1234(%rip)', Intel: '[rip + 1234]' + Points to the address 1234 bytes past the end of the current + instruction. + +AT&T: 'symbol(%rip)', Intel: '[rip + symbol]' + Points to the 'symbol' in RIP relative way, this is shorter than + the default absolute addressing. + + Other addressing modes remain unchanged in x86-64 architecture, +except registers used are 64-bit instead of 32-bit. + +9.7 Handling of Jump Instructions +================================= + +Jump instructions are always optimized to use the smallest possible +displacements. This is accomplished by using byte (8-bit) displacement +jumps whenever the target is sufficiently close. If a byte displacement +is insufficient a long displacement is used. We do not support word +(16-bit) displacement jumps in 32-bit mode (i.e. prefixing the jump +instruction with the 'data16' instruction prefix), since the 80386 +insists upon masking '%eip' to 16 bits after the word displacement is +added. (See also *note i386-Arch::) + + Note that the 'jcxz', 'jecxz', 'loop', 'loopz', 'loope', 'loopnz' and +'loopne' instructions only come in byte displacements, so that if you +use these instructions ('gcc' does not use them) you may get an error +message (and incorrect code). The AT&T 80386 assembler tries to get +around this problem by expanding 'jcxz foo' to + + jcxz cx_zero + jmp cx_nonzero + cx_zero: jmp foo + cx_nonzero: + +9.8 Floating Point +================== + +All 80387 floating point types except packed BCD are supported. (BCD +support may be added without much difficulty). These data types are +16-, 32-, and 64- bit integers, and single (32-bit), double (64-bit), +and extended (80-bit) precision floating point. Each supported type has +an instruction mnemonic suffix and a constructor associated with it. +Instruction mnemonic suffixes specify the operand's data type. +Constructors build these data types into memory. + + * Floating point constructors are '.float' or '.single', '.double', + and '.tfloat' for 32-, 64-, and 80-bit formats. These correspond + to instruction mnemonic suffixes 's', 'l', and 't'. 't' stands for + 80-bit (ten byte) real. The 80387 only supports this format via + the 'fldt' (load 80-bit real to stack top) and 'fstpt' (store + 80-bit real and pop stack) instructions. + + * Integer constructors are '.word', '.long' or '.int', and '.quad' + for the 16-, 32-, and 64-bit integer formats. The corresponding + instruction mnemonic suffixes are 's' (single), 'l' (long), and 'q' + (quad). As with the 80-bit real format, the 64-bit 'q' format is + only present in the 'fildq' (load quad integer to stack top) and + 'fistpq' (store quad integer and pop stack) instructions. + + Register to register operations should not use instruction mnemonic +suffixes. 'fstl %st, %st(1)' will give a warning, and be assembled as +if you wrote 'fst %st, %st(1)', since all register to register +operations use 80-bit floating point operands. (Contrast this with +'fstl %st, mem', which converts '%st' from 80-bit to 64-bit floating +point format, then stores the result in the 4 byte location 'mem') + +9.9 Intel's MMX and AMD's 3DNow! SIMD Operations +================================================ + +'as' supports Intel's MMX instruction set (SIMD instructions for integer +data), available on Intel's Pentium MMX processors and Pentium II +processors, AMD's K6 and K6-2 processors, Cyrix' M2 processor, and +probably others. It also supports AMD's 3DNow! instruction set (SIMD +instructions for 32-bit floating point data) available on AMD's K6-2 +processor and possibly others in the future. + + Currently, 'as' does not support Intel's floating point SIMD, Katmai +(KNI). + + The eight 64-bit MMX operands, also used by 3DNow!, are called +'%mm0', '%mm1', ... '%mm7'. They contain eight 8-bit integers, four +16-bit integers, two 32-bit integers, one 64-bit integer, or two 32-bit +floating point values. The MMX registers cannot be used at the same +time as the floating point stack. + + See Intel and AMD documentation, keeping in mind that the operand +order in instructions is reversed from the Intel syntax. + +9.10 Writing 16-bit Code +======================== + +While 'as' normally writes only "pure" 32-bit i386 code or 64-bit x86-64 +code depending on the default configuration, it also supports writing +code to run in real mode or in 16-bit protected mode code segments. To +do this, put a '.code16' or '.code16gcc' directive before the assembly +language instructions to be run in 16-bit mode. You can switch 'as' +back to writing normal 32-bit code with the '.code32' directive. + + '.code16gcc' provides experimental support for generating 16-bit code +from gcc, and differs from '.code16' in that 'call', 'ret', 'enter', +'leave', 'push', 'pop', 'pusha', 'popa', 'pushf', and 'popf' +instructions default to 32-bit size. This is so that the stack pointer +is manipulated in the same way over function calls, allowing access to +function parameters at the same stack offsets as in 32-bit mode. +'.code16gcc' also automatically adds address size prefixes where +necessary to use the 32-bit addressing modes that gcc generates. + + The code which 'as' generates in 16-bit mode will not necessarily run +on a 16-bit pre-80386 processor. To write code that runs on such a +processor, you must refrain from using _any_ 32-bit constructs which +require 'as' to output address or operand size prefixes. + + Note that writing 16-bit code instructions by explicitly specifying a +prefix or an instruction mnemonic suffix within a 32-bit code section +generates different machine instructions than those generated for a +16-bit code segment. In a 32-bit code section, the following code +generates the machine opcode bytes '66 6a 04', which pushes the value +'4' onto the stack, decrementing '%esp' by 2. + + pushw $4 + + The same code in a 16-bit code section would generate the machine +opcode bytes '6a 04' (i.e., without the operand size prefix), which is +correct since the processor default operand size is assumed to be 16 +bits in a 16-bit code section. + +9.11 AT&T Syntax bugs +===================== + +The UnixWare assembler, and probably other AT&T derived ix86 Unix +assemblers, generate floating point instructions with reversed source +and destination registers in certain cases. Unfortunately, gcc and +possibly many other programs use this reversed syntax, so we're stuck +with it. + + For example + + fsub %st,%st(3) +results in '%st(3)' being updated to '%st - %st(3)' rather than the +expected '%st(3) - %st'. This happens with all the non-commutative +arithmetic floating point operations with two register operands where +the source register is '%st' and the destination register is '%st(i)'. + +9.12 Specifying CPU Architecture +================================ + +'as' may be told to assemble for a particular CPU (sub-)architecture +with the '.arch CPU_TYPE' directive. This directive enables a warning +when gas detects an instruction that is not supported on the CPU +specified. The choices for CPU_TYPE are: + +'i8086' 'i186' 'i286' 'i386' +'i486' 'i586' 'i686' 'pentium' +'pentiumpro' 'pentiumii' 'pentiumiii' 'pentium4' +'prescott' 'nocona' 'core' 'core2' +'amdfam10' +'k6' 'athlon' 'sledgehammer' 'k8' +'.mmx' '.sse' '.sse2' '.sse3' +'.ssse3' '.sse4.1' '.sse4.2' '.sse4' +'.sse4a' '.3dnow' '.3dnowa' '.padlock' +'.pacifica' '.svme' '.abm' + + Apart from the warning, there are only two other effects on 'as' +operation; Firstly, if you specify a CPU other than 'i486', then shift +by one instructions such as 'sarl $1, %eax' will automatically use a two +byte opcode sequence. The larger three byte opcode sequence is used on +the 486 (and when no architecture is specified) because it executes +faster on the 486. Note that you can explicitly request the two byte +opcode by writing 'sarl %eax'. Secondly, if you specify 'i8086', +'i186', or 'i286', _and_ '.code16' or '.code16gcc' then byte offset +conditional jumps will be promoted when necessary to a two instruction +sequence consisting of a conditional jump of the opposite sense around +an unconditional jump to the target. + + Following the CPU architecture (but not a sub-architecture, which are +those starting with a dot), you may specify 'jumps' or 'nojumps' to +control automatic promotion of conditional jumps. 'jumps' is the +default, and enables jump promotion; All external jumps will be of the +long variety, and file-local jumps will be promoted as necessary. +(*note i386-Jumps::) 'nojumps' leaves external conditional jumps as byte +offset jumps, and warns about file-local conditional jumps that 'as' +promotes. Unconditional jumps are treated as for 'jumps'. + + For example + + .arch i8086,nojumps + +9.13 Notes +========== + +There is some trickery concerning the 'mul' and 'imul' instructions that +deserves mention. The 16-, 32-, 64- and 128-bit expanding multiplies +(base opcode '0xf6'; extension 4 for 'mul' and 5 for 'imul') can be +output only in the one operand form. Thus, 'imul %ebx, %eax' does _not_ +select the expanding multiply; the expanding multiply would clobber the +'%edx' register, and this would confuse 'gcc' output. Use 'imul %ebx' +to get the 64-bit product in '%edx:%eax'. + + We have added a two operand form of 'imul' when the first operand is +an immediate mode expression and the second operand is a register. This +is just a shorthand, so that, multiplying '%eax' by 69, for example, can +be done with 'imul $69, %eax' rather than 'imul $69, %eax, %eax'. + +10 IA-64 Dependent Features +*************************** + +10.1 Options +============ + +'-mconstant-gp' + This option instructs the assembler to mark the resulting object + file as using the "constant GP" model. With this model, it is + assumed that the entire program uses a single global pointer (GP) + value. Note that this option does not in any fashion affect the + machine code emitted by the assembler. All it does is turn on the + EF_IA_64_CONS_GP flag in the ELF file header. + +'-mauto-pic' + This option instructs the assembler to mark the resulting object + file as using the "constant GP without function descriptor" data + model. This model is like the "constant GP" model, except that it + additionally does away with function descriptors. What this means + is that the address of a function refers directly to the function's + code entry-point. Normally, such an address would refer to a + function descriptor, which contains both the code entry-point and + the GP-value needed by the function. Note that this option does + not in any fashion affect the machine code emitted by the + assembler. All it does is turn on the EF_IA_64_NOFUNCDESC_CONS_GP + flag in the ELF file header. + +'-milp32' +'-milp64' +'-mlp64' +'-mp64' + These options select the data model. The assembler defaults to + '-mlp64' (LP64 data model). + +'-mle' +'-mbe' + These options select the byte order. The '-mle' option selects + little-endian byte order (default) and '-mbe' selects big-endian + byte order. Note that IA-64 machine code always uses little-endian + byte order. + +'-mtune=itanium1' +'-mtune=itanium2' + Tune for a particular IA-64 CPU, ITANIUM1 or ITANIUM2. The default + is ITANIUM2. + +'-munwind-check=warning' +'-munwind-check=error' + These options control what the assembler will do when performing + consistency checks on unwind directives. '-munwind-check=warning' + will make the assembler issue a warning when an unwind directive + check fails. This is the default. '-munwind-check=error' will + make the assembler issue an error when an unwind directive check + fails. + +'-mhint.b=ok' +'-mhint.b=warning' +'-mhint.b=error' + These options control what the assembler will do when the 'hint.b' + instruction is used. '-mhint.b=ok' will make the assembler accept + 'hint.b'. '-mint.b=warning' will make the assembler issue a + warning when 'hint.b' is used. '-mhint.b=error' will make the + assembler treat 'hint.b' as an error, which is the default. + +'-x' +'-xexplicit' + These options turn on dependency violation checking. + +'-xauto' + This option instructs the assembler to automatically insert stop + bits where necessary to remove dependency violations. This is the + default mode. + +'-xnone' + This option turns off dependency violation checking. + +'-xdebug' + This turns on debug output intended to help tracking down bugs in + the dependency violation checker. + +'-xdebugn' + This is a shortcut for -xnone -xdebug. + +'-xdebugx' + This is a shortcut for -xexplicit -xdebug. + +10.2 Syntax +=========== + +The assembler syntax closely follows the IA-64 Assembly Language +Reference Guide. + +10.2.1 Special Characters +------------------------- + +'//' is the line comment token. + + ';' can be used instead of a newline to separate statements. + +10.2.2 Register Names +--------------------- + +The 128 integer registers are referred to as 'rN'. The 128 +floating-point registers are referred to as 'fN'. The 128 application +registers are referred to as 'arN'. The 128 control registers are +referred to as 'crN'. The 64 one-bit predicate registers are referred +to as 'pN'. The 8 branch registers are referred to as 'bN'. In +addition, the assembler defines a number of aliases: 'gp' ('r1'), 'sp' +('r12'), 'rp' ('b0'), 'ret0' ('r8'), 'ret1' ('r9'), 'ret2' ('r10'), +'ret3' ('r9'), 'fargN' ('f8+N'), and 'fretN' ('f8+N'). + + For convenience, the assembler also defines aliases for all named +application and control registers. For example, 'ar.bsp' refers to the +register backing store pointer ('ar17'). Similarly, 'cr.eoi' refers to +the end-of-interrupt register ('cr67'). + +10.2.3 IA-64 Processor-Status-Register (PSR) Bit Names +------------------------------------------------------ + +The assembler defines bit masks for each of the bits in the IA-64 +processor status register. For example, 'psr.ic' corresponds to a value +of 0x2000. These masks are primarily intended for use with the +'ssm'/'sum' and 'rsm'/'rum' instructions, but they can be used anywhere +else where an integer constant is expected. + +10.3 Opcodes +============ + +For detailed information on the IA-64 machine instruction set, see the +IA-64 Architecture Handbook +(http://developer.intel.com/design/itanium/arch_spec.htm). + +11 MIPS Dependent Features +************************** + +GNU 'as' for MIPS architectures supports several different MIPS +processors, and MIPS ISA levels I through V, MIPS32, and MIPS64. For +information about the MIPS instruction set, see 'MIPS RISC +Architecture', by Kane and Heindrich (Prentice-Hall). For an overview +of MIPS assembly conventions, see "Appendix D: Assembly Language +Programming" in the same work. + +11.1 Assembler options +====================== + +The MIPS configurations of GNU 'as' support these special options: + +'-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. The default value is 8. + +'-EB' +'-EL' + Any MIPS configuration of 'as' can select big-endian or + little-endian output at run time (unlike the other GNU development + tools, which must be configured for one or the other). Use '-EB' + to select big-endian output, and '-EL' for little-endian. + +'-KPIC' + Generate SVR4-style PIC. This option tells the assembler to + generate SVR4-style position-independent macro expansions. It also + tells the assembler to mark the output file as PIC. + +'-mvxworks-pic' + Generate VxWorks PIC. This option tells the assembler to generate + VxWorks-style position-independent macro expansions. + +'-mips1' +'-mips2' +'-mips3' +'-mips4' +'-mips5' +'-mips32' +'-mips32r2' +'-mips64' +'-mips64r2' + Generate code for a particular MIPS Instruction Set Architecture + level. '-mips1' corresponds to the R2000 and R3000 processors, + '-mips2' to the R6000 processor, '-mips3' to the R4000 processor, + and '-mips4' to the R8000 and R10000 processors. '-mips5', + '-mips32', '-mips32r2', '-mips64', and '-mips64r2' correspond to + generic MIPS V, MIPS32, MIPS32 RELEASE 2, MIPS64, and MIPS64 + RELEASE 2 ISA processors, respectively. You can also switch + instruction sets during the assembly; see *note Directives to + override the ISA level: MIPS ISA. + +'-mgp32' +'-mfp32' + Some macros have different expansions for 32-bit and 64-bit + registers. 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. + + The '.set gp=32' and '.set fp=32' directives allow the size of + registers to be changed for parts of an object. The default value + is restored by '.set gp=default' and '.set fp=default'. + + On some MIPS variants there is a 32-bit mode flag; when this flag + is set, 64-bit instructions generate a trap. Also, some 32-bit + OSes only save the 32-bit registers on a context switch, so it is + essential never to use the 64-bit registers. + +'-mgp64' +'-mfp64' + Assume that 64-bit registers are available. This is provided in + the interests of symmetry with '-mgp32' and '-mfp32'. + + The '.set gp=64' and '.set fp=64' directives allow the size of + registers to be changed for parts of an object. The default value + is restored by '.set gp=default' and '.set fp=default'. + +'-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 extensions to the MIPS32 instruction set, + which provides a number of new instructions which target smartcard + and cryptographic applications. 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. + +'-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. + +'-mfix-vr4120' +'-no-mfix-vr4120' + Insert nops to work around certain VR4120 errata. This option is + intended to be used on GCC-generated code: it is not designed to + catch all problems in hand-written assembler code. + +'-mfix-vr4130' +'-no-mfix-vr4130' + Insert nops to work around the VR4130 'mflo'/'mfhi' errata. + +'-m4010' +'-no-m4010' + Generate code for the LSI R4010 chip. This tells the assembler to + accept the R4010 specific instructions ('addciu', 'ffc', etc.), and + to not schedule 'nop' instructions around accesses to the 'HI' and + 'LO' registers. '-no-m4010' turns off this option. + +'-m4650' +'-no-m4650' + Generate code for the MIPS R4650 chip. This tells the assembler to + accept the 'mad' and 'madu' instruction, and to not schedule 'nop' + instructions around accesses to the 'HI' and 'LO' registers. + '-no-m4650' turns off this option. + +'-m3900' +'-no-m3900' +'-m4100' +'-no-m4100' + For each option '-mNNNN', generate code for the MIPS RNNNN chip. + This tells the assembler to accept instructions specific to that + chip, and to schedule for that chip's hazards. + +'-march=CPU' + Generate code for a particular MIPS cpu. It is exactly equivalent + to '-mCPU', except that there are more value of CPU understood. + Valid CPU value are: + + 2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, + vr4181, 4300, 4400, 4600, 4650, 5000, rm5200, rm5230, rm5231, + rm5261, rm5721, vr5400, vr5500, 6000, rm7000, 8000, rm9000, + 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem, 4kep, 4ksd, + m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf, + 34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a + +'-mtune=CPU' + Schedule and tune for a particular MIPS cpu. Valid CPU values are + identical to '-march=CPU'. + +'-mabi=ABI' + Record which ABI the source code uses. The recognized arguments + are: '32', 'n32', 'o64', '64' and 'eabi'. + +'-msym32' +'-mno-sym32' + Equivalent to adding '.set sym32' or '.set nosym32' to the + beginning of the assembler input. *Note MIPS symbol sizes::. + +'-nocpp' + This option is ignored. It is accepted for command-line + compatibility with other assemblers, which use it to turn off C + style preprocessing. With GNU 'as', there is no need for '-nocpp', + because the GNU assembler itself never runs the C preprocessor. + +'--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. This feature is useful if the + processor support the FR bit in its status register, and this bit + is known (by the programmer) to be set. This bit prevents the + aliasing of the double width register by the single width + registers. + + By default '--construct-floats' is selected, allowing construction + of these floating point constants. + +'--trap' +'--no-break' + 'as' automatically macro expands certain division and + multiplication instructions to check for overflow and division by + zero. This option causes 'as' to generate code to take a trap + exception rather than a break exception when an error is detected. + The trap instructions are only supported at Instruction Set + Architecture level 2 and higher. + +'--break' +'--no-trap' + Generate code to take a break exception rather than a trap + exception when an error is detected. This is the default. + +'-mpdr' +'-mno-pdr' + Control generation of '.pdr' sections. Off by default on IRIX, on + elsewhere. + +'-mshared' +'-mno-shared' + When generating code using the Unix calling conventions (selected + by '-KPIC' or '-mcall_shared'), gas will normally generate code + which can go into a shared library. The '-mno-shared' option tells + gas to generate code which uses the calling convention, but can not + go into a shared library. The resulting code is slightly more + efficient. This option only affects the handling of the '.cpload' + and '.cpsetup' pseudo-ops. + +11.2 MIPS ECOFF object code +=========================== + +Assembling for a MIPS ECOFF target supports some additional sections +besides the usual '.text', '.data' and '.bss'. The additional sections +are '.rdata', used for read-only data, '.sdata', used for small data, +and '.sbss', used for small common objects. + + When assembling for ECOFF, the assembler uses the '$gp' ('$28') +register to form the address of a "small object". Any object in the +'.sdata' or '.sbss' sections is considered "small" in this sense. For +external objects, or for objects in the '.bss' section, you can use the +'gcc' '-G' option to control the size of objects addressed via '$gp'; +the default value is 8, meaning that a reference to any object eight +bytes or smaller uses '$gp'. Passing '-G 0' to 'as' prevents it from +using the '$gp' register on the basis of object size (but the assembler +uses '$gp' for objects in '.sdata' or 'sbss' in any case). The size of +an object in the '.bss' section is set by the '.comm' or '.lcomm' +directive that defines it. The size of an external object may be set +with the '.extern' directive. For example, '.extern sym,4' declares +that the object at 'sym' is 4 bytes in length, whie leaving 'sym' +otherwise undefined. + + Using small ECOFF objects requires linker support, and assumes that +the '$gp' register is correctly initialized (normally done automatically +by the startup code). MIPS ECOFF assembly code must not modify the +'$gp' register. + +11.3 Directives for debugging information +========================================= + +MIPS ECOFF 'as' supports several directives used for generating +debugging information which are not support by traditional MIPS +assemblers. These are '.def', '.endef', '.dim', '.file', '.scl', +'.size', '.tag', '.type', '.val', '.stabd', '.stabn', and '.stabs'. The +debugging information generated by the three '.stab' directives can only +be read by GDB, not by traditional MIPS debuggers (this enhancement is +required to fully support C++ debugging). These directives are +primarily used by compilers, not assembly language programmers! + +11.4 Directives to override the size of symbols +=============================================== + +The n64 ABI allows symbols to have any 64-bit value. Although this +provides a great deal of flexibility, it means that some macros have +much longer expansions than their 32-bit counterparts. For example, the +non-PIC expansion of 'dla $4,sym' is usually: + + lui $4,%highest(sym) + lui $1,%hi(sym) + daddiu $4,$4,%higher(sym) + daddiu $1,$1,%lo(sym) + dsll32 $4,$4,0 + daddu $4,$4,$1 + + whereas the 32-bit expansion is simply: + + lui $4,%hi(sym) + daddiu $4,$4,%lo(sym) + + n64 code is sometimes constructed in such a way that all symbolic +constants are known to have 32-bit values, and in such cases, it's +preferable to use the 32-bit expansion instead of the 64-bit expansion. + + You can use the '.set sym32' directive to tell the assembler that, +from this point on, all expressions of the form 'SYMBOL' or 'SYMBOL + +OFFSET' have 32-bit values. For example: + + .set sym32 + dla $4,sym + lw $4,sym+16 + sw $4,sym+0x8000($4) + + will cause the assembler to treat 'sym', 'sym+16' and 'sym+0x8000' as +32-bit values. The handling of non-symbolic addresses is not affected. + + The directive '.set nosym32' ends a '.set sym32' block and reverts to +the normal behavior. It is also possible to change the symbol size +using the command-line options '-msym32' and '-mno-sym32'. + + These options and directives are always accepted, but at present, +they have no effect for anything other than n64. + +11.5 Directives to override the ISA level +========================================= + +GNU 'as' supports an additional directive to change the MIPS Instruction +Set Architecture level on the fly: '.set mipsN'. N should be a number +from 0 to 5, or 32, 32r2, 64 or 64r2. The values other than 0 make the +assembler accept instructions for the corresponding ISA level, from that +point on in the assembly. '.set mipsN' affects not only which +instructions are permitted, but also how certain macros are expanded. +'.set mips0' restores the ISA level to its original level: either the +level you selected with command line options, or the default for your +configuration. You can use this feature to permit specific MIPS3 +instructions while assembling in 32 bit mode. Use this directive with +care! + + The '.set arch=CPU' directive provides even finer control. It +changes the effective CPU target and allows the assembler to use +instructions specific to a particular CPU. All CPUs supported by the +'-march' command line option are also selectable by this directive. The +original value is restored by '.set arch=default'. + + The directive '.set mips16' puts the assembler into MIPS 16 mode, in +which it will assemble instructions for the MIPS 16 processor. Use +'.set nomips16' to return to normal 32 bit mode. + + Traditional MIPS assemblers do not support this directive. + +11.6 Directives for extending MIPS 16 bit instructions +====================================================== + +By default, MIPS 16 instructions are automatically extended to 32 bits +when necessary. The directive '.set noautoextend' will turn this off. +When '.set noautoextend' is in effect, any 32 bit instruction must be +explicitly extended with the '.e' modifier (e.g., 'li.e $4,1000'). The +directive '.set autoextend' may be used to once again automatically +extend instructions when necessary. + + This directive is only meaningful when in MIPS 16 mode. Traditional +MIPS assemblers do not support this directive. + +11.7 Directive to mark data as an instruction +============================================= + +The '.insn' directive tells 'as' that the following data is actually +instructions. This makes a difference in MIPS 16 mode: when loading the +address of a label which precedes instructions, 'as' automatically adds +1 to the value, so that jumping to the loaded address will do the right +thing. + +11.8 Directives to save and restore options +=========================================== + +The directives '.set push' and '.set pop' may be used to save and +restore the current settings for all the options which are controlled by +'.set'. The '.set push' directive saves the current settings on a +stack. The '.set pop' directive pops the stack and restores the +settings. + + These directives can be useful inside an macro which must change an +option such as the ISA level or instruction reordering but does not want +to change the state of the code which invoked the macro. + + Traditional MIPS assemblers do not support these directives. + +11.9 Directives to control generation of MIPS ASE instructions +============================================================== + +The directive '.set mips3d' makes the assembler accept instructions from +the MIPS-3D Application Specific Extension from that point on in the +assembly. The '.set nomips3d' directive prevents MIPS-3D instructions +from being accepted. + + The directive '.set smartmips' makes the assembler accept +instructions from the SmartMIPS Application Specific Extension to the +MIPS32 ISA from that point on in the assembly. The '.set nosmartmips' +directive prevents SmartMIPS instructions from being accepted. + + The directive '.set mdmx' makes the assembler accept instructions +from the MDMX Application Specific Extension from that point on in the +assembly. The '.set nomdmx' directive prevents MDMX instructions from +being accepted. + + The directive '.set dsp' makes the assembler accept instructions from +the DSP Release 1 Application Specific Extension from that point on in +the assembly. The '.set nodsp' directive prevents DSP Release 1 +instructions from being accepted. + + The directive '.set dspr2' makes the assembler accept instructions +from the DSP Release 2 Application Specific Extension from that point on +in the assembly. This dirctive implies '.set dsp'. The '.set nodspr2' +directive prevents DSP Release 2 instructions from being accepted. + + The directive '.set mt' makes the assembler accept instructions from +the MT Application Specific Extension from that point on in the +assembly. The '.set nomt' directive prevents MT instructions from being +accepted. + + Traditional MIPS assemblers do not support these directives. + +12 PowerPC Dependent Features +***************************** + +12.1 Options +============ + +The PowerPC chip family includes several successive levels, using the +same core instruction set, but including a few additional instructions +at each level. There are exceptions to this however. For details on +what instructions each variant supports, please see the chip's +architecture reference manual. + + The following table lists all available PowerPC options. + +'-mpwrx | -mpwr2' + Generate code for POWER/2 (RIOS2). + +'-mpwr' + Generate code for POWER (RIOS1) + +'-m601' + Generate code for PowerPC 601. + +'-mppc, -mppc32, -m603, -m604' + Generate code for PowerPC 603/604. + +'-m403, -m405' + Generate code for PowerPC 403/405. + +'-m440' + Generate code for PowerPC 440. BookE and some 405 instructions. + +'-m7400, -m7410, -m7450, -m7455' + Generate code for PowerPC 7400/7410/7450/7455. + +'-mppc64, -m620' + Generate code for PowerPC 620/625/630. + +'-me500, -me500x2' + Generate code for Motorola e500 core complex. + +'-mspe' + Generate code for Motorola SPE instructions. + +'-mppc64bridge' + Generate code for PowerPC 64, including bridge insns. + +'-mbooke64' + Generate code for 64-bit BookE. + +'-mbooke, mbooke32' + Generate code for 32-bit BookE. + +'-me300' + Generate code for PowerPC e300 family. + +'-maltivec' + Generate code for processors with AltiVec instructions. + +'-mpower4' + Generate code for Power4 architecture. + +'-mpower5' + Generate code for Power5 architecture. + +'-mpower6' + Generate code for Power6 architecture. + +'-mcell' + Generate code for Cell Broadband Engine architecture. + +'-mcom' + Generate code Power/PowerPC common instructions. + +'-many' + Generate code for any architecture (PWR/PWRX/PPC). + +'-mregnames' + Allow symbolic names for registers. + +'-mno-regnames' + Do not allow symbolic names for registers. + +'-mrelocatable' + Support for GCC's -mrelocatable option. + +'-mrelocatable-lib' + Support for GCC's -mrelocatable-lib option. + +'-memb' + Set PPC_EMB bit in ELF flags. + +'-mlittle, -mlittle-endian' + Generate code for a little endian machine. + +'-mbig, -mbig-endian' + Generate code for a big endian machine. + +'-msolaris' + Generate code for Solaris. + +'-mno-solaris' + Do not generate code for Solaris. + +12.2 PowerPC Assembler Directives +================================= + +A number of assembler directives are available for PowerPC. The +following table is far from complete. + +'.machine "string"' + This directive allows you to change the machine for which code is + generated. '"string"' may be any of the -m cpu selection options + (without the -m) enclosed in double quotes, '"push"', or '"pop"'. + '.machine "push"' saves the currently selected cpu, which may be + restored with '.machine "pop"'. + +13 SPARC Dependent Features +*************************** + +13.1 Options +============ + +The SPARC chip family includes several successive levels, using the same +core instruction set, but including a few additional instructions at +each level. There are exceptions to this however. For details on what +instructions each variant supports, please see the chip's architecture +reference manual. + + By default, 'as' assumes the core instruction set (SPARC v6), but +"bumps" the architecture level as needed: it switches to successively +higher architectures as it encounters instructions that only exist in +the higher levels. + + If not configured for SPARC v9 ('sparc64-*-*') GAS will not bump +passed sparclite by default, an option must be passed to enable the v9 +instructions. + + GAS treats sparclite as being compatible with v8, unless an +architecture is explicitly requested. SPARC v9 is always incompatible +with sparclite. + +'-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite' +'-Av8plus | -Av8plusa | -Av9 | -Av9a' + Use one of the '-A' options to select one of the SPARC + architectures explicitly. If you select an architecture + explicitly, 'as' reports a fatal error if it encounters an + instruction or feature requiring an incompatible or higher level. + + '-Av8plus' and '-Av8plusa' select a 32 bit environment. + + '-Av9' and '-Av9a' select a 64 bit environment and are not + available unless GAS is explicitly configured with 64 bit + environment support. + + '-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 whenever it is necessary to switch to another level. If an + architecture level is explicitly requested, GAS will not issue + warnings until that level is reached, and will then bump the level + as required (except between incompatible levels). + +'-32 | -64' + Select the word size, either 32 bits or 64 bits. These options are + only available with the ELF object file format, and require that + the necessary BFD support has been included. + +13.2 Enforcing aligned data +=========================== + +SPARC GAS normally permits data to be misaligned. For example, it +permits the '.long' pseudo-op to be used on a byte boundary. However, +the native SunOS and Solaris assemblers issue an error when they see +misaligned data. + + You can use the '--enforce-aligned-data' option to make SPARC GAS +also issue an error about misaligned data, just as the SunOS and Solaris +assemblers do. + + The '--enforce-aligned-data' option is not the default because gcc +issues misaligned data pseudo-ops when it initializes certain packed +data structures (structures defined using the 'packed' attribute). You +may have to assemble with GAS in order to initialize packed data +structures in your own code. + +13.3 Floating Point +=================== + +The Sparc uses IEEE floating-point numbers. + +13.4 Sparc Machine Directives +============================= + +The Sparc version of 'as' supports the following additional machine +directives: + +'.align' + This must be followed by the desired alignment in bytes. + +'.common' + This must be followed by a symbol name, a positive number, and + '"bss"'. This behaves somewhat like '.comm', but the syntax is + different. + +'.half' + This is functionally identical to '.short'. + +'.nword' + On the Sparc, the '.nword' directive produces native word sized + value, ie. if assembling with -32 it is equivalent to '.word', if + assembling with -64 it is equivalent to '.xword'. + +'.proc' + This directive is ignored. Any text following it on the same line + is also ignored. + +'.register' + This directive declares use of a global application or system + register. It must be followed by a register name %g2, %g3, %g6 or + %g7, comma and the symbol name for that register. If symbol name + is '#scratch', it is a scratch register, if it is '#ignore', it + just suppresses any errors about using undeclared global register, + but does not emit any information about it into the object file. + This can be useful e.g. if you save the register before use and + restore it after. + +'.reserve' + This must be followed by a symbol name, a positive number, and + '"bss"'. This behaves somewhat like '.lcomm', but the syntax is + different. + +'.seg' + This must be followed by '"text"', '"data"', or '"data1"'. It + behaves like '.text', '.data', or '.data 1'. + +'.skip' + This is functionally identical to the '.space' directive. + +'.word' + On the Sparc, the '.word' directive produces 32 bit values, instead + of the 16 bit values it produces on many other machines. + +'.xword' + On the Sparc V9 processor, the '.xword' directive produces 64 bit + values. + +14 Reporting Bugs +***************** + +Your bug reports play an essential role in making 'as' reliable. + + Reporting a bug may help you by bringing a solution to your problem, +or it may not. But in any case the principal function of a bug report +is to help the entire community by making the next version of 'as' work +better. Bug reports are your contribution to the maintenance of 'as'. + + In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. + +14.1 Have You Found a Bug? +========================== + +If you are not sure whether you have found a bug, here are some +guidelines: + + * If the assembler gets a fatal signal, for any input whatever, that + is a 'as' bug. Reliable assemblers never crash. + + * If 'as' produces an error message for valid input, that is a bug. + + * If 'as' does not produce an error message for invalid input, that + is a bug. However, you should note that your idea of "invalid + input" might be our idea of "an extension" or "support for + traditional practice". + + * If you are an experienced user of assemblers, your suggestions for + improvement of 'as' are welcome in any case. + +14.2 How to Report Bugs +======================= + +A number of companies and individuals offer support for GNU products. +If you obtained 'as' from a support organization, we recommend you +contact that organization first. + + You can find contact information for many support companies and +individuals in the file 'etc/SERVICE' in the GNU Emacs distribution. + + The fundamental principle of reporting bugs usefully is this: *report +all the facts*. If you are not sure whether to state a fact or leave it +out, state it! + + Often people omit facts because they think they know what causes the +problem and assume that some details do not matter. Thus, you might +assume that the name of a symbol you use in an example does not matter. +Well, probably it does not, but one cannot be sure. Perhaps the bug is +a stray memory reference which happens to fetch from the location where +that name is stored in memory; perhaps, if the name were different, the +contents of that location would fool the assembler into doing the right +thing despite the bug. Play it safe and give a specific, complete +example. That is the easiest thing for you to do, and the most helpful. + + Keep in mind that the purpose of a bug report is to enable us to fix +the bug if it is new to us. Therefore, always write your bug reports on +the assumption that the bug has not been reported previously. + + Sometimes people give a few sketchy facts and ask, "Does this ring a +bell?" This cannot help us fix a bug, so it is basically useless. We +respond by asking for enough details to enable us to investigate. You +might as well expedite matters by sending them to begin with. + + To enable us to fix the bug, you should include all these things: + + * The version of 'as'. 'as' announces it if you start it with the + '--version' argument. + + Without this, we will not know whether there is any point in + looking for the bug in the current version of 'as'. + + * Any patches you may have applied to the 'as' source. + + * The type of machine you are using, and the operating system name + and version number. + + * What compiler (and its version) was used to compile 'as'--e.g. + "'gcc-2.7'". + + * The command arguments you gave the assembler to assemble your + example and observe the bug. To guarantee you will not omit + something important, list them all. A copy of the Makefile (or the + output from make) is sufficient. + + If we were to try to guess the arguments, we would probably guess + wrong and then we might not encounter the bug. + + * A complete input file that will reproduce the bug. If the bug is + observed when the assembler is invoked via a compiler, send the + assembler source, not the high level language source. Most + compilers will produce the assembler source when run with the '-S' + option. If you are using 'gcc', use the options '-v --save-temps'; + this will save the assembler source in a file with an extension of + '.s', and also show you exactly how 'as' is being run. + + * A description of what behavior you observe that you believe is + incorrect. For example, "It gets a fatal signal." + + Of course, if the bug is that 'as' gets a fatal signal, then we + will certainly notice it. But if the bug is incorrect output, we + might not notice unless it is glaringly wrong. You might as well + not give us a chance to make a mistake. + + Even if the problem you experience is a fatal signal, you should + still say so explicitly. Suppose something strange is going on, + such as, your copy of 'as' is out of sync, or you have encountered + a bug in the C library on your system. (This has happened!) Your + copy might crash and ours would not. If you told us to expect a + crash, then when ours fails to crash, we would know that the bug + was not happening for us. If you had not told us to expect a + crash, then we would not be able to draw any conclusion from our + observations. + + * If you wish to suggest changes to the 'as' source, send us context + diffs, as generated by 'diff' with the '-u', '-c', or '-p' option. + Always send diffs from the old file to the new file. If you even + discuss something in the 'as' source, refer to it by context, not + by line number. + + The line numbers in our development sources will not match those in + your sources. Your line numbers would convey no useful information + to us. + + Here are some things that are not necessary: + + * A description of the envelope of the bug. + + Often people who encounter a bug spend a lot of time investigating + which changes to the input file will make the bug go away and which + changes will not affect it. + + This is often time consuming and not very useful, because the way + we will find the bug is by running a single example under the + debugger with breakpoints, not by pure deduction from a series of + examples. We recommend that you save your time for something else. + + Of course, if you can find a simpler example to report _instead_ of + the original one, that is a convenience for us. Errors in the + output will be easier to spot, running under the debugger will take + less time, and so on. + + However, simplification is not vital; if you do not want to do + this, report the bug anyway and send us the entire test case you + used. + + * A patch for the bug. + + A patch for the bug does help us if it is a good one. But do not + omit the necessary information, such as the test case, on the + assumption that a patch is all we need. We might see problems with + your patch and decide to fix the problem another way, or we might + not understand it at all. + + Sometimes with a program as complicated as 'as' it is very hard to + construct an example that will make the program follow a certain + path through the code. If you do not send us the example, we will + not be able to construct one, so we will not be able to verify that + the bug is fixed. + + And if we cannot understand what bug you are trying to fix, or why + your patch should be an improvement, we will not install it. A + test case will help us to understand. + + * A guess about what the bug is or what it depends on. + + Such guesses are usually wrong. Even we cannot guess right about + such things without first using the debugger to find the facts. + +15 Acknowledgements +******************* + +If you have contributed to GAS and your name isn't listed here, it is +not meant as a slight. We just don't know about it. Send mail to the +maintainer, and we'll correct the situation. Currently the maintainer +is Ken Raeburn (email address 'raeburn@cygnus.com'). + + Dean Elsner wrote the original GNU assembler for the VAX.(1) + + Jay Fenlason maintained GAS for a while, adding support for +GDB-specific debug information and the 68k series machines, most of the +preprocessing pass, and extensive changes in 'messages.c', +'input-file.c', 'write.c'. + + K. Richard Pixley maintained GAS for a while, adding various +enhancements and many bug fixes, including merging support for several +processors, breaking GAS up to handle multiple object file format back +ends (including heavy rewrite, testing, an integration of the coff and +b.out back ends), adding configuration including heavy testing and +verification of cross assemblers and file splits and renaming, converted +GAS to strictly ANSI C including full prototypes, added support for +m680[34]0 and cpu32, did considerable work on i960 including a COFF port +(including considerable amounts of reverse engineering), a SPARC opcode +file rewrite, DECstation, rs6000, and hp300hpux host ports, updated +"know" assertions and made them work, much other reorganization, +cleanup, and lint. + + Ken Raeburn wrote the high-level BFD interface code to replace most +of the code in format-specific I/O modules. + + The original VMS support was contributed by David L. Kashtan. Eric +Youngdale has done much work with it since. + + The Intel 80386 machine description was written by Eliot Dresselhaus. + + Minh Tran-Le at IntelliCorp contributed some AIX 386 support. + + The Motorola 88k machine description was contributed by Devon Bowen +of Buffalo University and Torbjorn Granlund of the Swedish Institute of +Computer Science. + + Keith Knowles at the Open Software Foundation wrote the original MIPS +back end ('tc-mips.c', 'tc-mips.h'), and contributed Rose format support +(which hasn't been merged in yet). Ralph Campbell worked with the MIPS +code to support a.out format. + + Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, +tc-h8300), and IEEE 695 object file format (obj-ieee), was written by +Steve Chamberlain of Cygnus Support. Steve also modified the COFF back +end to use BFD for some low-level operations, for use with the H8/300 +and AMD 29k targets. + + John Gilmore built the AMD 29000 support, added '.include' support, +and simplified the configuration of which versions accept which +directives. He updated the 68k machine description so that Motorola's +opcodes always produced fixed-size instructions (e.g., 'jsr'), while +synthetic instructions remained shrinkable ('jbsr'). John fixed many +bugs, including true tested cross-compilation support, and one bug in +relaxation that took a week and required the proverbial one-bit fix. + + Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax +for the 68k, completed support for some COFF targets (68k, i386 SVR3, +and SCO Unix), added support for MIPS ECOFF and ELF targets, wrote the +initial RS/6000 and PowerPC assembler, and made a few other minor +patches. + + Steve Chamberlain made GAS able to generate listings. + + Hewlett-Packard contributed support for the HP9000/300. + + Jeff Law wrote GAS and BFD support for the native HPPA object format +(SOM) along with a fairly extensive HPPA testsuite (for both SOM and ELF +object formats). This work was supported by both the Center for +Software Science at the University of Utah and Cygnus Support. + + Support for ELF format files has been worked on by Mark Eichin of +Cygnus Support (original, incomplete implementation for SPARC), Pete +Hoogenboom and Jeff Law at the University of Utah (HPPA mainly), Michael +Meissner of the Open Software Foundation (i386 mainly), and Ken Raeburn +of Cygnus Support (sparc, and some initial 64-bit support). + + Linas Vepstas added GAS support for the ESA/390 "IBM 370" +architecture. + + Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote +GAS and BFD support for openVMS/Alpha. + + Timothy Wall, Michael Hayes, and Greg Smart contributed to the +various tic* flavors. + + David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from +Tensilica, Inc. added support for Xtensa processors. + + Several engineers at Cygnus Support have also provided many small bug +fixes and configuration enhancements. + + Many others have contributed large or small bugfixes and +enhancements. If you have contributed significant work and are not +mentioned on this list, and want to be, let us know. Some of the +history has been lost; we are not intentionally leaving anyone out. + +Appendix A GNU Free Documentation License +***************************************** + + Version 1.1, March 2000 + + Copyright (C) 2000, 2003 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + written document "free" in the sense of freedom: to assure everyone + the effective freedom to copy and redistribute it, with or without + modifying it, either commercially or noncommercially. Secondarily, + this License preserves for the author and publisher a way to get + credit for their work, while not being considered responsible for + modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work that contains a + notice placed by the copyright holder saying it can be distributed + under the terms of this License. The "Document", below, refers to + any such manual or work. Any member of the public is a licensee, + and is addressed as "you." + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (For example, if the + Document is in part a textbook of mathematics, a Secondary Section + may not explain any mathematics.) The relationship could be a + matter of historical connection with the subject or with related + matters, or of legal, commercial, philosophical, ethical or + political position regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, whose contents can be viewed and edited directly + and straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup has been designed to + thwart or discourage subsequent modification by readers is not + Transparent. A copy that is not "Transparent" is called "Opaque." + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML designed for human modification. Opaque formats + include PostScript, PDF, proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML produced by some word processors for + output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies of the Document numbering more than + 100, and the Document's license notice requires Cover Texts, you + must enclose the copies in covers that carry, clearly and legibly, + all these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a publicly-accessible computer-network location + containing a complete Transparent copy of the Document, free of + added material, which the general network-using public has access + to download anonymously at no charge using public-standard network + protocols. If you use the latter option, you must take reasonably + prudent steps, when you begin distribution of Opaque copies in + quantity, to ensure that this Transparent copy will remain thus + accessible at the stated location until at least one year after the + last time you distribute an Opaque copy (directly or through your + agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the History + section of the Document). You may use the same title as a previous + version if the original publisher of that version gives permission. + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in the + Modified Version, together with at least five of the principal + authors of the Document (all of its principal authors, if it has + less than five). + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + D. Preserve all the copyright notices of the Document. + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified Version + under the terms of this License, in the form shown in the Addendum + below. + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's license + notice. + H. Include an unaltered copy of this License. + I. Preserve the section entitled "History", and its title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. + J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + K. In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + M. Delete any section entitled "Endorsements." Such a section may + not be included in the Modified Version. + N. Do not retitle any existing section as "Endorsements" or to + conflict in title with any Invariant Section. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties-for example, statements of peer review or that the text has + been approved by an organization as the authoritative definition of + a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections entitled + "History" in the various original documents, forming one section + entitled "History"; likewise combine any sections entitled + "Acknowledgements", and any sections entitled "Dedications." You + must delete all sections entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, does not as a whole count as a + Modified Version of the Document, provided no compilation copyright + is claimed for the compilation. Such a compilation is called an + "aggregate", and this License does not apply to the other + self-contained works thus compiled with the Document, on account of + their being thus compiled, if they are not themselves derivative + works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one + quarter of the entire aggregate, the Document's Cover Texts may be + placed on covers that surround only the Document within the + aggregate. Otherwise they must appear on covers around the whole + aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License provided that you also include the + original English version of this License. In case of a + disagreement between the translation and the original English + version of this License, the original English version will prevail. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided for under this License. Any other + attempt to copy, modify, sublicense or distribute the Document is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses terminated + so long as such parties remain in full compliance. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + http://www.gnu.org/copyleft/. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License." + + If you have no Invariant Sections, write "with no Invariant Sections" +instead of saying which ones are invariant. If you have no Front-Cover +Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being +LIST"; likewise for Back-Cover Texts. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + ---------- Footnotes ---------- + + (1) Any more details? + +AS Index +******** + +* Menu: + +* #: Comments. (line 1306) +* #APP: Preprocessing. (line 1268) +* #NO_APP: Preprocessing. (line 1268) +* '$a': ARM Mapping Symbols. + (line 4193) +* '$d': ARM Mapping Symbols. + (line 4199) +* '$t': ARM Mapping Symbols. + (line 4196) +* --: Command Line. (line 760) +* '--32' option, i386: i386-Options. (line 4220) +* '--32' option, x86-64: i386-Options. (line 4220) +* '--64' option, i386: i386-Options. (line 4220) +* '--64' option, x86-64: i386-Options. (line 4220) +* --alternate: alternate. (line 929) +* '--divide' option, i386: i386-Options. (line 4236) +* --enforce-aligned-data: Sparc-Aligned-Data. (line 5460) +* --fatal-warnings: W. (line 1222) +* --hash-size=NUMBER: Overview. (line 459) +* --listing-cont-lines: listing. (line 1015) +* --listing-lhs-width: listing. (line 997) +* --listing-lhs-width2: listing. (line 1002) +* --listing-rhs-width: listing. (line 1009) +* --MD: MD. (line 1149) +* --no-warn: W. (line 1217) +* --statistics: statistics. (line 1188) +* --traditional-format: traditional-format. (line 1196) +* --warn: W. (line 1225) +* -a: a. (line 894) +* -ac: a. (line 894) +* -ad: a. (line 894) +* -ah: a. (line 894) +* -al: a. (line 894) +* -an: a. (line 894) +* -as: a. (line 894) +* -Asparclet: Sparc-Opts. (line 5421) +* -Asparclite: Sparc-Opts. (line 5421) +* -Av6: Sparc-Opts. (line 5421) +* -Av8: Sparc-Opts. (line 5421) +* -Av9: Sparc-Opts. (line 5421) +* -Av9a: Sparc-Opts. (line 5421) +* -construct-floats: MIPS Opts. (line 5056) +* -D: D. (line 934) +* '-eabi=' command line option, ARM: ARM Options. (line 3844) +* '-EB' command line option, ARM: ARM Options. (line 3849) +* '-EB' option (MIPS): MIPS Opts. (line 4879) +* '-EL' command line option, ARM: ARM Options. (line 3853) +* '-EL' option (MIPS): MIPS Opts. (line 4879) +* -f: f. (line 940) +* '-G' option (MIPS): MIPS Opts. (line 4874) +* -I PATH: I. (line 952) +* -K: K. (line 962) +* '-k' command line option, ARM: ARM Options. (line 3857) +* '-KPIC' option, MIPS: MIPS Opts. (line 4887) +* -L: L. (line 972) +* -M: M. (line 1022) +* '-mapcs' command line option, ARM: ARM Options. (line 3817) +* '-mapcs-float' command line option, ARM: ARM Options. (line 3830) +* '-mapcs-reentrant' command line option, ARM: ARM Options. (line 3835) +* '-march=' command line option, ARM: ARM Options. (line 3773) +* '-march=' option, i386: i386-Options. (line 4243) +* '-march=' option, x86-64: i386-Options. (line 4243) +* '-matpcs' command line option, ARM: ARM Options. (line 3822) +* '-mconstant-gp' command line option, IA-64: IA-64 Options. (line 4733) +* '-mcpu=' command line option, ARM: ARM Options. (line 3742) +* '-mfloat-abi=' command line option, ARM: ARM Options. (line 3839) +* '-mfpu=' command line option, ARM: ARM Options. (line 3788) +* -mno-sym32: MIPS Opts. (line 5045) +* -msym32: MIPS Opts. (line 5045) +* '-mthumb' command line option, ARM: ARM Options. (line 3808) +* '-mthumb-interwork' command line option, ARM: ARM Options. (line 3813) +* '-mtune=' option, i386: i386-Options. (line 4255) +* '-mtune=' option, x86-64: i386-Options. (line 4255) +* '-mvxworks-pic' option, MIPS: MIPS Opts. (line 4892) +* -no-construct-floats: MIPS Opts. (line 5056) +* '-nocpp' ignored (MIPS): MIPS Opts. (line 5048) +* -o: o. (line 1160) +* -R: R. (line 1170) +* -v: v. (line 1206) +* -version: v. (line 1206) +* -W: W. (line 1217) +* '.' (symbol): Dot. (line 1898) +* '.arch' directive, ARM: ARM Directives. (line 4118) +* '.cantunwind' directive, ARM: ARM Directives. (line 4022) +* '.cpu' directive, ARM: ARM Directives. (line 4114) +* '.eabi_attribute' directive, ARM: ARM Directives. (line 4132) +* '.fnend' directive, ARM: ARM Directives. (line 4014) +* '.fnstart' directive, ARM: ARM Directives. (line 4011) +* '.fpu' directive, ARM: ARM Directives. (line 4128) +* '.handlerdata' directive, ARM: ARM Directives. (line 4033) +* '.insn': MIPS insn. (line 5223) +* '.ltorg' directive, ARM: ARM Directives. (line 3994) +* '.movsp' directive, ARM: ARM Directives. (line 4088) +* .o: Object. (line 827) +* '.object_arch' directive, ARM: ARM Directives. (line 4122) +* '.pad' directive, ARM: ARM Directives. (line 4083) +* '.personality' directive, ARM: ARM Directives. (line 4026) +* '.personalityindex' directive, ARM: ARM Directives. (line 4029) +* '.pool' directive, ARM: ARM Directives. (line 4008) +* '.save' directive, ARM: ARM Directives. (line 4042) +* '.set arch=CPU': MIPS ISA. (line 5195) +* '.set autoextend': MIPS autoextend. (line 5210) +* '.set dsp': MIPS ASE instruction generation overrides. + (line 5262) +* '.set dspr2': MIPS ASE instruction generation overrides. + (line 5267) +* '.set mdmx': MIPS ASE instruction generation overrides. + (line 5257) +* '.set mips3d': MIPS ASE instruction generation overrides. + (line 5247) +* '.set mipsN': MIPS ISA. (line 5183) +* '.set mt': MIPS ASE instruction generation overrides. + (line 5272) +* '.set noautoextend': MIPS autoextend. (line 5210) +* '.set nodsp': MIPS ASE instruction generation overrides. + (line 5262) +* '.set nodspr2': MIPS ASE instruction generation overrides. + (line 5267) +* '.set nomdmx': MIPS ASE instruction generation overrides. + (line 5257) +* '.set nomips3d': MIPS ASE instruction generation overrides. + (line 5247) +* '.set nomt': MIPS ASE instruction generation overrides. + (line 5272) +* '.set nosmartmips': MIPS ASE instruction generation overrides. + (line 5252) +* '.set nosym32': MIPS symbol sizes. (line 5140) +* '.set pop': MIPS option stack. (line 5232) +* '.set push': MIPS option stack. (line 5232) +* '.set smartmips': MIPS ASE instruction generation overrides. + (line 5252) +* '.set sym32': MIPS symbol sizes. (line 5140) +* '.setfp' directive, ARM: ARM Directives. (line 4093) +* '.unwind_raw' directive, ARM: ARM Directives. (line 4107) +* '.vsave' directive, ARM: ARM Directives. (line 4066) +* 16-bit code, i386: i386-16bit. (line 4615) +* 3DNow!, i386: i386-SIMD. (line 4593) +* 3DNow!, x86-64: i386-SIMD. (line 4593) +* ':' (label): Statements. (line 1355) +* '\"' (doublequote character): Strings. (line 1423) +* '\b' (backspace character): Strings. (line 1395) +* '\DDD' (octal character code): Strings. (line 1410) +* '\f' (formfeed character): Strings. (line 1398) +* '\n' (newline character): Strings. (line 1401) +* '\r' (carriage return character): Strings. (line 1404) +* '\t' (tab): Strings. (line 1407) +* '\XD...' (hex character code): Strings. (line 1416) +* '\\' ('\' character): Strings. (line 1420) +* a.out: Object. (line 827) +* 'abort' directive: Abort. (line 2114) +* absolute section: Ld Sections. (line 1632) +* addition, permitted arguments: Infix Ops. (line 2055) +* addresses: Expressions. (line 1946) +* addresses, format of: Secs Background. (line 1573) +* 'ADR reg,<label>' pseudo op, ARM: ARM Opcodes. (line 4159) +* 'ADRL reg,<label>' pseudo op, ARM: ARM Opcodes. (line 4169) +* advancing location counter: Org. (line 3101) +* 'align' directive: Align. (line 2123) +* 'align' directive, ARM: ARM Directives. (line 3915) +* 'align' directive, SPARC: Sparc-Directives. (line 5481) +* arch directive, i386: i386-Arch. (line 4670) +* arch directive, x86-64: i386-Arch. (line 4670) +* architectures, PowerPC: PowerPC-Opts. (line 5285) +* architectures, SPARC: Sparc-Opts. (line 5402) +* arguments for addition: Infix Ops. (line 2055) +* arguments for subtraction: Infix Ops. (line 2060) +* arguments in expressions: Arguments. (line 1973) +* arithmetic functions: Operators. (line 1998) +* arithmetic operands: Arguments. (line 1973) +* ARM data relocations: ARM-Relocations. (line 3886) +* 'arm' directive, ARM: ARM Directives. (line 3969) +* ARM floating point (IEEE): ARM Floating Point. (line 3910) +* ARM identifiers: ARM-Chars. (line 3876) +* ARM immediate character: ARM-Chars. (line 3874) +* ARM line comment character: ARM-Chars. (line 3867) +* ARM line separator: ARM-Chars. (line 3871) +* ARM machine directives: ARM Directives. (line 3915) +* ARM opcodes: ARM Opcodes. (line 4140) +* ARM options (none): ARM Options. (line 3742) +* ARM register names: ARM-Regs. (line 3881) +* ARM support: Machine Dependencies. + (line 3739) +* 'ascii' directive: Ascii. (line 2165) +* 'asciz' directive: Asciz. (line 2172) +* assembler bugs, reporting: Bug Reporting. (line 5566) +* assembler crash: Bug Criteria. (line 5550) +* assembler internal logic error: As Sections. (line 1674) +* assembler version: v. (line 1206) +* assembler, and linker: Secs Background. (line 1535) +* assembly listings, enabling: a. (line 894) +* assigning values to symbols: Setting Symbols. (line 1772) +* assigning values to symbols <1>: Equ. (line 2471) +* attributes, symbol: Symbol Attributes. (line 1907) +* att_syntax pseudo op, i386: i386-Syntax. (line 4265) +* att_syntax pseudo op, x86-64: i386-Syntax. (line 4265) +* Av7: Sparc-Opts. (line 5421) +* backslash ('\\'): Strings. (line 1420) +* backspace ('\b'): Strings. (line 1395) +* 'balign' directive: Balign. (line 2178) +* 'balignl' directive: Balign. (line 2199) +* 'balignw' directive: Balign. (line 2199) +* big endian output, MIPS: Overview. (line 560) +* big-endian output, MIPS: MIPS Opts. (line 4879) +* bignums: Bignums. (line 1485) +* binary files, including: Incbin. (line 2707) +* binary integers: Integers. (line 1466) +* bit names, IA-64: IA-64-Bits. (line 4846) +* bss section: Ld Sections. (line 1623) +* bss section <1>: bss. (line 1739) +* bug criteria: Bug Criteria. (line 5547) +* bug reports: Bug Reporting. (line 5566) +* bugs in assembler: Reporting Bugs. (line 5534) +* bus lock prefixes, i386: i386-Prefixes. (line 4444) +* 'byte' directive: Byte. (line 2211) +* call instructions, i386: i386-Mnemonics. (line 4353) +* call instructions, x86-64: i386-Mnemonics. (line 4353) +* carriage return ('\r'): Strings. (line 1404) +* 'cfi_endproc' directive: CFI directives. (line 2249) +* 'cfi_startproc' directive: CFI directives. (line 2239) +* character constants: Characters. (line 1377) +* character escape codes: Strings. (line 1395) +* character, single: Chars. (line 1443) +* characters used in symbols: Symbol Intro. (line 1325) +* 'code' directive, ARM: ARM Directives. (line 3962) +* 'code16' directive, i386: i386-16bit. (line 4615) +* 'code16gcc' directive, i386: i386-16bit. (line 4615) +* 'code32' directive, i386: i386-16bit. (line 4615) +* 'code64' directive, i386: i386-16bit. (line 4615) +* 'code64' directive, x86-64: i386-16bit. (line 4615) +* COMDAT: Linkonce. (line 2831) +* 'comm' directive: Comm. (line 2217) +* command line conventions: Command Line. (line 756) +* comments: Comments. (line 1288) +* comments, removed by preprocessor: Preprocessing. (line 1253) +* 'common' directive, SPARC: Sparc-Directives. (line 5484) +* common sections: Linkonce. (line 2831) +* common variable storage: bss. (line 1739) +* comparison expressions: Infix Ops. (line 2066) +* conditional assembly: If. (line 2629) +* constant, single character: Chars. (line 1443) +* constants: Constants. (line 1366) +* constants, bignum: Bignums. (line 1485) +* constants, character: Characters. (line 1377) +* constants, converted by preprocessor: Preprocessing. (line 1256) +* constants, floating point: Flonums. (line 1493) +* constants, integer: Integers. (line 1466) +* constants, number: Numbers. (line 1457) +* constants, string: Strings. (line 1386) +* conversion instructions, i386: i386-Mnemonics. (line 4334) +* conversion instructions, x86-64: i386-Mnemonics. (line 4334) +* coprocessor wait, i386: i386-Prefixes. (line 4448) +* crash of assembler: Bug Criteria. (line 5550) +* current address: Dot. (line 1898) +* current address, advancing: Org. (line 3101) +* data alignment on SPARC: Sparc-Aligned-Data. (line 5455) +* data and text sections, joining: R. (line 1170) +* 'data' directive: Data. (line 2421) +* data relocations, ARM: ARM-Relocations. (line 3886) +* debuggers, and symbol order: Symbols. (line 1757) +* decimal integers: Integers. (line 1472) +* dependency tracking: MD. (line 1149) +* deprecated directives: Deprecated. (line 3731) +* directives and instructions: Statements. (line 1347) +* directives for PowerPC: PowerPC-Pseudo. (line 5386) +* directives, machine independent: Pseudo Ops. (line 2105) +* 'dn' and 'qn' directives, ARM: ARM Directives. (line 3938) +* dollar local symbols: Symbol Names. (line 1879) +* dot (symbol): Dot. (line 1898) +* 'double' directive: Double. (line 2428) +* 'double' directive, i386: i386-Float. (line 4569) +* 'double' directive, x86-64: i386-Float. (line 4569) +* doublequote ('\"'): Strings. (line 1423) +* ECOFF sections: MIPS Object. (line 5100) +* eight-byte integer: Quad. (line 3245) +* 'eject' directive: Eject. (line 2434) +* ELF symbol type: Type. (line 3620) +* 'else' directive: Else. (line 2439) +* 'elseif' directive: Elseif. (line 2446) +* empty expressions: Empty Exprs. (line 1959) +* emulation: Overview. (line 663) +* 'end' directive: End. (line 2453) +* 'endfunc' directive: Endfunc. (line 2459) +* endianness, MIPS: Overview. (line 560) +* 'endif' directive: Endif. (line 2464) +* 'endm' directive: Macro. (line 3025) +* EOF, newline must precede: Statements. (line 1341) +* 'equ' directive: Equ. (line 2471) +* 'equiv' directive: Equiv. (line 2477) +* 'eqv' directive: Eqv. (line 2493) +* 'err' directive: Err. (line 2501) +* error directive: Error. (line 2509) +* error messages: Errors. (line 844) +* error on valid input: Bug Criteria. (line 5553) +* errors, caused by warnings: W. (line 1222) +* errors, continuing after: Z. (line 1231) +* escape codes, character: Strings. (line 1395) +* 'exitm' directive: Macro. (line 3028) +* expr (internal section): As Sections. (line 1678) +* expression arguments: Arguments. (line 1973) +* expressions: Expressions. (line 1946) +* expressions, comparison: Infix Ops. (line 2066) +* expressions, empty: Empty Exprs. (line 1959) +* expressions, integer: Integer Exprs. (line 1967) +* 'extern' directive: Extern. (line 2524) +* 'fail' directive: Fail. (line 2531) +* faster processing ('-f'): f. (line 940) +* fatal signal: Bug Criteria. (line 5550) +* 'file' directive: LNS directives. (line 2369) +* 'file' directive <1>: File. (line 2540) +* file name, logical: File. (line 2540) +* files, including: Include. (line 2721) +* files, input: Input Files. (line 780) +* 'fill' directive: Fill. (line 2550) +* filling memory: Skip. (line 3452) +* filling memory <1>: Space. (line 3459) +* 'float' directive: Float. (line 2568) +* 'float' directive, i386: i386-Float. (line 4569) +* 'float' directive, x86-64: i386-Float. (line 4569) +* floating point numbers: Flonums. (line 1493) +* floating point numbers (double): Double. (line 2428) +* floating point numbers (single): Float. (line 2568) +* floating point numbers (single) <1>: Single. (line 3425) +* floating point, ARM (IEEE): ARM Floating Point. (line 3910) +* floating point, i386: i386-Float. (line 4561) +* floating point, SPARC (IEEE): Sparc-Float. (line 5473) +* floating point, x86-64: i386-Float. (line 4561) +* flonums: Flonums. (line 1493) +* 'force_thumb' directive, ARM: ARM Directives. (line 3972) +* format of error messages: Errors. (line 861) +* format of warning messages: Errors. (line 850) +* formfeed ('\f'): Strings. (line 1398) +* 'func' directive: Func. (line 2574) +* functions, in expressions: Operators. (line 1998) +* 'global' directive: Global. (line 2585) +* 'gp' register, MIPS: MIPS Object. (line 5105) +* grouping data: Sub-Sections. (line 1686) +* 'half' directive, SPARC: Sparc-Directives. (line 5489) +* hex character code ('\XD...'): Strings. (line 1416) +* hexadecimal integers: Integers. (line 1475) +* 'hidden' directive: Hidden. (line 2597) +* 'hword' directive: hword. (line 2610) +* i386 16-bit code: i386-16bit. (line 4615) +* i386 arch directive: i386-Arch. (line 4670) +* i386 att_syntax pseudo op: i386-Syntax. (line 4265) +* i386 conversion instructions: i386-Mnemonics. (line 4334) +* i386 floating point: i386-Float. (line 4561) +* i386 immediate operands: i386-Syntax. (line 4274) +* i386 instruction naming: i386-Mnemonics. (line 4309) +* i386 instruction prefixes: i386-Prefixes. (line 4414) +* i386 intel_syntax pseudo op: i386-Syntax. (line 4265) +* i386 jump optimization: i386-Jumps. (line 4538) +* i386 jump, call, return: i386-Syntax. (line 4296) +* i386 jump/call operands: i386-Syntax. (line 4274) +* i386 memory references: i386-Memory. (line 4471) +* i386 'mul', 'imul' instructions: i386-Notes. (line 4714) +* i386 options: i386-Options. (line 4218) +* i386 register operands: i386-Syntax. (line 4274) +* i386 registers: i386-Regs. (line 4359) +* i386 sections: i386-Syntax. (line 4302) +* i386 size suffixes: i386-Syntax. (line 4287) +* i386 source, destination operands: i386-Syntax. (line 4280) +* i386 support: . (line 4211) +* i386 syntax compatibility: i386-Syntax. (line 4265) +* i80306 support: . (line 4211) +* IA-64 line comment character: IA-64-Chars. (line 4822) +* IA-64 line separator: IA-64-Chars. (line 4824) +* IA-64 options: IA-64 Options. (line 4733) +* IA-64 Processor-status-Register bit names: IA-64-Bits. (line 4846) +* IA-64 registers: IA-64-Regs. (line 4829) +* IA-64 support: . (line 4730) +* IA-64 Syntax: IA-64 Options. (line 4812) +* 'ident' directive: Ident. (line 2618) +* identifiers, ARM: ARM-Chars. (line 3876) +* 'if' directive: If. (line 2629) +* 'ifb' directive: If. (line 2644) +* 'ifc' directive: If. (line 2648) +* 'ifdef' directive: If. (line 2639) +* 'ifeq' directive: If. (line 2656) +* 'ifeqs' directive: If. (line 2659) +* 'ifge' directive: If. (line 2663) +* 'ifgt' directive: If. (line 2667) +* 'ifle' directive: If. (line 2671) +* 'iflt' directive: If. (line 2675) +* 'ifnb' directive: If. (line 2679) +* 'ifnc' directive: If. (line 2684) +* 'ifndef' directive: If. (line 2688) +* 'ifne' directive: If. (line 2695) +* 'ifnes' directive: If. (line 2699) +* 'ifnotdef' directive: If. (line 2688) +* immediate character, ARM: ARM-Chars. (line 3874) +* immediate operands, i386: i386-Syntax. (line 4274) +* immediate operands, x86-64: i386-Syntax. (line 4274) +* 'imul' instruction, i386: i386-Notes. (line 4714) +* 'imul' instruction, x86-64: i386-Notes. (line 4714) +* 'incbin' directive: Incbin. (line 2707) +* 'include' directive: Include. (line 2721) +* 'include' directive search path: I. (line 952) +* infix operators: Infix Ops. (line 2016) +* inhibiting interrupts, i386: i386-Prefixes. (line 4444) +* input: Input Files. (line 780) +* input file linenumbers: Input Files. (line 809) +* instruction naming, i386: i386-Mnemonics. (line 4309) +* instruction naming, x86-64: i386-Mnemonics. (line 4309) +* instruction prefixes, i386: i386-Prefixes. (line 4414) +* instructions and directives: Statements. (line 1347) +* 'int' directive: Int. (line 2732) +* 'int' directive, i386: i386-Float. (line 4576) +* 'int' directive, x86-64: i386-Float. (line 4576) +* integer expressions: Integer Exprs. (line 1967) +* integer, 16-byte: Octa. (line 3092) +* integer, 8-byte: Quad. (line 3245) +* integers: Integers. (line 1466) +* integers, 16-bit: hword. (line 2610) +* integers, 32-bit: Int. (line 2732) +* integers, binary: Integers. (line 1466) +* integers, decimal: Integers. (line 1472) +* integers, hexadecimal: Integers. (line 1475) +* integers, octal: Integers. (line 1469) +* integers, one byte: Byte. (line 2211) +* intel_syntax pseudo op, i386: i386-Syntax. (line 4265) +* intel_syntax pseudo op, x86-64: i386-Syntax. (line 4265) +* internal assembler sections: As Sections. (line 1667) +* 'internal' directive: Internal. (line 2740) +* invalid input: Bug Criteria. (line 5555) +* invocation summary: Overview. (line 249) +* 'irp' directive: Irp. (line 2754) +* 'irpc' directive: Irpc. (line 2779) +* joining text and data sections: R. (line 1170) +* jump instructions, i386: i386-Mnemonics. (line 4353) +* jump instructions, x86-64: i386-Mnemonics. (line 4353) +* jump optimization, i386: i386-Jumps. (line 4538) +* jump optimization, x86-64: i386-Jumps. (line 4538) +* jump/call operands, i386: i386-Syntax. (line 4274) +* jump/call operands, x86-64: i386-Syntax. (line 4274) +* label (':'): Statements. (line 1355) +* labels: Labels. (line 1763) +* 'lcomm' directive: Lcomm. (line 2805) +* ld: Object. (line 836) +* 'LDR reg,=<label>' pseudo op, ARM: ARM Opcodes. (line 4149) +* length of symbols: Symbol Intro. (line 1331) +* 'lflags' directive (ignored): Lflags. (line 2814) +* line comment character: Comments. (line 1301) +* line comment character, ARM: ARM-Chars. (line 3867) +* line comment character, IA-64: IA-64-Chars. (line 4822) +* 'line' directive: Line. (line 2820) +* line numbers, in input files: Input Files. (line 809) +* line numbers, in warnings/errors: Errors. (line 854) +* line separator character: Statements. (line 1336) +* line separator, ARM: ARM-Chars. (line 3871) +* line separator, IA-64: IA-64-Chars. (line 4824) +* lines starting with '#': Comments. (line 1306) +* linker: Object. (line 836) +* linker, and assembler: Secs Background. (line 1535) +* 'linkonce' directive: Linkonce. (line 2831) +* 'list' directive: List. (line 2876) +* listing control, turning off: Nolist. (line 3083) +* listing control, turning on: List. (line 2876) +* listing control: new page: Eject. (line 2434) +* listing control: paper size: Psize. (line 3208) +* listing control: subtitle: Sbttl. (line 3284) +* listing control: title line: Title. (line 3609) +* listings, enabling: a. (line 894) +* little endian output, MIPS: Overview. (line 563) +* little-endian output, MIPS: MIPS Opts. (line 4879) +* 'ln' directive: Ln. (line 2863) +* 'loc' directive: LNS directives. (line 2382) +* local common symbols: Lcomm. (line 2805) +* local labels: Symbol Names. (line 1810) +* local symbol names: Symbol Names. (line 1797) +* local symbols, retaining in output: L. (line 972) +* location counter: Dot. (line 1898) +* location counter, advancing: Org. (line 3101) +* 'loc_mark_blocks' directive: LNS directives. (line 2412) +* logical file name: File. (line 2540) +* logical line number: Line. (line 2820) +* logical line numbers: Comments. (line 1306) +* 'long' directive: Long. (line 2889) +* 'long' directive, i386: i386-Float. (line 4576) +* 'long' directive, x86-64: i386-Float. (line 4576) +* machine directives, ARM: ARM Directives. (line 3915) +* machine directives, SPARC: Sparc-Directives. (line 5478) +* machine independent directives: Pseudo Ops. (line 2105) +* machine instructions (not covered): Manual. (line 716) +* machine-independent syntax: Syntax. (line 1241) +* 'macro' directive: Macro. (line 2916) +* macros: Macro. (line 2894) +* macros, count executed: Macro. (line 3030) +* make rules: MD. (line 1149) +* manual, structure and purpose: Manual. (line 708) +* Maximum number of continuation lines: listing. (line 1015) +* memory references, i386: i386-Memory. (line 4471) +* memory references, x86-64: i386-Memory. (line 4471) +* merging text and data sections: R. (line 1170) +* messages from assembler: Errors. (line 844) +* minus, permitted arguments: Infix Ops. (line 2060) +* MIPS architecture options: MIPS Opts. (line 4895) +* MIPS big-endian output: MIPS Opts. (line 4879) +* MIPS CPU override: MIPS ISA. (line 5195) +* MIPS debugging directives: MIPS Stabs. (line 5128) +* MIPS DSP Release 1 instruction generation override: MIPS ASE instruction generation overrides. + (line 5262) +* MIPS DSP Release 2 instruction generation override: MIPS ASE instruction generation overrides. + (line 5267) +* MIPS ECOFF sections: MIPS Object. (line 5100) +* MIPS endianness: Overview. (line 560) +* MIPS ISA: Overview. (line 566) +* MIPS ISA override: MIPS ISA. (line 5183) +* MIPS little-endian output: MIPS Opts. (line 4879) +* MIPS MDMX instruction generation override: MIPS ASE instruction generation overrides. + (line 5257) +* MIPS MIPS-3D instruction generation override: MIPS ASE instruction generation overrides. + (line 5247) +* MIPS MT instruction generation override: MIPS ASE instruction generation overrides. + (line 5272) +* MIPS option stack: MIPS option stack. (line 5232) +* MIPS processor: . (line 4862) +* MMX, i386: i386-SIMD. (line 4593) +* MMX, x86-64: i386-SIMD. (line 4593) +* mnemonic suffixes, i386: i386-Syntax. (line 4287) +* mnemonic suffixes, x86-64: i386-Syntax. (line 4287) +* MOVW and MOVT relocations, ARM: ARM-Relocations. (line 3900) +* MRI compatibility mode: M. (line 1022) +* 'mri' directive: MRI. (line 2868) +* MRI mode, temporarily: MRI. (line 2868) +* 'mul' instruction, i386: i386-Notes. (line 4714) +* 'mul' instruction, x86-64: i386-Notes. (line 4714) +* named section: Section. (line 3293) +* named sections: Ld Sections. (line 1613) +* names, symbol: Symbol Names. (line 1781) +* naming object file: o. (line 1160) +* new page, in listings: Eject. (line 2434) +* newline ('\n'): Strings. (line 1401) +* newline, required at file end: Statements. (line 1341) +* 'nolist' directive: Nolist. (line 3083) +* 'NOP' pseudo op, ARM: ARM Opcodes. (line 4143) +* null-terminated strings: Asciz. (line 2172) +* number constants: Numbers. (line 1457) +* number of macros executed: Macro. (line 3030) +* numbered subsections: Sub-Sections. (line 1686) +* numbers, 16-bit: hword. (line 2610) +* numeric values: Expressions. (line 1946) +* 'nword' directive, SPARC: Sparc-Directives. (line 5492) +* object file: Object. (line 827) +* object file format: Object Formats. (line 746) +* object file name: o. (line 1160) +* object file, after errors: Z. (line 1231) +* obsolescent directives: Deprecated. (line 3731) +* 'octa' directive: Octa. (line 3092) +* octal character code ('\DDD'): Strings. (line 1410) +* octal integers: Integers. (line 1469) +* opcodes for ARM: ARM Opcodes. (line 4140) +* operand delimiters, i386: i386-Syntax. (line 4274) +* operand delimiters, x86-64: i386-Syntax. (line 4274) +* operands in expressions: Arguments. (line 1973) +* operator precedence: Infix Ops. (line 2021) +* operators, in expressions: Operators. (line 1998) +* operators, permitted arguments: Infix Ops. (line 2016) +* option summary: Overview. (line 249) +* options for ARM (none): ARM Options. (line 3742) +* options for i386: i386-Options. (line 4218) +* options for IA-64: IA-64 Options. (line 4733) +* options for PowerPC: PowerPC-Opts. (line 5285) +* options for SPARC: Sparc-Opts. (line 5402) +* options for x86-64: i386-Options. (line 4218) +* options, all versions of assembler: Invoking. (line 870) +* options, command line: Command Line. (line 763) +* 'org' directive: Org. (line 3101) +* output file: Object. (line 827) +* 'p2align' directive: P2align. (line 3127) +* 'p2alignl' directive: P2align. (line 3149) +* 'p2alignw' directive: P2align. (line 3149) +* padding the location counter: Align. (line 2123) +* padding the location counter given a power of two: P2align. + (line 3127) +* padding the location counter given number of bytes: Balign. + (line 2178) +* page, in listings: Eject. (line 2434) +* paper size, for listings: Psize. (line 3208) +* paths for '.include': I. (line 952) +* patterns, writing in memory: Fill. (line 2550) +* PIC code generation for ARM: ARM Options. (line 3857) +* PIC selection, MIPS: MIPS Opts. (line 4887) +* plus, permitted arguments: Infix Ops. (line 2055) +* 'popsection' directive: PopSection. (line 3177) +* PowerPC architectures: PowerPC-Opts. (line 5285) +* PowerPC directives: PowerPC-Pseudo. (line 5386) +* PowerPC options: PowerPC-Opts. (line 5285) +* PowerPC support: . (line 5282) +* precedence of operators: Infix Ops. (line 2021) +* precision, floating point: Flonums. (line 1493) +* prefix operators: Prefix Ops. (line 2005) +* prefixes, i386: i386-Prefixes. (line 4414) +* preprocessing: Preprocessing. (line 1248) +* preprocessing, turning on and off: Preprocessing. (line 1268) +* 'previous' directive: Previous. (line 3161) +* 'print' directive: Print. (line 3189) +* 'proc' directive, SPARC: Sparc-Directives. (line 5497) +* 'protected' directive: Protected. (line 3195) +* pseudo-ops, machine independent: Pseudo Ops. (line 2105) +* 'psize' directive: Psize. (line 3208) +* PSR bits: IA-64-Bits. (line 4846) +* 'purgem' directive: Purgem. (line 3224) +* purpose of GNU assembler: GNU Assembler. (line 734) +* 'pushsection' directive: PushSection. (line 3230) +* 'quad' directive: Quad. (line 3242) +* 'quad' directive, i386: i386-Float. (line 4576) +* 'quad' directive, x86-64: i386-Float. (line 4576) +* real-mode code, i386: i386-16bit. (line 4615) +* 'register' directive, SPARC: Sparc-Directives. (line 5501) +* register names, ARM: ARM-Regs. (line 3881) +* register names, IA-64: IA-64-Regs. (line 4829) +* register operands, i386: i386-Syntax. (line 4274) +* register operands, x86-64: i386-Syntax. (line 4274) +* registers, i386: i386-Regs. (line 4359) +* registers, x86-64: i386-Regs. (line 4359) +* 'reloc' directive: Reloc. (line 3253) +* relocation: Sections. (line 1528) +* relocation example: Ld Sections. (line 1643) +* repeat prefixes, i386: i386-Prefixes. (line 4452) +* reporting bugs in assembler: Reporting Bugs. (line 5534) +* 'rept' directive: Rept. (line 3266) +* 'req' directive, ARM: ARM Directives. (line 3922) +* 'reserve' directive, SPARC: Sparc-Directives. (line 5511) +* return instructions, i386: i386-Syntax. (line 4296) +* return instructions, x86-64: i386-Syntax. (line 4296) +* REX prefixes, i386: i386-Prefixes. (line 4454) +* 'sbttl' directive: Sbttl. (line 3284) +* search path for '.include': I. (line 952) +* 'section' directive (ELF version): Section. (line 3305) +* section override prefixes, i386: i386-Prefixes. (line 4431) +* Section Stack: Previous. (line 3161) +* Section Stack <1>: PopSection. (line 3177) +* Section Stack <2>: PushSection. (line 3230) +* Section Stack <3>: Section. (line 3300) +* Section Stack <4>: SubSection. (line 3545) +* section-relative addressing: Secs Background. (line 1573) +* sections: Sections. (line 1528) +* sections in messages, internal: As Sections. (line 1667) +* sections, i386: i386-Syntax. (line 4302) +* sections, named: Ld Sections. (line 1613) +* sections, x86-64: i386-Syntax. (line 4302) +* 'seg' directive, SPARC: Sparc-Directives. (line 5516) +* 'set' directive: Set. (line 3407) +* 'short' directive: Short. (line 3419) +* SIMD, i386: i386-SIMD. (line 4593) +* SIMD, x86-64: i386-SIMD. (line 4593) +* single character constant: Chars. (line 1443) +* 'single' directive: Single. (line 3425) +* 'single' directive, i386: i386-Float. (line 4569) +* 'single' directive, x86-64: i386-Float. (line 4569) +* sixteen bit integers: hword. (line 2610) +* sixteen byte integer: Octa. (line 3092) +* 'size' directive (ELF version): Size. (line 3433) +* size prefixes, i386: i386-Prefixes. (line 4435) +* sizes operands, i386: i386-Syntax. (line 4287) +* sizes operands, x86-64: i386-Syntax. (line 4287) +* 'skip' directive: Skip. (line 3452) +* 'skip' directive, SPARC: Sparc-Directives. (line 5520) +* 'sleb128' directive: Sleb128. (line 3445) +* small objects, MIPS ECOFF: MIPS Object. (line 5105) +* SmartMIPS instruction generation override: MIPS ASE instruction generation overrides. + (line 5252) +* source program: Input Files. (line 780) +* source, destination operands; i386: i386-Syntax. (line 4280) +* source, destination operands; x86-64: i386-Syntax. (line 4280) +* 'space' directive: Space. (line 3459) +* space used, maximum for assembly: statistics. (line 1188) +* SPARC architectures: Sparc-Opts. (line 5402) +* SPARC data alignment: Sparc-Aligned-Data. (line 5455) +* SPARC floating point (IEEE): Sparc-Float. (line 5473) +* SPARC machine directives: Sparc-Directives. (line 5478) +* SPARC options: Sparc-Opts. (line 5402) +* SPARC support: . (line 5399) +* 'stabd' directive: Stab. (line 3498) +* 'stabn' directive: Stab. (line 3509) +* 'stabs' directive: Stab. (line 3512) +* 'stabX' directives: Stab. (line 3466) +* standard assembler sections: Secs Background. (line 1550) +* standard input, as input file: Command Line. (line 760) +* statement separator character: Statements. (line 1336) +* statement separator, ARM: ARM-Chars. (line 3871) +* statement separator, IA-64: IA-64-Chars. (line 4824) +* statements, structure of: Statements. (line 1336) +* statistics, about assembly: statistics. (line 1188) +* stopping the assembly: Abort. (line 2114) +* string constants: Strings. (line 1386) +* 'string' directive: String. (line 3518) +* string literals: Ascii. (line 2165) +* string, copying to object file: String. (line 3518) +* 'struct' directive: Struct. (line 3527) +* subexpressions: Arguments. (line 1991) +* 'subsection' directive: SubSection. (line 3545) +* subtitles for listings: Sbttl. (line 3284) +* subtraction, permitted arguments: Infix Ops. (line 2060) +* summary of options: Overview. (line 249) +* supporting files, including: Include. (line 2721) +* suppressing warnings: W. (line 1217) +* symbol attributes: Symbol Attributes. (line 1907) +* symbol names: Symbol Names. (line 1781) +* symbol names, local: Symbol Names. (line 1797) +* symbol names, temporary: Symbol Names. (line 1810) +* symbol type: Symbol Type. (line 1938) +* symbol type, ELF: Type. (line 3620) +* symbol value: Symbol Value. (line 1918) +* symbol value, setting: Set. (line 3407) +* symbol values, assigning: Setting Symbols. (line 1772) +* symbol versioning: Symver. (line 3557) +* symbol, common: Comm. (line 2217) +* symbol, making visible to linker: Global. (line 2585) +* symbolic debuggers, information for: Stab. (line 3466) +* symbols: Symbols. (line 1753) +* symbols, assigning values to: Equ. (line 2471) +* symbols, local common: Lcomm. (line 2805) +* 'symver' directive: Symver. (line 3557) +* syntax compatibility, i386: i386-Syntax. (line 4265) +* syntax compatibility, x86-64: i386-Syntax. (line 4265) +* syntax, machine-independent: Syntax. (line 1241) +* tab ('\t'): Strings. (line 1407) +* temporary symbol names: Symbol Names. (line 1810) +* text and data sections, joining: R. (line 1170) +* 'text' directive: Text. (line 3602) +* 'tfloat' directive, i386: i386-Float. (line 4569) +* 'tfloat' directive, x86-64: i386-Float. (line 4569) +* 'thumb' directive, ARM: ARM Directives. (line 3966) +* Thumb support: Machine Dependencies. + (line 3739) +* 'thumb_func' directive, ARM: ARM Directives. (line 3976) +* 'thumb_set' directive, ARM: ARM Directives. (line 3987) +* time, total for assembly: statistics. (line 1188) +* 'title' directive: Title. (line 3609) +* trusted compiler: f. (line 940) +* turning preprocessing on and off: Preprocessing. (line 1268) +* 'type' directive (ELF version): Type. (line 3620) +* type of a symbol: Symbol Type. (line 1938) +* 'uleb128' directive: Uleb128. (line 3656) +* undefined section: Ld Sections. (line 1639) +* 'unreq' directive, ARM: ARM Directives. (line 3927) +* value of a symbol: Symbol Value. (line 1918) +* 'version' directive: Version. (line 3663) +* version of assembler: v. (line 1206) +* versions of symbols: Symver. (line 3557) +* visibility: Hidden. (line 2597) +* visibility <1>: Internal. (line 2740) +* visibility <2>: Protected. (line 3195) +* 'vtable_entry' directive: VTableEntry. (line 3669) +* 'vtable_inherit' directive: VTableInherit. (line 3675) +* warning directive: Warning. (line 3683) +* warning messages: Errors. (line 844) +* warnings, causing error: W. (line 1222) +* warnings, suppressing: W. (line 1217) +* warnings, switching on: W. (line 1225) +* 'weak' directive: Weak. (line 3689) +* 'weakref' directive: Weakref. (line 3705) +* whitespace: Whitespace. (line 1280) +* whitespace, removed by preprocessor: Preprocessing. (line 1249) +* Width of continuation lines of disassembly output: listing. + (line 1002) +* Width of first line disassembly output: listing. (line 997) +* Width of source line output: listing. (line 1009) +* 'word' directive: Word. (line 3725) +* 'word' directive, i386: i386-Float. (line 4576) +* 'word' directive, SPARC: Sparc-Directives. (line 5523) +* 'word' directive, x86-64: i386-Float. (line 4576) +* writing patterns in memory: Fill. (line 2550) +* x86-64 arch directive: i386-Arch. (line 4670) +* x86-64 att_syntax pseudo op: i386-Syntax. (line 4265) +* x86-64 conversion instructions: i386-Mnemonics. (line 4334) +* x86-64 floating point: i386-Float. (line 4561) +* x86-64 immediate operands: i386-Syntax. (line 4274) +* x86-64 instruction naming: i386-Mnemonics. (line 4309) +* x86-64 intel_syntax pseudo op: i386-Syntax. (line 4265) +* x86-64 jump optimization: i386-Jumps. (line 4538) +* x86-64 jump, call, return: i386-Syntax. (line 4296) +* x86-64 jump/call operands: i386-Syntax. (line 4274) +* x86-64 memory references: i386-Memory. (line 4471) +* x86-64 options: i386-Options. (line 4218) +* x86-64 register operands: i386-Syntax. (line 4274) +* x86-64 registers: i386-Regs. (line 4359) +* x86-64 sections: i386-Syntax. (line 4302) +* x86-64 size suffixes: i386-Syntax. (line 4287) +* x86-64 source, destination operands: i386-Syntax. (line 4280) +* x86-64 support: . (line 4211) +* x86-64 syntax compatibility: i386-Syntax. (line 4265) +* 'xword' directive, SPARC: Sparc-Directives. (line 5527) +* zero-terminated strings: Asciz. (line 2172) + +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 <ctl-D> 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. + + '<STRING>' + 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 <name> STT_FUNCTION + .type <name> STT_OBJECT + + .type <name>,#function + .type <name>,#object + + .type <name>,@function + .type <name>,@object + + .type <name>,%function + .type <name>,%object + + .type <name>,"function" + .type <name>,"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 <register> , = <expression> + + 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 <register> <label> + + This instruction will load the address of LABEL into the indicated + register. The instruction will evaluate to a PC relative ADD or + SUB instruction depending upon where the label is located. If the + label is out of range, or if it is not defined in the same file + (and section) as the ADR instruction, then an error will be + generated. This instruction will not make use of the literal pool. + +'ADRL' + adrl <register> <label> + + This instruction will load the address of LABEL into the indicated + register. The instruction will evaluate to one or two PC relative + ADD or SUB instructions depending upon where the label is located. + If a second instruction is not needed a NOP instruction will be + generated in its place, so that this instruction is always 8 bytes + long. + + If the label is out of range, or if it is not defined in the same + file (and section) as the ADRL instruction, then an error will be + generated. This instruction will not make use of the literal pool. + + For information on the ARM or Thumb instruction sets, see 'ARM +Software Development Toolkit Reference Manual', Advanced RISC Machines +Ltd. + +8.6 Mapping Symbols +=================== + +The ARM ELF specification requires that special symbols be inserted into +object files to mark certain features: + +'$a' + At the start of a region of code containing ARM instructions. + +'$t' + At the start of a region of code containing THUMB instructions. + +'$d' + At the start of a region of data. + + The assembler will automatically insert these symbols for you - there +is no need to code them yourself. Support for tagging symbols ($b, $f, +$p and $m) which is also mentioned in the current ARM ELF specification +is not implemented. This is because they have been dropped from the new +EABI and so tools cannot rely upon their presence. + +9 80386 Dependent Features +************************** + +The i386 version 'as' supports both the original Intel 386 architecture +in both 16 and 32-bit mode as well as AMD x86-64 architecture extending +the Intel architecture to 64-bits. + +9.1 Options +=========== + +The i386 version of 'as' has a few machine dependent options: + +'--32 | --64' + Select the word size, either 32 bits or 64 bits. Selecting 32-bit + implies Intel i386 architecture, while 64-bit implies AMD x86-64 + architecture. + + These options are only available with the ELF object file format, + and require that the necessary BFD support has been included (on a + 32-bit platform you have to add -enable-64-bit-bfd to configure + enable 64-bit usage and use x86-64 as target platform). + +'-n' + By default, x86 GAS replaces multiple nop instructions used for + alignment within code sections with multi-byte nop instructions + such as leal 0(%esi,1),%esi. This switch disables the + optimization. + +'--divide' + On SVR4-derived platforms, the character '/' is treated as a + comment character, which means that it cannot be used in + expressions. The '--divide' option turns '/' into a normal + character. This does not disable '/' at the beginning of a line + starting a comment, or affect using '#' for starting a comment. + +'-march=CPU' + This option specifies an instruction set architecture for + generating instructions. The following architectures are + recognized: 'i8086', 'i186', 'i286', 'i386', 'i486', 'i586', + 'i686', 'pentium', 'pentiumpro', 'pentiumii', 'pentiumiii', + 'pentium4', 'prescott', 'nocona', 'core', 'core2', 'k6', 'k6_2', + 'athlon', 'sledgehammer', 'opteron', 'k8', 'generic32' and + 'generic64'. + + This option only affects instructions generated by the assembler. + The '.arch' directive will take precedent. + +'-mtune=CPU' + This option specifies a processor to optimize for. When used in + conjunction with the '-march' option, only instructions of the + processor specified by the '-march' option will be generated. + + Valid CPU values are identical to '-march=CPU'. + +9.2 AT&T Syntax versus Intel Syntax +=================================== + +'as' now supports assembly using Intel assembler syntax. +'.intel_syntax' selects Intel mode, and '.att_syntax' switches back to +the usual AT&T mode for compatibility with the output of 'gcc'. Either +of these directives may have an optional argument, 'prefix', or +'noprefix' specifying whether registers require a '%' prefix. AT&T +System V/386 assembler syntax is quite different from Intel syntax. We +mention these differences because almost all 80386 documents use Intel +syntax. Notable differences between the two syntaxes are: + + * AT&T immediate operands are preceded by '$'; Intel immediate + operands are undelimited (Intel 'push 4' is AT&T 'pushl $4'). AT&T + register operands are preceded by '%'; Intel register operands are + undelimited. AT&T absolute (as opposed to PC relative) jump/call + operands are prefixed by '*'; they are undelimited in Intel syntax. + + * AT&T and Intel syntax use the opposite order for source and + destination operands. Intel 'add eax, 4' is 'addl $4, %eax'. The + 'source, dest' convention is maintained for compatibility with + previous Unix assemblers. Note that instructions with more than + one source operand, such as the 'enter' instruction, do _not_ have + reversed order. *note i386-Bugs::. + + * In AT&T syntax the size of memory operands is determined from the + last character of the instruction mnemonic. Mnemonic suffixes of + 'b', 'w', 'l' and 'q' specify byte (8-bit), word (16-bit), long + (32-bit) and quadruple word (64-bit) memory references. Intel + syntax accomplishes this by prefixing memory operands (_not_ the + instruction mnemonics) with 'byte ptr', 'word ptr', 'dword ptr' and + 'qword ptr'. Thus, Intel 'mov al, byte ptr FOO' is 'movb FOO, %al' + in AT&T syntax. + + * Immediate form long jumps and calls are 'lcall/ljmp $SECTION, + $OFFSET' in AT&T syntax; the Intel syntax is 'call/jmp far + SECTION:OFFSET'. Also, the far return instruction is 'lret + $STACK-ADJUST' in AT&T syntax; Intel syntax is 'ret far + STACK-ADJUST'. + + * The AT&T assembler does not provide support for multiple section + programs. Unix style systems expect all programs to be single + sections. + +9.3 Instruction Naming +====================== + +Instruction mnemonics are suffixed with one character modifiers which +specify the size of operands. The letters 'b', 'w', 'l' and 'q' specify +byte, word, long and quadruple word operands. If no suffix is specified +by an instruction then 'as' tries to fill in the missing suffix based on +the destination register operand (the last one by convention). Thus, +'mov %ax, %bx' is equivalent to 'movw %ax, %bx'; also, 'mov $1, %bx' is +equivalent to 'movw $1, bx'. Note that this is incompatible with the +AT&T Unix assembler which assumes that a missing mnemonic suffix implies +long operand size. (This incompatibility does not affect compiler +output since compilers always explicitly specify the mnemonic suffix.) + + Almost all instructions have the same names in AT&T and Intel format. +There are a few exceptions. The sign extend and zero extend +instructions need two sizes to specify them. They need a size to +sign/zero extend _from_ and a size to zero extend _to_. This is +accomplished by using two instruction mnemonic suffixes in AT&T syntax. +Base names for sign extend and zero extend are 'movs...' and 'movz...' +in AT&T syntax ('movsx' and 'movzx' in Intel syntax). The instruction +mnemonic suffixes are tacked on to this base name, the _from_ suffix +before the _to_ suffix. Thus, 'movsbl %al, %edx' is AT&T syntax for +"move sign extend _from_ %al _to_ %edx." Possible suffixes, thus, are +'bl' (from byte to long), 'bw' (from byte to word), 'wl' (from word to +long), 'bq' (from byte to quadruple word), 'wq' (from word to quadruple +word), and 'lq' (from long to quadruple word). + + The Intel-syntax conversion instructions + + * 'cbw' -- sign-extend byte in '%al' to word in '%ax', + + * 'cwde' -- sign-extend word in '%ax' to long in '%eax', + + * 'cwd' -- sign-extend word in '%ax' to long in '%dx:%ax', + + * 'cdq' -- sign-extend dword in '%eax' to quad in '%edx:%eax', + + * 'cdqe' -- sign-extend dword in '%eax' to quad in '%rax' (x86-64 + only), + + * 'cqo' -- sign-extend quad in '%rax' to octuple in '%rdx:%rax' + (x86-64 only), + +are called 'cbtw', 'cwtl', 'cwtd', 'cltd', 'cltq', and 'cqto' in AT&T +naming. 'as' accepts either naming for these instructions. + + Far call/jump instructions are 'lcall' and 'ljmp' in AT&T syntax, but +are 'call far' and 'jump far' in Intel convention. + +9.4 Register Naming +=================== + +Register operands are always prefixed with '%'. The 80386 registers +consist of + + * the 8 32-bit registers '%eax' (the accumulator), '%ebx', '%ecx', + '%edx', '%edi', '%esi', '%ebp' (the frame pointer), and '%esp' (the + stack pointer). + + * the 8 16-bit low-ends of these: '%ax', '%bx', '%cx', '%dx', '%di', + '%si', '%bp', and '%sp'. + + * the 8 8-bit registers: '%ah', '%al', '%bh', '%bl', '%ch', '%cl', + '%dh', and '%dl' (These are the high-bytes and low-bytes of '%ax', + '%bx', '%cx', and '%dx') + + * the 6 section registers '%cs' (code section), '%ds' (data section), + '%ss' (stack section), '%es', '%fs', and '%gs'. + + * the 3 processor control registers '%cr0', '%cr2', and '%cr3'. + + * the 6 debug registers '%db0', '%db1', '%db2', '%db3', '%db6', and + '%db7'. + + * the 2 test registers '%tr6' and '%tr7'. + + * the 8 floating point register stack '%st' or equivalently '%st(0)', + '%st(1)', '%st(2)', '%st(3)', '%st(4)', '%st(5)', '%st(6)', and + '%st(7)'. These registers are overloaded by 8 MMX registers + '%mm0', '%mm1', '%mm2', '%mm3', '%mm4', '%mm5', '%mm6' and '%mm7'. + + * the 8 SSE registers registers '%xmm0', '%xmm1', '%xmm2', '%xmm3', + '%xmm4', '%xmm5', '%xmm6' and '%xmm7'. + + The AMD x86-64 architecture extends the register set by: + + * enhancing the 8 32-bit registers to 64-bit: '%rax' (the + accumulator), '%rbx', '%rcx', '%rdx', '%rdi', '%rsi', '%rbp' (the + frame pointer), '%rsp' (the stack pointer) + + * the 8 extended registers '%r8'-'%r15'. + + * the 8 32-bit low ends of the extended registers: '%r8d'-'%r15d' + + * the 8 16-bit low ends of the extended registers: '%r8w'-'%r15w' + + * the 8 8-bit low ends of the extended registers: '%r8b'-'%r15b' + + * the 4 8-bit registers: '%sil', '%dil', '%bpl', '%spl'. + + * the 8 debug registers: '%db8'-'%db15'. + + * the 8 SSE registers: '%xmm8'-'%xmm15'. + +9.5 Instruction Prefixes +======================== + +Instruction prefixes are used to modify the following instruction. They +are used to repeat string instructions, to provide section overrides, to +perform bus lock operations, and to change operand and address sizes. +(Most instructions that normally operate on 32-bit operands will use +16-bit operands if the instruction has an "operand size" prefix.) +Instruction prefixes are best written on the same line as the +instruction they act upon. For example, the 'scas' (scan string) +instruction is repeated with: + + repne scas %es:(%edi),%al + + You may also place prefixes on the lines immediately preceding the +instruction, but this circumvents checks that 'as' does with prefixes, +and will not work with all prefixes. + + Here is a list of instruction prefixes: + + * Section override prefixes 'cs', 'ds', 'ss', 'es', 'fs', 'gs'. + These are automatically added by specifying using the + SECTION:MEMORY-OPERAND form for memory references. + + * Operand/Address size prefixes 'data16' and 'addr16' change 32-bit + operands/addresses into 16-bit operands/addresses, while 'data32' + and 'addr32' change 16-bit ones (in a '.code16' section) into + 32-bit operands/addresses. These prefixes _must_ appear on the + same line of code as the instruction they modify. For example, in + a 16-bit '.code16' section, you might write: + + addr32 jmpl *(%ebx) + + * The bus lock prefix 'lock' inhibits interrupts during execution of + the instruction it precedes. (This is only valid with certain + instructions; see a 80386 manual for details). + + * The wait for coprocessor prefix 'wait' waits for the coprocessor to + complete the current instruction. This should never be needed for + the 80386/80387 combination. + + * The 'rep', 'repe', and 'repne' prefixes are added to string + instructions to make them repeat '%ecx' times ('%cx' times if the + current address size is 16-bits). + * The 'rex' family of prefixes is used by x86-64 to encode extensions + to i386 instruction set. The 'rex' prefix has four bits -- an + operand size overwrite ('64') used to change operand size from + 32-bit to 64-bit and X, Y and Z extensions bits used to extend the + register set. + + You may write the 'rex' prefixes directly. The 'rex64xyz' + instruction emits 'rex' prefix with all the bits set. By omitting + the '64', 'x', 'y' or 'z' you may write other prefixes as well. + Normally, there is no need to write the prefixes explicitly, since + gas will automatically generate them based on the instruction + operands. + +9.6 Memory References +===================== + +An Intel syntax indirect memory reference of the form + + SECTION:[BASE + INDEX*SCALE + DISP] + +is translated into the AT&T syntax + + SECTION:DISP(BASE, INDEX, SCALE) + +where BASE and INDEX are the optional 32-bit base and index registers, +DISP is the optional displacement, and SCALE, taking the values 1, 2, 4, +and 8, multiplies INDEX to calculate the address of the operand. If no +SCALE is specified, SCALE is taken to be 1. SECTION specifies the +optional section register for the memory operand, and may override the +default section register (see a 80386 manual for section register +defaults). Note that section overrides in AT&T syntax _must_ be +preceded by a '%'. If you specify a section override which coincides +with the default section register, 'as' does _not_ output any section +register override prefixes to assemble the given instruction. Thus, +section overrides can be specified to emphasize which section register +is used for a given memory operand. + + Here are some examples of Intel and AT&T style memory references: + +AT&T: '-4(%ebp)', Intel: '[ebp - 4]' + BASE is '%ebp'; DISP is '-4'. SECTION is missing, and the default + section is used ('%ss' for addressing with '%ebp' as the base + register). INDEX, SCALE are both missing. + +AT&T: 'foo(,%eax,4)', Intel: '[foo + eax*4]' + INDEX is '%eax' (scaled by a SCALE 4); DISP is 'foo'. All other + fields are missing. The section register here defaults to '%ds'. + +AT&T: 'foo(,1)'; Intel '[foo]' + This uses the value pointed to by 'foo' as a memory operand. Note + that BASE and INDEX are both missing, but there is only _one_ ','. + This is a syntactic exception. + +AT&T: '%gs:foo'; Intel 'gs:foo' + This selects the contents of the variable 'foo' with section + register SECTION being '%gs'. + + Absolute (as opposed to PC relative) call and jump operands must be +prefixed with '*'. If no '*' is specified, 'as' always chooses PC +relative addressing for jump/call labels. + + Any instruction that has a memory operand, but no register operand, +_must_ specify its size (byte, word, long, or quadruple) with an +instruction mnemonic suffix ('b', 'w', 'l' or 'q', respectively). + + The x86-64 architecture adds an RIP (instruction pointer relative) +addressing. This addressing mode is specified by using 'rip' as a base +register. Only constant offsets are valid. For example: + +AT&T: '1234(%rip)', Intel: '[rip + 1234]' + Points to the address 1234 bytes past the end of the current + instruction. + +AT&T: 'symbol(%rip)', Intel: '[rip + symbol]' + Points to the 'symbol' in RIP relative way, this is shorter than + the default absolute addressing. + + Other addressing modes remain unchanged in x86-64 architecture, +except registers used are 64-bit instead of 32-bit. + +9.7 Handling of Jump Instructions +================================= + +Jump instructions are always optimized to use the smallest possible +displacements. This is accomplished by using byte (8-bit) displacement +jumps whenever the target is sufficiently close. If a byte displacement +is insufficient a long displacement is used. We do not support word +(16-bit) displacement jumps in 32-bit mode (i.e. prefixing the jump +instruction with the 'data16' instruction prefix), since the 80386 +insists upon masking '%eip' to 16 bits after the word displacement is +added. (See also *note i386-Arch::) + + Note that the 'jcxz', 'jecxz', 'loop', 'loopz', 'loope', 'loopnz' and +'loopne' instructions only come in byte displacements, so that if you +use these instructions ('gcc' does not use them) you may get an error +message (and incorrect code). The AT&T 80386 assembler tries to get +around this problem by expanding 'jcxz foo' to + + jcxz cx_zero + jmp cx_nonzero + cx_zero: jmp foo + cx_nonzero: + +9.8 Floating Point +================== + +All 80387 floating point types except packed BCD are supported. (BCD +support may be added without much difficulty). These data types are +16-, 32-, and 64- bit integers, and single (32-bit), double (64-bit), +and extended (80-bit) precision floating point. Each supported type has +an instruction mnemonic suffix and a constructor associated with it. +Instruction mnemonic suffixes specify the operand's data type. +Constructors build these data types into memory. + + * Floating point constructors are '.float' or '.single', '.double', + and '.tfloat' for 32-, 64-, and 80-bit formats. These correspond + to instruction mnemonic suffixes 's', 'l', and 't'. 't' stands for + 80-bit (ten byte) real. The 80387 only supports this format via + the 'fldt' (load 80-bit real to stack top) and 'fstpt' (store + 80-bit real and pop stack) instructions. + + * Integer constructors are '.word', '.long' or '.int', and '.quad' + for the 16-, 32-, and 64-bit integer formats. The corresponding + instruction mnemonic suffixes are 's' (single), 'l' (long), and 'q' + (quad). As with the 80-bit real format, the 64-bit 'q' format is + only present in the 'fildq' (load quad integer to stack top) and + 'fistpq' (store quad integer and pop stack) instructions. + + Register to register operations should not use instruction mnemonic +suffixes. 'fstl %st, %st(1)' will give a warning, and be assembled as +if you wrote 'fst %st, %st(1)', since all register to register +operations use 80-bit floating point operands. (Contrast this with +'fstl %st, mem', which converts '%st' from 80-bit to 64-bit floating +point format, then stores the result in the 4 byte location 'mem') + +9.9 Intel's MMX and AMD's 3DNow! SIMD Operations +================================================ + +'as' supports Intel's MMX instruction set (SIMD instructions for integer +data), available on Intel's Pentium MMX processors and Pentium II +processors, AMD's K6 and K6-2 processors, Cyrix' M2 processor, and +probably others. It also supports AMD's 3DNow! instruction set (SIMD +instructions for 32-bit floating point data) available on AMD's K6-2 +processor and possibly others in the future. + + Currently, 'as' does not support Intel's floating point SIMD, Katmai +(KNI). + + The eight 64-bit MMX operands, also used by 3DNow!, are called +'%mm0', '%mm1', ... '%mm7'. They contain eight 8-bit integers, four +16-bit integers, two 32-bit integers, one 64-bit integer, or two 32-bit +floating point values. The MMX registers cannot be used at the same +time as the floating point stack. + + See Intel and AMD documentation, keeping in mind that the operand +order in instructions is reversed from the Intel syntax. + +9.10 Writing 16-bit Code +======================== + +While 'as' normally writes only "pure" 32-bit i386 code or 64-bit x86-64 +code depending on the default configuration, it also supports writing +code to run in real mode or in 16-bit protected mode code segments. To +do this, put a '.code16' or '.code16gcc' directive before the assembly +language instructions to be run in 16-bit mode. You can switch 'as' +back to writing normal 32-bit code with the '.code32' directive. + + '.code16gcc' provides experimental support for generating 16-bit code +from gcc, and differs from '.code16' in that 'call', 'ret', 'enter', +'leave', 'push', 'pop', 'pusha', 'popa', 'pushf', and 'popf' +instructions default to 32-bit size. This is so that the stack pointer +is manipulated in the same way over function calls, allowing access to +function parameters at the same stack offsets as in 32-bit mode. +'.code16gcc' also automatically adds address size prefixes where +necessary to use the 32-bit addressing modes that gcc generates. + + The code which 'as' generates in 16-bit mode will not necessarily run +on a 16-bit pre-80386 processor. To write code that runs on such a +processor, you must refrain from using _any_ 32-bit constructs which +require 'as' to output address or operand size prefixes. + + Note that writing 16-bit code instructions by explicitly specifying a +prefix or an instruction mnemonic suffix within a 32-bit code section +generates different machine instructions than those generated for a +16-bit code segment. In a 32-bit code section, the following code +generates the machine opcode bytes '66 6a 04', which pushes the value +'4' onto the stack, decrementing '%esp' by 2. + + pushw $4 + + The same code in a 16-bit code section would generate the machine +opcode bytes '6a 04' (i.e., without the operand size prefix), which is +correct since the processor default operand size is assumed to be 16 +bits in a 16-bit code section. + +9.11 AT&T Syntax bugs +===================== + +The UnixWare assembler, and probably other AT&T derived ix86 Unix +assemblers, generate floating point instructions with reversed source +and destination registers in certain cases. Unfortunately, gcc and +possibly many other programs use this reversed syntax, so we're stuck +with it. + + For example + + fsub %st,%st(3) +results in '%st(3)' being updated to '%st - %st(3)' rather than the +expected '%st(3) - %st'. This happens with all the non-commutative +arithmetic floating point operations with two register operands where +the source register is '%st' and the destination register is '%st(i)'. + +9.12 Specifying CPU Architecture +================================ + +'as' may be told to assemble for a particular CPU (sub-)architecture +with the '.arch CPU_TYPE' directive. This directive enables a warning +when gas detects an instruction that is not supported on the CPU +specified. The choices for CPU_TYPE are: + +'i8086' 'i186' 'i286' 'i386' +'i486' 'i586' 'i686' 'pentium' +'pentiumpro' 'pentiumii' 'pentiumiii' 'pentium4' +'prescott' 'nocona' 'core' 'core2' +'amdfam10' +'k6' 'athlon' 'sledgehammer' 'k8' +'.mmx' '.sse' '.sse2' '.sse3' +'.ssse3' '.sse4.1' '.sse4.2' '.sse4' +'.sse4a' '.3dnow' '.3dnowa' '.padlock' +'.pacifica' '.svme' '.abm' + + Apart from the warning, there are only two other effects on 'as' +operation; Firstly, if you specify a CPU other than 'i486', then shift +by one instructions such as 'sarl $1, %eax' will automatically use a two +byte opcode sequence. The larger three byte opcode sequence is used on +the 486 (and when no architecture is specified) because it executes +faster on the 486. Note that you can explicitly request the two byte +opcode by writing 'sarl %eax'. Secondly, if you specify 'i8086', +'i186', or 'i286', _and_ '.code16' or '.code16gcc' then byte offset +conditional jumps will be promoted when necessary to a two instruction +sequence consisting of a conditional jump of the opposite sense around +an unconditional jump to the target. + + Following the CPU architecture (but not a sub-architecture, which are +those starting with a dot), you may specify 'jumps' or 'nojumps' to +control automatic promotion of conditional jumps. 'jumps' is the +default, and enables jump promotion; All external jumps will be of the +long variety, and file-local jumps will be promoted as necessary. +(*note i386-Jumps::) 'nojumps' leaves external conditional jumps as byte +offset jumps, and warns about file-local conditional jumps that 'as' +promotes. Unconditional jumps are treated as for 'jumps'. + + For example + + .arch i8086,nojumps + +9.13 Notes +========== + +There is some trickery concerning the 'mul' and 'imul' instructions that +deserves mention. The 16-, 32-, 64- and 128-bit expanding multiplies +(base opcode '0xf6'; extension 4 for 'mul' and 5 for 'imul') can be +output only in the one operand form. Thus, 'imul %ebx, %eax' does _not_ +select the expanding multiply; the expanding multiply would clobber the +'%edx' register, and this would confuse 'gcc' output. Use 'imul %ebx' +to get the 64-bit product in '%edx:%eax'. + + We have added a two operand form of 'imul' when the first operand is +an immediate mode expression and the second operand is a register. This +is just a shorthand, so that, multiplying '%eax' by 69, for example, can +be done with 'imul $69, %eax' rather than 'imul $69, %eax, %eax'. + +10 IA-64 Dependent Features +*************************** + +10.1 Options +============ + +'-mconstant-gp' + This option instructs the assembler to mark the resulting object + file as using the "constant GP" model. With this model, it is + assumed that the entire program uses a single global pointer (GP) + value. Note that this option does not in any fashion affect the + machine code emitted by the assembler. All it does is turn on the + EF_IA_64_CONS_GP flag in the ELF file header. + +'-mauto-pic' + This option instructs the assembler to mark the resulting object + file as using the "constant GP without function descriptor" data + model. This model is like the "constant GP" model, except that it + additionally does away with function descriptors. What this means + is that the address of a function refers directly to the function's + code entry-point. Normally, such an address would refer to a + function descriptor, which contains both the code entry-point and + the GP-value needed by the function. Note that this option does + not in any fashion affect the machine code emitted by the + assembler. All it does is turn on the EF_IA_64_NOFUNCDESC_CONS_GP + flag in the ELF file header. + +'-milp32' +'-milp64' +'-mlp64' +'-mp64' + These options select the data model. The assembler defaults to + '-mlp64' (LP64 data model). + +'-mle' +'-mbe' + These options select the byte order. The '-mle' option selects + little-endian byte order (default) and '-mbe' selects big-endian + byte order. Note that IA-64 machine code always uses little-endian + byte order. + +'-mtune=itanium1' +'-mtune=itanium2' + Tune for a particular IA-64 CPU, ITANIUM1 or ITANIUM2. The default + is ITANIUM2. + +'-munwind-check=warning' +'-munwind-check=error' + These options control what the assembler will do when performing + consistency checks on unwind directives. '-munwind-check=warning' + will make the assembler issue a warning when an unwind directive + check fails. This is the default. '-munwind-check=error' will + make the assembler issue an error when an unwind directive check + fails. + +'-mhint.b=ok' +'-mhint.b=warning' +'-mhint.b=error' + These options control what the assembler will do when the 'hint.b' + instruction is used. '-mhint.b=ok' will make the assembler accept + 'hint.b'. '-mint.b=warning' will make the assembler issue a + warning when 'hint.b' is used. '-mhint.b=error' will make the + assembler treat 'hint.b' as an error, which is the default. + +'-x' +'-xexplicit' + These options turn on dependency violation checking. + +'-xauto' + This option instructs the assembler to automatically insert stop + bits where necessary to remove dependency violations. This is the + default mode. + +'-xnone' + This option turns off dependency violation checking. + +'-xdebug' + This turns on debug output intended to help tracking down bugs in + the dependency violation checker. + +'-xdebugn' + This is a shortcut for -xnone -xdebug. + +'-xdebugx' + This is a shortcut for -xexplicit -xdebug. + +10.2 Syntax +=========== + +The assembler syntax closely follows the IA-64 Assembly Language +Reference Guide. + +10.2.1 Special Characters +------------------------- + +'//' is the line comment token. + + ';' can be used instead of a newline to separate statements. + +10.2.2 Register Names +--------------------- + +The 128 integer registers are referred to as 'rN'. The 128 +floating-point registers are referred to as 'fN'. The 128 application +registers are referred to as 'arN'. The 128 control registers are +referred to as 'crN'. The 64 one-bit predicate registers are referred +to as 'pN'. The 8 branch registers are referred to as 'bN'. In +addition, the assembler defines a number of aliases: 'gp' ('r1'), 'sp' +('r12'), 'rp' ('b0'), 'ret0' ('r8'), 'ret1' ('r9'), 'ret2' ('r10'), +'ret3' ('r9'), 'fargN' ('f8+N'), and 'fretN' ('f8+N'). + + For convenience, the assembler also defines aliases for all named +application and control registers. For example, 'ar.bsp' refers to the +register backing store pointer ('ar17'). Similarly, 'cr.eoi' refers to +the end-of-interrupt register ('cr67'). + +10.2.3 IA-64 Processor-Status-Register (PSR) Bit Names +------------------------------------------------------ + +The assembler defines bit masks for each of the bits in the IA-64 +processor status register. For example, 'psr.ic' corresponds to a value +of 0x2000. These masks are primarily intended for use with the +'ssm'/'sum' and 'rsm'/'rum' instructions, but they can be used anywhere +else where an integer constant is expected. + +10.3 Opcodes +============ + +For detailed information on the IA-64 machine instruction set, see the +IA-64 Architecture Handbook +(http://developer.intel.com/design/itanium/arch_spec.htm). + +11 MIPS Dependent Features +************************** + +GNU 'as' for MIPS architectures supports several different MIPS +processors, and MIPS ISA levels I through V, MIPS32, and MIPS64. For +information about the MIPS instruction set, see 'MIPS RISC +Architecture', by Kane and Heindrich (Prentice-Hall). For an overview +of MIPS assembly conventions, see "Appendix D: Assembly Language +Programming" in the same work. + +11.1 Assembler options +====================== + +The MIPS configurations of GNU 'as' support these special options: + +'-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. The default value is 8. + +'-EB' +'-EL' + Any MIPS configuration of 'as' can select big-endian or + little-endian output at run time (unlike the other GNU development + tools, which must be configured for one or the other). Use '-EB' + to select big-endian output, and '-EL' for little-endian. + +'-KPIC' + Generate SVR4-style PIC. This option tells the assembler to + generate SVR4-style position-independent macro expansions. It also + tells the assembler to mark the output file as PIC. + +'-mvxworks-pic' + Generate VxWorks PIC. This option tells the assembler to generate + VxWorks-style position-independent macro expansions. + +'-mips1' +'-mips2' +'-mips3' +'-mips4' +'-mips5' +'-mips32' +'-mips32r2' +'-mips64' +'-mips64r2' + Generate code for a particular MIPS Instruction Set Architecture + level. '-mips1' corresponds to the R2000 and R3000 processors, + '-mips2' to the R6000 processor, '-mips3' to the R4000 processor, + and '-mips4' to the R8000 and R10000 processors. '-mips5', + '-mips32', '-mips32r2', '-mips64', and '-mips64r2' correspond to + generic MIPS V, MIPS32, MIPS32 RELEASE 2, MIPS64, and MIPS64 + RELEASE 2 ISA processors, respectively. You can also switch + instruction sets during the assembly; see *note Directives to + override the ISA level: MIPS ISA. + +'-mgp32' +'-mfp32' + Some macros have different expansions for 32-bit and 64-bit + registers. 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. + + The '.set gp=32' and '.set fp=32' directives allow the size of + registers to be changed for parts of an object. The default value + is restored by '.set gp=default' and '.set fp=default'. + + On some MIPS variants there is a 32-bit mode flag; when this flag + is set, 64-bit instructions generate a trap. Also, some 32-bit + OSes only save the 32-bit registers on a context switch, so it is + essential never to use the 64-bit registers. + +'-mgp64' +'-mfp64' + Assume that 64-bit registers are available. This is provided in + the interests of symmetry with '-mgp32' and '-mfp32'. + + The '.set gp=64' and '.set fp=64' directives allow the size of + registers to be changed for parts of an object. The default value + is restored by '.set gp=default' and '.set fp=default'. + +'-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 extensions to the MIPS32 instruction set, + which provides a number of new instructions which target smartcard + and cryptographic applications. 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. + +'-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. + +'-mfix-vr4120' +'-no-mfix-vr4120' + Insert nops to work around certain VR4120 errata. This option is + intended to be used on GCC-generated code: it is not designed to + catch all problems in hand-written assembler code. + +'-mfix-vr4130' +'-no-mfix-vr4130' + Insert nops to work around the VR4130 'mflo'/'mfhi' errata. + +'-m4010' +'-no-m4010' + Generate code for the LSI R4010 chip. This tells the assembler to + accept the R4010 specific instructions ('addciu', 'ffc', etc.), and + to not schedule 'nop' instructions around accesses to the 'HI' and + 'LO' registers. '-no-m4010' turns off this option. + +'-m4650' +'-no-m4650' + Generate code for the MIPS R4650 chip. This tells the assembler to + accept the 'mad' and 'madu' instruction, and to not schedule 'nop' + instructions around accesses to the 'HI' and 'LO' registers. + '-no-m4650' turns off this option. + +'-m3900' +'-no-m3900' +'-m4100' +'-no-m4100' + For each option '-mNNNN', generate code for the MIPS RNNNN chip. + This tells the assembler to accept instructions specific to that + chip, and to schedule for that chip's hazards. + +'-march=CPU' + Generate code for a particular MIPS cpu. It is exactly equivalent + to '-mCPU', except that there are more value of CPU understood. + Valid CPU value are: + + 2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, + vr4181, 4300, 4400, 4600, 4650, 5000, rm5200, rm5230, rm5231, + rm5261, rm5721, vr5400, vr5500, 6000, rm7000, 8000, rm9000, + 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem, 4kep, 4ksd, + m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf, + 34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a + +'-mtune=CPU' + Schedule and tune for a particular MIPS cpu. Valid CPU values are + identical to '-march=CPU'. + +'-mabi=ABI' + Record which ABI the source code uses. The recognized arguments + are: '32', 'n32', 'o64', '64' and 'eabi'. + +'-msym32' +'-mno-sym32' + Equivalent to adding '.set sym32' or '.set nosym32' to the + beginning of the assembler input. *Note MIPS symbol sizes::. + +'-nocpp' + This option is ignored. It is accepted for command-line + compatibility with other assemblers, which use it to turn off C + style preprocessing. With GNU 'as', there is no need for '-nocpp', + because the GNU assembler itself never runs the C preprocessor. + +'--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. This feature is useful if the + processor support the FR bit in its status register, and this bit + is known (by the programmer) to be set. This bit prevents the + aliasing of the double width register by the single width + registers. + + By default '--construct-floats' is selected, allowing construction + of these floating point constants. + +'--trap' +'--no-break' + 'as' automatically macro expands certain division and + multiplication instructions to check for overflow and division by + zero. This option causes 'as' to generate code to take a trap + exception rather than a break exception when an error is detected. + The trap instructions are only supported at Instruction Set + Architecture level 2 and higher. + +'--break' +'--no-trap' + Generate code to take a break exception rather than a trap + exception when an error is detected. This is the default. + +'-mpdr' +'-mno-pdr' + Control generation of '.pdr' sections. Off by default on IRIX, on + elsewhere. + +'-mshared' +'-mno-shared' + When generating code using the Unix calling conventions (selected + by '-KPIC' or '-mcall_shared'), gas will normally generate code + which can go into a shared library. The '-mno-shared' option tells + gas to generate code which uses the calling convention, but can not + go into a shared library. The resulting code is slightly more + efficient. This option only affects the handling of the '.cpload' + and '.cpsetup' pseudo-ops. + +11.2 MIPS ECOFF object code +=========================== + +Assembling for a MIPS ECOFF target supports some additional sections +besides the usual '.text', '.data' and '.bss'. The additional sections +are '.rdata', used for read-only data, '.sdata', used for small data, +and '.sbss', used for small common objects. + + When assembling for ECOFF, the assembler uses the '$gp' ('$28') +register to form the address of a "small object". Any object in the +'.sdata' or '.sbss' sections is considered "small" in this sense. For +external objects, or for objects in the '.bss' section, you can use the +'gcc' '-G' option to control the size of objects addressed via '$gp'; +the default value is 8, meaning that a reference to any object eight +bytes or smaller uses '$gp'. Passing '-G 0' to 'as' prevents it from +using the '$gp' register on the basis of object size (but the assembler +uses '$gp' for objects in '.sdata' or 'sbss' in any case). The size of +an object in the '.bss' section is set by the '.comm' or '.lcomm' +directive that defines it. The size of an external object may be set +with the '.extern' directive. For example, '.extern sym,4' declares +that the object at 'sym' is 4 bytes in length, whie leaving 'sym' +otherwise undefined. + + Using small ECOFF objects requires linker support, and assumes that +the '$gp' register is correctly initialized (normally done automatically +by the startup code). MIPS ECOFF assembly code must not modify the +'$gp' register. + +11.3 Directives for debugging information +========================================= + +MIPS ECOFF 'as' supports several directives used for generating +debugging information which are not support by traditional MIPS +assemblers. These are '.def', '.endef', '.dim', '.file', '.scl', +'.size', '.tag', '.type', '.val', '.stabd', '.stabn', and '.stabs'. The +debugging information generated by the three '.stab' directives can only +be read by GDB, not by traditional MIPS debuggers (this enhancement is +required to fully support C++ debugging). These directives are +primarily used by compilers, not assembly language programmers! + +11.4 Directives to override the size of symbols +=============================================== + +The n64 ABI allows symbols to have any 64-bit value. Although this +provides a great deal of flexibility, it means that some macros have +much longer expansions than their 32-bit counterparts. For example, the +non-PIC expansion of 'dla $4,sym' is usually: + + lui $4,%highest(sym) + lui $1,%hi(sym) + daddiu $4,$4,%higher(sym) + daddiu $1,$1,%lo(sym) + dsll32 $4,$4,0 + daddu $4,$4,$1 + + whereas the 32-bit expansion is simply: + + lui $4,%hi(sym) + daddiu $4,$4,%lo(sym) + + n64 code is sometimes constructed in such a way that all symbolic +constants are known to have 32-bit values, and in such cases, it's +preferable to use the 32-bit expansion instead of the 64-bit expansion. + + You can use the '.set sym32' directive to tell the assembler that, +from this point on, all expressions of the form 'SYMBOL' or 'SYMBOL + +OFFSET' have 32-bit values. For example: + + .set sym32 + dla $4,sym + lw $4,sym+16 + sw $4,sym+0x8000($4) + + will cause the assembler to treat 'sym', 'sym+16' and 'sym+0x8000' as +32-bit values. The handling of non-symbolic addresses is not affected. + + The directive '.set nosym32' ends a '.set sym32' block and reverts to +the normal behavior. It is also possible to change the symbol size +using the command-line options '-msym32' and '-mno-sym32'. + + These options and directives are always accepted, but at present, +they have no effect for anything other than n64. + +11.5 Directives to override the ISA level +========================================= + +GNU 'as' supports an additional directive to change the MIPS Instruction +Set Architecture level on the fly: '.set mipsN'. N should be a number +from 0 to 5, or 32, 32r2, 64 or 64r2. The values other than 0 make the +assembler accept instructions for the corresponding ISA level, from that +point on in the assembly. '.set mipsN' affects not only which +instructions are permitted, but also how certain macros are expanded. +'.set mips0' restores the ISA level to its original level: either the +level you selected with command line options, or the default for your +configuration. You can use this feature to permit specific MIPS3 +instructions while assembling in 32 bit mode. Use this directive with +care! + + The '.set arch=CPU' directive provides even finer control. It +changes the effective CPU target and allows the assembler to use +instructions specific to a particular CPU. All CPUs supported by the +'-march' command line option are also selectable by this directive. The +original value is restored by '.set arch=default'. + + The directive '.set mips16' puts the assembler into MIPS 16 mode, in +which it will assemble instructions for the MIPS 16 processor. Use +'.set nomips16' to return to normal 32 bit mode. + + Traditional MIPS assemblers do not support this directive. + +11.6 Directives for extending MIPS 16 bit instructions +====================================================== + +By default, MIPS 16 instructions are automatically extended to 32 bits +when necessary. The directive '.set noautoextend' will turn this off. +When '.set noautoextend' is in effect, any 32 bit instruction must be +explicitly extended with the '.e' modifier (e.g., 'li.e $4,1000'). The +directive '.set autoextend' may be used to once again automatically +extend instructions when necessary. + + This directive is only meaningful when in MIPS 16 mode. Traditional +MIPS assemblers do not support this directive. + +11.7 Directive to mark data as an instruction +============================================= + +The '.insn' directive tells 'as' that the following data is actually +instructions. This makes a difference in MIPS 16 mode: when loading the +address of a label which precedes instructions, 'as' automatically adds +1 to the value, so that jumping to the loaded address will do the right +thing. + +11.8 Directives to save and restore options +=========================================== + +The directives '.set push' and '.set pop' may be used to save and +restore the current settings for all the options which are controlled by +'.set'. The '.set push' directive saves the current settings on a +stack. The '.set pop' directive pops the stack and restores the +settings. + + These directives can be useful inside an macro which must change an +option such as the ISA level or instruction reordering but does not want +to change the state of the code which invoked the macro. + + Traditional MIPS assemblers do not support these directives. + +11.9 Directives to control generation of MIPS ASE instructions +============================================================== + +The directive '.set mips3d' makes the assembler accept instructions from +the MIPS-3D Application Specific Extension from that point on in the +assembly. The '.set nomips3d' directive prevents MIPS-3D instructions +from being accepted. + + The directive '.set smartmips' makes the assembler accept +instructions from the SmartMIPS Application Specific Extension to the +MIPS32 ISA from that point on in the assembly. The '.set nosmartmips' +directive prevents SmartMIPS instructions from being accepted. + + The directive '.set mdmx' makes the assembler accept instructions +from the MDMX Application Specific Extension from that point on in the +assembly. The '.set nomdmx' directive prevents MDMX instructions from +being accepted. + + The directive '.set dsp' makes the assembler accept instructions from +the DSP Release 1 Application Specific Extension from that point on in +the assembly. The '.set nodsp' directive prevents DSP Release 1 +instructions from being accepted. + + The directive '.set dspr2' makes the assembler accept instructions +from the DSP Release 2 Application Specific Extension from that point on +in the assembly. This dirctive implies '.set dsp'. The '.set nodspr2' +directive prevents DSP Release 2 instructions from being accepted. + + The directive '.set mt' makes the assembler accept instructions from +the MT Application Specific Extension from that point on in the +assembly. The '.set nomt' directive prevents MT instructions from being +accepted. + + Traditional MIPS assemblers do not support these directives. + +12 PowerPC Dependent Features +***************************** + +12.1 Options +============ + +The PowerPC chip family includes several successive levels, using the +same core instruction set, but including a few additional instructions +at each level. There are exceptions to this however. For details on +what instructions each variant supports, please see the chip's +architecture reference manual. + + The following table lists all available PowerPC options. + +'-mpwrx | -mpwr2' + Generate code for POWER/2 (RIOS2). + +'-mpwr' + Generate code for POWER (RIOS1) + +'-m601' + Generate code for PowerPC 601. + +'-mppc, -mppc32, -m603, -m604' + Generate code for PowerPC 603/604. + +'-m403, -m405' + Generate code for PowerPC 403/405. + +'-m440' + Generate code for PowerPC 440. BookE and some 405 instructions. + +'-m7400, -m7410, -m7450, -m7455' + Generate code for PowerPC 7400/7410/7450/7455. + +'-mppc64, -m620' + Generate code for PowerPC 620/625/630. + +'-me500, -me500x2' + Generate code for Motorola e500 core complex. + +'-mspe' + Generate code for Motorola SPE instructions. + +'-mppc64bridge' + Generate code for PowerPC 64, including bridge insns. + +'-mbooke64' + Generate code for 64-bit BookE. + +'-mbooke, mbooke32' + Generate code for 32-bit BookE. + +'-me300' + Generate code for PowerPC e300 family. + +'-maltivec' + Generate code for processors with AltiVec instructions. + +'-mpower4' + Generate code for Power4 architecture. + +'-mpower5' + Generate code for Power5 architecture. + +'-mpower6' + Generate code for Power6 architecture. + +'-mcell' + Generate code for Cell Broadband Engine architecture. + +'-mcom' + Generate code Power/PowerPC common instructions. + +'-many' + Generate code for any architecture (PWR/PWRX/PPC). + +'-mregnames' + Allow symbolic names for registers. + +'-mno-regnames' + Do not allow symbolic names for registers. + +'-mrelocatable' + Support for GCC's -mrelocatable option. + +'-mrelocatable-lib' + Support for GCC's -mrelocatable-lib option. + +'-memb' + Set PPC_EMB bit in ELF flags. + +'-mlittle, -mlittle-endian' + Generate code for a little endian machine. + +'-mbig, -mbig-endian' + Generate code for a big endian machine. + +'-msolaris' + Generate code for Solaris. + +'-mno-solaris' + Do not generate code for Solaris. + +12.2 PowerPC Assembler Directives +================================= + +A number of assembler directives are available for PowerPC. The +following table is far from complete. + +'.machine "string"' + This directive allows you to change the machine for which code is + generated. '"string"' may be any of the -m cpu selection options + (without the -m) enclosed in double quotes, '"push"', or '"pop"'. + '.machine "push"' saves the currently selected cpu, which may be + restored with '.machine "pop"'. + +13 SPARC Dependent Features +*************************** + +13.1 Options +============ + +The SPARC chip family includes several successive levels, using the same +core instruction set, but including a few additional instructions at +each level. There are exceptions to this however. For details on what +instructions each variant supports, please see the chip's architecture +reference manual. + + By default, 'as' assumes the core instruction set (SPARC v6), but +"bumps" the architecture level as needed: it switches to successively +higher architectures as it encounters instructions that only exist in +the higher levels. + + If not configured for SPARC v9 ('sparc64-*-*') GAS will not bump +passed sparclite by default, an option must be passed to enable the v9 +instructions. + + GAS treats sparclite as being compatible with v8, unless an +architecture is explicitly requested. SPARC v9 is always incompatible +with sparclite. + +'-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite' +'-Av8plus | -Av8plusa | -Av9 | -Av9a' + Use one of the '-A' options to select one of the SPARC + architectures explicitly. If you select an architecture + explicitly, 'as' reports a fatal error if it encounters an + instruction or feature requiring an incompatible or higher level. + + '-Av8plus' and '-Av8plusa' select a 32 bit environment. + + '-Av9' and '-Av9a' select a 64 bit environment and are not + available unless GAS is explicitly configured with 64 bit + environment support. + + '-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 whenever it is necessary to switch to another level. If an + architecture level is explicitly requested, GAS will not issue + warnings until that level is reached, and will then bump the level + as required (except between incompatible levels). + +'-32 | -64' + Select the word size, either 32 bits or 64 bits. These options are + only available with the ELF object file format, and require that + the necessary BFD support has been included. + +13.2 Enforcing aligned data +=========================== + +SPARC GAS normally permits data to be misaligned. For example, it +permits the '.long' pseudo-op to be used on a byte boundary. However, +the native SunOS and Solaris assemblers issue an error when they see +misaligned data. + + You can use the '--enforce-aligned-data' option to make SPARC GAS +also issue an error about misaligned data, just as the SunOS and Solaris +assemblers do. + + The '--enforce-aligned-data' option is not the default because gcc +issues misaligned data pseudo-ops when it initializes certain packed +data structures (structures defined using the 'packed' attribute). You +may have to assemble with GAS in order to initialize packed data +structures in your own code. + +13.3 Floating Point +=================== + +The Sparc uses IEEE floating-point numbers. + +13.4 Sparc Machine Directives +============================= + +The Sparc version of 'as' supports the following additional machine +directives: + +'.align' + This must be followed by the desired alignment in bytes. + +'.common' + This must be followed by a symbol name, a positive number, and + '"bss"'. This behaves somewhat like '.comm', but the syntax is + different. + +'.half' + This is functionally identical to '.short'. + +'.nword' + On the Sparc, the '.nword' directive produces native word sized + value, ie. if assembling with -32 it is equivalent to '.word', if + assembling with -64 it is equivalent to '.xword'. + +'.proc' + This directive is ignored. Any text following it on the same line + is also ignored. + +'.register' + This directive declares use of a global application or system + register. It must be followed by a register name %g2, %g3, %g6 or + %g7, comma and the symbol name for that register. If symbol name + is '#scratch', it is a scratch register, if it is '#ignore', it + just suppresses any errors about using undeclared global register, + but does not emit any information about it into the object file. + This can be useful e.g. if you save the register before use and + restore it after. + +'.reserve' + This must be followed by a symbol name, a positive number, and + '"bss"'. This behaves somewhat like '.lcomm', but the syntax is + different. + +'.seg' + This must be followed by '"text"', '"data"', or '"data1"'. It + behaves like '.text', '.data', or '.data 1'. + +'.skip' + This is functionally identical to the '.space' directive. + +'.word' + On the Sparc, the '.word' directive produces 32 bit values, instead + of the 16 bit values it produces on many other machines. + +'.xword' + On the Sparc V9 processor, the '.xword' directive produces 64 bit + values. + +14 Reporting Bugs +***************** + +Your bug reports play an essential role in making 'as' reliable. + + Reporting a bug may help you by bringing a solution to your problem, +or it may not. But in any case the principal function of a bug report +is to help the entire community by making the next version of 'as' work +better. Bug reports are your contribution to the maintenance of 'as'. + + In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. + +14.1 Have You Found a Bug? +========================== + +If you are not sure whether you have found a bug, here are some +guidelines: + + * If the assembler gets a fatal signal, for any input whatever, that + is a 'as' bug. Reliable assemblers never crash. + + * If 'as' produces an error message for valid input, that is a bug. + + * If 'as' does not produce an error message for invalid input, that + is a bug. However, you should note that your idea of "invalid + input" might be our idea of "an extension" or "support for + traditional practice". + + * If you are an experienced user of assemblers, your suggestions for + improvement of 'as' are welcome in any case. + +14.2 How to Report Bugs +======================= + +A number of companies and individuals offer support for GNU products. +If you obtained 'as' from a support organization, we recommend you +contact that organization first. + + You can find contact information for many support companies and +individuals in the file 'etc/SERVICE' in the GNU Emacs distribution. + + The fundamental principle of reporting bugs usefully is this: *report +all the facts*. If you are not sure whether to state a fact or leave it +out, state it! + + Often people omit facts because they think they know what causes the +problem and assume that some details do not matter. Thus, you might +assume that the name of a symbol you use in an example does not matter. +Well, probably it does not, but one cannot be sure. Perhaps the bug is +a stray memory reference which happens to fetch from the location where +that name is stored in memory; perhaps, if the name were different, the +contents of that location would fool the assembler into doing the right +thing despite the bug. Play it safe and give a specific, complete +example. That is the easiest thing for you to do, and the most helpful. + + Keep in mind that the purpose of a bug report is to enable us to fix +the bug if it is new to us. Therefore, always write your bug reports on +the assumption that the bug has not been reported previously. + + Sometimes people give a few sketchy facts and ask, "Does this ring a +bell?" This cannot help us fix a bug, so it is basically useless. We +respond by asking for enough details to enable us to investigate. You +might as well expedite matters by sending them to begin with. + + To enable us to fix the bug, you should include all these things: + + * The version of 'as'. 'as' announces it if you start it with the + '--version' argument. + + Without this, we will not know whether there is any point in + looking for the bug in the current version of 'as'. + + * Any patches you may have applied to the 'as' source. + + * The type of machine you are using, and the operating system name + and version number. + + * What compiler (and its version) was used to compile 'as'--e.g. + "'gcc-2.7'". + + * The command arguments you gave the assembler to assemble your + example and observe the bug. To guarantee you will not omit + something important, list them all. A copy of the Makefile (or the + output from make) is sufficient. + + If we were to try to guess the arguments, we would probably guess + wrong and then we might not encounter the bug. + + * A complete input file that will reproduce the bug. If the bug is + observed when the assembler is invoked via a compiler, send the + assembler source, not the high level language source. Most + compilers will produce the assembler source when run with the '-S' + option. If you are using 'gcc', use the options '-v --save-temps'; + this will save the assembler source in a file with an extension of + '.s', and also show you exactly how 'as' is being run. + + * A description of what behavior you observe that you believe is + incorrect. For example, "It gets a fatal signal." + + Of course, if the bug is that 'as' gets a fatal signal, then we + will certainly notice it. But if the bug is incorrect output, we + might not notice unless it is glaringly wrong. You might as well + not give us a chance to make a mistake. + + Even if the problem you experience is a fatal signal, you should + still say so explicitly. Suppose something strange is going on, + such as, your copy of 'as' is out of sync, or you have encountered + a bug in the C library on your system. (This has happened!) Your + copy might crash and ours would not. If you told us to expect a + crash, then when ours fails to crash, we would know that the bug + was not happening for us. If you had not told us to expect a + crash, then we would not be able to draw any conclusion from our + observations. + + * If you wish to suggest changes to the 'as' source, send us context + diffs, as generated by 'diff' with the '-u', '-c', or '-p' option. + Always send diffs from the old file to the new file. If you even + discuss something in the 'as' source, refer to it by context, not + by line number. + + The line numbers in our development sources will not match those in + your sources. Your line numbers would convey no useful information + to us. + + Here are some things that are not necessary: + + * A description of the envelope of the bug. + + Often people who encounter a bug spend a lot of time investigating + which changes to the input file will make the bug go away and which + changes will not affect it. + + This is often time consuming and not very useful, because the way + we will find the bug is by running a single example under the + debugger with breakpoints, not by pure deduction from a series of + examples. We recommend that you save your time for something else. + + Of course, if you can find a simpler example to report _instead_ of + the original one, that is a convenience for us. Errors in the + output will be easier to spot, running under the debugger will take + less time, and so on. + + However, simplification is not vital; if you do not want to do + this, report the bug anyway and send us the entire test case you + used. + + * A patch for the bug. + + A patch for the bug does help us if it is a good one. But do not + omit the necessary information, such as the test case, on the + assumption that a patch is all we need. We might see problems with + your patch and decide to fix the problem another way, or we might + not understand it at all. + + Sometimes with a program as complicated as 'as' it is very hard to + construct an example that will make the program follow a certain + path through the code. If you do not send us the example, we will + not be able to construct one, so we will not be able to verify that + the bug is fixed. + + And if we cannot understand what bug you are trying to fix, or why + your patch should be an improvement, we will not install it. A + test case will help us to understand. + + * A guess about what the bug is or what it depends on. + + Such guesses are usually wrong. Even we cannot guess right about + such things without first using the debugger to find the facts. + +15 Acknowledgements +******************* + +If you have contributed to GAS and your name isn't listed here, it is +not meant as a slight. We just don't know about it. Send mail to the +maintainer, and we'll correct the situation. Currently the maintainer +is Ken Raeburn (email address 'raeburn@cygnus.com'). + + Dean Elsner wrote the original GNU assembler for the VAX.(1) + + Jay Fenlason maintained GAS for a while, adding support for +GDB-specific debug information and the 68k series machines, most of the +preprocessing pass, and extensive changes in 'messages.c', +'input-file.c', 'write.c'. + + K. Richard Pixley maintained GAS for a while, adding various +enhancements and many bug fixes, including merging support for several +processors, breaking GAS up to handle multiple object file format back +ends (including heavy rewrite, testing, an integration of the coff and +b.out back ends), adding configuration including heavy testing and +verification of cross assemblers and file splits and renaming, converted +GAS to strictly ANSI C including full prototypes, added support for +m680[34]0 and cpu32, did considerable work on i960 including a COFF port +(including considerable amounts of reverse engineering), a SPARC opcode +file rewrite, DECstation, rs6000, and hp300hpux host ports, updated +"know" assertions and made them work, much other reorganization, +cleanup, and lint. + + Ken Raeburn wrote the high-level BFD interface code to replace most +of the code in format-specific I/O modules. + + The original VMS support was contributed by David L. Kashtan. Eric +Youngdale has done much work with it since. + + The Intel 80386 machine description was written by Eliot Dresselhaus. + + Minh Tran-Le at IntelliCorp contributed some AIX 386 support. + + The Motorola 88k machine description was contributed by Devon Bowen +of Buffalo University and Torbjorn Granlund of the Swedish Institute of +Computer Science. + + Keith Knowles at the Open Software Foundation wrote the original MIPS +back end ('tc-mips.c', 'tc-mips.h'), and contributed Rose format support +(which hasn't been merged in yet). Ralph Campbell worked with the MIPS +code to support a.out format. + + Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, +tc-h8300), and IEEE 695 object file format (obj-ieee), was written by +Steve Chamberlain of Cygnus Support. Steve also modified the COFF back +end to use BFD for some low-level operations, for use with the H8/300 +and AMD 29k targets. + + John Gilmore built the AMD 29000 support, added '.include' support, +and simplified the configuration of which versions accept which +directives. He updated the 68k machine description so that Motorola's +opcodes always produced fixed-size instructions (e.g., 'jsr'), while +synthetic instructions remained shrinkable ('jbsr'). John fixed many +bugs, including true tested cross-compilation support, and one bug in +relaxation that took a week and required the proverbial one-bit fix. + + Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax +for the 68k, completed support for some COFF targets (68k, i386 SVR3, +and SCO Unix), added support for MIPS ECOFF and ELF targets, wrote the +initial RS/6000 and PowerPC assembler, and made a few other minor +patches. + + Steve Chamberlain made GAS able to generate listings. + + Hewlett-Packard contributed support for the HP9000/300. + + Jeff Law wrote GAS and BFD support for the native HPPA object format +(SOM) along with a fairly extensive HPPA testsuite (for both SOM and ELF +object formats). This work was supported by both the Center for +Software Science at the University of Utah and Cygnus Support. + + Support for ELF format files has been worked on by Mark Eichin of +Cygnus Support (original, incomplete implementation for SPARC), Pete +Hoogenboom and Jeff Law at the University of Utah (HPPA mainly), Michael +Meissner of the Open Software Foundation (i386 mainly), and Ken Raeburn +of Cygnus Support (sparc, and some initial 64-bit support). + + Linas Vepstas added GAS support for the ESA/390 "IBM 370" +architecture. + + Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote +GAS and BFD support for openVMS/Alpha. + + Timothy Wall, Michael Hayes, and Greg Smart contributed to the +various tic* flavors. + + David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from +Tensilica, Inc. added support for Xtensa processors. + + Several engineers at Cygnus Support have also provided many small bug +fixes and configuration enhancements. + + Many others have contributed large or small bugfixes and +enhancements. If you have contributed significant work and are not +mentioned on this list, and want to be, let us know. Some of the +history has been lost; we are not intentionally leaving anyone out. + +Appendix A GNU Free Documentation License +***************************************** + + Version 1.1, March 2000 + + Copyright (C) 2000, 2003 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + written document "free" in the sense of freedom: to assure everyone + the effective freedom to copy and redistribute it, with or without + modifying it, either commercially or noncommercially. Secondarily, + this License preserves for the author and publisher a way to get + credit for their work, while not being considered responsible for + modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work that contains a + notice placed by the copyright holder saying it can be distributed + under the terms of this License. The "Document", below, refers to + any such manual or work. Any member of the public is a licensee, + and is addressed as "you." + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (For example, if the + Document is in part a textbook of mathematics, a Secondary Section + may not explain any mathematics.) The relationship could be a + matter of historical connection with the subject or with related + matters, or of legal, commercial, philosophical, ethical or + political position regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, whose contents can be viewed and edited directly + and straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup has been designed to + thwart or discourage subsequent modification by readers is not + Transparent. A copy that is not "Transparent" is called "Opaque." + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML designed for human modification. Opaque formats + include PostScript, PDF, proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML produced by some word processors for + output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies of the Document numbering more than + 100, and the Document's license notice requires Cover Texts, you + must enclose the copies in covers that carry, clearly and legibly, + all these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a publicly-accessible computer-network location + containing a complete Transparent copy of the Document, free of + added material, which the general network-using public has access + to download anonymously at no charge using public-standard network + protocols. If you use the latter option, you must take reasonably + prudent steps, when you begin distribution of Opaque copies in + quantity, to ensure that this Transparent copy will remain thus + accessible at the stated location until at least one year after the + last time you distribute an Opaque copy (directly or through your + agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the History + section of the Document). You may use the same title as a previous + version if the original publisher of that version gives permission. + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in the + Modified Version, together with at least five of the principal + authors of the Document (all of its principal authors, if it has + less than five). + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + D. Preserve all the copyright notices of the Document. + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified Version + under the terms of this License, in the form shown in the Addendum + below. + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's license + notice. + H. Include an unaltered copy of this License. + I. Preserve the section entitled "History", and its title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. + J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + K. In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + M. Delete any section entitled "Endorsements." Such a section may + not be included in the Modified Version. + N. Do not retitle any existing section as "Endorsements" or to + conflict in title with any Invariant Section. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties-for example, statements of peer review or that the text has + been approved by an organization as the authoritative definition of + a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections entitled + "History" in the various original documents, forming one section + entitled "History"; likewise combine any sections entitled + "Acknowledgements", and any sections entitled "Dedications." You + must delete all sections entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, does not as a whole count as a + Modified Version of the Document, provided no compilation copyright + is claimed for the compilation. Such a compilation is called an + "aggregate", and this License does not apply to the other + self-contained works thus compiled with the Document, on account of + their being thus compiled, if they are not themselves derivative + works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one + quarter of the entire aggregate, the Document's Cover Texts may be + placed on covers that surround only the Document within the + aggregate. Otherwise they must appear on covers around the whole + aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License provided that you also include the + original English version of this License. In case of a + disagreement between the translation and the original English + version of this License, the original English version will prevail. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided for under this License. Any other + attempt to copy, modify, sublicense or distribute the Document is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses terminated + so long as such parties remain in full compliance. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + http://www.gnu.org/copyleft/. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License." + + If you have no Invariant Sections, write "with no Invariant Sections" +instead of saying which ones are invariant. If you have no Front-Cover +Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being +LIST"; likewise for Back-Cover Texts. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + ---------- Footnotes ---------- + + (1) Any more details? + +AS Index +******** + +* Menu: + +* #: Comments. (line 1306) +* #APP: Preprocessing. (line 1268) +* #NO_APP: Preprocessing. (line 1268) +* '$a': ARM Mapping Symbols. + (line 4193) +* '$d': ARM Mapping Symbols. + (line 4199) +* '$t': ARM Mapping Symbols. + (line 4196) +* --: Command Line. (line 760) +* '--32' option, i386: i386-Options. (line 4220) +* '--32' option, x86-64: i386-Options. (line 4220) +* '--64' option, i386: i386-Options. (line 4220) +* '--64' option, x86-64: i386-Options. (line 4220) +* --alternate: alternate. (line 929) +* '--divide' option, i386: i386-Options. (line 4236) +* --enforce-aligned-data: Sparc-Aligned-Data. (line 5460) +* --fatal-warnings: W. (line 1222) +* --hash-size=NUMBER: Overview. (line 459) +* --listing-cont-lines: listing. (line 1015) +* --listing-lhs-width: listing. (line 997) +* --listing-lhs-width2: listing. (line 1002) +* --listing-rhs-width: listing. (line 1009) +* --MD: MD. (line 1149) +* --no-warn: W. (line 1217) +* --statistics: statistics. (line 1188) +* --traditional-format: traditional-format. (line 1196) +* --warn: W. (line 1225) +* -a: a. (line 894) +* -ac: a. (line 894) +* -ad: a. (line 894) +* -ah: a. (line 894) +* -al: a. (line 894) +* -an: a. (line 894) +* -as: a. (line 894) +* -Asparclet: Sparc-Opts. (line 5421) +* -Asparclite: Sparc-Opts. (line 5421) +* -Av6: Sparc-Opts. (line 5421) +* -Av8: Sparc-Opts. (line 5421) +* -Av9: Sparc-Opts. (line 5421) +* -Av9a: Sparc-Opts. (line 5421) +* -construct-floats: MIPS Opts. (line 5056) +* -D: D. (line 934) +* '-eabi=' command line option, ARM: ARM Options. (line 3844) +* '-EB' command line option, ARM: ARM Options. (line 3849) +* '-EB' option (MIPS): MIPS Opts. (line 4879) +* '-EL' command line option, ARM: ARM Options. (line 3853) +* '-EL' option (MIPS): MIPS Opts. (line 4879) +* -f: f. (line 940) +* '-G' option (MIPS): MIPS Opts. (line 4874) +* -I PATH: I. (line 952) +* -K: K. (line 962) +* '-k' command line option, ARM: ARM Options. (line 3857) +* '-KPIC' option, MIPS: MIPS Opts. (line 4887) +* -L: L. (line 972) +* -M: M. (line 1022) +* '-mapcs' command line option, ARM: ARM Options. (line 3817) +* '-mapcs-float' command line option, ARM: ARM Options. (line 3830) +* '-mapcs-reentrant' command line option, ARM: ARM Options. (line 3835) +* '-march=' command line option, ARM: ARM Options. (line 3773) +* '-march=' option, i386: i386-Options. (line 4243) +* '-march=' option, x86-64: i386-Options. (line 4243) +* '-matpcs' command line option, ARM: ARM Options. (line 3822) +* '-mconstant-gp' command line option, IA-64: IA-64 Options. (line 4733) +* '-mcpu=' command line option, ARM: ARM Options. (line 3742) +* '-mfloat-abi=' command line option, ARM: ARM Options. (line 3839) +* '-mfpu=' command line option, ARM: ARM Options. (line 3788) +* -mno-sym32: MIPS Opts. (line 5045) +* -msym32: MIPS Opts. (line 5045) +* '-mthumb' command line option, ARM: ARM Options. (line 3808) +* '-mthumb-interwork' command line option, ARM: ARM Options. (line 3813) +* '-mtune=' option, i386: i386-Options. (line 4255) +* '-mtune=' option, x86-64: i386-Options. (line 4255) +* '-mvxworks-pic' option, MIPS: MIPS Opts. (line 4892) +* -no-construct-floats: MIPS Opts. (line 5056) +* '-nocpp' ignored (MIPS): MIPS Opts. (line 5048) +* -o: o. (line 1160) +* -R: R. (line 1170) +* -v: v. (line 1206) +* -version: v. (line 1206) +* -W: W. (line 1217) +* '.' (symbol): Dot. (line 1898) +* '.arch' directive, ARM: ARM Directives. (line 4118) +* '.cantunwind' directive, ARM: ARM Directives. (line 4022) +* '.cpu' directive, ARM: ARM Directives. (line 4114) +* '.eabi_attribute' directive, ARM: ARM Directives. (line 4132) +* '.fnend' directive, ARM: ARM Directives. (line 4014) +* '.fnstart' directive, ARM: ARM Directives. (line 4011) +* '.fpu' directive, ARM: ARM Directives. (line 4128) +* '.handlerdata' directive, ARM: ARM Directives. (line 4033) +* '.insn': MIPS insn. (line 5223) +* '.ltorg' directive, ARM: ARM Directives. (line 3994) +* '.movsp' directive, ARM: ARM Directives. (line 4088) +* .o: Object. (line 827) +* '.object_arch' directive, ARM: ARM Directives. (line 4122) +* '.pad' directive, ARM: ARM Directives. (line 4083) +* '.personality' directive, ARM: ARM Directives. (line 4026) +* '.personalityindex' directive, ARM: ARM Directives. (line 4029) +* '.pool' directive, ARM: ARM Directives. (line 4008) +* '.save' directive, ARM: ARM Directives. (line 4042) +* '.set arch=CPU': MIPS ISA. (line 5195) +* '.set autoextend': MIPS autoextend. (line 5210) +* '.set dsp': MIPS ASE instruction generation overrides. + (line 5262) +* '.set dspr2': MIPS ASE instruction generation overrides. + (line 5267) +* '.set mdmx': MIPS ASE instruction generation overrides. + (line 5257) +* '.set mips3d': MIPS ASE instruction generation overrides. + (line 5247) +* '.set mipsN': MIPS ISA. (line 5183) +* '.set mt': MIPS ASE instruction generation overrides. + (line 5272) +* '.set noautoextend': MIPS autoextend. (line 5210) +* '.set nodsp': MIPS ASE instruction generation overrides. + (line 5262) +* '.set nodspr2': MIPS ASE instruction generation overrides. + (line 5267) +* '.set nomdmx': MIPS ASE instruction generation overrides. + (line 5257) +* '.set nomips3d': MIPS ASE instruction generation overrides. + (line 5247) +* '.set nomt': MIPS ASE instruction generation overrides. + (line 5272) +* '.set nosmartmips': MIPS ASE instruction generation overrides. + (line 5252) +* '.set nosym32': MIPS symbol sizes. (line 5140) +* '.set pop': MIPS option stack. (line 5232) +* '.set push': MIPS option stack. (line 5232) +* '.set smartmips': MIPS ASE instruction generation overrides. + (line 5252) +* '.set sym32': MIPS symbol sizes. (line 5140) +* '.setfp' directive, ARM: ARM Directives. (line 4093) +* '.unwind_raw' directive, ARM: ARM Directives. (line 4107) +* '.vsave' directive, ARM: ARM Directives. (line 4066) +* 16-bit code, i386: i386-16bit. (line 4615) +* 3DNow!, i386: i386-SIMD. (line 4593) +* 3DNow!, x86-64: i386-SIMD. (line 4593) +* ':' (label): Statements. (line 1355) +* '\"' (doublequote character): Strings. (line 1423) +* '\b' (backspace character): Strings. (line 1395) +* '\DDD' (octal character code): Strings. (line 1410) +* '\f' (formfeed character): Strings. (line 1398) +* '\n' (newline character): Strings. (line 1401) +* '\r' (carriage return character): Strings. (line 1404) +* '\t' (tab): Strings. (line 1407) +* '\XD...' (hex character code): Strings. (line 1416) +* '\\' ('\' character): Strings. (line 1420) +* a.out: Object. (line 827) +* 'abort' directive: Abort. (line 2114) +* absolute section: Ld Sections. (line 1632) +* addition, permitted arguments: Infix Ops. (line 2055) +* addresses: Expressions. (line 1946) +* addresses, format of: Secs Background. (line 1573) +* 'ADR reg,<label>' pseudo op, ARM: ARM Opcodes. (line 4159) +* 'ADRL reg,<label>' pseudo op, ARM: ARM Opcodes. (line 4169) +* advancing location counter: Org. (line 3101) +* 'align' directive: Align. (line 2123) +* 'align' directive, ARM: ARM Directives. (line 3915) +* 'align' directive, SPARC: Sparc-Directives. (line 5481) +* arch directive, i386: i386-Arch. (line 4670) +* arch directive, x86-64: i386-Arch. (line 4670) +* architectures, PowerPC: PowerPC-Opts. (line 5285) +* architectures, SPARC: Sparc-Opts. (line 5402) +* arguments for addition: Infix Ops. (line 2055) +* arguments for subtraction: Infix Ops. (line 2060) +* arguments in expressions: Arguments. (line 1973) +* arithmetic functions: Operators. (line 1998) +* arithmetic operands: Arguments. (line 1973) +* ARM data relocations: ARM-Relocations. (line 3886) +* 'arm' directive, ARM: ARM Directives. (line 3969) +* ARM floating point (IEEE): ARM Floating Point. (line 3910) +* ARM identifiers: ARM-Chars. (line 3876) +* ARM immediate character: ARM-Chars. (line 3874) +* ARM line comment character: ARM-Chars. (line 3867) +* ARM line separator: ARM-Chars. (line 3871) +* ARM machine directives: ARM Directives. (line 3915) +* ARM opcodes: ARM Opcodes. (line 4140) +* ARM options (none): ARM Options. (line 3742) +* ARM register names: ARM-Regs. (line 3881) +* ARM support: Machine Dependencies. + (line 3739) +* 'ascii' directive: Ascii. (line 2165) +* 'asciz' directive: Asciz. (line 2172) +* assembler bugs, reporting: Bug Reporting. (line 5566) +* assembler crash: Bug Criteria. (line 5550) +* assembler internal logic error: As Sections. (line 1674) +* assembler version: v. (line 1206) +* assembler, and linker: Secs Background. (line 1535) +* assembly listings, enabling: a. (line 894) +* assigning values to symbols: Setting Symbols. (line 1772) +* assigning values to symbols <1>: Equ. (line 2471) +* attributes, symbol: Symbol Attributes. (line 1907) +* att_syntax pseudo op, i386: i386-Syntax. (line 4265) +* att_syntax pseudo op, x86-64: i386-Syntax. (line 4265) +* Av7: Sparc-Opts. (line 5421) +* backslash ('\\'): Strings. (line 1420) +* backspace ('\b'): Strings. (line 1395) +* 'balign' directive: Balign. (line 2178) +* 'balignl' directive: Balign. (line 2199) +* 'balignw' directive: Balign. (line 2199) +* big endian output, MIPS: Overview. (line 560) +* big-endian output, MIPS: MIPS Opts. (line 4879) +* bignums: Bignums. (line 1485) +* binary files, including: Incbin. (line 2707) +* binary integers: Integers. (line 1466) +* bit names, IA-64: IA-64-Bits. (line 4846) +* bss section: Ld Sections. (line 1623) +* bss section <1>: bss. (line 1739) +* bug criteria: Bug Criteria. (line 5547) +* bug reports: Bug Reporting. (line 5566) +* bugs in assembler: Reporting Bugs. (line 5534) +* bus lock prefixes, i386: i386-Prefixes. (line 4444) +* 'byte' directive: Byte. (line 2211) +* call instructions, i386: i386-Mnemonics. (line 4353) +* call instructions, x86-64: i386-Mnemonics. (line 4353) +* carriage return ('\r'): Strings. (line 1404) +* 'cfi_endproc' directive: CFI directives. (line 2249) +* 'cfi_startproc' directive: CFI directives. (line 2239) +* character constants: Characters. (line 1377) +* character escape codes: Strings. (line 1395) +* character, single: Chars. (line 1443) +* characters used in symbols: Symbol Intro. (line 1325) +* 'code' directive, ARM: ARM Directives. (line 3962) +* 'code16' directive, i386: i386-16bit. (line 4615) +* 'code16gcc' directive, i386: i386-16bit. (line 4615) +* 'code32' directive, i386: i386-16bit. (line 4615) +* 'code64' directive, i386: i386-16bit. (line 4615) +* 'code64' directive, x86-64: i386-16bit. (line 4615) +* COMDAT: Linkonce. (line 2831) +* 'comm' directive: Comm. (line 2217) +* command line conventions: Command Line. (line 756) +* comments: Comments. (line 1288) +* comments, removed by preprocessor: Preprocessing. (line 1253) +* 'common' directive, SPARC: Sparc-Directives. (line 5484) +* common sections: Linkonce. (line 2831) +* common variable storage: bss. (line 1739) +* comparison expressions: Infix Ops. (line 2066) +* conditional assembly: If. (line 2629) +* constant, single character: Chars. (line 1443) +* constants: Constants. (line 1366) +* constants, bignum: Bignums. (line 1485) +* constants, character: Characters. (line 1377) +* constants, converted by preprocessor: Preprocessing. (line 1256) +* constants, floating point: Flonums. (line 1493) +* constants, integer: Integers. (line 1466) +* constants, number: Numbers. (line 1457) +* constants, string: Strings. (line 1386) +* conversion instructions, i386: i386-Mnemonics. (line 4334) +* conversion instructions, x86-64: i386-Mnemonics. (line 4334) +* coprocessor wait, i386: i386-Prefixes. (line 4448) +* crash of assembler: Bug Criteria. (line 5550) +* current address: Dot. (line 1898) +* current address, advancing: Org. (line 3101) +* data alignment on SPARC: Sparc-Aligned-Data. (line 5455) +* data and text sections, joining: R. (line 1170) +* 'data' directive: Data. (line 2421) +* data relocations, ARM: ARM-Relocations. (line 3886) +* debuggers, and symbol order: Symbols. (line 1757) +* decimal integers: Integers. (line 1472) +* dependency tracking: MD. (line 1149) +* deprecated directives: Deprecated. (line 3731) +* directives and instructions: Statements. (line 1347) +* directives for PowerPC: PowerPC-Pseudo. (line 5386) +* directives, machine independent: Pseudo Ops. (line 2105) +* 'dn' and 'qn' directives, ARM: ARM Directives. (line 3938) +* dollar local symbols: Symbol Names. (line 1879) +* dot (symbol): Dot. (line 1898) +* 'double' directive: Double. (line 2428) +* 'double' directive, i386: i386-Float. (line 4569) +* 'double' directive, x86-64: i386-Float. (line 4569) +* doublequote ('\"'): Strings. (line 1423) +* ECOFF sections: MIPS Object. (line 5100) +* eight-byte integer: Quad. (line 3245) +* 'eject' directive: Eject. (line 2434) +* ELF symbol type: Type. (line 3620) +* 'else' directive: Else. (line 2439) +* 'elseif' directive: Elseif. (line 2446) +* empty expressions: Empty Exprs. (line 1959) +* emulation: Overview. (line 663) +* 'end' directive: End. (line 2453) +* 'endfunc' directive: Endfunc. (line 2459) +* endianness, MIPS: Overview. (line 560) +* 'endif' directive: Endif. (line 2464) +* 'endm' directive: Macro. (line 3025) +* EOF, newline must precede: Statements. (line 1341) +* 'equ' directive: Equ. (line 2471) +* 'equiv' directive: Equiv. (line 2477) +* 'eqv' directive: Eqv. (line 2493) +* 'err' directive: Err. (line 2501) +* error directive: Error. (line 2509) +* error messages: Errors. (line 844) +* error on valid input: Bug Criteria. (line 5553) +* errors, caused by warnings: W. (line 1222) +* errors, continuing after: Z. (line 1231) +* escape codes, character: Strings. (line 1395) +* 'exitm' directive: Macro. (line 3028) +* expr (internal section): As Sections. (line 1678) +* expression arguments: Arguments. (line 1973) +* expressions: Expressions. (line 1946) +* expressions, comparison: Infix Ops. (line 2066) +* expressions, empty: Empty Exprs. (line 1959) +* expressions, integer: Integer Exprs. (line 1967) +* 'extern' directive: Extern. (line 2524) +* 'fail' directive: Fail. (line 2531) +* faster processing ('-f'): f. (line 940) +* fatal signal: Bug Criteria. (line 5550) +* 'file' directive: LNS directives. (line 2369) +* 'file' directive <1>: File. (line 2540) +* file name, logical: File. (line 2540) +* files, including: Include. (line 2721) +* files, input: Input Files. (line 780) +* 'fill' directive: Fill. (line 2550) +* filling memory: Skip. (line 3452) +* filling memory <1>: Space. (line 3459) +* 'float' directive: Float. (line 2568) +* 'float' directive, i386: i386-Float. (line 4569) +* 'float' directive, x86-64: i386-Float. (line 4569) +* floating point numbers: Flonums. (line 1493) +* floating point numbers (double): Double. (line 2428) +* floating point numbers (single): Float. (line 2568) +* floating point numbers (single) <1>: Single. (line 3425) +* floating point, ARM (IEEE): ARM Floating Point. (line 3910) +* floating point, i386: i386-Float. (line 4561) +* floating point, SPARC (IEEE): Sparc-Float. (line 5473) +* floating point, x86-64: i386-Float. (line 4561) +* flonums: Flonums. (line 1493) +* 'force_thumb' directive, ARM: ARM Directives. (line 3972) +* format of error messages: Errors. (line 861) +* format of warning messages: Errors. (line 850) +* formfeed ('\f'): Strings. (line 1398) +* 'func' directive: Func. (line 2574) +* functions, in expressions: Operators. (line 1998) +* 'global' directive: Global. (line 2585) +* 'gp' register, MIPS: MIPS Object. (line 5105) +* grouping data: Sub-Sections. (line 1686) +* 'half' directive, SPARC: Sparc-Directives. (line 5489) +* hex character code ('\XD...'): Strings. (line 1416) +* hexadecimal integers: Integers. (line 1475) +* 'hidden' directive: Hidden. (line 2597) +* 'hword' directive: hword. (line 2610) +* i386 16-bit code: i386-16bit. (line 4615) +* i386 arch directive: i386-Arch. (line 4670) +* i386 att_syntax pseudo op: i386-Syntax. (line 4265) +* i386 conversion instructions: i386-Mnemonics. (line 4334) +* i386 floating point: i386-Float. (line 4561) +* i386 immediate operands: i386-Syntax. (line 4274) +* i386 instruction naming: i386-Mnemonics. (line 4309) +* i386 instruction prefixes: i386-Prefixes. (line 4414) +* i386 intel_syntax pseudo op: i386-Syntax. (line 4265) +* i386 jump optimization: i386-Jumps. (line 4538) +* i386 jump, call, return: i386-Syntax. (line 4296) +* i386 jump/call operands: i386-Syntax. (line 4274) +* i386 memory references: i386-Memory. (line 4471) +* i386 'mul', 'imul' instructions: i386-Notes. (line 4714) +* i386 options: i386-Options. (line 4218) +* i386 register operands: i386-Syntax. (line 4274) +* i386 registers: i386-Regs. (line 4359) +* i386 sections: i386-Syntax. (line 4302) +* i386 size suffixes: i386-Syntax. (line 4287) +* i386 source, destination operands: i386-Syntax. (line 4280) +* i386 support: . (line 4211) +* i386 syntax compatibility: i386-Syntax. (line 4265) +* i80306 support: . (line 4211) +* IA-64 line comment character: IA-64-Chars. (line 4822) +* IA-64 line separator: IA-64-Chars. (line 4824) +* IA-64 options: IA-64 Options. (line 4733) +* IA-64 Processor-status-Register bit names: IA-64-Bits. (line 4846) +* IA-64 registers: IA-64-Regs. (line 4829) +* IA-64 support: . (line 4730) +* IA-64 Syntax: IA-64 Options. (line 4812) +* 'ident' directive: Ident. (line 2618) +* identifiers, ARM: ARM-Chars. (line 3876) +* 'if' directive: If. (line 2629) +* 'ifb' directive: If. (line 2644) +* 'ifc' directive: If. (line 2648) +* 'ifdef' directive: If. (line 2639) +* 'ifeq' directive: If. (line 2656) +* 'ifeqs' directive: If. (line 2659) +* 'ifge' directive: If. (line 2663) +* 'ifgt' directive: If. (line 2667) +* 'ifle' directive: If. (line 2671) +* 'iflt' directive: If. (line 2675) +* 'ifnb' directive: If. (line 2679) +* 'ifnc' directive: If. (line 2684) +* 'ifndef' directive: If. (line 2688) +* 'ifne' directive: If. (line 2695) +* 'ifnes' directive: If. (line 2699) +* 'ifnotdef' directive: If. (line 2688) +* immediate character, ARM: ARM-Chars. (line 3874) +* immediate operands, i386: i386-Syntax. (line 4274) +* immediate operands, x86-64: i386-Syntax. (line 4274) +* 'imul' instruction, i386: i386-Notes. (line 4714) +* 'imul' instruction, x86-64: i386-Notes. (line 4714) +* 'incbin' directive: Incbin. (line 2707) +* 'include' directive: Include. (line 2721) +* 'include' directive search path: I. (line 952) +* infix operators: Infix Ops. (line 2016) +* inhibiting interrupts, i386: i386-Prefixes. (line 4444) +* input: Input Files. (line 780) +* input file linenumbers: Input Files. (line 809) +* instruction naming, i386: i386-Mnemonics. (line 4309) +* instruction naming, x86-64: i386-Mnemonics. (line 4309) +* instruction prefixes, i386: i386-Prefixes. (line 4414) +* instructions and directives: Statements. (line 1347) +* 'int' directive: Int. (line 2732) +* 'int' directive, i386: i386-Float. (line 4576) +* 'int' directive, x86-64: i386-Float. (line 4576) +* integer expressions: Integer Exprs. (line 1967) +* integer, 16-byte: Octa. (line 3092) +* integer, 8-byte: Quad. (line 3245) +* integers: Integers. (line 1466) +* integers, 16-bit: hword. (line 2610) +* integers, 32-bit: Int. (line 2732) +* integers, binary: Integers. (line 1466) +* integers, decimal: Integers. (line 1472) +* integers, hexadecimal: Integers. (line 1475) +* integers, octal: Integers. (line 1469) +* integers, one byte: Byte. (line 2211) +* intel_syntax pseudo op, i386: i386-Syntax. (line 4265) +* intel_syntax pseudo op, x86-64: i386-Syntax. (line 4265) +* internal assembler sections: As Sections. (line 1667) +* 'internal' directive: Internal. (line 2740) +* invalid input: Bug Criteria. (line 5555) +* invocation summary: Overview. (line 249) +* 'irp' directive: Irp. (line 2754) +* 'irpc' directive: Irpc. (line 2779) +* joining text and data sections: R. (line 1170) +* jump instructions, i386: i386-Mnemonics. (line 4353) +* jump instructions, x86-64: i386-Mnemonics. (line 4353) +* jump optimization, i386: i386-Jumps. (line 4538) +* jump optimization, x86-64: i386-Jumps. (line 4538) +* jump/call operands, i386: i386-Syntax. (line 4274) +* jump/call operands, x86-64: i386-Syntax. (line 4274) +* label (':'): Statements. (line 1355) +* labels: Labels. (line 1763) +* 'lcomm' directive: Lcomm. (line 2805) +* ld: Object. (line 836) +* 'LDR reg,=<label>' pseudo op, ARM: ARM Opcodes. (line 4149) +* length of symbols: Symbol Intro. (line 1331) +* 'lflags' directive (ignored): Lflags. (line 2814) +* line comment character: Comments. (line 1301) +* line comment character, ARM: ARM-Chars. (line 3867) +* line comment character, IA-64: IA-64-Chars. (line 4822) +* 'line' directive: Line. (line 2820) +* line numbers, in input files: Input Files. (line 809) +* line numbers, in warnings/errors: Errors. (line 854) +* line separator character: Statements. (line 1336) +* line separator, ARM: ARM-Chars. (line 3871) +* line separator, IA-64: IA-64-Chars. (line 4824) +* lines starting with '#': Comments. (line 1306) +* linker: Object. (line 836) +* linker, and assembler: Secs Background. (line 1535) +* 'linkonce' directive: Linkonce. (line 2831) +* 'list' directive: List. (line 2876) +* listing control, turning off: Nolist. (line 3083) +* listing control, turning on: List. (line 2876) +* listing control: new page: Eject. (line 2434) +* listing control: paper size: Psize. (line 3208) +* listing control: subtitle: Sbttl. (line 3284) +* listing control: title line: Title. (line 3609) +* listings, enabling: a. (line 894) +* little endian output, MIPS: Overview. (line 563) +* little-endian output, MIPS: MIPS Opts. (line 4879) +* 'ln' directive: Ln. (line 2863) +* 'loc' directive: LNS directives. (line 2382) +* local common symbols: Lcomm. (line 2805) +* local labels: Symbol Names. (line 1810) +* local symbol names: Symbol Names. (line 1797) +* local symbols, retaining in output: L. (line 972) +* location counter: Dot. (line 1898) +* location counter, advancing: Org. (line 3101) +* 'loc_mark_blocks' directive: LNS directives. (line 2412) +* logical file name: File. (line 2540) +* logical line number: Line. (line 2820) +* logical line numbers: Comments. (line 1306) +* 'long' directive: Long. (line 2889) +* 'long' directive, i386: i386-Float. (line 4576) +* 'long' directive, x86-64: i386-Float. (line 4576) +* machine directives, ARM: ARM Directives. (line 3915) +* machine directives, SPARC: Sparc-Directives. (line 5478) +* machine independent directives: Pseudo Ops. (line 2105) +* machine instructions (not covered): Manual. (line 716) +* machine-independent syntax: Syntax. (line 1241) +* 'macro' directive: Macro. (line 2916) +* macros: Macro. (line 2894) +* macros, count executed: Macro. (line 3030) +* make rules: MD. (line 1149) +* manual, structure and purpose: Manual. (line 708) +* Maximum number of continuation lines: listing. (line 1015) +* memory references, i386: i386-Memory. (line 4471) +* memory references, x86-64: i386-Memory. (line 4471) +* merging text and data sections: R. (line 1170) +* messages from assembler: Errors. (line 844) +* minus, permitted arguments: Infix Ops. (line 2060) +* MIPS architecture options: MIPS Opts. (line 4895) +* MIPS big-endian output: MIPS Opts. (line 4879) +* MIPS CPU override: MIPS ISA. (line 5195) +* MIPS debugging directives: MIPS Stabs. (line 5128) +* MIPS DSP Release 1 instruction generation override: MIPS ASE instruction generation overrides. + (line 5262) +* MIPS DSP Release 2 instruction generation override: MIPS ASE instruction generation overrides. + (line 5267) +* MIPS ECOFF sections: MIPS Object. (line 5100) +* MIPS endianness: Overview. (line 560) +* MIPS ISA: Overview. (line 566) +* MIPS ISA override: MIPS ISA. (line 5183) +* MIPS little-endian output: MIPS Opts. (line 4879) +* MIPS MDMX instruction generation override: MIPS ASE instruction generation overrides. + (line 5257) +* MIPS MIPS-3D instruction generation override: MIPS ASE instruction generation overrides. + (line 5247) +* MIPS MT instruction generation override: MIPS ASE instruction generation overrides. + (line 5272) +* MIPS option stack: MIPS option stack. (line 5232) +* MIPS processor: . (line 4862) +* MMX, i386: i386-SIMD. (line 4593) +* MMX, x86-64: i386-SIMD. (line 4593) +* mnemonic suffixes, i386: i386-Syntax. (line 4287) +* mnemonic suffixes, x86-64: i386-Syntax. (line 4287) +* MOVW and MOVT relocations, ARM: ARM-Relocations. (line 3900) +* MRI compatibility mode: M. (line 1022) +* 'mri' directive: MRI. (line 2868) +* MRI mode, temporarily: MRI. (line 2868) +* 'mul' instruction, i386: i386-Notes. (line 4714) +* 'mul' instruction, x86-64: i386-Notes. (line 4714) +* named section: Section. (line 3293) +* named sections: Ld Sections. (line 1613) +* names, symbol: Symbol Names. (line 1781) +* naming object file: o. (line 1160) +* new page, in listings: Eject. (line 2434) +* newline ('\n'): Strings. (line 1401) +* newline, required at file end: Statements. (line 1341) +* 'nolist' directive: Nolist. (line 3083) +* 'NOP' pseudo op, ARM: ARM Opcodes. (line 4143) +* null-terminated strings: Asciz. (line 2172) +* number constants: Numbers. (line 1457) +* number of macros executed: Macro. (line 3030) +* numbered subsections: Sub-Sections. (line 1686) +* numbers, 16-bit: hword. (line 2610) +* numeric values: Expressions. (line 1946) +* 'nword' directive, SPARC: Sparc-Directives. (line 5492) +* object file: Object. (line 827) +* object file format: Object Formats. (line 746) +* object file name: o. (line 1160) +* object file, after errors: Z. (line 1231) +* obsolescent directives: Deprecated. (line 3731) +* 'octa' directive: Octa. (line 3092) +* octal character code ('\DDD'): Strings. (line 1410) +* octal integers: Integers. (line 1469) +* opcodes for ARM: ARM Opcodes. (line 4140) +* operand delimiters, i386: i386-Syntax. (line 4274) +* operand delimiters, x86-64: i386-Syntax. (line 4274) +* operands in expressions: Arguments. (line 1973) +* operator precedence: Infix Ops. (line 2021) +* operators, in expressions: Operators. (line 1998) +* operators, permitted arguments: Infix Ops. (line 2016) +* option summary: Overview. (line 249) +* options for ARM (none): ARM Options. (line 3742) +* options for i386: i386-Options. (line 4218) +* options for IA-64: IA-64 Options. (line 4733) +* options for PowerPC: PowerPC-Opts. (line 5285) +* options for SPARC: Sparc-Opts. (line 5402) +* options for x86-64: i386-Options. (line 4218) +* options, all versions of assembler: Invoking. (line 870) +* options, command line: Command Line. (line 763) +* 'org' directive: Org. (line 3101) +* output file: Object. (line 827) +* 'p2align' directive: P2align. (line 3127) +* 'p2alignl' directive: P2align. (line 3149) +* 'p2alignw' directive: P2align. (line 3149) +* padding the location counter: Align. (line 2123) +* padding the location counter given a power of two: P2align. + (line 3127) +* padding the location counter given number of bytes: Balign. + (line 2178) +* page, in listings: Eject. (line 2434) +* paper size, for listings: Psize. (line 3208) +* paths for '.include': I. (line 952) +* patterns, writing in memory: Fill. (line 2550) +* PIC code generation for ARM: ARM Options. (line 3857) +* PIC selection, MIPS: MIPS Opts. (line 4887) +* plus, permitted arguments: Infix Ops. (line 2055) +* 'popsection' directive: PopSection. (line 3177) +* PowerPC architectures: PowerPC-Opts. (line 5285) +* PowerPC directives: PowerPC-Pseudo. (line 5386) +* PowerPC options: PowerPC-Opts. (line 5285) +* PowerPC support: . (line 5282) +* precedence of operators: Infix Ops. (line 2021) +* precision, floating point: Flonums. (line 1493) +* prefix operators: Prefix Ops. (line 2005) +* prefixes, i386: i386-Prefixes. (line 4414) +* preprocessing: Preprocessing. (line 1248) +* preprocessing, turning on and off: Preprocessing. (line 1268) +* 'previous' directive: Previous. (line 3161) +* 'print' directive: Print. (line 3189) +* 'proc' directive, SPARC: Sparc-Directives. (line 5497) +* 'protected' directive: Protected. (line 3195) +* pseudo-ops, machine independent: Pseudo Ops. (line 2105) +* 'psize' directive: Psize. (line 3208) +* PSR bits: IA-64-Bits. (line 4846) +* 'purgem' directive: Purgem. (line 3224) +* purpose of GNU assembler: GNU Assembler. (line 734) +* 'pushsection' directive: PushSection. (line 3230) +* 'quad' directive: Quad. (line 3242) +* 'quad' directive, i386: i386-Float. (line 4576) +* 'quad' directive, x86-64: i386-Float. (line 4576) +* real-mode code, i386: i386-16bit. (line 4615) +* 'register' directive, SPARC: Sparc-Directives. (line 5501) +* register names, ARM: ARM-Regs. (line 3881) +* register names, IA-64: IA-64-Regs. (line 4829) +* register operands, i386: i386-Syntax. (line 4274) +* register operands, x86-64: i386-Syntax. (line 4274) +* registers, i386: i386-Regs. (line 4359) +* registers, x86-64: i386-Regs. (line 4359) +* 'reloc' directive: Reloc. (line 3253) +* relocation: Sections. (line 1528) +* relocation example: Ld Sections. (line 1643) +* repeat prefixes, i386: i386-Prefixes. (line 4452) +* reporting bugs in assembler: Reporting Bugs. (line 5534) +* 'rept' directive: Rept. (line 3266) +* 'req' directive, ARM: ARM Directives. (line 3922) +* 'reserve' directive, SPARC: Sparc-Directives. (line 5511) +* return instructions, i386: i386-Syntax. (line 4296) +* return instructions, x86-64: i386-Syntax. (line 4296) +* REX prefixes, i386: i386-Prefixes. (line 4454) +* 'sbttl' directive: Sbttl. (line 3284) +* search path for '.include': I. (line 952) +* 'section' directive (ELF version): Section. (line 3305) +* section override prefixes, i386: i386-Prefixes. (line 4431) +* Section Stack: Previous. (line 3161) +* Section Stack <1>: PopSection. (line 3177) +* Section Stack <2>: PushSection. (line 3230) +* Section Stack <3>: Section. (line 3300) +* Section Stack <4>: SubSection. (line 3545) +* section-relative addressing: Secs Background. (line 1573) +* sections: Sections. (line 1528) +* sections in messages, internal: As Sections. (line 1667) +* sections, i386: i386-Syntax. (line 4302) +* sections, named: Ld Sections. (line 1613) +* sections, x86-64: i386-Syntax. (line 4302) +* 'seg' directive, SPARC: Sparc-Directives. (line 5516) +* 'set' directive: Set. (line 3407) +* 'short' directive: Short. (line 3419) +* SIMD, i386: i386-SIMD. (line 4593) +* SIMD, x86-64: i386-SIMD. (line 4593) +* single character constant: Chars. (line 1443) +* 'single' directive: Single. (line 3425) +* 'single' directive, i386: i386-Float. (line 4569) +* 'single' directive, x86-64: i386-Float. (line 4569) +* sixteen bit integers: hword. (line 2610) +* sixteen byte integer: Octa. (line 3092) +* 'size' directive (ELF version): Size. (line 3433) +* size prefixes, i386: i386-Prefixes. (line 4435) +* sizes operands, i386: i386-Syntax. (line 4287) +* sizes operands, x86-64: i386-Syntax. (line 4287) +* 'skip' directive: Skip. (line 3452) +* 'skip' directive, SPARC: Sparc-Directives. (line 5520) +* 'sleb128' directive: Sleb128. (line 3445) +* small objects, MIPS ECOFF: MIPS Object. (line 5105) +* SmartMIPS instruction generation override: MIPS ASE instruction generation overrides. + (line 5252) +* source program: Input Files. (line 780) +* source, destination operands; i386: i386-Syntax. (line 4280) +* source, destination operands; x86-64: i386-Syntax. (line 4280) +* 'space' directive: Space. (line 3459) +* space used, maximum for assembly: statistics. (line 1188) +* SPARC architectures: Sparc-Opts. (line 5402) +* SPARC data alignment: Sparc-Aligned-Data. (line 5455) +* SPARC floating point (IEEE): Sparc-Float. (line 5473) +* SPARC machine directives: Sparc-Directives. (line 5478) +* SPARC options: Sparc-Opts. (line 5402) +* SPARC support: . (line 5399) +* 'stabd' directive: Stab. (line 3498) +* 'stabn' directive: Stab. (line 3509) +* 'stabs' directive: Stab. (line 3512) +* 'stabX' directives: Stab. (line 3466) +* standard assembler sections: Secs Background. (line 1550) +* standard input, as input file: Command Line. (line 760) +* statement separator character: Statements. (line 1336) +* statement separator, ARM: ARM-Chars. (line 3871) +* statement separator, IA-64: IA-64-Chars. (line 4824) +* statements, structure of: Statements. (line 1336) +* statistics, about assembly: statistics. (line 1188) +* stopping the assembly: Abort. (line 2114) +* string constants: Strings. (line 1386) +* 'string' directive: String. (line 3518) +* string literals: Ascii. (line 2165) +* string, copying to object file: String. (line 3518) +* 'struct' directive: Struct. (line 3527) +* subexpressions: Arguments. (line 1991) +* 'subsection' directive: SubSection. (line 3545) +* subtitles for listings: Sbttl. (line 3284) +* subtraction, permitted arguments: Infix Ops. (line 2060) +* summary of options: Overview. (line 249) +* supporting files, including: Include. (line 2721) +* suppressing warnings: W. (line 1217) +* symbol attributes: Symbol Attributes. (line 1907) +* symbol names: Symbol Names. (line 1781) +* symbol names, local: Symbol Names. (line 1797) +* symbol names, temporary: Symbol Names. (line 1810) +* symbol type: Symbol Type. (line 1938) +* symbol type, ELF: Type. (line 3620) +* symbol value: Symbol Value. (line 1918) +* symbol value, setting: Set. (line 3407) +* symbol values, assigning: Setting Symbols. (line 1772) +* symbol versioning: Symver. (line 3557) +* symbol, common: Comm. (line 2217) +* symbol, making visible to linker: Global. (line 2585) +* symbolic debuggers, information for: Stab. (line 3466) +* symbols: Symbols. (line 1753) +* symbols, assigning values to: Equ. (line 2471) +* symbols, local common: Lcomm. (line 2805) +* 'symver' directive: Symver. (line 3557) +* syntax compatibility, i386: i386-Syntax. (line 4265) +* syntax compatibility, x86-64: i386-Syntax. (line 4265) +* syntax, machine-independent: Syntax. (line 1241) +* tab ('\t'): Strings. (line 1407) +* temporary symbol names: Symbol Names. (line 1810) +* text and data sections, joining: R. (line 1170) +* 'text' directive: Text. (line 3602) +* 'tfloat' directive, i386: i386-Float. (line 4569) +* 'tfloat' directive, x86-64: i386-Float. (line 4569) +* 'thumb' directive, ARM: ARM Directives. (line 3966) +* Thumb support: Machine Dependencies. + (line 3739) +* 'thumb_func' directive, ARM: ARM Directives. (line 3976) +* 'thumb_set' directive, ARM: ARM Directives. (line 3987) +* time, total for assembly: statistics. (line 1188) +* 'title' directive: Title. (line 3609) +* trusted compiler: f. (line 940) +* turning preprocessing on and off: Preprocessing. (line 1268) +* 'type' directive (ELF version): Type. (line 3620) +* type of a symbol: Symbol Type. (line 1938) +* 'uleb128' directive: Uleb128. (line 3656) +* undefined section: Ld Sections. (line 1639) +* 'unreq' directive, ARM: ARM Directives. (line 3927) +* value of a symbol: Symbol Value. (line 1918) +* 'version' directive: Version. (line 3663) +* version of assembler: v. (line 1206) +* versions of symbols: Symver. (line 3557) +* visibility: Hidden. (line 2597) +* visibility <1>: Internal. (line 2740) +* visibility <2>: Protected. (line 3195) +* 'vtable_entry' directive: VTableEntry. (line 3669) +* 'vtable_inherit' directive: VTableInherit. (line 3675) +* warning directive: Warning. (line 3683) +* warning messages: Errors. (line 844) +* warnings, causing error: W. (line 1222) +* warnings, suppressing: W. (line 1217) +* warnings, switching on: W. (line 1225) +* 'weak' directive: Weak. (line 3689) +* 'weakref' directive: Weakref. (line 3705) +* whitespace: Whitespace. (line 1280) +* whitespace, removed by preprocessor: Preprocessing. (line 1249) +* Width of continuation lines of disassembly output: listing. + (line 1002) +* Width of first line disassembly output: listing. (line 997) +* Width of source line output: listing. (line 1009) +* 'word' directive: Word. (line 3725) +* 'word' directive, i386: i386-Float. (line 4576) +* 'word' directive, SPARC: Sparc-Directives. (line 5523) +* 'word' directive, x86-64: i386-Float. (line 4576) +* writing patterns in memory: Fill. (line 2550) +* x86-64 arch directive: i386-Arch. (line 4670) +* x86-64 att_syntax pseudo op: i386-Syntax. (line 4265) +* x86-64 conversion instructions: i386-Mnemonics. (line 4334) +* x86-64 floating point: i386-Float. (line 4561) +* x86-64 immediate operands: i386-Syntax. (line 4274) +* x86-64 instruction naming: i386-Mnemonics. (line 4309) +* x86-64 intel_syntax pseudo op: i386-Syntax. (line 4265) +* x86-64 jump optimization: i386-Jumps. (line 4538) +* x86-64 jump, call, return: i386-Syntax. (line 4296) +* x86-64 jump/call operands: i386-Syntax. (line 4274) +* x86-64 memory references: i386-Memory. (line 4471) +* x86-64 options: i386-Options. (line 4218) +* x86-64 register operands: i386-Syntax. (line 4274) +* x86-64 registers: i386-Regs. (line 4359) +* x86-64 sections: i386-Syntax. (line 4302) +* x86-64 size suffixes: i386-Syntax. (line 4287) +* x86-64 source, destination operands: i386-Syntax. (line 4280) +* x86-64 support: . (line 4211) +* x86-64 syntax compatibility: i386-Syntax. (line 4265) +* 'xword' directive, SPARC: Sparc-Directives. (line 5527) +* zero-terminated strings: Asciz. (line 2172) + diff --git a/contrib/binutils/gas/doc/asconfig.texi b/contrib/binutils/gas/doc/asconfig.texi new file mode 100644 index 000000000000..95f4a5b36b5e --- /dev/null +++ b/contrib/binutils/gas/doc/asconfig.texi @@ -0,0 +1,90 @@ +@c $FreeBSD: stable/10/gnu/usr.bin/binutils/doc/asconfig.texi 218822 2011-02-18 20:54:12Z dim $ +@c Copyright 1992, 1993, 1994, 1996, 1997, 1999, 2000, 2001, 2002, +@c 2003, 2005 +@c Free Software Foundation, Inc. +@c This file is part of the documentation for the GAS manual + +@c Configuration settings for all-inclusive version of manual + +@c switches:------------------------------------------------------------ +@c Properties of the manual +@c ======================== +@c Discuss all architectures? +@clear ALL-ARCH +@c A generic form of manual (not tailored to specific target)? +@clear GENERIC +@c Include text on assembler internals? +@set INTERNALS +@c Many object formats supported in this config? +@clear MULTI-OBJ + +@c Object formats of interest +@c ========================== +@clear AOUT +@clear COFF +@set ELF +@clear SOM + +@c CPUs of interest +@c ================ +@clear ALPHA +@clear ARC +@set ARM +@clear BFIN +@clear CRIS +@clear D10V +@clear D30V +@clear H8/300 +@clear HPPA +@clear I370 +@set I80386 +@clear I860 +@clear I960 +@set IA64 +@clear IP2K +@clear M32C +@clear M32R +@clear xc16x +@clear M68HC11 +@clear M680X0 +@clear MCORE +@set MIPS +@clear MMIX +@clear MS1 +@clear MSP430 +@clear PDP11 +@clear PJ +@set PPC +@clear SH +@set SPARC +@clear TIC54X +@clear V850 +@clear VAX +@clear XTENSA +@clear Z80 +@clear Z8000 + +@c Does this version of the assembler use the difference-table kludge? +@clear DIFF-TBL-KLUGE + +@c Do all machines described use IEEE floating point? +@clear IEEEFLOAT + +@c Is a word 32 bits, or 16? +@set W32 +@clear W16 + +@c Do symbols have different characters than usual? +@clear SPECIAL-SYMS + +@c strings:------------------------------------------------------------ +@c Name of the assembler: +@set AS as +@c Name of C compiler: +@set GCC gcc +@c Name of linker: +@set LD ld +@c Text for target machine (best not used in generic case; but just in case...) +@set TARGET machine specific +@c Name of object format NOT SET in generic version +@set OBJ-NAME ELF diff --git a/contrib/binutils/ld/configdoc.texi b/contrib/binutils/ld/configdoc.texi new file mode 100644 index 000000000000..03ab5583bdab --- /dev/null +++ b/contrib/binutils/ld/configdoc.texi @@ -0,0 +1,25 @@ +@c ------------------------------ CONFIGURATION VARS: +@c 1. Inclusiveness of this manual +@set GENERIC + +@c 2. Specific target machines +@set ARM +@set H8300 +@set HPPA +@set I960 +@set M68HC11 +@set MMIX +@set MSP430 +@set POWERPC +@set POWERPC64 +@set Renesas +@set SPU +@set TICOFF +@set WIN32 +@set XTENSA + +@c 3. Properties of this configuration +@clear SingleFormat +@set UsesEnvVars +@c ------------------------------ end CONFIGURATION VARS + diff --git a/contrib/binutils/ld/ld.txt b/contrib/binutils/ld/ld.txt new file mode 100644 index 000000000000..e4aa1f17d050 --- /dev/null +++ b/contrib/binutils/ld/ld.txt @@ -0,0 +1,6564 @@ +START-INFO-DIR-ENTRY +* Ld: (ld). The GNU linker. +END-INFO-DIR-ENTRY + +LD +1 Overview +2 Invocation + 2.1 Command Line Options + 2.1.1 Options Specific to i386 PE Targets + 2.1.2 Options specific to Motorola 68HC11 and 68HC12 targets + 2.2 Environment Variables +3 Linker Scripts + 3.1 Basic Linker Script Concepts + 3.2 Linker Script Format + 3.3 Simple Linker Script Example + 3.4 Simple Linker Script Commands + 3.4.1 Setting the Entry Point + 3.4.2 Commands Dealing with Files + 3.4.3 Commands Dealing with Object File Formats + 3.4.4 Other Linker Script Commands + 3.5 Assigning Values to Symbols + 3.5.1 Simple Assignments + 3.5.2 PROVIDE + 3.5.3 PROVIDE_HIDDEN + 3.5.4 Source Code Reference + 3.6 SECTIONS Command + 3.6.1 Output Section Description + 3.6.2 Output Section Name + 3.6.3 Output Section Address + 3.6.4 Input Section Description + 3.6.4.1 Input Section Basics + 3.6.4.2 Input Section Wildcard Patterns + 3.6.4.3 Input Section for Common Symbols + 3.6.4.4 Input Section and Garbage Collection + 3.6.4.5 Input Section Example + 3.6.5 Output Section Data + 3.6.6 Output Section Keywords + 3.6.7 Output Section Discarding + 3.6.8 Output Section Attributes + 3.6.8.1 Output Section Type + 3.6.8.2 Output Section LMA + 3.6.8.3 Forced Output Alignment + 3.6.8.4 Forced Input Alignment + 3.6.8.5 Output Section Region + 3.6.8.6 Output Section Phdr + 3.6.8.7 Output Section Fill + 3.6.9 Overlay Description + 3.7 MEMORY Command + 3.8 PHDRS Command + 3.9 VERSION Command + 3.10 Expressions in Linker Scripts + 3.10.1 Constants + 3.10.2 Symbol Names + 3.10.3 Orphan Sections + 3.10.4 The Location Counter + 3.10.5 Operators + 3.10.6 Evaluation + 3.10.7 The Section of an Expression + 3.10.8 Builtin Functions + 3.11 Implicit Linker Scripts +4 Machine Dependent Features + 4.1 'ld' and the H8/300 + 4.2 'ld' and the Intel 960 Family + 4.3 'ld' and the Motorola 68HC11 and 68HC12 families + 4.3.1 Linker Relaxation + 4.3.2 Trampoline Generation + 4.4 'ld' and the ARM family + 4.5 'ld' and HPPA 32-bit ELF Support + 4.6 'ld' and MMIX + 4.7 'ld' and MSP430 + 4.8 'ld' and PowerPC 32-bit ELF Support + 4.9 'ld' and PowerPC64 64-bit ELF Support + 4.10 'ld' and SPU ELF Support + 4.11 'ld''s Support for Various TI COFF Versions + 4.12 'ld' and WIN32 (cygwin/mingw) + 4.13 'ld' and Xtensa Processors +5 BFD + 5.1 How It Works: An Outline of BFD + 5.1.1 Information Loss + 5.1.2 The BFD canonical object-file format +6 Reporting Bugs + 6.1 Have You Found a Bug? + 6.2 How to Report Bugs +Appendix A MRI Compatible Script Files +Appendix B GNU Free Documentation License + ADDENDUM: How to use this License for your documents +LD Index +LD +** + +This file documents the GNU linker ld version "2.17.50 [FreeBSD] +2007-07-03". + + 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 +********** + +'ld' combines a number of object and archive files, relocates their data +and ties up symbol references. Usually the last step in compiling a +program is to run 'ld'. + + 'ld' accepts Linker Command Language files written in a superset of +AT&T's Link Editor Command Language syntax, to provide explicit and +total control over the linking process. + + This version of 'ld' uses the general purpose BFD libraries to +operate on object files. This allows 'ld' to read, combine, and write +object files in many different formats--for example, COFF or 'a.out'. +Different formats may be linked together to produce any available kind +of object file. *Note BFD::, for more information. + + Aside from its flexibility, the GNU linker is more helpful than other +linkers in providing diagnostic information. Many linkers abandon +execution immediately upon encountering an error; whenever possible, +'ld' continues executing, allowing you to identify other errors (or, in +some cases, to get an output file in spite of the error). + +2 Invocation +************ + +The GNU linker 'ld' is meant to cover a broad range of situations, and +to be as compatible as possible with other linkers. As a result, you +have many choices to control its behavior. + +2.1 Command Line Options +======================== + +The linker supports a plethora of command-line options, but in actual +practice few of them are used in any particular context. For instance, +a frequent use of 'ld' is to link standard Unix object files on a +standard, supported Unix system. On such a system, to link a file +'hello.o': + + ld -o OUTPUT /lib/crt0.o hello.o -lc + + This tells 'ld' to produce a file called OUTPUT as the result of +linking the file '/lib/crt0.o' with 'hello.o' and the library 'libc.a', +which will come from the standard search directories. (See the +discussion of the '-l' option below.) + + Some of the command-line options to 'ld' may be specified at any +point in the command line. However, options which refer to files, such +as '-l' or '-T', cause the file to be read at the point at which the +option appears in the command line, relative to the object files and +other file options. Repeating non-file options with a different +argument will either have no further effect, or override prior +occurrences (those further to the left on the command line) of that +option. Options which may be meaningfully specified more than once are +noted in the descriptions below. + + Non-option arguments are object files or archives which are to be +linked together. They may follow, precede, or be mixed in with +command-line options, except that an object file argument may not be +placed between an option and its argument. + + Usually the linker is invoked with at least one object file, but you +can specify other forms of binary input files using '-l', '-R', and the +script command language. If _no_ binary input files at all are +specified, the linker does not produce any output, and issues the +message 'No input files'. + + If the linker cannot recognize the format of an object file, it will +assume that it is a linker script. A script specified in this way +augments the main linker script used for the link (either the default +linker script or the one specified by using '-T'). This feature permits +the linker to link against a file which appears to be an object or an +archive, but actually merely defines some symbol values, or uses 'INPUT' +or 'GROUP' to load other objects. Note that specifying a script in this +way merely augments the main linker script; use the '-T' option to +replace the default linker script entirely. *Note Scripts::. + + For options whose names are a single letter, option arguments must +either follow the option letter without intervening whitespace, or be +given as separate arguments immediately following the option that +requires them. + + For options whose names are multiple letters, either one dash or two +can precede the option name; for example, '-trace-symbol' and +'--trace-symbol' are equivalent. Note--there is one exception to this +rule. Multiple letter options that start with a lower case 'o' can only +be preceded by two dashes. This is to reduce confusion with the '-o' +option. So for example '-omagic' sets the output file name to 'magic' +whereas '--omagic' sets the NMAGIC flag on the output. + + Arguments to multiple-letter options must either be separated from +the option name by an equals sign, or be given as separate arguments +immediately following the option that requires them. For example, +'--trace-symbol foo' and '--trace-symbol=foo' are equivalent. Unique +abbreviations of the names of multiple-letter options are accepted. + + Note--if the linker is being invoked indirectly, via a compiler +driver (e.g. 'gcc') then all the linker command line options should be +prefixed by '-Wl,' (or whatever is appropriate for the particular +compiler driver) like this: + + gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup + + This is important, because otherwise the compiler driver program may +silently drop the linker options, resulting in a bad link. + + Here is a table of the generic command line switches accepted by the +GNU linker: + +'@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. + +'-aKEYWORD' + This option is supported for HP/UX compatibility. The KEYWORD + argument must be one of the strings 'archive', 'shared', or + 'default'. '-aarchive' is functionally equivalent to '-Bstatic', + and the other two keywords are functionally equivalent to + '-Bdynamic'. This option may be used any number of times. + +'-AARCHITECTURE' +'--architecture=ARCHITECTURE' + In the current release of 'ld', this option is useful only for the + Intel 960 family of architectures. In that 'ld' configuration, the + ARCHITECTURE argument identifies the particular architecture in the + 960 family, enabling some safeguards and modifying the + archive-library search path. *Note 'ld' and the Intel 960 family: + i960, for details. + + Future releases of 'ld' may support similar functionality for other + architecture families. + +'-b INPUT-FORMAT' +'--format=INPUT-FORMAT' + 'ld' may be configured to support more than one kind of object + file. If your 'ld' is configured this way, you can use the '-b' + option to specify the binary format for input object files that + follow this option on the command line. Even when 'ld' is + configured to support alternative object formats, you don't usually + need to specify this, as 'ld' should be configured to expect as a + default input format the most usual format on each machine. + INPUT-FORMAT is a text string, the name of a particular format + supported by the BFD libraries. (You can list the available binary + formats with 'objdump -i'.) *Note BFD::. + + You may want to use this option if you are linking files with an + unusual binary format. You can also use '-b' to switch formats + explicitly (when linking object files of different formats), by + including '-b INPUT-FORMAT' before each group of object files in a + particular format. + + The default format is taken from the environment variable + 'GNUTARGET'. *Note Environment::. You can also define the input + format from a script, using the command 'TARGET'; see *note Format + Commands::. + +'-c MRI-COMMANDFILE' +'--mri-script=MRI-COMMANDFILE' + For compatibility with linkers produced by MRI, 'ld' accepts script + files written in an alternate, restricted command language, + described in *note MRI Compatible Script Files: MRI. Introduce MRI + script files with the option '-c'; use the '-T' option to run + linker scripts written in the general-purpose 'ld' scripting + language. If MRI-CMDFILE does not exist, 'ld' looks for it in the + directories specified by any '-L' options. + +'-d' +'-dc' +'-dp' + These three options are equivalent; multiple forms are supported + for compatibility with other linkers. They assign space to common + symbols even if a relocatable output file is specified (with '-r'). + The script command 'FORCE_COMMON_ALLOCATION' has the same effect. + *Note Miscellaneous Commands::. + +'-e ENTRY' +'--entry=ENTRY' + Use ENTRY as the explicit symbol for beginning execution of your + program, rather than the default entry point. If there is no + symbol named ENTRY, the linker will try to parse ENTRY as a number, + and use that as the entry address (the number will be interpreted + in base 10; you may use a leading '0x' for base 16, or a leading + '0' for base 8). *Note Entry Point::, for a discussion of defaults + and other ways of specifying the entry point. + +'--exclude-libs LIB,LIB,...' + Specifies a list of archive libraries from which symbols should not + be automatically exported. The library names may be delimited by + commas or colons. Specifying '--exclude-libs ALL' excludes symbols + in all archive libraries from automatic export. This option is + available only for the i386 PE targeted port of the linker and for + ELF targeted ports. For i386 PE, symbols explicitly listed in a + .def file are still exported, regardless of this option. For ELF + targeted ports, symbols affected by this option will be treated as + hidden. + +'-E' +'--export-dynamic' + When creating a dynamically linked executable, add all symbols to + the dynamic symbol table. The dynamic symbol table is the set of + symbols which are visible from dynamic objects at run time. + + If you do not use this option, the dynamic symbol table will + normally contain only those symbols which are referenced by some + dynamic object mentioned in the link. + + If you use 'dlopen' to load a dynamic object which needs to refer + back to the symbols defined by the program, rather than some other + dynamic object, then you will probably need to use this option when + linking the program itself. + + You can also use the dynamic list to control what symbols should be + added to the dynamic symbol table if the output format supports it. + See the description of '--dynamic-list'. + +'-EB' + Link big-endian objects. This affects the default output format. + +'-EL' + Link little-endian objects. This affects the default output + format. + +'-f' +'--auxiliary NAME' + When creating an ELF shared object, set the internal DT_AUXILIARY + field to the specified name. This tells the dynamic linker that + the symbol table of the shared object should be used as an + auxiliary filter on the symbol table of the shared object NAME. + + If you later link a program against this filter object, then, when + you run the program, the dynamic linker will see the DT_AUXILIARY + field. If the dynamic linker resolves any symbols from the filter + object, it will first check whether there is a definition in the + shared object NAME. If there is one, it will be used instead of + the definition in the filter object. The shared object NAME need + not exist. Thus the shared object NAME may be used to provide an + alternative implementation of certain functions, perhaps for + debugging or for machine specific performance. + + This option may be specified more than once. The DT_AUXILIARY + entries will be created in the order in which they appear on the + command line. + +'-F NAME' +'--filter NAME' + When creating an ELF shared object, set the internal DT_FILTER + field to the specified name. This tells the dynamic linker that + the symbol table of the shared object which is being created should + be used as a filter on the symbol table of the shared object NAME. + + If you later link a program against this filter object, then, when + you run the program, the dynamic linker will see the DT_FILTER + field. The dynamic linker will resolve symbols according to the + symbol table of the filter object as usual, but it will actually + link to the definitions found in the shared object NAME. Thus the + filter object can be used to select a subset of the symbols + provided by the object NAME. + + Some older linkers used the '-F' option throughout a compilation + toolchain for specifying object-file format for both input and + output object files. The GNU linker uses other mechanisms for this + purpose: the '-b', '--format', '--oformat' options, the 'TARGET' + command in linker scripts, and the 'GNUTARGET' environment + variable. The GNU linker will ignore the '-F' option when not + creating an ELF shared object. + +'-fini NAME' + When creating an ELF executable or shared object, call NAME when + the executable or shared object is unloaded, by setting DT_FINI to + the address of the function. By default, the linker uses '_fini' + as the function to call. + +'-g' + Ignored. Provided for compatibility with other tools. + +'-GVALUE' +'--gpsize=VALUE' + Set the maximum size of objects to be optimized using the GP + register to SIZE. This is only meaningful for object file formats + such as MIPS ECOFF which supports putting large and small objects + into different sections. This is ignored for other object file + formats. + +'-hNAME' +'-soname=NAME' + When creating an ELF shared object, set the internal DT_SONAME + field to the specified name. When an executable is linked with a + shared object which has a DT_SONAME field, then when the executable + is run the dynamic linker will attempt to load the shared object + specified by the DT_SONAME field rather than the using the file + name given to the linker. + +'-i' + Perform an incremental link (same as option '-r'). + +'-init NAME' + When creating an ELF executable or shared object, call NAME when + the executable or shared object is loaded, by setting DT_INIT to + the address of the function. By default, the linker uses '_init' + as the function to call. + +'-lNAMESPEC' +'--library=NAMESPEC' + Add the archive or object file specified by NAMESPEC to the list of + files to link. This option may be used any number of times. If + NAMESPEC is of the form ':FILENAME', 'ld' will search the library + path for a file called FILENAME, otherise it will search the + library path for a file called 'libNAMESPEC.a'. + + On systems which support shared libraries, 'ld' may also search for + files other than 'libNAMESPEC.a'. Specifically, on ELF and SunOS + systems, 'ld' will search a directory for a library called + 'libNAMESPEC.so' before searching for one called 'libNAMESPEC.a'. + (By convention, a '.so' extension indicates a shared library.) + Note that this behavior does not apply to ':FILENAME', which always + specifies a file called FILENAME. + + The linker will search an archive only once, at the location where + it is specified on the command line. If the archive defines a + symbol which was undefined in some object which appeared before the + archive on the command line, the linker will include the + appropriate file(s) from the archive. However, an undefined symbol + in an object appearing later on the command line will not cause the + linker to search the archive again. + + See the '-(' option for a way to force the linker to search + archives multiple times. + + You may list the same archive multiple times on the command line. + + This type of archive searching is standard for Unix linkers. + However, if you are using 'ld' on AIX, note that it is different + from the behaviour of the AIX linker. + +'-LSEARCHDIR' +'--library-path=SEARCHDIR' + Add path SEARCHDIR to the list of paths that 'ld' will search for + archive libraries and 'ld' control scripts. You may use this + option any number of times. The directories are searched in the + order in which they are specified on the command line. Directories + specified on the command line are searched before the default + directories. All '-L' options apply to all '-l' options, + regardless of the order in which the options appear. + + If SEARCHDIR begins with '=', then the '=' will be replaced by the + "sysroot prefix", a path specified when the linker is configured. + + The default set of paths searched (without being specified with + '-L') depends on which emulation mode 'ld' is using, and in some + cases also on how it was configured. *Note Environment::. + + The paths can also be specified in a link script with the + 'SEARCH_DIR' command. Directories specified this way are searched + at the point in which the linker script appears in the command + line. + +'-mEMULATION' + Emulate the EMULATION linker. You can list the available + emulations with the '--verbose' or '-V' options. + + If the '-m' option is not used, the emulation is taken from the + 'LDEMULATION' environment variable, if that is defined. + + Otherwise, the default emulation depends upon how the linker was + configured. + +'-M' +'--print-map' + Print a link map to the standard output. A link map provides + information about the link, including the following: + + * Where object files are mapped into memory. + * How common symbols are allocated. + * All archive members included in the link, with a mention of + the symbol which caused the archive member to be brought in. + * The values assigned to symbols. + + Note - symbols whose values are computed by an expression + which involves a reference to a previous value of the same + symbol may not have correct result displayed in the link map. + This is because the linker discards intermediate results and + only retains the final value of an expression. Under such + circumstances the linker will display the final value enclosed + by square brackets. Thus for example a linker script + containing: + + foo = 1 + foo = foo * 4 + foo = foo + 8 + + will produce the following output in the link map if the '-M' + option is used: + + 0x00000001 foo = 0x1 + [0x0000000c] foo = (foo * 0x4) + [0x0000000c] foo = (foo + 0x8) + + See *note Expressions:: for more information about expressions + in linker scripts. + +'-n' +'--nmagic' + Turn off page alignment of sections, and mark the output as + 'NMAGIC' if possible. + +'-N' +'--omagic' + Set the text and data sections to be readable and writable. Also, + do not page-align the data segment, and disable linking against + shared libraries. If the output format supports Unix style magic + numbers, mark the output as 'OMAGIC'. Note: Although a writable + text section is allowed for PE-COFF targets, it does not conform to + the format specification published by Microsoft. + +'--no-omagic' + This option negates most of the effects of the '-N' option. It + sets the text section to be read-only, and forces the data segment + to be page-aligned. Note - this option does not enable linking + against shared libraries. Use '-Bdynamic' for this. + +'-o OUTPUT' +'--output=OUTPUT' + Use OUTPUT as the name for the program produced by 'ld'; if this + option is not specified, the name 'a.out' is used by default. The + script command 'OUTPUT' can also specify the output file name. + +'-O LEVEL' + If LEVEL is a numeric values greater than zero 'ld' optimizes the + output. This might take significantly longer and therefore + probably should only be enabled for the final binary. + +'-q' +'--emit-relocs' + Leave relocation sections and contents in fully linked executables. + Post link analysis and optimization tools may need this information + in order to perform correct modifications of executables. This + results in larger executables. + + This option is currently only supported on ELF platforms. + +'--force-dynamic' + Force the output file to have dynamic sections. This option is + specific to VxWorks targets. + +'-r' +'--relocatable' + Generate relocatable output--i.e., generate an output file that can + in turn serve as input to 'ld'. This is often called "partial + linking". As a side effect, in environments that support standard + Unix magic numbers, this option also sets the output file's magic + number to 'OMAGIC'. If this option is not specified, an absolute + file is produced. When linking C++ programs, this option _will + not_ resolve references to constructors; to do that, use '-Ur'. + + When an input file does not have the same format as the output + file, partial linking is only supported if that input file does not + contain any relocations. Different output formats can have further + restrictions; for example some 'a.out'-based formats do not support + partial linking with input files in other formats at all. + + This option does the same thing as '-i'. + +'-R FILENAME' +'--just-symbols=FILENAME' + Read symbol names and their addresses from FILENAME, but do not + relocate it or include it in the output. This allows your output + file to refer symbolically to absolute locations of memory defined + in other programs. You may use this option more than once. + + For compatibility with other ELF linkers, if the '-R' option is + followed by a directory name, rather than a file name, it is + treated as the '-rpath' option. + +'-s' +'--strip-all' + Omit all symbol information from the output file. + +'-S' +'--strip-debug' + Omit debugger symbol information (but not all symbols) from the + output file. + +'-t' +'--trace' + Print the names of the input files as 'ld' processes them. + +'-T SCRIPTFILE' +'--script=SCRIPTFILE' + Use SCRIPTFILE as the linker script. This script replaces 'ld''s + default linker script (rather than adding to it), so COMMANDFILE + must specify everything necessary to describe the output file. + *Note Scripts::. If SCRIPTFILE does not exist in the current + directory, 'ld' looks for it in the directories specified by any + preceding '-L' options. Multiple '-T' options accumulate. + +'-dT SCRIPTFILE' +'--default-script=SCRIPTFILE' + Use SCRIPTFILE as the default linker script. *Note Scripts::. + + This option is similar to the '--script' option except that + processing of the script is delayed until after the rest of the + command line has been processed. This allows options placed after + the '--default-script' option on the command line to affect the + behaviour of the linker script, which can be important when the + linker command line cannot be directly controlled by the user. (eg + because the command line is being constructed by another tool, such + as 'gcc'). + +'-u SYMBOL' +'--undefined=SYMBOL' + Force SYMBOL to be entered in the output file as an undefined + symbol. Doing this may, for example, trigger linking of additional + modules from standard libraries. '-u' may be repeated with + different option arguments to enter additional undefined symbols. + This option is equivalent to the 'EXTERN' linker script command. + +'-Ur' + For anything other than C++ programs, this option is equivalent to + '-r': it generates relocatable output--i.e., an output file that + can in turn serve as input to 'ld'. When linking C++ programs, + '-Ur' _does_ resolve references to constructors, unlike '-r'. It + does not work to use '-Ur' on files that were themselves linked + with '-Ur'; once the constructor table has been built, it cannot be + added to. Use '-Ur' only for the last partial link, and '-r' for + the others. + +'--unique[=SECTION]' + Creates a separate output section for every input section matching + SECTION, or if the optional wildcard SECTION argument is missing, + for every orphan input section. An orphan section is one not + specifically mentioned in a linker script. You may use this option + multiple times on the command line; It prevents the normal merging + of input sections with the same name, overriding output section + assignments in a linker script. + +'-v' +'--version' +'-V' + Display the version number for 'ld'. The '-V' option also lists + the supported emulations. + +'-x' +'--discard-all' + Delete all local symbols. + +'-X' +'--discard-locals' + Delete all temporary local symbols. (These symbols start with + system-specific local label prefixes, typically '.L' for ELF + systems or 'L' for traditional a.out systems.) + +'-y SYMBOL' +'--trace-symbol=SYMBOL' + Print the name of each linked file in which SYMBOL appears. This + option may be given any number of times. On many systems it is + necessary to prepend an underscore. + + This option is useful when you have an undefined symbol in your + link but don't know where the reference is coming from. + +'-Y PATH' + Add PATH to the default library search path. This option exists + for Solaris compatibility. + +'-z KEYWORD' + The recognized keywords are: + + 'combreloc' + Combines multiple reloc sections and sorts them to make + dynamic symbol lookup caching possible. + + 'defs' + Disallows undefined symbols in object files. Undefined + symbols in shared libraries are still allowed. + + 'execstack' + Marks the object as requiring executable stack. + + 'initfirst' + This option is only meaningful when building a shared object. + It marks the object so that its runtime initialization will + occur before the runtime initialization of any other objects + brought into the process at the same time. Similarly the + runtime finalization of the object will occur after the + runtime finalization of any other objects. + + 'interpose' + Marks the object that its symbol table interposes before all + symbols but the primary executable. + + 'lazy' + When generating an executable or shared library, mark it to + tell the dynamic linker to defer function call resolution to + the point when the function is called (lazy binding), rather + than at load time. Lazy binding is the default. + + 'loadfltr' + Marks the object that its filters be processed immediately at + runtime. + + 'muldefs' + Allows multiple definitions. + + 'nocombreloc' + Disables multiple reloc sections combining. + + 'nocopyreloc' + Disables production of copy relocs. + + 'nodefaultlib' + Marks the object that the search for dependencies of this + object will ignore any default library search paths. + + 'nodelete' + Marks the object shouldn't be unloaded at runtime. + + 'nodlopen' + Marks the object not available to 'dlopen'. + + 'nodump' + Marks the object can not be dumped by 'dldump'. + + 'noexecstack' + Marks the object as not requiring executable stack. + + 'norelro' + Don't create an ELF 'PT_GNU_RELRO' segment header in the + object. + + 'now' + When generating an executable or shared library, mark it to + tell the dynamic linker to resolve all symbols when the + program is started, or when the shared library is linked to + using dlopen, instead of deferring function call resolution to + the point when the function is first called. + + 'origin' + Marks the object may contain $ORIGIN. + + 'relro' + Create an ELF 'PT_GNU_RELRO' segment header in the object. + + 'max-page-size=VALUE' + Set the emulation maximum page size to VALUE. + + 'common-page-size=VALUE' + Set the emulation common page size to VALUE. + + Other keywords are ignored for Solaris compatibility. + +'-( ARCHIVES -)' +'--start-group ARCHIVES --end-group' + The ARCHIVES should be a list of archive files. They may be either + explicit file names, or '-l' options. + + The specified archives are searched repeatedly until no new + undefined references are created. Normally, an archive is searched + only once in the order that it is specified on the command line. + If a symbol in that archive is needed to resolve an undefined + symbol referred to by an object in an archive that appears later on + the command line, the linker would not be able to resolve that + reference. By grouping the archives, they all be searched + repeatedly until all possible references are resolved. + + Using this option has a significant performance cost. It is best + to use it only when there are unavoidable circular references + between two or more archives. + +'--accept-unknown-input-arch' +'--no-accept-unknown-input-arch' + Tells the linker to accept input files whose architecture cannot be + recognised. The assumption is that the user knows what they are + doing and deliberately wants to link in these unknown input files. + This was the default behaviour of the linker, before release 2.14. + The default behaviour from release 2.14 onwards is to reject such + input files, and so the '--accept-unknown-input-arch' option has + been added to restore the old behaviour. + +'--as-needed' +'--no-as-needed' + This option affects ELF DT_NEEDED tags for dynamic libraries + mentioned on the command line after the '--as-needed' option. + Normally, the linker will add a DT_NEEDED tag for each dynamic + library mentioned on the command line, regardless of whether the + library is actually needed. '--as-needed' causes DT_NEEDED tags to + only be emitted for libraries that satisfy some symbol reference + from regular objects which is undefined at the point that the + library was linked. '--no-as-needed' restores the default + behaviour. + +'--add-needed' +'--no-add-needed' + This option affects the treatment of dynamic libraries from ELF + DT_NEEDED tags in dynamic libraries mentioned on the command line + after the '--no-add-needed' option. Normally, the linker will add + a DT_NEEDED tag for each dynamic library from DT_NEEDED tags. + '--no-add-needed' causes DT_NEEDED tags will never be emitted for + those libraries from DT_NEEDED tags. '--add-needed' restores the + default behaviour. + +'-assert KEYWORD' + This option is ignored for SunOS compatibility. + +'-Bdynamic' +'-dy' +'-call_shared' + Link against dynamic libraries. This is only meaningful on + platforms for which shared libraries are supported. This option is + normally the default on such platforms. The different variants of + this option are for compatibility with various systems. You may + use this option multiple times on the command line: it affects + library searching for '-l' options which follow it. + +'-Bgroup' + Set the 'DF_1_GROUP' flag in the 'DT_FLAGS_1' entry in the dynamic + section. This causes the runtime linker to handle lookups in this + object and its dependencies to be performed only inside the group. + '--unresolved-symbols=report-all' is implied. This option is only + meaningful on ELF platforms which support shared libraries. + +'-Bstatic' +'-dn' +'-non_shared' +'-static' + Do not link against shared libraries. This is only meaningful on + platforms for which shared libraries are supported. The different + variants of this option are for compatibility with various systems. + You may use this option multiple times on the command line: it + affects library searching for '-l' options which follow it. This + option also implies '--unresolved-symbols=report-all'. This option + can be used with '-shared'. Doing so means that a shared library + is being created but that all of the library's external references + must be resolved by pulling in entries from static libraries. + +'-Bsymbolic' + When creating a shared library, bind references to global symbols + to the definition within the shared library, if any. Normally, it + is possible for a program linked against a shared library to + override the definition within the shared library. This option is + only meaningful on ELF platforms which support shared libraries. + +'-Bsymbolic-functions' + When creating a shared library, bind references to global function + symbols to the definition within the shared library, if any. This + option is only meaningful on ELF platforms which support shared + libraries. + +'--dynamic-list=DYNAMIC-LIST-FILE' + Specify the name of a dynamic list file to the linker. This is + typically used when creating shared libraries to specify a list of + global symbols whose references shouldn't be bound to the + definition within the shared library, or creating dynamically + linked executables to specify a list of symbols which should be + added to the symbol table in the executable. This option is only + meaningful on ELF platforms which support shared libraries. + + The format of the dynamic list is the same as the version node + without scope and node name. See *note VERSION:: for more + information. + +'--dynamic-list-data' + Include all global data symbols to the dynamic list. + +'--dynamic-list-cpp-new' + Provide the builtin dynamic list for C++ operator new and delete. + It is mainly useful for building shared libstdc++. + +'--dynamic-list-cpp-typeinfo' + Provide the builtin dynamic list for C++ runtime type + identification. + +'--check-sections' +'--no-check-sections' + Asks the linker _not_ to check section addresses after they have + been assigned to see if there are any overlaps. Normally the + linker will perform this check, and if it finds any overlaps it + will produce suitable error messages. The linker does know about, + and does make allowances for sections in overlays. The default + behaviour can be restored by using the command line switch + '--check-sections'. + +'--cref' + Output a cross reference table. If a linker map file is being + generated, the cross reference table is printed to the map file. + Otherwise, it is printed on the standard output. + + The format of the table is intentionally simple, so that it may be + easily processed by a script if necessary. The symbols are printed + out, sorted by name. For each symbol, a list of file names is + given. If the symbol is defined, the first file listed is the + location of the definition. The remaining files contain references + to the symbol. + +'--no-define-common' + This option inhibits the assignment of addresses to common symbols. + The script command 'INHIBIT_COMMON_ALLOCATION' has the same effect. + *Note Miscellaneous Commands::. + + The '--no-define-common' option allows decoupling the decision to + assign addresses to Common symbols from the choice of the output + file type; otherwise a non-Relocatable output type forces assigning + addresses to Common symbols. Using '--no-define-common' allows + Common symbols that are referenced from a shared library to be + assigned addresses only in the main program. This eliminates the + unused duplicate space in the shared library, and also prevents any + possible confusion over resolving to the wrong duplicate when there + are many dynamic modules with specialized search paths for runtime + symbol resolution. + +'--defsym SYMBOL=EXPRESSION' + Create a global symbol in the output file, containing the absolute + address given by EXPRESSION. You may use this option as many times + as necessary to define multiple symbols in the command line. A + limited form of arithmetic is supported for the EXPRESSION in this + context: you may give a hexadecimal constant or the name of an + existing symbol, or use '+' and '-' to add or subtract hexadecimal + constants or symbols. If you need more elaborate expressions, + consider using the linker command language from a script (*note + Assignment: Symbol Definitions: Assignments.). _Note:_ there + should be no white space between SYMBOL, the equals sign ("<=>"), + and EXPRESSION. + +'--demangle[=STYLE]' +'--no-demangle' + These options control whether to demangle symbol names in error + messages and other output. When the linker is told to demangle, it + tries to present symbol names in a readable fashion: it strips + leading underscores if they are used by the object file format, and + converts C++ mangled symbol names into user readable names. + Different compilers have different mangling styles. The optional + demangling style argument can be used to choose an appropriate + demangling style for your compiler. The linker will demangle by + default unless the environment variable 'COLLECT_NO_DEMANGLE' is + set. These options may be used to override the default. + +'--dynamic-linker FILE' + Set the name of the dynamic linker. This is only meaningful when + generating dynamically linked ELF executables. The default dynamic + linker is normally correct; don't use this unless you know what you + are doing. + +'--fatal-warnings' + Treat all warnings as errors. + +'--force-exe-suffix' + Make sure that an output file has a .exe suffix. + + If a successfully built fully linked output file does not have a + '.exe' or '.dll' suffix, this option forces the linker to copy the + output file to one of the same name with a '.exe' suffix. This + option is useful when using unmodified Unix makefiles on a + Microsoft Windows host, since some versions of Windows won't run an + image unless it ends in a '.exe' suffix. + +'--gc-sections' +'--no-gc-sections' + Enable garbage collection of unused input sections. It is ignored + on targets that do not support this option. This option is not + compatible with '-r' or '--emit-relocs'. The default behaviour (of + not performing this garbage collection) can be restored by + specifying '--no-gc-sections' on the command line. + +'--print-gc-sections' +'--no-print-gc-sections' + List all sections removed by garbage collection. The listing is + printed on stderr. This option is only effective if garbage + collection has been enabled via the '--gc-sections') option. The + default behaviour (of not listing the sections that are removed) + can be restored by specifying '--no-print-gc-sections' on the + command line. + +'--help' + Print a summary of the command-line options on the standard output + and exit. + +'--target-help' + Print a summary of all target specific options on the standard + output and exit. + +'-Map MAPFILE' + Print a link map to the file MAPFILE. See the description of the + '-M' option, above. + +'--no-keep-memory' + 'ld' normally optimizes for speed over memory usage by caching the + symbol tables of input files in memory. This option tells 'ld' to + instead optimize for memory usage, by rereading the symbol tables + as necessary. This may be required if 'ld' runs out of memory + space while linking a large executable. + +'--no-undefined' +'-z defs' + Report unresolved symbol references from regular object files. + This is done even if the linker is creating a non-symbolic shared + library. The switch '--[no-]allow-shlib-undefined' controls the + behaviour for reporting unresolved references found in shared + libraries being linked in. + +'--allow-multiple-definition' +'-z muldefs' + Normally when a symbol is defined multiple times, the linker will + report a fatal error. These options allow multiple definitions and + the first definition will be used. + +'--allow-shlib-undefined' +'--no-allow-shlib-undefined' + Allows (the default) or disallows undefined symbols in shared + libraries. This switch is similar to '--no-undefined' except that + it determines the behaviour when the undefined symbols are in a + shared library rather than a regular object file. It does not + affect how undefined symbols in regular object files are handled. + + The reason that '--allow-shlib-undefined' is the default is that + the shared library being specified at link time may not be the same + as the one that is available at load time, so the symbols might + actually be resolvable at load time. Plus there are some systems, + (eg BeOS) where undefined symbols in shared libraries is normal. + (The kernel patches them at load time to select which function is + most appropriate for the current architecture. This is used for + example to dynamically select an appropriate memset function). + Apparently it is also normal for HPPA shared libraries to have + undefined symbols. + +'--no-undefined-version' + Normally when a symbol has an undefined version, the linker will + ignore it. This option disallows symbols with undefined version + and a fatal error will be issued instead. + +'--default-symver' + Create and use a default symbol version (the soname) for + unversioned exported symbols. + +'--default-imported-symver' + Create and use a default symbol version (the soname) for + unversioned imported symbols. + +'--no-warn-mismatch' + Normally 'ld' will give an error if you try to link together input + files that are mismatched for some reason, perhaps because they + have been compiled for different processors or for different + endiannesses. This option tells 'ld' that it should silently + permit such possible errors. This option should only be used with + care, in cases when you have taken some special action that ensures + that the linker errors are inappropriate. + +'--no-warn-search-mismatch' + Normally 'ld' will give a warning if it finds an incompatible + library during a library search. This option silences the warning. + +'--no-whole-archive' + Turn off the effect of the '--whole-archive' option for subsequent + archive files. + +'--noinhibit-exec' + Retain the executable output file whenever it is still usable. + Normally, the linker will not produce an output file if it + encounters errors during the link process; it exits without writing + an output file when it issues any error whatsoever. + +'-nostdlib' + Only search library directories explicitly specified on the command + line. Library directories specified in linker scripts (including + linker scripts specified on the command line) are ignored. + +'--oformat OUTPUT-FORMAT' + 'ld' may be configured to support more than one kind of object + file. If your 'ld' is configured this way, you can use the + '--oformat' option to specify the binary format for the output + object file. Even when 'ld' is configured to support alternative + object formats, you don't usually need to specify this, as 'ld' + should be configured to produce as a default output format the most + usual format on each machine. OUTPUT-FORMAT is a text string, the + name of a particular format supported by the BFD libraries. (You + can list the available binary formats with 'objdump -i'.) The + script command 'OUTPUT_FORMAT' can also specify the output format, + but this option overrides it. *Note BFD::. + +'-pie' +'--pic-executable' + Create a position independent executable. This is currently only + supported on ELF platforms. Position independent executables are + similar to shared libraries in that they are relocated by the + dynamic linker to the virtual address the OS chooses for them + (which can vary between invocations). Like normal dynamically + linked executables they can be executed and symbols defined in the + executable cannot be overridden by shared libraries. + +'-qmagic' + This option is ignored for Linux compatibility. + +'-Qy' + This option is ignored for SVR4 compatibility. + +'--relax' + An option with machine dependent effects. This option is only + supported on a few targets. *Note 'ld' and the H8/300: H8/300. + *Note 'ld' and the Intel 960 family: i960. *Note 'ld' and Xtensa + Processors: Xtensa. *Note 'ld' and the 68HC11 and 68HC12: + M68HC11/68HC12. *Note 'ld' and PowerPC 32-bit ELF Support: PowerPC + ELF32. + + On some platforms, the '--relax' option performs global + optimizations that become possible when the linker resolves + addressing in the program, such as relaxing address modes and + synthesizing new instructions in the output object file. + + On some platforms these link time global optimizations may make + symbolic debugging of the resulting executable impossible. This is + known to be the case for the Matsushita MN10200 and MN10300 family + of processors. + + On platforms where this is not supported, '--relax' is accepted, + but ignored. + +'--retain-symbols-file FILENAME' + Retain _only_ the symbols listed in the file FILENAME, discarding + all others. FILENAME is simply a flat file, with one symbol name + per line. This option is especially useful in environments (such + as VxWorks) where a large global symbol table is accumulated + gradually, to conserve run-time memory. + + '--retain-symbols-file' does _not_ discard undefined symbols, or + symbols needed for relocations. + + You may only specify '--retain-symbols-file' once in the command + line. It overrides '-s' and '-S'. + +'-rpath DIR' + Add a directory to the runtime library search path. This is used + when linking an ELF executable with shared objects. All '-rpath' + arguments are concatenated and passed to the runtime linker, which + uses them to locate shared objects at runtime. The '-rpath' option + is also used when locating shared objects which are needed by + shared objects explicitly included in the link; see the description + of the '-rpath-link' option. If '-rpath' is not used when linking + an ELF executable, the contents of the environment variable + 'LD_RUN_PATH' will be used if it is defined. + + The '-rpath' option may also be used on SunOS. By default, on + SunOS, the linker will form a runtime search patch out of all the + '-L' options it is given. If a '-rpath' option is used, the + runtime search path will be formed exclusively using the '-rpath' + options, ignoring the '-L' options. This can be useful when using + gcc, which adds many '-L' options which may be on NFS mounted file + systems. + + For compatibility with other ELF linkers, if the '-R' option is + followed by a directory name, rather than a file name, it is + treated as the '-rpath' option. + +'-rpath-link DIR' + When using ELF or SunOS, one shared library may require another. + This happens when an 'ld -shared' link includes a shared library as + one of the input files. + + When the linker encounters such a dependency when doing a + non-shared, non-relocatable link, it will automatically try to + locate the required shared library and include it in the link, if + it is not included explicitly. In such a case, the '-rpath-link' + option specifies the first set of directories to search. The + '-rpath-link' option may specify a sequence of directory names + either by specifying a list of names separated by colons, or by + appearing multiple times. + + This option should be used with caution as it overrides the search + path that may have been hard compiled into a shared library. In + such a case it is possible to use unintentionally a different + search path than the runtime linker would do. + + The linker uses the following search paths to locate required + shared libraries: + 1. Any directories specified by '-rpath-link' options. + 2. Any directories specified by '-rpath' options. The difference + between '-rpath' and '-rpath-link' is that directories + specified by '-rpath' options are included in the executable + and used at runtime, whereas the '-rpath-link' option is only + effective at link time. Searching '-rpath' in this way is + only supported by native linkers and cross linkers which have + been configured with the '--with-sysroot' option. + 3. On an ELF system, if the '-rpath' and 'rpath-link' options + were not used, search the contents of the environment variable + 'LD_RUN_PATH'. It is for the native linker only. + 4. On SunOS, if the '-rpath' option was not used, search any + directories specified using '-L' options. + 5. For a native linker, the contents of the environment variable + 'LD_LIBRARY_PATH'. + 6. For a native ELF linker, the directories in 'DT_RUNPATH' or + 'DT_RPATH' of a shared library are searched for shared + libraries needed by it. The 'DT_RPATH' entries are ignored if + 'DT_RUNPATH' entries exist. + 7. The default directories, normally '/lib' and '/usr/lib'. + 8. For a native linker on an ELF system, if the file + '/etc/ld.so.conf' exists, the list of directories found in + that file. + + If the required shared library is not found, the linker will issue + a warning and continue with the link. + +'-shared' +'-Bshareable' + Create a shared library. This is currently only supported on ELF, + XCOFF and SunOS platforms. On SunOS, the linker will automatically + create a shared library if the '-e' option is not used and there + are undefined symbols in the link. + +'--sort-common' + This option tells 'ld' to sort the common symbols by size when it + places them in the appropriate output sections. First come all the + one byte symbols, then all the two byte, then all the four byte, + and then everything else. This is to prevent gaps between symbols + due to alignment constraints. + +'--sort-section name' + This option will apply 'SORT_BY_NAME' to all wildcard section + patterns in the linker script. + +'--sort-section alignment' + This option will apply 'SORT_BY_ALIGNMENT' to all wildcard section + patterns in the linker script. + +'--split-by-file [SIZE]' + Similar to '--split-by-reloc' but creates a new output section for + each input file when SIZE is reached. SIZE defaults to a size of 1 + if not given. + +'--split-by-reloc [COUNT]' + Tries to creates extra sections in the output file so that no + single output section in the file contains more than COUNT + relocations. This is useful when generating huge relocatable files + for downloading into certain real time kernels with the COFF object + file format; since COFF cannot represent more than 65535 + relocations in a single section. Note that this will fail to work + with object file formats which do not support arbitrary sections. + The linker will not split up individual input sections for + redistribution, so if a single input section contains more than + COUNT relocations one output section will contain that many + relocations. COUNT defaults to a value of 32768. + +'--stats' + Compute and display statistics about the operation of the linker, + such as execution time and memory usage. + +'--sysroot=DIRECTORY' + Use DIRECTORY as the location of the sysroot, overriding the + configure-time default. This option is only supported by linkers + that were configured using '--with-sysroot'. + +'--traditional-format' + For some targets, the output of 'ld' is different in some ways from + the output of some existing linker. This switch requests 'ld' to + use the traditional format instead. + + For example, on SunOS, 'ld' combines duplicate entries in the + symbol string table. This can reduce the size of an output file + with full debugging information by over 30 percent. Unfortunately, + the SunOS 'dbx' program can not read the resulting program ('gdb' + has no trouble). The '--traditional-format' switch tells 'ld' to + not combine duplicate entries. + +'--section-start SECTIONNAME=ORG' + Locate a section in the output file at the absolute address given + by ORG. You may use this option as many times as necessary to + locate multiple sections in the command line. ORG must be a single + hexadecimal integer; for compatibility with other linkers, you may + omit the leading '0x' usually associated with hexadecimal values. + _Note:_ there should be no white space between SECTIONNAME, the + equals sign ("<=>"), and ORG. + +'-Tbss ORG' +'-Tdata ORG' +'-Ttext ORG' + Same as -section-start, with '.bss', '.data' or '.text' as the + SECTIONNAME. + +'--unresolved-symbols=METHOD' + Determine how to handle unresolved symbols. There are four + possible values for 'method': + + 'ignore-all' + Do not report any unresolved symbols. + + 'report-all' + Report all unresolved symbols. This is the default. + + 'ignore-in-object-files' + Report unresolved symbols that are contained in shared + libraries, but ignore them if they come from regular object + files. + + 'ignore-in-shared-libs' + Report unresolved symbols that come from regular object files, + but ignore them if they come from shared libraries. This can + be useful when creating a dynamic binary and it is known that + all the shared libraries that it should be referencing are + included on the linker's command line. + + The behaviour for shared libraries on their own can also be + controlled by the '--[no-]allow-shlib-undefined' option. + + Normally the linker will generate an error message for each + reported unresolved symbol but the option + '--warn-unresolved-symbols' can change this to a warning. + +'--dll-verbose' +'--verbose' + Display the version number for 'ld' and list the linker emulations + supported. Display which input files can and cannot be opened. + Display the linker script being used by the linker. + +'--version-script=VERSION-SCRIPTFILE' + Specify the name of a version script to the linker. This is + typically used when creating shared libraries to specify additional + information about the version hierarchy for the library being + created. This option is only meaningful on ELF platforms which + support shared libraries. *Note VERSION::. + +'--warn-common' + Warn when a common symbol is combined with another common symbol or + with a symbol definition. Unix linkers allow this somewhat sloppy + practise, but linkers on some other operating systems do not. This + option allows you to find potential problems from combining global + symbols. Unfortunately, some C libraries use this practise, so you + may get some warnings about symbols in the libraries as well as in + your programs. + + There are three kinds of global symbols, illustrated here by C + examples: + + 'int i = 1;' + A definition, which goes in the initialized data section of + the output file. + + 'extern int i;' + An undefined reference, which does not allocate space. There + must be either a definition or a common symbol for the + variable somewhere. + + 'int i;' + A common symbol. If there are only (one or more) common + symbols for a variable, it goes in the uninitialized data area + of the output file. The linker merges multiple common symbols + for the same variable into a single symbol. If they are of + different sizes, it picks the largest size. The linker turns + a common symbol into a declaration, if there is a definition + of the same variable. + + The '--warn-common' option can produce five kinds of warnings. + Each warning consists of a pair of lines: the first describes the + symbol just encountered, and the second describes the previous + symbol encountered with the same name. One or both of the two + symbols will be a common symbol. + + 1. Turning a common symbol into a reference, because there is + already a definition for the symbol. + FILE(SECTION): warning: common of `SYMBOL' + overridden by definition + FILE(SECTION): warning: defined here + + 2. Turning a common symbol into a reference, because a later + definition for the symbol is encountered. This is the same as + the previous case, except that the symbols are encountered in + a different order. + FILE(SECTION): warning: definition of `SYMBOL' + overriding common + FILE(SECTION): warning: common is here + + 3. Merging a common symbol with a previous same-sized common + symbol. + FILE(SECTION): warning: multiple common + of `SYMBOL' + FILE(SECTION): warning: previous common is here + + 4. Merging a common symbol with a previous larger common symbol. + FILE(SECTION): warning: common of `SYMBOL' + overridden by larger common + FILE(SECTION): warning: larger common is here + + 5. Merging a common symbol with a previous smaller common symbol. + This is the same as the previous case, except that the symbols + are encountered in a different order. + FILE(SECTION): warning: common of `SYMBOL' + overriding smaller common + FILE(SECTION): warning: smaller common is here + +'--warn-constructors' + Warn if any global constructors are used. This is only useful for + a few object file formats. For formats like COFF or ELF, the + linker can not detect the use of global constructors. + +'--warn-multiple-gp' + Warn if multiple global pointer values are required in the output + file. This is only meaningful for certain processors, such as the + Alpha. Specifically, some processors put large-valued constants in + a special section. A special register (the global pointer) points + into the middle of this section, so that constants can be loaded + efficiently via a base-register relative addressing mode. Since + the offset in base-register relative mode is fixed and relatively + small (e.g., 16 bits), this limits the maximum size of the constant + pool. Thus, in large programs, it is often necessary to use + multiple global pointer values in order to be able to address all + possible constants. This option causes a warning to be issued + whenever this case occurs. + +'--warn-once' + Only warn once for each undefined symbol, rather than once per + module which refers to it. + +'--warn-section-align' + Warn if the address of an output section is changed because of + alignment. Typically, the alignment will be set by an input + section. The address will only be changed if it not explicitly + specified; that is, if the 'SECTIONS' command does not specify a + start address for the section (*note SECTIONS::). + +'--warn-shared-textrel' + Warn if the linker adds a DT_TEXTREL to a shared object. + +'--warn-unresolved-symbols' + If the linker is going to report an unresolved symbol (see the + option '--unresolved-symbols') it will normally generate an error. + This option makes it generate a warning instead. + +'--error-unresolved-symbols' + This restores the linker's default behaviour of generating errors + when it is reporting unresolved symbols. + +'--whole-archive' + For each archive mentioned on the command line after the + '--whole-archive' option, include every object file in the archive + in the link, rather than searching the archive for the required + object files. This is normally used to turn an archive file into a + shared library, forcing every object to be included in the + resulting shared library. This option may be used more than once. + + Two notes when using this option from gcc: First, gcc doesn't know + about this option, so you have to use '-Wl,-whole-archive'. + Second, don't forget to use '-Wl,-no-whole-archive' after your list + of archives, because gcc will add its own list of archives to your + link and you may not want this flag to affect those as well. + +'--wrap SYMBOL' + Use a wrapper function for SYMBOL. Any undefined reference to + SYMBOL will be resolved to '__wrap_SYMBOL'. Any undefined + reference to '__real_SYMBOL' will be resolved to SYMBOL. + + This can be used to provide a wrapper for a system function. The + wrapper function should be called '__wrap_SYMBOL'. If it wishes to + call the system function, it should call '__real_SYMBOL'. + + Here is a trivial example: + + void * + __wrap_malloc (size_t c) + { + printf ("malloc called with %zu\n", c); + return __real_malloc (c); + } + + If you link other code with this file using '--wrap malloc', then + all calls to 'malloc' will call the function '__wrap_malloc' + instead. The call to '__real_malloc' in '__wrap_malloc' will call + the real 'malloc' function. + + You may wish to provide a '__real_malloc' function as well, so that + links without the '--wrap' option will succeed. If you do this, + you should not put the definition of '__real_malloc' in the same + file as '__wrap_malloc'; if you do, the assembler may resolve the + call before the linker has a chance to wrap it to 'malloc'. + +'--eh-frame-hdr' + Request creation of '.eh_frame_hdr' section and ELF + 'PT_GNU_EH_FRAME' segment header. + +'--enable-new-dtags' +'--disable-new-dtags' + This linker can create the new dynamic tags in ELF. But the older + ELF systems may not understand them. If you specify + '--enable-new-dtags', the dynamic tags will be created as needed. + If you specify '--disable-new-dtags', no new dynamic tags will be + created. By default, the new dynamic tags are not created. Note + that those options are only available for ELF systems. + +'--hash-size=NUMBER' + Set the default size of the linker's hash tables to a prime number + close to NUMBER. Increasing this value can reduce the length of + time it takes the linker to perform its tasks, at the expense of + increasing the linker's memory requirements. Similarly reducing + this value can reduce the memory requirements at the expense of + speed. + +'--hash-style=STYLE' + Set the type of linker's hash table(s). STYLE can be either 'sysv' + for classic ELF '.hash' section, 'gnu' for new style GNU + '.gnu.hash' section or 'both' for both the classic ELF '.hash' and + new style GNU '.gnu.hash' hash tables. The default is 'sysv'. + +'--reduce-memory-overheads' + This option reduces memory requirements at ld runtime, at the + expense of linking speed. This was introduced to select the old + O(n^2) algorithm for link map file generation, rather than the new + O(n) algorithm which uses about 40% more memory for symbol storage. + + Another effect of the switch is to set the default hash table size + to 1021, which again saves memory at the cost of lengthening the + linker's run time. This is not done however if the '--hash-size' + switch has been used. + + The '--reduce-memory-overheads' switch may be also be used to + enable other tradeoffs in future versions of the linker. + +2.1.1 Options Specific to i386 PE Targets +----------------------------------------- + +The i386 PE linker supports the '-shared' option, which causes the +output to be a dynamically linked library (DLL) instead of a normal +executable. You should name the output '*.dll' when you use this +option. In addition, the linker fully supports the standard '*.def' +files, which may be specified on the linker command line like an object +file (in fact, it should precede archives it exports symbols from, to +ensure that they get linked in, just like a normal object file). + + In addition to the options common to all targets, the i386 PE linker +support additional command line options that are specific to the i386 PE +target. Options that take values may be separated from their values by +either a space or an equals sign. + +'--add-stdcall-alias' + If given, symbols with a stdcall suffix (@NN) will be exported + as-is and also with the suffix stripped. [This option is specific + to the i386 PE targeted port of the linker] + +'--base-file FILE' + Use FILE as the name of a file in which to save the base addresses + of all the relocations needed for generating DLLs with 'dlltool'. + [This is an i386 PE specific option] + +'--dll' + Create a DLL instead of a regular executable. You may also use + '-shared' or specify a 'LIBRARY' in a given '.def' file. [This + option is specific to the i386 PE targeted port of the linker] + +'--enable-stdcall-fixup' +'--disable-stdcall-fixup' + If the link finds a symbol that it cannot resolve, it will attempt + to do "fuzzy linking" by looking for another defined symbol that + differs only in the format of the symbol name (cdecl vs stdcall) + and will resolve that symbol by linking to the match. For example, + the undefined symbol '_foo' might be linked to the function + '_foo@12', or the undefined symbol '_bar@16' might be linked to the + function '_bar'. When the linker does this, it prints a warning, + since it normally should have failed to link, but sometimes import + libraries generated from third-party dlls may need this feature to + be usable. If you specify '--enable-stdcall-fixup', this feature + is fully enabled and warnings are not printed. If you specify + '--disable-stdcall-fixup', this feature is disabled and such + mismatches are considered to be errors. [This option is specific + to the i386 PE targeted port of the linker] + +'--export-all-symbols' + If given, all global symbols in the objects used to build a DLL + will be exported by the DLL. Note that this is the default if there + otherwise wouldn't be any exported symbols. When symbols are + explicitly exported via DEF files or implicitly exported via + function attributes, the default is to not export anything else + unless this option is given. Note that the symbols 'DllMain@12', + 'DllEntryPoint@0', 'DllMainCRTStartup@12', and 'impure_ptr' will + not be automatically exported. Also, symbols imported from other + DLLs will not be re-exported, nor will symbols specifying the DLL's + internal layout such as those beginning with '_head_' or ending + with '_iname'. In addition, no symbols from 'libgcc', 'libstd++', + 'libmingw32', or 'crtX.o' will be exported. Symbols whose names + begin with '__rtti_' or '__builtin_' will not be exported, to help + with C++ DLLs. Finally, there is an extensive list of + cygwin-private symbols that are not exported (obviously, this + applies on when building DLLs for cygwin targets). These + cygwin-excludes are: '_cygwin_dll_entry@12', + '_cygwin_crt0_common@8', '_cygwin_noncygwin_dll_entry@12', + '_fmode', '_impure_ptr', 'cygwin_attach_dll', 'cygwin_premain0', + 'cygwin_premain1', 'cygwin_premain2', 'cygwin_premain3', and + 'environ'. [This option is specific to the i386 PE targeted port + of the linker] + +'--exclude-symbols SYMBOL,SYMBOL,...' + Specifies a list of symbols which should not be automatically + exported. The symbol names may be delimited by commas or colons. + [This option is specific to the i386 PE targeted port of the + linker] + +'--file-alignment' + Specify the file alignment. Sections in the file will always begin + at file offsets which are multiples of this number. This defaults + to 512. [This option is specific to the i386 PE targeted port of + the linker] + +'--heap RESERVE' +'--heap RESERVE,COMMIT' + Specify the amount of memory to reserve (and optionally commit) to + be used as heap for this program. The default is 1Mb reserved, 4K + committed. [This option is specific to the i386 PE targeted port + of the linker] + +'--image-base VALUE' + Use VALUE as the base address of your program or dll. This is the + lowest memory location that will be used when your program or dll + is loaded. To reduce the need to relocate and improve performance + of your dlls, each should have a unique base address and not + overlap any other dlls. The default is 0x400000 for executables, + and 0x10000000 for dlls. [This option is specific to the i386 PE + targeted port of the linker] + +'--kill-at' + If given, the stdcall suffixes (@NN) will be stripped from symbols + before they are exported. [This option is specific to the i386 PE + targeted port of the linker] + +'--large-address-aware' + If given, the appropriate bit in the "Characteristics" field of the + COFF header is set to indicate that this executable supports + virtual addresses greater than 2 gigabytes. This should be used in + conjunction with the /3GB or /USERVA=VALUE megabytes switch in the + "[operating systems]" section of the BOOT.INI. Otherwise, this bit + has no effect. [This option is specific to PE targeted ports of + the linker] + +'--major-image-version VALUE' + Sets the major number of the "image version". Defaults to 1. + [This option is specific to the i386 PE targeted port of the + linker] + +'--major-os-version VALUE' + Sets the major number of the "os version". Defaults to 4. [This + option is specific to the i386 PE targeted port of the linker] + +'--major-subsystem-version VALUE' + Sets the major number of the "subsystem version". Defaults to 4. + [This option is specific to the i386 PE targeted port of the + linker] + +'--minor-image-version VALUE' + Sets the minor number of the "image version". Defaults to 0. + [This option is specific to the i386 PE targeted port of the + linker] + +'--minor-os-version VALUE' + Sets the minor number of the "os version". Defaults to 0. [This + option is specific to the i386 PE targeted port of the linker] + +'--minor-subsystem-version VALUE' + Sets the minor number of the "subsystem version". Defaults to 0. + [This option is specific to the i386 PE targeted port of the + linker] + +'--output-def FILE' + The linker will create the file FILE which will contain a DEF file + corresponding to the DLL the linker is generating. This DEF file + (which should be called '*.def') may be used to create an import + library with 'dlltool' or may be used as a reference to + automatically or implicitly exported symbols. [This option is + specific to the i386 PE targeted port of the linker] + +'--out-implib FILE' + The linker will create the file FILE which will contain an import + lib corresponding to the DLL the linker is generating. This import + lib (which should be called '*.dll.a' or '*.a' may be used to link + clients against the generated DLL; this behaviour makes it possible + to skip a separate 'dlltool' import library creation step. [This + option is specific to the i386 PE targeted port of the linker] + +'--enable-auto-image-base' + Automatically choose the image base for DLLs, unless one is + specified using the '--image-base' argument. By using a hash + generated from the dllname to create unique image bases for each + DLL, in-memory collisions and relocations which can delay program + execution are avoided. [This option is specific to the i386 PE + targeted port of the linker] + +'--disable-auto-image-base' + Do not automatically generate a unique image base. If there is no + user-specified image base ('--image-base') then use the platform + default. [This option is specific to the i386 PE targeted port of + the linker] + +'--dll-search-prefix STRING' + When linking dynamically to a dll without an import library, search + for '<string><basename>.dll' in preference to 'lib<basename>.dll'. + This behaviour allows easy distinction between DLLs built for the + various "subplatforms": native, cygwin, uwin, pw, etc. For + instance, cygwin DLLs typically use '--dll-search-prefix=cyg'. + [This option is specific to the i386 PE targeted port of the + linker] + +'--enable-auto-import' + Do sophisticated linking of '_symbol' to '__imp__symbol' for DATA + imports from DLLs, and create the necessary thunking symbols when + building the import libraries with those DATA exports. Note: Use + of the 'auto-import' extension will cause the text section of the + image file to be made writable. This does not conform to the + PE-COFF format specification published by Microsoft. + + Using 'auto-import' generally will 'just work' - but sometimes you + may see this message: + + "variable '<var>' can't be auto-imported. Please read the + documentation for ld's '--enable-auto-import' for details." + + This message occurs when some (sub)expression accesses an address + ultimately given by the sum of two constants (Win32 import tables + only allow one). Instances where this may occur include accesses + to member fields of struct variables imported from a DLL, as well + as using a constant index into an array variable imported from a + DLL. Any multiword variable (arrays, structs, long long, etc) may + trigger this error condition. However, regardless of the exact + data type of the offending exported variable, ld will always detect + it, issue the warning, and exit. + + There are several ways to address this difficulty, regardless of + the data type of the exported variable: + + One way is to use -enable-runtime-pseudo-reloc switch. This leaves + the task of adjusting references in your client code for runtime + environment, so this method works only when runtime environment + supports this feature. + + A second solution is to force one of the 'constants' to be a + variable - that is, unknown and un-optimizable at compile time. + For arrays, there are two possibilities: a) make the indexee (the + array's address) a variable, or b) make the 'constant' index a + variable. Thus: + + extern type extern_array[]; + extern_array[1] --> + { volatile type *t=extern_array; t[1] } + + or + + extern type extern_array[]; + extern_array[1] --> + { volatile int t=1; extern_array[t] } + + For structs (and most other multiword data types) the only option + is to make the struct itself (or the long long, or the ...) + variable: + + extern struct s extern_struct; + extern_struct.field --> + { volatile struct s *t=&extern_struct; t->field } + + or + + extern long long extern_ll; + extern_ll --> + { volatile long long * local_ll=&extern_ll; *local_ll } + + A third method of dealing with this difficulty is to abandon + 'auto-import' for the offending symbol and mark it with + '__declspec(dllimport)'. However, in practise that requires using + compile-time #defines to indicate whether you are building a DLL, + building client code that will link to the DLL, or merely + building/linking to a static library. In making the choice between + the various methods of resolving the 'direct address with constant + offset' problem, you should consider typical real-world usage: + + Original: + --foo.h + extern int arr[]; + --foo.c + #include "foo.h" + void main(int argc, char **argv){ + printf("%d\n",arr[1]); + } + + Solution 1: + --foo.h + extern int arr[]; + --foo.c + #include "foo.h" + void main(int argc, char **argv){ + /* This workaround is for win32 and cygwin; do not "optimize" */ + volatile int *parr = arr; + printf("%d\n",parr[1]); + } + + Solution 2: + --foo.h + /* Note: auto-export is assumed (no __declspec(dllexport)) */ + #if (defined(_WIN32) || defined(__CYGWIN__)) && \ + !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC)) + #define FOO_IMPORT __declspec(dllimport) + #else + #define FOO_IMPORT + #endif + extern FOO_IMPORT int arr[]; + --foo.c + #include "foo.h" + void main(int argc, char **argv){ + printf("%d\n",arr[1]); + } + + A fourth way to avoid this problem is to re-code your library to + use a functional interface rather than a data interface for the + offending variables (e.g. set_foo() and get_foo() accessor + functions). [This option is specific to the i386 PE targeted port + of the linker] + +'--disable-auto-import' + Do not attempt to do sophisticated linking of '_symbol' to + '__imp__symbol' for DATA imports from DLLs. [This option is + specific to the i386 PE targeted port of the linker] + +'--enable-runtime-pseudo-reloc' + If your code contains expressions described in -enable-auto-import + section, that is, DATA imports from DLL with non-zero offset, this + switch will create a vector of 'runtime pseudo relocations' which + can be used by runtime environment to adjust references to such + data in your client code. [This option is specific to the i386 PE + targeted port of the linker] + +'--disable-runtime-pseudo-reloc' + Do not create pseudo relocations for non-zero offset DATA imports + from DLLs. This is the default. [This option is specific to the + i386 PE targeted port of the linker] + +'--enable-extra-pe-debug' + Show additional debug info related to auto-import symbol thunking. + [This option is specific to the i386 PE targeted port of the + linker] + +'--section-alignment' + Sets the section alignment. Sections in memory will always begin + at addresses which are a multiple of this number. Defaults to + 0x1000. [This option is specific to the i386 PE targeted port of + the linker] + +'--stack RESERVE' +'--stack RESERVE,COMMIT' + Specify the amount of memory to reserve (and optionally commit) to + be used as stack for this program. The default is 2Mb reserved, 4K + committed. [This option is specific to the i386 PE targeted port + of the linker] + +'--subsystem WHICH' +'--subsystem WHICH:MAJOR' +'--subsystem WHICH:MAJOR.MINOR' + Specifies the subsystem under which your program will execute. The + legal values for WHICH are 'native', 'windows', 'console', 'posix', + and 'xbox'. You may optionally set the subsystem version also. + Numeric values are also accepted for WHICH. [This option is + specific to the i386 PE targeted port of the linker] + +2.1.2 Options specific to Motorola 68HC11 and 68HC12 targets +------------------------------------------------------------ + +The 68HC11 and 68HC12 linkers support specific options to control the +memory bank switching mapping and trampoline code generation. + +'--no-trampoline' + This option disables the generation of trampoline. By default a + trampoline is generated for each far function which is called using + a 'jsr' instruction (this happens when a pointer to a far function + is taken). + +'--bank-window NAME' + This option indicates to the linker the name of the memory region + in the 'MEMORY' specification that describes the memory bank + window. The definition of such region is then used by the linker + to compute paging and addresses within the memory window. + +2.2 Environment Variables +========================= + +You can change the behaviour of 'ld' with the environment variables +'GNUTARGET', 'LDEMULATION' and 'COLLECT_NO_DEMANGLE'. + + 'GNUTARGET' determines the input-file object format if you don't use +'-b' (or its synonym '--format'). Its value should be one of the BFD +names for an input format (*note BFD::). If there is no 'GNUTARGET' in +the environment, 'ld' uses the natural format of the target. If +'GNUTARGET' is set to 'default' then BFD attempts to discover the input +format by examining binary input files; this method often succeeds, but +there are potential ambiguities, since there is no method of ensuring +that the magic number used to specify object-file formats is unique. +However, the configuration procedure for BFD on each system places the +conventional format for that system first in the search-list, so +ambiguities are resolved in favor of convention. + + 'LDEMULATION' determines the default emulation if you don't use the +'-m' option. The emulation can affect various aspects of linker +behaviour, particularly the default linker script. You can list the +available emulations with the '--verbose' or '-V' options. If the '-m' +option is not used, and the 'LDEMULATION' environment variable is not +defined, the default emulation depends upon how the linker was +configured. + + Normally, the linker will default to demangling symbols. However, if +'COLLECT_NO_DEMANGLE' is set in the environment, then it will default to +not demangling symbols. This environment variable is used in a similar +fashion by the 'gcc' linker wrapper program. The default may be +overridden by the '--demangle' and '--no-demangle' options. + +3 Linker Scripts +**************** + +Every link is controlled by a "linker script". This script is written +in the linker command language. + + The main purpose of the linker script is to describe how the sections +in the input files should be mapped into the output file, and to control +the memory layout of the output file. Most linker scripts do nothing +more than this. However, when necessary, the linker script can also +direct the linker to perform many other operations, using the commands +described below. + + The linker always uses a linker script. If you do not supply one +yourself, the linker will use a default script that is compiled into the +linker executable. You can use the '--verbose' command line option to +display the default linker script. Certain command line options, such +as '-r' or '-N', will affect the default linker script. + + You may supply your own linker script by using the '-T' command line +option. When you do this, your linker script will replace the default +linker script. + + You may also use linker scripts implicitly by naming them as input +files to the linker, as though they were files to be linked. *Note +Implicit Linker Scripts::. + +3.1 Basic Linker Script Concepts +================================ + +We need to define some basic concepts and vocabulary in order to +describe the linker script language. + + The linker combines input files into a single output file. The +output file and each input file are in a special data format known as an +"object file format". Each file is called an "object file". The output +file is often called an "executable", but for our purposes we will also +call it an object file. Each object file has, among other things, a +list of "sections". We sometimes refer to a section in an input file as +an "input section"; similarly, a section in the output file is an +"output section". + + Each section in an object file has a name and a size. Most sections +also have an associated block of data, known as the "section contents". +A section may be marked as "loadable", which mean that the contents +should be loaded into memory when the output file is run. A section +with no contents may be "allocatable", which means that an area in +memory should be set aside, but nothing in particular should be loaded +there (in some cases this memory must be zeroed out). A section which +is neither loadable nor allocatable typically contains some sort of +debugging information. + + Every loadable or allocatable output section has two addresses. The +first is the "VMA", or virtual memory address. This is the address the +section will have when the output file is run. The second is the "LMA", +or load memory address. This is the address at which the section will +be loaded. In most cases the two addresses will be the same. An +example of when they might be different is when a data section is loaded +into ROM, and then copied into RAM when the program starts up (this +technique is often used to initialize global variables in a ROM based +system). In this case the ROM address would be the LMA, and the RAM +address would be the VMA. + + You can see the sections in an object file by using the 'objdump' +program with the '-h' option. + + Every object file also has a list of "symbols", known as the "symbol +table". A symbol may be defined or undefined. Each symbol has a name, +and each defined symbol has an address, among other information. If you +compile a C or C++ program into an object file, you will get a defined +symbol for every defined function and global or static variable. Every +undefined function or global variable which is referenced in the input +file will become an undefined symbol. + + You can see the symbols in an object file by using the 'nm' program, +or by using the 'objdump' program with the '-t' option. + +3.2 Linker Script Format +======================== + +Linker scripts are text files. + + You write a linker script as a series of commands. Each command is +either a keyword, possibly followed by arguments, or an assignment to a +symbol. You may separate commands using semicolons. Whitespace is +generally ignored. + + Strings such as file or format names can normally be entered +directly. If the file name contains a character such as a comma which +would otherwise serve to separate file names, you may put the file name +in double quotes. There is no way to use a double quote character in a +file name. + + You may include comments in linker scripts just as in C, delimited by +'/*' and '*/'. As in C, comments are syntactically equivalent to +whitespace. + +3.3 Simple Linker Script Example +================================ + +Many linker scripts are fairly simple. + + The simplest possible linker script has just one command: 'SECTIONS'. +You use the 'SECTIONS' command to describe the memory layout of the +output file. + + The 'SECTIONS' command is a powerful command. Here we will describe +a simple use of it. Let's assume your program consists only of code, +initialized data, and uninitialized data. These will be in the '.text', +'.data', and '.bss' sections, respectively. Let's assume further that +these are the only sections which appear in your input files. + + For this example, let's say that the code should be loaded at address +0x10000, and that the data should start at address 0x8000000. Here is a +linker script which will do that: + SECTIONS + { + . = 0x10000; + .text : { *(.text) } + . = 0x8000000; + .data : { *(.data) } + .bss : { *(.bss) } + } + + You write the 'SECTIONS' command as the keyword 'SECTIONS', followed +by a series of symbol assignments and output section descriptions +enclosed in curly braces. + + The first line inside the 'SECTIONS' command of the above example +sets the value of the special symbol '.', which is the location counter. +If you do not specify the address of an output section in some other way +(other ways are described later), the address is set from the current +value of the location counter. The location counter is then incremented +by the size of the output section. At the start of the 'SECTIONS' +command, the location counter has the value '0'. + + The second line defines an output section, '.text'. The colon is +required syntax which may be ignored for now. Within the curly braces +after the output section name, you list the names of the input sections +which should be placed into this output section. The '*' is a wildcard +which matches any file name. The expression '*(.text)' means all +'.text' input sections in all input files. + + Since the location counter is '0x10000' when the output section +'.text' is defined, the linker will set the address of the '.text' +section in the output file to be '0x10000'. + + The remaining lines define the '.data' and '.bss' sections in the +output file. The linker will place the '.data' output section at +address '0x8000000'. After the linker places the '.data' output +section, the value of the location counter will be '0x8000000' plus the +size of the '.data' output section. The effect is that the linker will +place the '.bss' output section immediately after the '.data' output +section in memory. + + The linker will ensure that each output section has the required +alignment, by increasing the location counter if necessary. In this +example, the specified addresses for the '.text' and '.data' sections +will probably satisfy any alignment constraints, but the linker may have +to create a small gap between the '.data' and '.bss' sections. + + That's it! That's a simple and complete linker script. + +3.4 Simple Linker Script Commands +================================= + +In this section we describe the simple linker script commands. + +3.4.1 Setting the Entry Point +----------------------------- + +The first instruction to execute in a program is called the "entry +point". You can use the 'ENTRY' linker script command to set the entry +point. The argument is a symbol name: + ENTRY(SYMBOL) + + There are several ways to set the entry point. The linker will set +the entry point by trying each of the following methods in order, and +stopping when one of them succeeds: + * the '-e' ENTRY command-line option; + * the 'ENTRY(SYMBOL)' command in a linker script; + * the value of the symbol 'start', if defined; + * the address of the first byte of the '.text' section, if present; + * The address '0'. + +3.4.2 Commands Dealing with Files +--------------------------------- + +Several linker script commands deal with files. + +'INCLUDE FILENAME' + Include the linker script FILENAME at this point. The file will be + searched for in the current directory, and in any directory + specified with the '-L' option. You can nest calls to 'INCLUDE' up + to 10 levels deep. + +'INPUT(FILE, FILE, ...)' +'INPUT(FILE FILE ...)' + The 'INPUT' command directs the linker to include the named files + in the link, as though they were named on the command line. + + For example, if you always want to include 'subr.o' any time you do + a link, but you can't be bothered to put it on every link command + line, then you can put 'INPUT (subr.o)' in your linker script. + + In fact, if you like, you can list all of your input files in the + linker script, and then invoke the linker with nothing but a '-T' + option. + + In case a "sysroot prefix" is configured, and the filename starts + with the '/' character, and the script being processed was located + inside the "sysroot prefix", the filename will be looked for in the + "sysroot prefix". Otherwise, the linker will try to open the file + in the current directory. If it is not found, the linker will + search through the archive library search path. See the + description of '-L' in *note Command Line Options: Options. + + If you use 'INPUT (-lFILE)', 'ld' will transform the name to + 'libFILE.a', as with the command line argument '-l'. + + When you use the 'INPUT' command in an implicit linker script, the + files will be included in the link at the point at which the linker + script file is included. This can affect archive searching. + +'GROUP(FILE, FILE, ...)' +'GROUP(FILE FILE ...)' + The 'GROUP' command is like 'INPUT', except that the named files + should all be archives, and they are searched repeatedly until no + new undefined references are created. See the description of '-(' + in *note Command Line Options: Options. + +'AS_NEEDED(FILE, FILE, ...)' +'AS_NEEDED(FILE FILE ...)' + This construct can appear only inside of the 'INPUT' or 'GROUP' + commands, among other filenames. The files listed will be handled + as if they appear directly in the 'INPUT' or 'GROUP' commands, with + the exception of ELF shared libraries, that will be added only when + they are actually needed. This construct essentially enables + '--as-needed' option for all the files listed inside of it and + restores previous '--as-needed' resp. '--no-as-needed' setting + afterwards. + +'OUTPUT(FILENAME)' + The 'OUTPUT' command names the output file. Using + 'OUTPUT(FILENAME)' in the linker script is exactly like using '-o + FILENAME' on the command line (*note Command Line Options: + Options.). If both are used, the command line option takes + precedence. + + You can use the 'OUTPUT' command to define a default name for the + output file other than the usual default of 'a.out'. + +'SEARCH_DIR(PATH)' + The 'SEARCH_DIR' command adds PATH to the list of paths where 'ld' + looks for archive libraries. Using 'SEARCH_DIR(PATH)' is exactly + like using '-L PATH' on the command line (*note Command Line + Options: Options.). If both are used, then the linker will search + both paths. Paths specified using the command line option are + searched first. + +'STARTUP(FILENAME)' + The 'STARTUP' command is just like the 'INPUT' command, except that + FILENAME will become the first input file to be linked, as though + it were specified first on the command line. This may be useful + when using a system in which the entry point is always the start of + the first file. + +3.4.3 Commands Dealing with Object File Formats +----------------------------------------------- + +A couple of linker script commands deal with object file formats. + +'OUTPUT_FORMAT(BFDNAME)' +'OUTPUT_FORMAT(DEFAULT, BIG, LITTLE)' + The 'OUTPUT_FORMAT' command names the BFD format to use for the + output file (*note BFD::). Using 'OUTPUT_FORMAT(BFDNAME)' is + exactly like using '--oformat BFDNAME' on the command line (*note + Command Line Options: Options.). If both are used, the command + line option takes precedence. + + You can use 'OUTPUT_FORMAT' with three arguments to use different + formats based on the '-EB' and '-EL' command line options. This + permits the linker script to set the output format based on the + desired endianness. + + If neither '-EB' nor '-EL' are used, then the output format will be + the first argument, DEFAULT. If '-EB' is used, the output format + will be the second argument, BIG. If '-EL' is used, the output + format will be the third argument, LITTLE. + + For example, the default linker script for the MIPS ELF target uses + this command: + OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips) + This says that the default format for the output file is + 'elf32-bigmips', but if the user uses the '-EL' command line + option, the output file will be created in the 'elf32-littlemips' + format. + +'TARGET(BFDNAME)' + The 'TARGET' command names the BFD format to use when reading input + files. It affects subsequent 'INPUT' and 'GROUP' commands. This + command is like using '-b BFDNAME' on the command line (*note + Command Line Options: Options.). If the 'TARGET' command is used + but 'OUTPUT_FORMAT' is not, then the last 'TARGET' command is also + used to set the format for the output file. *Note BFD::. + +3.4.4 Other Linker Script Commands +---------------------------------- + +There are a few other linker scripts commands. + +'ASSERT(EXP, MESSAGE)' + Ensure that EXP is non-zero. If it is zero, then exit the linker + with an error code, and print MESSAGE. + +'EXTERN(SYMBOL SYMBOL ...)' + Force SYMBOL to be entered in the output file as an undefined + symbol. Doing this may, for example, trigger linking of additional + modules from standard libraries. You may list several SYMBOLs for + each 'EXTERN', and you may use 'EXTERN' multiple times. This + command has the same effect as the '-u' command-line option. + +'FORCE_COMMON_ALLOCATION' + This command has the same effect as the '-d' command-line option: + to make 'ld' assign space to common symbols even if a relocatable + output file is specified ('-r'). + +'INHIBIT_COMMON_ALLOCATION' + This command has the same effect as the '--no-define-common' + command-line option: to make 'ld' omit the assignment of addresses + to common symbols even for a non-relocatable output file. + +'NOCROSSREFS(SECTION SECTION ...)' + This command may be used to tell 'ld' to issue an error about any + references among certain output sections. + + In certain types of programs, particularly on embedded systems when + using overlays, when one section is loaded into memory, another + section will not be. Any direct references between the two + sections would be errors. For example, it would be an error if + code in one section called a function defined in the other section. + + The 'NOCROSSREFS' command takes a list of output section names. If + 'ld' detects any cross references between the sections, it reports + an error and returns a non-zero exit status. Note that the + 'NOCROSSREFS' command uses output section names, not input section + names. + +'OUTPUT_ARCH(BFDARCH)' + Specify a particular output machine architecture. The argument is + one of the names used by the BFD library (*note BFD::). You can + see the architecture of an object file by using the 'objdump' + program with the '-f' option. + +3.5 Assigning Values to Symbols +=============================== + +You may assign a value to a symbol in a linker script. This will define +the symbol and place it into the symbol table with a global scope. + +3.5.1 Simple Assignments +------------------------ + +You may assign to a symbol using any of the C assignment operators: + +'SYMBOL = EXPRESSION ;' +'SYMBOL += EXPRESSION ;' +'SYMBOL -= EXPRESSION ;' +'SYMBOL *= EXPRESSION ;' +'SYMBOL /= EXPRESSION ;' +'SYMBOL <<= EXPRESSION ;' +'SYMBOL >>= EXPRESSION ;' +'SYMBOL &= EXPRESSION ;' +'SYMBOL |= EXPRESSION ;' + + The first case will define SYMBOL to the value of EXPRESSION. In the +other cases, SYMBOL must already be defined, and the value will be +adjusted accordingly. + + The special symbol name '.' indicates the location counter. You may +only use this within a 'SECTIONS' command. *Note Location Counter::. + + The semicolon after EXPRESSION is required. + + Expressions are defined below; see *note Expressions::. + + You may write symbol assignments as commands in their own right, or +as statements within a 'SECTIONS' command, or as part of an output +section description in a 'SECTIONS' command. + + The section of the symbol will be set from the section of the +expression; for more information, see *note Expression Section::. + + Here is an example showing the three different places that symbol +assignments may be used: + + floating_point = 0; + SECTIONS + { + .text : + { + *(.text) + _etext = .; + } + _bdata = (. + 3) & ~ 3; + .data : { *(.data) } + } +In this example, the symbol 'floating_point' will be defined as zero. +The symbol '_etext' will be defined as the address following the last +'.text' input section. The symbol '_bdata' will be defined as the +address following the '.text' output section aligned upward to a 4 byte +boundary. + +3.5.2 PROVIDE +------------- + +In some cases, it is desirable for a linker script to define a symbol +only if it is referenced and is not defined by any object included in +the link. For example, traditional linkers defined the symbol 'etext'. +However, ANSI C requires that the user be able to use 'etext' as a +function name without encountering an error. The 'PROVIDE' keyword may +be used to define a symbol, such as 'etext', only if it is referenced +but not defined. The syntax is 'PROVIDE(SYMBOL = EXPRESSION)'. + + Here is an example of using 'PROVIDE' to define 'etext': + SECTIONS + { + .text : + { + *(.text) + _etext = .; + PROVIDE(etext = .); + } + } + + In this example, if the program defines '_etext' (with a leading +underscore), the linker will give a multiple definition error. If, on +the other hand, the program defines 'etext' (with no leading +underscore), the linker will silently use the definition in the program. +If the program references 'etext' but does not define it, the linker +will use the definition in the linker script. + +3.5.3 PROVIDE_HIDDEN +-------------------- + +Similar to 'PROVIDE'. For ELF targeted ports, the symbol will be hidden +and won't be exported. + +3.5.4 Source Code Reference +--------------------------- + +Accessing a linker script defined variable from source code is not +intuitive. In particular a linker script symbol is not equivalent to a +variable declaration in a high level language, it is instead a symbol +that does not have a value. + + Before going further, it is important to note that compilers often +transform names in the source code into different names when they are +stored in the symbol table. For example, Fortran compilers commonly +prepend or append an underscore, and C++ performs extensive 'name +mangling'. Therefore there might be a discrepancy between the name of a +variable as it is used in source code and the name of the same variable +as it is defined in a linker script. For example in C a linker script +variable might be referred to as: + + extern int foo; + + But in the linker script it might be defined as: + + _foo = 1000; + + In the remaining examples however it is assumed that no name +transformation has taken place. + + When a symbol is declared in a high level language such as C, two +things happen. The first is that the compiler reserves enough space in +the program's memory to hold the _value_ of the symbol. The second is +that the compiler creates an entry in the program's symbol table which +holds the symbol's _address_. ie the symbol table contains the address +of the block of memory holding the symbol's value. So for example the +following C declaration, at file scope: + + int foo = 1000; + + creates a entry called 'foo' in the symbol table. This entry holds +the address of an 'int' sized block of memory where the number 1000 is +initially stored. + + When a program references a symbol the compiler generates code that +first accesses the symbol table to find the address of the symbol's +memory block and then code to read the value from that memory block. +So: + + foo = 1; + + looks up the symbol 'foo' in the symbol table, gets the address +associated with this symbol and then writes the value 1 into that +address. Whereas: + + int * a = & foo; + + looks up the symbol 'foo' in the symbol table, gets it address and +then copies this address into the block of memory associated with the +variable 'a'. + + Linker scripts symbol declarations, by contrast, create an entry in +the symbol table but do not assign any memory to them. Thus they are an +address without a value. So for example the linker script definition: + + foo = 1000; + + creates an entry in the symbol table called 'foo' which holds the +address of memory location 1000, but nothing special is stored at +address 1000. This means that you cannot access the _value_ of a linker +script defined symbol - it has no value - all you can do is access the +_address_ of a linker script defined symbol. + + Hence when you are using a linker script defined symbol in source +code you should always take the address of the symbol, and never attempt +to use its value. For example suppose you want to copy the contents of +a section of memory called .ROM into a section called .FLASH and the +linker script contains these declarations: + + start_of_ROM = .ROM; + end_of_ROM = .ROM + sizeof (.ROM) - 1; + start_of_FLASH = .FLASH; + + Then the C source code to perform the copy would be: + + extern char start_of_ROM, end_of_ROM, start_of_FLASH; + + memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM); + + Note the use of the '&' operators. These are correct. + +3.6 SECTIONS Command +==================== + +The 'SECTIONS' command tells the linker how to map input sections into +output sections, and how to place the output sections in memory. + + The format of the 'SECTIONS' command is: + SECTIONS + { + SECTIONS-COMMAND + SECTIONS-COMMAND + ... + } + + Each SECTIONS-COMMAND may of be one of the following: + + * an 'ENTRY' command (*note Entry command: Entry Point.) + * a symbol assignment (*note Assignments::) + * an output section description + * an overlay description + + The 'ENTRY' command and symbol assignments are permitted inside the +'SECTIONS' command for convenience in using the location counter in +those commands. This can also make the linker script easier to +understand because you can use those commands at meaningful points in +the layout of the output file. + + Output section descriptions and overlay descriptions are described +below. + + If you do not use a 'SECTIONS' command in your linker script, the +linker will place each input section into an identically named output +section in the order that the sections are first encountered in the +input files. If all input sections are present in the first file, for +example, the order of sections in the output file will match the order +in the first input file. The first section will be at address zero. + +3.6.1 Output Section Description +-------------------------------- + +The full description of an output section looks like this: + SECTION [ADDRESS] [(TYPE)] : + [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)] + { + OUTPUT-SECTION-COMMAND + OUTPUT-SECTION-COMMAND + ... + } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP] + + Most output sections do not use most of the optional section +attributes. + + The whitespace around SECTION is required, so that the section name +is unambiguous. The colon and the curly braces are also required. The +line breaks and other white space are optional. + + Each OUTPUT-SECTION-COMMAND may be one of the following: + + * a symbol assignment (*note Assignments::) + * an input section description (*note Input Section::) + * data values to include directly (*note Output Section Data::) + * a special output section keyword (*note Output Section Keywords::) + +3.6.2 Output Section Name +------------------------- + +The name of the output section is SECTION. SECTION must meet the +constraints of your output format. In formats which only support a +limited number of sections, such as 'a.out', the name must be one of the +names supported by the format ('a.out', for example, allows only +'.text', '.data' or '.bss'). If the output format supports any number +of sections, but with numbers and not names (as is the case for Oasys), +the name should be supplied as a quoted numeric string. A section name +may consist of any sequence of characters, but a name which contains any +unusual characters such as commas must be quoted. + + The output section name '/DISCARD/' is special; *note Output Section +Discarding::. + +3.6.3 Output Section Address +---------------------------- + +The ADDRESS is an expression for the VMA (the virtual memory address) of +the output section. If you do not provide ADDRESS, the linker will set +it based on REGION if present, or otherwise based on the current value +of the location counter. + + If you provide ADDRESS, the address of the output section will be set +to precisely that. If you provide neither ADDRESS nor REGION, then the +address of the output section will be set to the current value of the +location counter aligned to the alignment requirements of the output +section. The alignment requirement of the output section is the +strictest alignment of any input section contained within the output +section. + + For example, + .text . : { *(.text) } +and + .text : { *(.text) } +are subtly different. The first will set the address of the '.text' +output section to the current value of the location counter. The second +will set it to the current value of the location counter aligned to the +strictest alignment of a '.text' input section. + + The ADDRESS may be an arbitrary expression; *note Expressions::. For +example, if you want to align the section on a 0x10 byte boundary, so +that the lowest four bits of the section address are zero, you could do +something like this: + .text ALIGN(0x10) : { *(.text) } +This works because 'ALIGN' returns the current location counter aligned +upward to the specified value. + + Specifying ADDRESS for a section will change the value of the +location counter. + +3.6.4 Input Section Description +------------------------------- + +The most common output section command is an input section description. + + The input section description is the most basic linker script +operation. You use output sections to tell the linker how to lay out +your program in memory. You use input section descriptions to tell the +linker how to map the input files into your memory layout. + +3.6.4.1 Input Section Basics +............................ + +An input section description consists of a file name optionally followed +by a list of section names in parentheses. + + The file name and the section name may be wildcard patterns, which we +describe further below (*note Input Section Wildcards::). + + The most common input section description is to include all input +sections with a particular name in the output section. For example, to +include all input '.text' sections, you would write: + *(.text) +Here the '*' is a wildcard which matches any file name. To exclude a +list of files from matching the file name wildcard, EXCLUDE_FILE may be +used to match all files except the ones specified in the EXCLUDE_FILE +list. For example: + (*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)) + will cause all .ctors sections from all files except 'crtend.o' and +'otherfile.o' to be included. + + There are two ways to include more than one section: + *(.text .rdata) + *(.text) *(.rdata) +The difference between these is the order in which the '.text' and +'.rdata' input sections will appear in the output section. In the first +example, they will be intermingled, appearing in the same order as they +are found in the linker input. In the second example, all '.text' input +sections will appear first, followed by all '.rdata' input sections. + + You can specify a file name to include sections from a particular +file. You would do this if one or more of your files contain special +data that needs to be at a particular location in memory. For example: + data.o(.data) + + If you use a file name without a list of sections, then all sections +in the input file will be included in the output section. This is not +commonly done, but it may by useful on occasion. For example: + data.o + + When you use a file name which does not contain any wild card +characters, the linker will first see if you also specified the file +name on the linker command line or in an 'INPUT' command. If you did +not, the linker will attempt to open the file as an input file, as +though it appeared on the command line. Note that this differs from an +'INPUT' command, because the linker will not search for the file in the +archive search path. + +3.6.4.2 Input Section Wildcard Patterns +....................................... + +In an input section description, either the file name or the section +name or both may be wildcard patterns. + + The file name of '*' seen in many examples is a simple wildcard +pattern for the file name. + + The wildcard patterns are like those used by the Unix shell. + +'*' + matches any number of characters +'?' + matches any single character +'[CHARS]' + matches a single instance of any of the CHARS; the '-' character + may be used to specify a range of characters, as in '[a-z]' to + match any lower case letter +'\' + quotes the following character + + When a file name is matched with a wildcard, the wildcard characters +will not match a '/' character (used to separate directory names on +Unix). A pattern consisting of a single '*' character is an exception; +it will always match any file name, whether it contains a '/' or not. +In a section name, the wildcard characters will match a '/' character. + + File name wildcard patterns only match files which are explicitly +specified on the command line or in an 'INPUT' command. The linker does +not search directories to expand wildcards. + + If a file name matches more than one wildcard pattern, or if a file +name appears explicitly and is also matched by a wildcard pattern, the +linker will use the first match in the linker script. For example, this +sequence of input section descriptions is probably in error, because the +'data.o' rule will not be used: + .data : { *(.data) } + .data1 : { data.o(.data) } + + Normally, the linker will place files and sections matched by +wildcards in the order in which they are seen during the link. You can +change this by using the 'SORT_BY_NAME' keyword, which appears before a +wildcard pattern in parentheses (e.g., 'SORT_BY_NAME(.text*)'). When +the 'SORT_BY_NAME' keyword is used, the linker will sort the files or +sections into ascending order by name before placing them in the output +file. + + 'SORT_BY_ALIGNMENT' is very similar to 'SORT_BY_NAME'. The +difference is 'SORT_BY_ALIGNMENT' will sort sections into ascending +order by alignment before placing them in the output file. + + 'SORT' is an alias for 'SORT_BY_NAME'. + + When there are nested section sorting commands in linker script, +there can be at most 1 level of nesting for section sorting commands. + + 1. 'SORT_BY_NAME' ('SORT_BY_ALIGNMENT' (wildcard section pattern)). + It will sort the input sections by name first, then by alignment if + 2 sections have the same name. + 2. 'SORT_BY_ALIGNMENT' ('SORT_BY_NAME' (wildcard section pattern)). + It will sort the input sections by alignment first, then by name if + 2 sections have the same alignment. + 3. 'SORT_BY_NAME' ('SORT_BY_NAME' (wildcard section pattern)) is + treated the same as 'SORT_BY_NAME' (wildcard section pattern). + 4. 'SORT_BY_ALIGNMENT' ('SORT_BY_ALIGNMENT' (wildcard section + pattern)) is treated the same as 'SORT_BY_ALIGNMENT' (wildcard + section pattern). + 5. All other nested section sorting commands are invalid. + + When both command line section sorting option and linker script +section sorting command are used, section sorting command always takes +precedence over the command line option. + + If the section sorting command in linker script isn't nested, the +command line option will make the section sorting command to be treated +as nested sorting command. + + 1. 'SORT_BY_NAME' (wildcard section pattern ) with '--sort-sections + alignment' is equivalent to 'SORT_BY_NAME' ('SORT_BY_ALIGNMENT' + (wildcard section pattern)). + 2. 'SORT_BY_ALIGNMENT' (wildcard section pattern) with '--sort-section + name' is equivalent to 'SORT_BY_ALIGNMENT' ('SORT_BY_NAME' + (wildcard section pattern)). + + If the section sorting command in linker script is nested, the +command line option will be ignored. + + If you ever get confused about where input sections are going, use +the '-M' linker option to generate a map file. The map file shows +precisely how input sections are mapped to output sections. + + This example shows how wildcard patterns might be used to partition +files. This linker script directs the linker to place all '.text' +sections in '.text' and all '.bss' sections in '.bss'. The linker will +place the '.data' section from all files beginning with an upper case +character in '.DATA'; for all other files, the linker will place the +'.data' section in '.data'. + SECTIONS { + .text : { *(.text) } + .DATA : { [A-Z]*(.data) } + .data : { *(.data) } + .bss : { *(.bss) } + } + +3.6.4.3 Input Section for Common Symbols +........................................ + +A special notation is needed for common symbols, because in many object +file formats common symbols do not have a particular input section. The +linker treats common symbols as though they are in an input section +named 'COMMON'. + + You may use file names with the 'COMMON' section just as with any +other input sections. You can use this to place common symbols from a +particular input file in one section while common symbols from other +input files are placed in another section. + + In most cases, common symbols in input files will be placed in the +'.bss' section in the output file. For example: + .bss { *(.bss) *(COMMON) } + + Some object file formats have more than one type of common symbol. +For example, the MIPS ELF object file format distinguishes standard +common symbols and small common symbols. In this case, the linker will +use a different special section name for other types of common symbols. +In the case of MIPS ELF, the linker uses 'COMMON' for standard common +symbols and '.scommon' for small common symbols. This permits you to +map the different types of common symbols into memory at different +locations. + + You will sometimes see '[COMMON]' in old linker scripts. This +notation is now considered obsolete. It is equivalent to '*(COMMON)'. + +3.6.4.4 Input Section and Garbage Collection +............................................ + +When link-time garbage collection is in use ('--gc-sections'), it is +often useful to mark sections that should not be eliminated. This is +accomplished by surrounding an input section's wildcard entry with +'KEEP()', as in 'KEEP(*(.init))' or 'KEEP(SORT_BY_NAME(*)(.ctors))'. + +3.6.4.5 Input Section Example +............................. + +The following example is a complete linker script. It tells the linker +to read all of the sections from file 'all.o' and place them at the +start of output section 'outputa' which starts at location '0x10000'. +All of section '.input1' from file 'foo.o' follows immediately, in the +same output section. All of section '.input2' from 'foo.o' goes into +output section 'outputb', followed by section '.input1' from 'foo1.o'. +All of the remaining '.input1' and '.input2' sections from any files are +written to output section 'outputc'. + + SECTIONS { + outputa 0x10000 : + { + all.o + foo.o (.input1) + } + outputb : + { + foo.o (.input2) + foo1.o (.input1) + } + outputc : + { + *(.input1) + *(.input2) + } + } + +3.6.5 Output Section Data +------------------------- + +You can include explicit bytes of data in an output section by using +'BYTE', 'SHORT', 'LONG', 'QUAD', or 'SQUAD' as an output section +command. Each keyword is followed by an expression in parentheses +providing the value to store (*note Expressions::). The value of the +expression is stored at the current value of the location counter. + + The 'BYTE', 'SHORT', 'LONG', and 'QUAD' commands store one, two, +four, and eight bytes (respectively). After storing the bytes, the +location counter is incremented by the number of bytes stored. + + For example, this will store the byte 1 followed by the four byte +value of the symbol 'addr': + BYTE(1) + LONG(addr) + + When using a 64 bit host or target, 'QUAD' and 'SQUAD' are the same; +they both store an 8 byte, or 64 bit, value. When both host and target +are 32 bits, an expression is computed as 32 bits. In this case 'QUAD' +stores a 32 bit value zero extended to 64 bits, and 'SQUAD' stores a 32 +bit value sign extended to 64 bits. + + If the object file format of the output file has an explicit +endianness, which is the normal case, the value will be stored in that +endianness. When the object file format does not have an explicit +endianness, as is true of, for example, S-records, the value will be +stored in the endianness of the first input object file. + + Note--these commands only work inside a section description and not +between them, so the following will produce an error from the linker: + SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } } + whereas this will work: + SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } } + + You may use the 'FILL' command to set the fill pattern for the +current section. It is followed by an expression in parentheses. Any +otherwise unspecified regions of memory within the section (for example, +gaps left due to the required alignment of input sections) are filled +with the value of the expression, repeated as necessary. A 'FILL' +statement covers memory locations after the point at which it occurs in +the section definition; by including more than one 'FILL' statement, you +can have different fill patterns in different parts of an output +section. + + This example shows how to fill unspecified regions of memory with the +value '0x90': + FILL(0x90909090) + + The 'FILL' command is similar to the '=FILLEXP' output section +attribute, but it only affects the part of the section following the +'FILL' command, rather than the entire section. If both are used, the +'FILL' command takes precedence. *Note Output Section Fill::, for +details on the fill expression. + +3.6.6 Output Section Keywords +----------------------------- + +There are a couple of keywords which can appear as output section +commands. + +'CREATE_OBJECT_SYMBOLS' + The command tells the linker to create a symbol for each input + file. The name of each symbol will be the name of the + corresponding input file. The section of each symbol will be the + output section in which the 'CREATE_OBJECT_SYMBOLS' command + appears. + + This is conventional for the a.out object file format. It is not + normally used for any other object file format. + +'CONSTRUCTORS' + When linking using the a.out object file format, the linker uses an + unusual set construct to support C++ global constructors and + destructors. When linking object file formats which do not support + arbitrary sections, such as ECOFF and XCOFF, the linker will + automatically recognize C++ global constructors and destructors by + name. For these object file formats, the 'CONSTRUCTORS' command + tells the linker to place constructor information in the output + section where the 'CONSTRUCTORS' command appears. The + 'CONSTRUCTORS' command is ignored for other object file formats. + + The symbol '__CTOR_LIST__' marks the start of the global + constructors, and the symbol '__CTOR_END__' marks the end. + Similarly, '__DTOR_LIST__' and '__DTOR_END__' mark the start and + end of the global destructors. The first word in the list is the + number of entries, followed by the address of each constructor or + destructor, followed by a zero word. The compiler must arrange to + actually run the code. For these object file formats GNU C++ + normally calls constructors from a subroutine '__main'; a call to + '__main' is automatically inserted into the startup code for + 'main'. GNU C++ normally runs destructors either by using + 'atexit', or directly from the function 'exit'. + + For object file formats such as 'COFF' or 'ELF' which support + arbitrary section names, GNU C++ will normally arrange to put the + addresses of global constructors and destructors into the '.ctors' + and '.dtors' sections. Placing the following sequence into your + linker script will build the sort of table which the GNU C++ + runtime code expects to see. + + __CTOR_LIST__ = .; + LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2) + *(.ctors) + LONG(0) + __CTOR_END__ = .; + __DTOR_LIST__ = .; + LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2) + *(.dtors) + LONG(0) + __DTOR_END__ = .; + + If you are using the GNU C++ support for initialization priority, + which provides some control over the order in which global + constructors are run, you must sort the constructors at link time + to ensure that they are executed in the correct order. When using + the 'CONSTRUCTORS' command, use 'SORT_BY_NAME(CONSTRUCTORS)' + instead. When using the '.ctors' and '.dtors' sections, use + '*(SORT_BY_NAME(.ctors))' and '*(SORT_BY_NAME(.dtors))' instead of + just '*(.ctors)' and '*(.dtors)'. + + Normally the compiler and linker will handle these issues + automatically, and you will not need to concern yourself with them. + However, you may need to consider this if you are using C++ and + writing your own linker scripts. + +3.6.7 Output Section Discarding +------------------------------- + +The linker will not create output sections with no contents. This is +for convenience when referring to input sections that may or may not be +present in any of the input files. For example: + .foo : { *(.foo) } +will only create a '.foo' section in the output file if there is a +'.foo' section in at least one input file, and if the input sections are +not all empty. Other link script directives that allocate space in an +output section will also create the output section. + + The linker will ignore address assignments (*note Output Section +Address::) on discarded output sections, except when the linker script +defines symbols in the output section. In that case the linker will +obey the address assignments, possibly advancing dot even though the +section is discarded. + + The special output section name '/DISCARD/' may be used to discard +input sections. Any input sections which are assigned to an output +section named '/DISCARD/' are not included in the output file. + +3.6.8 Output Section Attributes +------------------------------- + +We showed above that the full description of an output section looked +like this: + SECTION [ADDRESS] [(TYPE)] : + [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)] + { + OUTPUT-SECTION-COMMAND + OUTPUT-SECTION-COMMAND + ... + } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP] + We've already described SECTION, ADDRESS, and OUTPUT-SECTION-COMMAND. +In this section we will describe the remaining section attributes. + +3.6.8.1 Output Section Type +........................... + +Each output section may have a type. The type is a keyword in +parentheses. The following types are defined: + +'NOLOAD' + The section should be marked as not loadable, so that it will not + be loaded into memory when the program is run. +'DSECT' +'COPY' +'INFO' +'OVERLAY' + These type names are supported for backward compatibility, and are + rarely used. They all have the same effect: the section should be + marked as not allocatable, so that no memory is allocated for the + section when the program is run. + + The linker normally sets the attributes of an output section based on +the input sections which map into it. You can override this by using +the section type. For example, in the script sample below, the 'ROM' +section is addressed at memory location '0' and does not need to be +loaded when the program is run. The contents of the 'ROM' section will +appear in the linker output file as usual. + SECTIONS { + ROM 0 (NOLOAD) : { ... } + ... + } + +3.6.8.2 Output Section LMA +.......................... + +Every section has a virtual address (VMA) and a load address (LMA); see +*note Basic Script Concepts::. The address expression which may appear +in an output section description sets the VMA (*note Output Section +Address::). + + The expression LMA that follows the 'AT' keyword specifies the load +address of the section. + + Alternatively, with 'AT>LMA_REGION' expression, you may specify a +memory region for the section's load address. *Note MEMORY::. Note +that if the section has not had a VMA assigned to it then the linker +will use the LMA_REGION as the VMA region as well. + + If neither 'AT' nor 'AT>' is specified for an allocatable section, +the linker will set the LMA such that the difference between VMA and LMA +for the section is the same as the preceding output section in the same +region. If there is no preceding output section or the section is not +allocatable, the linker will set the LMA equal to the VMA. *Note Output +Section Region::. + + This feature is designed to make it easy to build a ROM image. For +example, the following linker script creates three output sections: one +called '.text', which starts at '0x1000', one called '.mdata', which is +loaded at the end of the '.text' section even though its VMA is +'0x2000', and one called '.bss' to hold uninitialized data at address +'0x3000'. The symbol '_data' is defined with the value '0x2000', which +shows that the location counter holds the VMA value, not the LMA value. + + SECTIONS + { + .text 0x1000 : { *(.text) _etext = . ; } + .mdata 0x2000 : + AT ( ADDR (.text) + SIZEOF (.text) ) + { _data = . ; *(.data); _edata = . ; } + .bss 0x3000 : + { _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;} + } + + The run-time initialization code for use with a program generated +with this linker script would include something like the following, to +copy the initialized data from the ROM image to its runtime address. +Notice how this code takes advantage of the symbols defined by the +linker script. + + extern char _etext, _data, _edata, _bstart, _bend; + char *src = &_etext; + char *dst = &_data; + + /* ROM has data at end of text; copy it. */ + while (dst < &_edata) { + *dst++ = *src++; + } + + /* Zero bss */ + for (dst = &_bstart; dst< &_bend; dst++) + *dst = 0; + +3.6.8.3 Forced Output Alignment +............................... + +You can increase an output section's alignment by using ALIGN. + +3.6.8.4 Forced Input Alignment +.............................. + +You can force input section alignment within an output section by using +SUBALIGN. The value specified overrides any alignment given by input +sections, whether larger or smaller. + +3.6.8.5 Output Section Region +............................. + +You can assign a section to a previously defined region of memory by +using '>REGION'. *Note MEMORY::. + + Here is a simple example: + MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 } + SECTIONS { ROM : { *(.text) } >rom } + +3.6.8.6 Output Section Phdr +........................... + +You can assign a section to a previously defined program segment by +using ':PHDR'. *Note PHDRS::. If a section is assigned to one or more +segments, then all subsequent allocated sections will be assigned to +those segments as well, unless they use an explicitly ':PHDR' modifier. +You can use ':NONE' to tell the linker to not put the section in any +segment at all. + + Here is a simple example: + PHDRS { text PT_LOAD ; } + SECTIONS { .text : { *(.text) } :text } + +3.6.8.7 Output Section Fill +........................... + +You can set the fill pattern for an entire section by using '=FILLEXP'. +FILLEXP is an expression (*note Expressions::). Any otherwise +unspecified regions of memory within the output section (for example, +gaps left due to the required alignment of input sections) will be +filled with the value, repeated as necessary. If the fill expression is +a simple hex number, ie. a string of hex digit starting with '0x' and +without a trailing 'k' or 'M', then an arbitrarily long sequence of hex +digits can be used to specify the fill pattern; Leading zeros become +part of the pattern too. For all other cases, including extra +parentheses or a unary '+', the fill pattern is the four least +significant bytes of the value of the expression. In all cases, the +number is big-endian. + + You can also change the fill value with a 'FILL' command in the +output section commands; (*note Output Section Data::). + + Here is a simple example: + SECTIONS { .text : { *(.text) } =0x90909090 } + +3.6.9 Overlay Description +------------------------- + +An overlay description provides an easy way to describe sections which +are to be loaded as part of a single memory image but are to be run at +the same memory address. At run time, some sort of overlay manager will +copy the overlaid sections in and out of the runtime memory address as +required, perhaps by simply manipulating addressing bits. This approach +can be useful, for example, when a certain region of memory is faster +than another. + + Overlays are described using the 'OVERLAY' command. The 'OVERLAY' +command is used within a 'SECTIONS' command, like an output section +description. The full syntax of the 'OVERLAY' command is as follows: + OVERLAY [START] : [NOCROSSREFS] [AT ( LDADDR )] + { + SECNAME1 + { + OUTPUT-SECTION-COMMAND + OUTPUT-SECTION-COMMAND + ... + } [:PHDR...] [=FILL] + SECNAME2 + { + OUTPUT-SECTION-COMMAND + OUTPUT-SECTION-COMMAND + ... + } [:PHDR...] [=FILL] + ... + } [>REGION] [:PHDR...] [=FILL] + + Everything is optional except 'OVERLAY' (a keyword), and each section +must have a name (SECNAME1 and SECNAME2 above). The section definitions +within the 'OVERLAY' construct are identical to those within the general +'SECTIONS' contruct (*note SECTIONS::), except that no addresses and no +memory regions may be defined for sections within an 'OVERLAY'. + + The sections are all defined with the same starting address. The +load addresses of the sections are arranged such that they are +consecutive in memory starting at the load address used for the +'OVERLAY' as a whole (as with normal section definitions, the load +address is optional, and defaults to the start address; the start +address is also optional, and defaults to the current value of the +location counter). + + If the 'NOCROSSREFS' keyword is used, and there any references among +the sections, the linker will report an error. Since the sections all +run at the same address, it normally does not make sense for one section +to refer directly to another. *Note NOCROSSREFS: Miscellaneous +Commands. + + For each section within the 'OVERLAY', the linker automatically +provides two symbols. The symbol '__load_start_SECNAME' is defined as +the starting load address of the section. The symbol +'__load_stop_SECNAME' is defined as the final load address of the +section. Any characters within SECNAME which are not legal within C +identifiers are removed. C (or assembler) code may use these symbols to +move the overlaid sections around as necessary. + + At the end of the overlay, the value of the location counter is set +to the start address of the overlay plus the size of the largest +section. + + Here is an example. Remember that this would appear inside a +'SECTIONS' construct. + OVERLAY 0x1000 : AT (0x4000) + { + .text0 { o1/*.o(.text) } + .text1 { o2/*.o(.text) } + } +This will define both '.text0' and '.text1' to start at address 0x1000. +'.text0' will be loaded at address 0x4000, and '.text1' will be loaded +immediately after '.text0'. The following symbols will be defined if +referenced: '__load_start_text0', '__load_stop_text0', +'__load_start_text1', '__load_stop_text1'. + + C code to copy overlay '.text1' into the overlay area might look like +the following. + + extern char __load_start_text1, __load_stop_text1; + memcpy ((char *) 0x1000, &__load_start_text1, + &__load_stop_text1 - &__load_start_text1); + + Note that the 'OVERLAY' command is just syntactic sugar, since +everything it does can be done using the more basic commands. The above +example could have been written identically as follows. + + .text0 0x1000 : AT (0x4000) { o1/*.o(.text) } + PROVIDE (__load_start_text0 = LOADADDR (.text0)); + PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0)); + .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) } + PROVIDE (__load_start_text1 = LOADADDR (.text1)); + PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1)); + . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); + +3.7 MEMORY Command +================== + +The linker's default configuration permits allocation of all available +memory. You can override this by using the 'MEMORY' command. + + The 'MEMORY' command describes the location and size of blocks of +memory in the target. You can use it to describe which memory regions +may be used by the linker, and which memory regions it must avoid. You +can then assign sections to particular memory regions. The linker will +set section addresses based on the memory regions, and will warn about +regions that become too full. The linker will not shuffle sections +around to fit into the available regions. + + A linker script may contain at most one use of the 'MEMORY' command. +However, you can define as many blocks of memory within it as you wish. +The syntax is: + MEMORY + { + NAME [(ATTR)] : ORIGIN = ORIGIN, LENGTH = LEN + ... + } + + The NAME is a name used in the linker script to refer to the region. +The region name has no meaning outside of the linker script. Region +names are stored in a separate name space, and will not conflict with +symbol names, file names, or section names. Each memory region must +have a distinct name. + + The ATTR string is an optional list of attributes that specify +whether to use a particular memory region for an input section which is +not explicitly mapped in the linker script. As described in *note +SECTIONS::, if you do not specify an output section for some input +section, the linker will create an output section with the same name as +the input section. If you define region attributes, the linker will use +them to select the memory region for the output section that it creates. + + The ATTR string must consist only of the following characters: +'R' + Read-only section +'W' + Read/write section +'X' + Executable section +'A' + Allocatable section +'I' + Initialized section +'L' + Same as 'I' +'!' + Invert the sense of any of the preceding attributes + + If a unmapped section matches any of the listed attributes other than +'!', it will be placed in the memory region. The '!' attribute reverses +this test, so that an unmapped section will be placed in the memory +region only if it does not match any of the listed attributes. + + The ORIGIN is an numerical expression for the start address of the +memory region. The expression must evaluate to a constant and it cannot +involve any symbols. The keyword 'ORIGIN' may be abbreviated to 'org' +or 'o' (but not, for example, 'ORG'). + + The LEN is an expression for the size in bytes of the memory region. +As with the ORIGIN expression, the expression must be numerical only and +must evaluate to a constant. The keyword 'LENGTH' may be abbreviated to +'len' or 'l'. + + In the following example, we specify that there are two memory +regions available for allocation: one starting at '0' for 256 kilobytes, +and the other starting at '0x40000000' for four megabytes. The linker +will place into the 'rom' memory region every section which is not +explicitly mapped into a memory region, and is either read-only or +executable. The linker will place other sections which are not +explicitly mapped into a memory region into the 'ram' memory region. + + MEMORY + { + rom (rx) : ORIGIN = 0, LENGTH = 256K + ram (!rx) : org = 0x40000000, l = 4M + } + + Once you define a memory region, you can direct the linker to place +specific output sections into that memory region by using the '>REGION' +output section attribute. For example, if you have a memory region +named 'mem', you would use '>mem' in the output section definition. +*Note Output Section Region::. If no address was specified for the +output section, the linker will set the address to the next available +address within the memory region. If the combined output sections +directed to a memory region are too large for the region, the linker +will issue an error message. + + It is possible to access the origin and length of a memory in an +expression via the 'ORIGIN(MEMORY)' and 'LENGTH(MEMORY)' functions: + + _fstack = ORIGIN(ram) + LENGTH(ram) - 4; + +3.8 PHDRS Command +================= + +The ELF object file format uses "program headers", also knows as +"segments". The program headers describe how the program should be +loaded into memory. You can print them out by using the 'objdump' +program with the '-p' option. + + When you run an ELF program on a native ELF system, the system loader +reads the program headers in order to figure out how to load the +program. This will only work if the program headers are set correctly. +This manual does not describe the details of how the system loader +interprets program headers; for more information, see the ELF ABI. + + The linker will create reasonable program headers by default. +However, in some cases, you may need to specify the program headers more +precisely. You may use the 'PHDRS' command for this purpose. When the +linker sees the 'PHDRS' command in the linker script, it will not create +any program headers other than the ones specified. + + The linker only pays attention to the 'PHDRS' command when generating +an ELF output file. In other cases, the linker will simply ignore +'PHDRS'. + + This is the syntax of the 'PHDRS' command. The words 'PHDRS', +'FILEHDR', 'AT', and 'FLAGS' are keywords. + + PHDRS + { + NAME TYPE [ FILEHDR ] [ PHDRS ] [ AT ( ADDRESS ) ] + [ FLAGS ( FLAGS ) ] ; + } + + The NAME is used only for reference in the 'SECTIONS' command of the +linker script. It is not put into the output file. Program header +names are stored in a separate name space, and will not conflict with +symbol names, file names, or section names. Each program header must +have a distinct name. + + Certain program header types describe segments of memory which the +system loader will load from the file. In the linker script, you +specify the contents of these segments by placing allocatable output +sections in the segments. You use the ':PHDR' output section attribute +to place a section in a particular segment. *Note Output Section +Phdr::. + + It is normal to put certain sections in more than one segment. This +merely implies that one segment of memory contains another. You may +repeat ':PHDR', using it once for each segment which should contain the +section. + + If you place a section in one or more segments using ':PHDR', then +the linker will place all subsequent allocatable sections which do not +specify ':PHDR' in the same segments. This is for convenience, since +generally a whole set of contiguous sections will be placed in a single +segment. You can use ':NONE' to override the default segment and tell +the linker to not put the section in any segment at all. + + You may use the 'FILEHDR' and 'PHDRS' keywords appear after the +program header type to further describe the contents of the segment. +The 'FILEHDR' keyword means that the segment should include the ELF file +header. The 'PHDRS' keyword means that the segment should include the +ELF program headers themselves. + + The TYPE may be one of the following. The numbers indicate the value +of the keyword. + +'PT_NULL' (0) + Indicates an unused program header. + +'PT_LOAD' (1) + Indicates that this program header describes a segment to be loaded + from the file. + +'PT_DYNAMIC' (2) + Indicates a segment where dynamic linking information can be found. + +'PT_INTERP' (3) + Indicates a segment where the name of the program interpreter may + be found. + +'PT_NOTE' (4) + Indicates a segment holding note information. + +'PT_SHLIB' (5) + A reserved program header type, defined but not specified by the + ELF ABI. + +'PT_PHDR' (6) + Indicates a segment where the program headers may be found. + +EXPRESSION + An expression giving the numeric type of the program header. This + may be used for types not defined above. + + You can specify that a segment should be loaded at a particular +address in memory by using an 'AT' expression. This is identical to the +'AT' command used as an output section attribute (*note Output Section +LMA::). The 'AT' command for a program header overrides the output +section attribute. + + The linker will normally set the segment flags based on the sections +which comprise the segment. You may use the 'FLAGS' keyword to +explicitly specify the segment flags. The value of FLAGS must be an +integer. It is used to set the 'p_flags' field of the program header. + + Here is an example of 'PHDRS'. This shows a typical set of program +headers used on a native ELF system. + + PHDRS + { + headers PT_PHDR PHDRS ; + interp PT_INTERP ; + text PT_LOAD FILEHDR PHDRS ; + data PT_LOAD ; + dynamic PT_DYNAMIC ; + } + + SECTIONS + { + . = SIZEOF_HEADERS; + .interp : { *(.interp) } :text :interp + .text : { *(.text) } :text + .rodata : { *(.rodata) } /* defaults to :text */ + ... + . = . + 0x1000; /* move to a new page in memory */ + .data : { *(.data) } :data + .dynamic : { *(.dynamic) } :data :dynamic + ... + } + +3.9 VERSION Command +=================== + +The linker supports symbol versions when using ELF. Symbol versions are +only useful when using shared libraries. The dynamic linker can use +symbol versions to select a specific version of a function when it runs +a program that may have been linked against an earlier version of the +shared library. + + You can include a version script directly in the main linker script, +or you can supply the version script as an implicit linker script. You +can also use the '--version-script' linker option. + + The syntax of the 'VERSION' command is simply + VERSION { version-script-commands } + + The format of the version script commands is identical to that used +by Sun's linker in Solaris 2.5. The version script defines a tree of +version nodes. You specify the node names and interdependencies in the +version script. You can specify which symbols are bound to which +version nodes, and you can reduce a specified set of symbols to local +scope so that they are not globally visible outside of the shared +library. + + The easiest way to demonstrate the version script language is with a +few examples. + + VERS_1.1 { + global: + foo1; + local: + old*; + original*; + new*; + }; + + VERS_1.2 { + foo2; + } VERS_1.1; + + VERS_2.0 { + bar1; bar2; + extern "C++" { + ns::*; + "int f(int, double)"; + } + } VERS_1.2; + + This example version script defines three version nodes. The first +version node defined is 'VERS_1.1'; it has no other dependencies. The +script binds the symbol 'foo1' to 'VERS_1.1'. It reduces a number of +symbols to local scope so that they are not visible outside of the +shared library; this is done using wildcard patterns, so that any symbol +whose name begins with 'old', 'original', or 'new' is matched. The +wildcard patterns available are the same as those used in the shell when +matching filenames (also known as "globbing"). However, if you specify +the symbol name inside double quotes, then the name is treated as +literal, rather than as a glob pattern. + + Next, the version script defines node 'VERS_1.2'. This node depends +upon 'VERS_1.1'. The script binds the symbol 'foo2' to the version node +'VERS_1.2'. + + Finally, the version script defines node 'VERS_2.0'. This node +depends upon 'VERS_1.2'. The scripts binds the symbols 'bar1' and +'bar2' are bound to the version node 'VERS_2.0'. + + When the linker finds a symbol defined in a library which is not +specifically bound to a version node, it will effectively bind it to an +unspecified base version of the library. You can bind all otherwise +unspecified symbols to a given version node by using 'global: *;' +somewhere in the version script. + + The names of the version nodes have no specific meaning other than +what they might suggest to the person reading them. The '2.0' version +could just as well have appeared in between '1.1' and '1.2'. However, +this would be a confusing way to write a version script. + + Node name can be omitted, provided it is the only version node in the +version script. Such version script doesn't assign any versions to +symbols, only selects which symbols will be globally visible out and +which won't. + + { global: foo; bar; local: *; }; + + When you link an application against a shared library that has +versioned symbols, the application itself knows which version of each +symbol it requires, and it also knows which version nodes it needs from +each shared library it is linked against. Thus at runtime, the dynamic +loader can make a quick check to make sure that the libraries you have +linked against do in fact supply all of the version nodes that the +application will need to resolve all of the dynamic symbols. In this +way it is possible for the dynamic linker to know with certainty that +all external symbols that it needs will be resolvable without having to +search for each symbol reference. + + The symbol versioning is in effect a much more sophisticated way of +doing minor version checking that SunOS does. The fundamental problem +that is being addressed here is that typically references to external +functions are bound on an as-needed basis, and are not all bound when +the application starts up. If a shared library is out of date, a +required interface may be missing; when the application tries to use +that interface, it may suddenly and unexpectedly fail. With symbol +versioning, the user will get a warning when they start their program if +the libraries being used with the application are too old. + + There are several GNU extensions to Sun's versioning approach. The +first of these is the ability to bind a symbol to a version node in the +source file where the symbol is defined instead of in the versioning +script. This was done mainly to reduce the burden on the library +maintainer. You can do this by putting something like: + __asm__(".symver original_foo,foo@VERS_1.1"); +in the C source file. This renames the function 'original_foo' to be an +alias for 'foo' bound to the version node 'VERS_1.1'. The 'local:' +directive can be used to prevent the symbol 'original_foo' from being +exported. A '.symver' directive takes precedence over a version script. + + The second GNU extension is to allow multiple versions of the same +function to appear in a given shared library. In this way you can make +an incompatible change to an interface without increasing the major +version number of the shared library, while still allowing applications +linked against the old interface to continue to function. + + To do this, you must use multiple '.symver' directives in the source +file. Here is an example: + + __asm__(".symver original_foo,foo@"); + __asm__(".symver old_foo,foo@VERS_1.1"); + __asm__(".symver old_foo1,foo@VERS_1.2"); + __asm__(".symver new_foo,foo@@VERS_2.0"); + + In this example, 'foo@' represents the symbol 'foo' bound to the +unspecified base version of the symbol. The source file that contains +this example would define 4 C functions: 'original_foo', 'old_foo', +'old_foo1', and 'new_foo'. + + When you have multiple definitions of a given symbol, there needs to +be some way to specify a default version to which external references to +this symbol will be bound. You can do this with the 'foo@@VERS_2.0' +type of '.symver' directive. You can only declare one version of a +symbol as the default in this manner; otherwise you would effectively +have multiple definitions of the same symbol. + + If you wish to bind a reference to a specific version of the symbol +within the shared library, you can use the aliases of convenience (i.e., +'old_foo'), or you can use the '.symver' directive to specifically bind +to an external version of the function in question. + + You can also specify the language in the version script: + + VERSION extern "lang" { version-script-commands } + + The supported 'lang's are 'C', 'C++', and 'Java'. The linker will +iterate over the list of symbols at the link time and demangle them +according to 'lang' before matching them to the patterns specified in +'version-script-commands'. + + Demangled names may contains spaces and other special characters. As +described above, you can use a glob pattern to match demangled names, or +you can use a double-quoted string to match the string exactly. In the +latter case, be aware that minor differences (such as differing +whitespace) between the version script and the demangler output will +cause a mismatch. As the exact string generated by the demangler might +change in the future, even if the mangled name does not, you should +check that all of your version directives are behaving as you expect +when you upgrade. + +3.10 Expressions in Linker Scripts +================================== + +The syntax for expressions in the linker script language is identical to +that of C expressions. All expressions are evaluated as integers. All +expressions are evaluated in the same size, which is 32 bits if both the +host and target are 32 bits, and is otherwise 64 bits. + + You can use and set symbol values in expressions. + + The linker defines several special purpose builtin functions for use +in expressions. + +3.10.1 Constants +---------------- + +All constants are integers. + + As in C, the linker considers an integer beginning with '0' to be +octal, and an integer beginning with '0x' or '0X' to be hexadecimal. +The linker considers other integers to be decimal. + + In addition, you can use the suffixes 'K' and 'M' to scale a constant +by '1024' or '1024*1024' respectively. For example, the following all +refer to the same quantity: + _fourk_1 = 4K; + _fourk_2 = 4096; + _fourk_3 = 0x1000; + +3.10.2 Symbol Names +------------------- + +Unless quoted, symbol names start with a letter, underscore, or period +and may include letters, digits, underscores, periods, and hyphens. +Unquoted symbol names must not conflict with any keywords. You can +specify a symbol which contains odd characters or has the same name as a +keyword by surrounding the symbol name in double quotes: + "SECTION" = 9; + "with a space" = "also with a space" + 10; + + Since symbols can contain many non-alphabetic characters, it is +safest to delimit symbols with spaces. For example, 'A-B' is one +symbol, whereas 'A - B' is an expression involving subtraction. + +3.10.3 Orphan Sections +---------------------- + +Orphan sections are sections present in the input files which are not +explicitly placed into the output file by the linker script. The linker +will still copy these sections into the output file, but it has to guess +as to where they should be placed. The linker uses a simple heuristic +to do this. It attempts to place orphan sections after non-orphan +sections of the same attribute, such as code vs data, loadable vs +non-loadable, etc. If there is not enough room to do this then it +places at the end of the file. + + For ELF targets, the attribute of the section includes section type +as well as section flag. + +3.10.4 The Location Counter +--------------------------- + +The special linker variable "dot" '.' always contains the current output +location counter. Since the '.' always refers to a location in an +output section, it may only appear in an expression within a 'SECTIONS' +command. The '.' symbol may appear anywhere that an ordinary symbol is +allowed in an expression. + + Assigning a value to '.' will cause the location counter to be moved. +This may be used to create holes in the output section. The location +counter may not be moved backwards inside an output section, and may not +be moved backwards outside of an output section if so doing creates +areas with overlapping LMAs. + + SECTIONS + { + output : + { + file1(.text) + . = . + 1000; + file2(.text) + . += 1000; + file3(.text) + } = 0x12345678; + } +In the previous example, the '.text' section from 'file1' is located at +the beginning of the output section 'output'. It is followed by a 1000 +byte gap. Then the '.text' section from 'file2' appears, also with a +1000 byte gap following before the '.text' section from 'file3'. The +notation '= 0x12345678' specifies what data to write in the gaps (*note +Output Section Fill::). + + Note: '.' actually refers to the byte offset from the start of the +current containing object. Normally this is the 'SECTIONS' statement, +whose start address is 0, hence '.' can be used as an absolute address. +If '.' is used inside a section description however, it refers to the +byte offset from the start of that section, not an absolute address. +Thus in a script like this: + + SECTIONS + { + . = 0x100 + .text: { + *(.text) + . = 0x200 + } + . = 0x500 + .data: { + *(.data) + . += 0x600 + } + } + + The '.text' section will be assigned a starting address of 0x100 and +a size of exactly 0x200 bytes, even if there is not enough data in the +'.text' input sections to fill this area. (If there is too much data, +an error will be produced because this would be an attempt to move '.' +backwards). The '.data' section will start at 0x500 and it will have an +extra 0x600 bytes worth of space after the end of the values from the +'.data' input sections and before the end of the '.data' output section +itself. + + Setting symbols to the value of the location counter outside of an +output section statement can result in unexpected values if the linker +needs to place orphan sections. For example, given the following: + + SECTIONS + { + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + start_of_data = . ; + .data: { *(.data) } + end_of_data = . ; + } + + If the linker needs to place some input section, e.g. '.rodata', not +mentioned in the script, it might choose to place that section between +'.text' and '.data'. You might think the linker should place '.rodata' +on the blank line in the above script, but blank lines are of no +particular significance to the linker. As well, the linker doesn't +associate the above symbol names with their sections. Instead, it +assumes that all assignments or other statements belong to the previous +output section, except for the special case of an assignment to '.'. +I.e., the linker will place the orphan '.rodata' section as if the +script was written as follows: + + SECTIONS + { + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + start_of_data = . ; + .rodata: { *(.rodata) } + .data: { *(.data) } + end_of_data = . ; + } + + This may or may not be the script author's intention for the value of +'start_of_data'. One way to influence the orphan section placement is +to assign the location counter to itself, as the linker assumes that an +assignment to '.' is setting the start address of a following output +section and thus should be grouped with that section. So you could +write: + + SECTIONS + { + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + . = . ; + start_of_data = . ; + .data: { *(.data) } + end_of_data = . ; + } + + Now, the orphan '.rodata' section will be placed between +'end_of_text' and 'start_of_data'. + +3.10.5 Operators +---------------- + +The linker recognizes the standard C set of arithmetic operators, with +the standard bindings and precedence levels: + precedence associativity Operators Notes + (highest) + 1 left ! - ~ (1) + 2 left * / % + 3 left + - + 4 left >> << + 5 left == != > < <= >= + 6 left & + 7 left | + 8 left && + 9 left || + 10 right ? : + 11 right &= += -= *= /= (2) + (lowest) + Notes: (1) Prefix operators (2) *Note Assignments::. + +3.10.6 Evaluation +----------------- + +The linker evaluates expressions lazily. It only computes the value of +an expression when absolutely necessary. + + The linker needs some information, such as the value of the start +address of the first section, and the origins and lengths of memory +regions, in order to do any linking at all. These values are computed +as soon as possible when the linker reads in the linker script. + + However, other values (such as symbol values) are not known or needed +until after storage allocation. Such values are evaluated later, when +other information (such as the sizes of output sections) is available +for use in the symbol assignment expression. + + The sizes of sections cannot be known until after allocation, so +assignments dependent upon these are not performed until after +allocation. + + Some expressions, such as those depending upon the location counter +'.', must be evaluated during section allocation. + + If the result of an expression is required, but the value is not +available, then an error results. For example, a script like the +following + SECTIONS + { + .text 9+this_isnt_constant : + { *(.text) } + } +will cause the error message 'non constant expression for initial +address'. + +3.10.7 The Section of an Expression +----------------------------------- + +When the linker evaluates an expression, the result is either absolute +or relative to some section. A relative expression is expressed as a +fixed offset from the base of a section. + + The position of the expression within the linker script determines +whether it is absolute or relative. An expression which appears within +an output section definition is relative to the base of the output +section. An expression which appears elsewhere will be absolute. + + A symbol set to a relative expression will be relocatable if you +request relocatable output using the '-r' option. That means that a +further link operation may change the value of the symbol. The symbol's +section will be the section of the relative expression. + + A symbol set to an absolute expression will retain the same value +through any further link operation. The symbol will be absolute, and +will not have any particular associated section. + + You can use the builtin function 'ABSOLUTE' to force an expression to +be absolute when it would otherwise be relative. For example, to create +an absolute symbol set to the address of the end of the output section +'.data': + SECTIONS + { + .data : { *(.data) _edata = ABSOLUTE(.); } + } +If 'ABSOLUTE' were not used, '_edata' would be relative to the '.data' +section. + +3.10.8 Builtin Functions +------------------------ + +The linker script language includes a number of builtin functions for +use in linker script expressions. + +'ABSOLUTE(EXP)' + Return the absolute (non-relocatable, as opposed to non-negative) + value of the expression EXP. Primarily useful to assign an + absolute value to a symbol within a section definition, where + symbol values are normally section relative. *Note Expression + Section::. + +'ADDR(SECTION)' + Return the absolute address (the VMA) of the named SECTION. Your + script must previously have defined the location of that section. + In the following example, 'symbol_1' and 'symbol_2' are assigned + identical values: + SECTIONS { ... + .output1 : + { + start_of_output_1 = ABSOLUTE(.); + ... + } + .output : + { + symbol_1 = ADDR(.output1); + symbol_2 = start_of_output_1; + } + ... } + +'ALIGN(ALIGN)' +'ALIGN(EXP,ALIGN)' + Return the location counter ('.') or arbitrary expression aligned + to the next ALIGN boundary. The single operand 'ALIGN' doesn't + change the value of the location counter--it just does arithmetic + on it. The two operand 'ALIGN' allows an arbitrary expression to + be aligned upwards ('ALIGN(ALIGN)' is equivalent to 'ALIGN(., + ALIGN)'). + + Here is an example which aligns the output '.data' section to the + next '0x2000' byte boundary after the preceding section and sets a + variable within the section to the next '0x8000' boundary after the + input sections: + SECTIONS { ... + .data ALIGN(0x2000): { + *(.data) + variable = ALIGN(0x8000); + } + ... } + The first use of 'ALIGN' in this example specifies the location of + a section because it is used as the optional ADDRESS attribute of a + section definition (*note Output Section Address::). The second + use of 'ALIGN' is used to defines the value of a symbol. + + The builtin function 'NEXT' is closely related to 'ALIGN'. + +'ALIGNOF(SECTION)' + Return the alignment in bytes of the named SECTION, if that section + has been allocated. If the section has not been allocated when + this is evaluated, the linker will report an error. In the + following example, the alignment of the '.output' section is stored + as the first value in that section. + SECTIONS{ ... + .output { + LONG (ALIGNOF (.output)) + ... + } + ... } + +'BLOCK(EXP)' + This is a synonym for 'ALIGN', for compatibility with older linker + scripts. It is most often seen when setting the address of an + output section. + +'DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE)' + This is equivalent to either + (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - 1))) + or + (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - COMMONPAGESIZE))) + depending on whether the latter uses fewer COMMONPAGESIZE sized + pages for the data segment (area between the result of this + expression and 'DATA_SEGMENT_END') than the former or not. If the + latter form is used, it means COMMONPAGESIZE bytes of runtime + memory will be saved at the expense of up to COMMONPAGESIZE wasted + bytes in the on-disk file. + + This expression can only be used directly in 'SECTIONS' commands, + not in any output section descriptions and only once in the linker + script. COMMONPAGESIZE should be less or equal to MAXPAGESIZE and + should be the system page size the object wants to be optimized for + (while still working on system page sizes up to MAXPAGESIZE). + + Example: + . = DATA_SEGMENT_ALIGN(0x10000, 0x2000); + +'DATA_SEGMENT_END(EXP)' + This defines the end of data segment for 'DATA_SEGMENT_ALIGN' + evaluation purposes. + + . = DATA_SEGMENT_END(.); + +'DATA_SEGMENT_RELRO_END(OFFSET, EXP)' + This defines the end of the 'PT_GNU_RELRO' segment when '-z relro' + option is used. Second argument is returned. When '-z relro' + option is not present, 'DATA_SEGMENT_RELRO_END' does nothing, + otherwise 'DATA_SEGMENT_ALIGN' is padded so that EXP + OFFSET is + aligned to the most commonly used page boundary for particular + target. If present in the linker script, it must always come in + between 'DATA_SEGMENT_ALIGN' and 'DATA_SEGMENT_END'. + + . = DATA_SEGMENT_RELRO_END(24, .); + +'DEFINED(SYMBOL)' + Return 1 if SYMBOL is in the linker global symbol table and is + defined before the statement using DEFINED in the script, otherwise + return 0. You can use this function to provide default values for + symbols. For example, the following script fragment shows how to + set a global symbol 'begin' to the first location in the '.text' + section--but if a symbol called 'begin' already existed, its value + is preserved: + + SECTIONS { ... + .text : { + begin = DEFINED(begin) ? begin : . ; + ... + } + ... + } + +'LENGTH(MEMORY)' + Return the length of the memory region named MEMORY. + +'LOADADDR(SECTION)' + Return the absolute LMA of the named SECTION. This is normally the + same as 'ADDR', but it may be different if the 'AT' attribute is + used in the output section definition (*note Output Section LMA::). + +'MAX(EXP1, EXP2)' + Returns the maximum of EXP1 and EXP2. + +'MIN(EXP1, EXP2)' + Returns the minimum of EXP1 and EXP2. + +'NEXT(EXP)' + Return the next unallocated address that is a multiple of EXP. + This function is closely related to 'ALIGN(EXP)'; unless you use + the 'MEMORY' command to define discontinuous memory for the output + file, the two functions are equivalent. + +'ORIGIN(MEMORY)' + Return the origin of the memory region named MEMORY. + +'SEGMENT_START(SEGMENT, DEFAULT)' + Return the base address of the named SEGMENT. If an explicit value + has been given for this segment (with a command-line '-T' option) + that value will be returned; otherwise the value will be DEFAULT. + At present, the '-T' command-line option can only be used to set + the base address for the "text", "data", and "bss" sections, but + you use 'SEGMENT_START' with any segment name. + +'SIZEOF(SECTION)' + Return the size in bytes of the named SECTION, if that section has + been allocated. If the section has not been allocated when this is + evaluated, the linker will report an error. In the following + example, 'symbol_1' and 'symbol_2' are assigned identical values: + SECTIONS{ ... + .output { + .start = . ; + ... + .end = . ; + } + symbol_1 = .end - .start ; + symbol_2 = SIZEOF(.output); + ... } + +'SIZEOF_HEADERS' +'sizeof_headers' + Return the size in bytes of the output file's headers. This is + information which appears at the start of the output file. You can + use this number when setting the start address of the first + section, if you choose, to facilitate paging. + + When producing an ELF output file, if the linker script uses the + 'SIZEOF_HEADERS' builtin function, the linker must compute the + number of program headers before it has determined all the section + addresses and sizes. If the linker later discovers that it needs + additional program headers, it will report an error 'not enough + room for program headers'. To avoid this error, you must avoid + using the 'SIZEOF_HEADERS' function, or you must rework your linker + script to avoid forcing the linker to use additional program + headers, or you must define the program headers yourself using the + 'PHDRS' command (*note PHDRS::). + +3.11 Implicit Linker Scripts +============================ + +If you specify a linker input file which the linker can not recognize as +an object file or an archive file, it will try to read the file as a +linker script. If the file can not be parsed as a linker script, the +linker will report an error. + + An implicit linker script will not replace the default linker script. + + Typically an implicit linker script would contain only symbol +assignments, or the 'INPUT', 'GROUP', or 'VERSION' commands. + + Any input files read because of an implicit linker script will be +read at the position in the command line where the implicit linker +script was read. This can affect archive searching. + +4 Machine Dependent Features +**************************** + +'ld' has additional features on some platforms; the following sections +describe them. Machines where 'ld' has no additional functionality are +not listed. + +4.1 'ld' and the H8/300 +======================= + +For the H8/300, 'ld' can perform these global optimizations when you +specify the '--relax' command-line option. + +_relaxing address modes_ + 'ld' finds all 'jsr' and 'jmp' instructions whose targets are + within eight bits, and turns them into eight-bit program-counter + relative 'bsr' and 'bra' instructions, respectively. + +_synthesizing instructions_ + 'ld' finds all 'mov.b' instructions which use the sixteen-bit + absolute address form, but refer to the top page of memory, and + changes them to use the eight-bit address form. (That is: the + linker turns 'mov.b '@'AA:16' into 'mov.b '@'AA:8' whenever the + address AA is in the top page of memory). + +_bit manipulation instructions_ + 'ld' finds all bit manipulation instructions like 'band, bclr, + biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, + bxor' which use 32 bit and 16 bit absolute address form, but refer + to the top page of memory, and changes them to use the 8 bit + address form. (That is: the linker turns 'bset #xx:3,'@'AA:32' + into 'bset #xx:3,'@'AA:8' whenever the address AA is in the top + page of memory). + +_system control instructions_ + 'ld' finds all 'ldc.w, stc.w' instructions which use the 32 bit + absolute address form, but refer to the top page of memory, and + changes them to use 16 bit address form. (That is: the linker + turns 'ldc.w '@'AA:32,ccr' into 'ldc.w '@'AA:16,ccr' whenever the + address AA is in the top page of memory). + +4.2 'ld' and the Intel 960 Family +================================= + +You can use the '-AARCHITECTURE' command line option to specify one of +the two-letter names identifying members of the 960 family; the option +specifies the desired output target, and warns of any incompatible +instructions in the input files. It also modifies the linker's search +strategy for archive libraries, to support the use of libraries specific +to each particular architecture, by including in the search loop names +suffixed with the string identifying the architecture. + + For example, if your 'ld' command line included '-ACA' as well as +'-ltry', the linker would look (in its built-in search paths, and in any +paths you specify with '-L') for a library with the names + + try + libtry.a + tryca + libtryca.a + +The first two possibilities would be considered in any event; the last +two are due to the use of '-ACA'. + + You can meaningfully use '-A' more than once on a command line, since +the 960 architecture family allows combination of target architectures; +each use will add another pair of name variants to search for when '-l' +specifies a library. + + 'ld' supports the '--relax' option for the i960 family. If you +specify '--relax', 'ld' finds all 'balx' and 'calx' instructions whose +targets are within 24 bits, and turns them into 24-bit program-counter +relative 'bal' and 'cal' instructions, respectively. 'ld' also turns +'cal' instructions into 'bal' instructions when it determines that the +target subroutine is a leaf routine (that is, the target subroutine does +not itself call any subroutines). + +4.3 'ld' and the Motorola 68HC11 and 68HC12 families +==================================================== + +4.3.1 Linker Relaxation +----------------------- + +For the Motorola 68HC11, 'ld' can perform these global optimizations +when you specify the '--relax' command-line option. + +_relaxing address modes_ + 'ld' finds all 'jsr' and 'jmp' instructions whose targets are + within eight bits, and turns them into eight-bit program-counter + relative 'bsr' and 'bra' instructions, respectively. + + 'ld' also looks at all 16-bit extended addressing modes and + transforms them in a direct addressing mode when the address is in + page 0 (between 0 and 0x0ff). + +_relaxing gcc instruction group_ + When 'gcc' is called with '-mrelax', it can emit group of + instructions that the linker can optimize to use a 68HC11 direct + addressing mode. These instructions consists of 'bclr' or 'bset' + instructions. + +4.3.2 Trampoline Generation +--------------------------- + +For 68HC11 and 68HC12, 'ld' can generate trampoline code to call a far +function using a normal 'jsr' instruction. The linker will also change +the relocation to some far function to use the trampoline address +instead of the function address. This is typically the case when a +pointer to a function is taken. The pointer will in fact point to the +function trampoline. + + The '--pic-veneer' switch makes the linker use PIC sequences for +ARM/Thumb interworking veneers, even if the rest of the binary is not +PIC. This avoids problems on uClinux targets where '--emit-relocs' is +used to generate relocatable binaries. + +4.4 'ld' and the ARM family +=========================== + +For the ARM, 'ld' will generate code stubs to allow functions calls +between ARM and Thumb code. These stubs only work with code that has +been compiled and assembled with the '-mthumb-interwork' command line +option. If it is necessary to link with old ARM object files or +libraries, which have not been compiled with the -mthumb-interwork +option then the '--support-old-code' command line switch should be given +to the linker. This will make it generate larger stub functions which +will work with non-interworking aware ARM code. Note, however, the +linker does not support generating stubs for function calls to +non-interworking aware Thumb code. + + The '--thumb-entry' switch is a duplicate of the generic '--entry' +switch, in that it sets the program's starting address. But it also +sets the bottom bit of the address, so that it can be branched to using +a BX instruction, and the program will start executing in Thumb mode +straight away. + + The '--be8' switch instructs 'ld' to generate BE8 format executables. +This option is only valid when linking big-endian objects. The +resulting image will contain big-endian data and little-endian code. + + The 'R_ARM_TARGET1' relocation is typically used for entries in the +'.init_array' section. It is interpreted as either 'R_ARM_REL32' or +'R_ARM_ABS32', depending on the target. The '--target1-rel' and +'--target1-abs' switches override the default. + + The '--target2=type' switch overrides the default definition of the +'R_ARM_TARGET2' relocation. Valid values for 'type', their meanings, +and target defaults are as follows: +'rel' + 'R_ARM_REL32' (arm*-*-elf, arm*-*-eabi) +'abs' + 'R_ARM_ABS32' (arm*-*-symbianelf) +'got-rel' + 'R_ARM_GOT_PREL' (arm*-*-linux, arm*-*-*bsd) + + The 'R_ARM_V4BX' relocation (defined by the ARM AAELF specification) +enables objects compiled for the ARMv4 architecture to be +interworking-safe when linked with other objects compiled for ARMv4t, +but also allows pure ARMv4 binaries to be built from the same ARMv4 +objects. + + In the latter case, the switch '--fix-v4bx' must be passed to the +linker, which causes v4t 'BX rM' instructions to be rewritten as 'MOV +PC,rM', since v4 processors do not have a 'BX' instruction. + + In the former case, the switch should not be used, and 'R_ARM_V4BX' +relocations are ignored. + + The '--use-blx' switch enables the linker to use ARM/Thumb BLX +instructions (available on ARMv5t and above) in various situations. +Currently it is used to perform calls via the PLT from Thumb code using +BLX rather than using BX and a mode-switching stub before each PLT +entry. This should lead to such calls executing slightly faster. + + This option is enabled implicitly for SymbianOS, so there is no need +to specify it if you are using that target. + + The '--vfp11-denorm-fix' switch enables a link-time workaround for a +bug in certain VFP11 coprocessor hardware, which sometimes allows +instructions with denorm operands (which must be handled by support +code) to have those operands overwritten by subsequent instructions +before the support code can read the intended values. + + The bug may be avoided in scalar mode if you allow at least one +intervening instruction between a VFP11 instruction which uses a +register and another instruction which writes to the same register, or +at least two intervening instructions if vector mode is in use. The bug +only affects full-compliance floating-point mode: you do not need this +workaround if you are using "runfast" mode. Please contact ARM for +further details. + + If you know you are using buggy VFP11 hardware, you can enable this +workaround by specifying the linker option '--vfp-denorm-fix=scalar' if +you are using the VFP11 scalar mode only, or '--vfp-denorm-fix=vector' +if you are using vector mode (the latter also works for scalar code). +The default is '--vfp-denorm-fix=none'. + + If the workaround is enabled, instructions are scanned for +potentially-troublesome sequences, and a veneer is created for each such +sequence which may trigger the erratum. The veneer consists of the +first instruction of the sequence and a branch back to the subsequent +instruction. The original instruction is then replaced with a branch to +the veneer. The extra cycles required to call and return from the +veneer are sufficient to avoid the erratum in both the scalar and vector +cases. + + The '--no-enum-size-warning' switch prevents the linker from warning +when linking object files that specify incompatible EABI enumeration +size attributes. For example, with this switch enabled, linking of an +object file using 32-bit enumeration values with another using +enumeration values fitted into the smallest possible space will not be +diagnosed. + +4.5 'ld' and HPPA 32-bit ELF Support +==================================== + +When generating a shared library, 'ld' will by default generate import +stubs suitable for use with a single sub-space application. The +'--multi-subspace' switch causes 'ld' to generate export stubs, and +different (larger) import stubs suitable for use with multiple +sub-spaces. + + Long branch stubs and import/export stubs are placed by 'ld' in stub +sections located between groups of input sections. '--stub-group-size' +specifies the maximum size of a group of input sections handled by one +stub section. Since branch offsets are signed, a stub section may serve +two groups of input sections, one group before the stub section, and one +group after it. However, when using conditional branches that require +stubs, it may be better (for branch prediction) that stub sections only +serve one group of input sections. A negative value for 'N' chooses +this scheme, ensuring that branches to stubs always use a negative +offset. Two special values of 'N' are recognized, '1' and '-1'. These +both instruct 'ld' to automatically size input section groups for the +branch types detected, with the same behaviour regarding stub placement +as other positive or negative values of 'N' respectively. + + Note that '--stub-group-size' does not split input sections. A +single input section larger than the group size specified will of course +create a larger group (of one section). If input sections are too +large, it may not be possible for a branch to reach its stub. + +4.6 'ld' and MMIX +================= + +For MMIX, there is a choice of generating 'ELF' object files or 'mmo' +object files when linking. The simulator 'mmix' understands the 'mmo' +format. The binutils 'objcopy' utility can translate between the two +formats. + + There is one special section, the '.MMIX.reg_contents' section. +Contents in this section is assumed to correspond to that of global +registers, and symbols referring to it are translated to special +symbols, equal to registers. In a final link, the start address of the +'.MMIX.reg_contents' section corresponds to the first allocated global +register multiplied by 8. Register '$255' is not included in this +section; it is always set to the program entry, which is at the symbol +'Main' for 'mmo' files. + + Symbols with the prefix '__.MMIX.start.', for example +'__.MMIX.start..text' and '__.MMIX.start..data' are special; there must +be only one each, even if they are local. The default linker script +uses these to set the default start address of a section. + + Initial and trailing multiples of zero-valued 32-bit words in a +section, are left out from an mmo file. + +4.7 'ld' and MSP430 +=================== + +For the MSP430 it is possible to select the MPU architecture. The flag +'-m [mpu type]' will select an appropriate linker script for selected +MPU type. (To get a list of known MPUs just pass '-m help' option to +the linker). + + The linker will recognize some extra sections which are MSP430 +specific: + +''.vectors'' + Defines a portion of ROM where interrupt vectors located. + +''.bootloader'' + Defines the bootloader portion of the ROM (if applicable). Any + code in this section will be uploaded to the MPU. + +''.infomem'' + Defines an information memory section (if applicable). Any code in + this section will be uploaded to the MPU. + +''.infomemnobits'' + This is the same as the '.infomem' section except that any code in + this section will not be uploaded to the MPU. + +''.noinit'' + Denotes a portion of RAM located above '.bss' section. + + The last two sections are used by gcc. + +4.8 'ld' and PowerPC 32-bit ELF Support +======================================= + +Branches on PowerPC processors are limited to a signed 26-bit +displacement, which may result in 'ld' giving 'relocation truncated to +fit' errors with very large programs. '--relax' enables the generation +of trampolines that can access the entire 32-bit address space. These +trampolines are inserted at section boundaries, so may not themselves be +reachable if an input section exceeds 33M in size. + +'--bss-plt' + Current PowerPC GCC accepts a '-msecure-plt' option that generates + code capable of using a newer PLT and GOT layout that has the + security advantage of no executable section ever needing to be + writable and no writable section ever being executable. PowerPC + 'ld' will generate this layout, including stubs to access the PLT, + if all input files (including startup and static libraries) were + compiled with '-msecure-plt'. '--bss-plt' forces the old BSS PLT + (and GOT layout) which can give slightly better performance. + +'--secure-plt' + 'ld' will use the new PLT and GOT layout if it is linking new + '-fpic' or '-fPIC' code, but does not do so automatically when + linking non-PIC code. This option requests the new PLT and GOT + layout. A warning will be given if some object file requires the + old style BSS PLT. + +'--sdata-got' + The new secure PLT and GOT are placed differently relative to other + sections compared to older BSS PLT and GOT placement. The location + of '.plt' must change because the new secure PLT is an initialized + section while the old PLT is uninitialized. The reason for the + '.got' change is more subtle: The new placement allows '.got' to be + read-only in applications linked with '-z relro -z now'. However, + this placement means that '.sdata' cannot always be used in shared + libraries, because the PowerPC ABI accesses '.sdata' in shared + libraries from the GOT pointer. '--sdata-got' forces the old GOT + placement. PowerPC GCC doesn't use '.sdata' in shared libraries, + so this option is really only useful for other compilers that may + do so. + +'--emit-stub-syms' + This option causes 'ld' to label linker stubs with a local symbol + that encodes the stub type and destination. + +'--no-tls-optimize' + PowerPC 'ld' normally performs some optimization of code sequences + used to access Thread-Local Storage. Use this option to disable + the optimization. + +4.9 'ld' and PowerPC64 64-bit ELF Support +========================================= + +'--stub-group-size' + Long branch stubs, PLT call stubs and TOC adjusting stubs are + placed by 'ld' in stub sections located between groups of input + sections. '--stub-group-size' specifies the maximum size of a + group of input sections handled by one stub section. Since branch + offsets are signed, a stub section may serve two groups of input + sections, one group before the stub section, and one group after + it. However, when using conditional branches that require stubs, + it may be better (for branch prediction) that stub sections only + serve one group of input sections. A negative value for 'N' + chooses this scheme, ensuring that branches to stubs always use a + negative offset. Two special values of 'N' are recognized, '1' and + '-1'. These both instruct 'ld' to automatically size input section + groups for the branch types detected, with the same behaviour + regarding stub placement as other positive or negative values of + 'N' respectively. + + Note that '--stub-group-size' does not split input sections. A + single input section larger than the group size specified will of + course create a larger group (of one section). If input sections + are too large, it may not be possible for a branch to reach its + stub. + +'--emit-stub-syms' + This option causes 'ld' to label linker stubs with a local symbol + that encodes the stub type and destination. + +'--dotsyms, --no-dotsyms' + These two options control how 'ld' interprets version patterns in a + version script. Older PowerPC64 compilers emitted both a function + descriptor symbol with the same name as the function, and a code + entry symbol with the name prefixed by a dot ('.'). To properly + version a function 'foo', the version script thus needs to control + both 'foo' and '.foo'. The option '--dotsyms', on by default, + automatically adds the required dot-prefixed patterns. Use + '--no-dotsyms' to disable this feature. + +'--no-tls-optimize' + PowerPC64 'ld' normally performs some optimization of code + sequences used to access Thread-Local Storage. Use this option to + disable the optimization. + +'--no-opd-optimize' + PowerPC64 'ld' normally removes '.opd' section entries + corresponding to deleted link-once functions, or functions removed + by the action of '--gc-sections' or linker scrip '/DISCARD/'. Use + this option to disable '.opd' optimization. + +'--non-overlapping-opd' + Some PowerPC64 compilers have an option to generate compressed + '.opd' entries spaced 16 bytes apart, overlapping the third word, + the static chain pointer (unused in C) with the first word of the + next entry. This option expands such entries to the full 24 bytes. + +'--no-toc-optimize' + PowerPC64 'ld' normally removes unused '.toc' section entries. + Such entries are detected by examining relocations that reference + the TOC in code sections. A reloc in a deleted code section marks + a TOC word as unneeded, while a reloc in a kept code section marks + a TOC word as needed. Since the TOC may reference itself, TOC + relocs are also examined. TOC words marked as both needed and + unneeded will of course be kept. TOC words without any referencing + reloc are assumed to be part of a multi-word entry, and are kept or + discarded as per the nearest marked preceding word. This works + reliably for compiler generated code, but may be incorrect if + assembly code is used to insert TOC entries. Use this option to + disable the optimization. + +'--no-multi-toc' + By default, PowerPC64 GCC generates code for a TOC model where TOC + entries are accessed with a 16-bit offset from r2. This limits the + total TOC size to 64K. PowerPC64 'ld' extends this limit by + grouping code sections such that each group uses less than 64K for + its TOC entries, then inserts r2 adjusting stubs between + inter-group calls. 'ld' does not split apart input sections, so + cannot help if a single input file has a '.toc' section that + exceeds 64K, most likely from linking multiple files with 'ld -r'. + Use this option to turn off this feature. + +4.10 'ld' and SPU ELF Support +============================= + +'--plugin' + This option marks an executable as a PIC plugin module. + +'--no-overlays' + Normally, 'ld' recognizes calls to functions within overlay + regions, and redirects such calls to an overlay manager via a stub. + 'ld' also provides a built-in overlay manager. This option turns + off all this special overlay handling. + +'--emit-stub-syms' + This option causes 'ld' to label overlay stubs with a local symbol + that encodes the stub type and destination. + +'--extra-overlay-stubs' + This option causes 'ld' to add overlay call stubs on all function + calls out of overlay regions. Normally stubs are not added on + calls to non-overlay regions. + +'--local-store=lo:hi' + 'ld' usually checks that a final executable for SPU fits in the + address range 0 to 256k. This option may be used to change the + range. Disable the check entirely with '--local-store=0:0'. + +'--stack-analysis' + SPU local store space is limited. Over-allocation of stack space + unnecessarily limits space available for code and data, while + under-allocation results in runtime failures. If given this + option, 'ld' will provide an estimate of maximum stack usage. 'ld' + does this by examining symbols in code sections to determine the + extents of functions, and looking at function prologues for stack + adjusting instructions. A call-graph is created by looking for + relocations on branch instructions. The graph is then searched for + the maximum stack usage path. Note that this analysis does not + find calls made via function pointers, and does not handle + recursion and other cycles in the call graph. Stack usage may be + under-estimated if your code makes such calls. Also, stack usage + for dynamic allocation, e.g. alloca, will not be detected. If a + link map is requested, detailed information about each function's + stack usage and calls will be given. + +'--emit-stack-syms' + This option, if given along with '--stack-analysis' will result in + 'ld' emitting stack sizing symbols for each function. These take + the form '__stack_<function_name>' for global functions, and + '__stack_<number>_<function_name>' for static functions. + '<number>' is the section id in hex. The value of such symbols is + the stack requirement for the corresponding function. The symbol + size will be zero, type 'STT_NOTYPE', binding 'STB_LOCAL', and + section 'SHN_ABS'. + +4.11 'ld''s Support for Various TI COFF Versions +================================================ + +The '--format' switch allows selection of one of the various TI COFF +versions. The latest of this writing is 2; versions 0 and 1 are also +supported. The TI COFF versions also vary in header byte-order format; +'ld' will read any version or byte order, but the output header format +depends on the default specified by the specific target. + +4.12 'ld' and WIN32 (cygwin/mingw) +================================== + +This section describes some of the win32 specific 'ld' issues. See +*note Command Line Options: Options. for detailed description of the +command line options mentioned here. + +_import libraries_ + The standard Windows linker creates and uses so-called import + libraries, which contains information for linking to dll's. They + are regular static archives and are handled as any other static + archive. The cygwin and mingw ports of 'ld' have specific support + for creating such libraries provided with the '--out-implib' + command line option. + +_exporting DLL symbols_ + The cygwin/mingw 'ld' has several ways to export symbols for dll's. + + _using auto-export functionality_ + By default 'ld' exports symbols with the auto-export + functionality, which is controlled by the following command + line options: + + * -export-all-symbols [This is the default] + * -exclude-symbols + * -exclude-libs + + If, however, '--export-all-symbols' is not given explicitly on + the command line, then the default auto-export behavior will + be _disabled_ if either of the following are true: + + * A DEF file is used. + * Any symbol in any object file was marked with the + __declspec(dllexport) attribute. + + _using a DEF file_ + Another way of exporting symbols is using a DEF file. A DEF + file is an ASCII file containing definitions of symbols which + should be exported when a dll is created. Usually it is named + '<dll name>.def' and is added as any other object file to the + linker's command line. The file's name must end in '.def' or + '.DEF'. + + gcc -o <output> <objectfiles> <dll name>.def + + Using a DEF file turns off the normal auto-export behavior, + unless the '--export-all-symbols' option is also used. + + Here is an example of a DEF file for a shared library called + 'xyz.dll': + + LIBRARY "xyz.dll" BASE=0x20000000 + + EXPORTS + foo + bar + _bar = bar + another_foo = abc.dll.afoo + var1 DATA + + This example defines a DLL with a non-default base address and + five symbols in the export table. The third exported symbol + '_bar' is an alias for the second. The fourth symbol, + 'another_foo' is resolved by "forwarding" to another module + and treating it as an alias for 'afoo' exported from the DLL + 'abc.dll'. The final symbol 'var1' is declared to be a data + object. + + The optional 'LIBRARY <name>' command indicates the _internal_ + name of the output DLL. If '<name>' does not include a suffix, + the default library suffix, '.DLL' is appended. + + When the .DEF file is used to build an application, rather + than a library, the 'NAME <name>' command should be used + instead of 'LIBRARY'. If '<name>' does not include a suffix, + the default executable suffix, '.EXE' is appended. + + With either 'LIBRARY <name>' or 'NAME <name>' the optional + specification 'BASE = <number>' may be used to specify a + non-default base address for the image. + + If neither 'LIBRARY <name>' nor 'NAME <name>' is specified, or + they specify an empty string, the internal name is the same as + the filename specified on the command line. + + The complete specification of an export symbol is: + + EXPORTS + ( ( ( <name1> [ = <name2> ] ) + | ( <name1> = <module-name> . <external-name>)) + [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) * + + Declares '<name1>' as an exported symbol from the DLL, or + declares '<name1>' as an exported alias for '<name2>'; or + declares '<name1>' as a "forward" alias for the symbol + '<external-name>' in the DLL '<module-name>'. Optionally, the + symbol may be exported by the specified ordinal '<integer>' + alias. + + The optional keywords that follow the declaration indicate: + + 'NONAME': Do not put the symbol name in the DLL's export + table. It will still be exported by its ordinal alias (either + the value specified by the .def specification or, otherwise, + the value assigned by the linker). The symbol name, however, + does remain visible in the import library (if any), unless + 'PRIVATE' is also specified. + + 'DATA': The symbol is a variable or object, rather than a + function. The import lib will export only an indirect + reference to 'foo' as the symbol '_imp__foo' (ie, 'foo' must + be resolved as '*_imp__foo'). + + 'CONSTANT': Like 'DATA', but put the undecorated 'foo' as well + as '_imp__foo' into the import library. Both refer to the + read-only import address table's pointer to the variable, not + to the variable itself. This can be dangerous. If the user + code fails to add the 'dllimport' attribute and also fails to + explicitly add the extra indirection that the use of the + attribute enforces, the application will behave unexpectedly. + + 'PRIVATE': Put the symbol in the DLL's export table, but do + not put it into the static import library used to resolve + imports at link time. The symbol can still be imported using + the 'LoadLibrary/GetProcAddress' API at runtime or by by using + the GNU ld extension of linking directly to the DLL without an + import library. + + See ld/deffilep.y in the binutils sources for the full + specification of other DEF file statements + + While linking a shared dll, 'ld' is able to create a DEF file + with the '--output-def <file>' command line option. + + _Using decorations_ + Another way of marking symbols for export is to modify the + source code itself, so that when building the DLL each symbol + to be exported is declared as: + + __declspec(dllexport) int a_variable + __declspec(dllexport) void a_function(int with_args) + + All such symbols will be exported from the DLL. If, however, + any of the object files in the DLL contain symbols decorated + in this way, then the normal auto-export behavior is disabled, + unless the '--export-all-symbols' option is also used. + + Note that object files that wish to access these symbols must + _not_ decorate them with dllexport. Instead, they should use + dllimport, instead: + + __declspec(dllimport) int a_variable + __declspec(dllimport) void a_function(int with_args) + + This complicates the structure of library header files, + because when included by the library itself the header must + declare the variables and functions as dllexport, but when + included by client code the header must declare them as + dllimport. There are a number of idioms that are typically + used to do this; often client code can omit the __declspec() + declaration completely. See '--enable-auto-import' and + 'automatic data imports' for more information. + +_automatic data imports_ + The standard Windows dll format supports data imports from dlls + only by adding special decorations (dllimport/dllexport), which let + the compiler produce specific assembler instructions to deal with + this issue. This increases the effort necessary to port existing + Un*x code to these platforms, especially for large c++ libraries + and applications. The auto-import feature, which was initially + provided by Paul Sokolovsky, allows one to omit the decorations to + achieve a behavior that conforms to that on POSIX/Un*x platforms. + This feature is enabled with the '--enable-auto-import' + command-line option, although it is enabled by default on + cygwin/mingw. The '--enable-auto-import' option itself now serves + mainly to suppress any warnings that are ordinarily emitted when + linked objects trigger the feature's use. + + auto-import of variables does not always work flawlessly without + additional assistance. Sometimes, you will see this message + + "variable '<var>' can't be auto-imported. Please read the + documentation for ld's '--enable-auto-import' for details." + + The '--enable-auto-import' documentation explains why this error + occurs, and several methods that can be used to overcome this + difficulty. One of these methods is the _runtime pseudo-relocs_ + feature, described below. + + For complex variables imported from DLLs (such as structs or + classes), object files typically contain a base address for the + variable and an offset (_addend_) within the variable-to specify a + particular field or public member, for instance. Unfortunately, + the runtime loader used in win32 environments is incapable of + fixing these references at runtime without the additional + information supplied by dllimport/dllexport decorations. The + standard auto-import feature described above is unable to resolve + these references. + + The '--enable-runtime-pseudo-relocs' switch allows these references + to be resolved without error, while leaving the task of adjusting + the references themselves (with their non-zero addends) to + specialized code provided by the runtime environment. Recent + versions of the cygwin and mingw environments and compilers provide + this runtime support; older versions do not. However, the support + is only necessary on the developer's platform; the compiled result + will run without error on an older system. + + '--enable-runtime-pseudo-relocs' is not the default; it must be + explicitly enabled as needed. + +_direct linking to a dll_ + The cygwin/mingw ports of 'ld' support the direct linking, + including data symbols, to a dll without the usage of any import + libraries. This is much faster and uses much less memory than does + the traditional import library method, especially when linking + large libraries or applications. When 'ld' creates an import lib, + each function or variable exported from the dll is stored in its + own bfd, even though a single bfd could contain many exports. The + overhead involved in storing, loading, and processing so many bfd's + is quite large, and explains the tremendous time, memory, and + storage needed to link against particularly large or complex + libraries when using import libs. + + Linking directly to a dll uses no extra command-line switches other + than '-L' and '-l', because 'ld' already searches for a number of + names to match each library. All that is needed from the + developer's perspective is an understanding of this search, in + order to force ld to select the dll instead of an import library. + + For instance, when ld is called with the argument '-lxxx' it will + attempt to find, in the first directory of its search path, + + libxxx.dll.a + xxx.dll.a + libxxx.a + xxx.lib + cygxxx.dll (*) + libxxx.dll + xxx.dll + + before moving on to the next directory in the search path. + + (*) Actually, this is not 'cygxxx.dll' but in fact is + '<prefix>xxx.dll', where '<prefix>' is set by the 'ld' option + '--dll-search-prefix=<prefix>'. In the case of cygwin, the + standard gcc spec file includes '--dll-search-prefix=cyg', so in + effect we actually search for 'cygxxx.dll'. + + Other win32-based unix environments, such as mingw or pw32, may use + other '<prefix>'es, although at present only cygwin makes use of + this feature. It was originally intended to help avoid name + conflicts among dll's built for the various win32/un*x + environments, so that (for example) two versions of a zlib dll + could coexist on the same machine. + + The generic cygwin/mingw path layout uses a 'bin' directory for + applications and dll's and a 'lib' directory for the import + libraries (using cygwin nomenclature): + + bin/ + cygxxx.dll + lib/ + libxxx.dll.a (in case of dll's) + libxxx.a (in case of static archive) + + Linking directly to a dll without using the import library can be + done two ways: + + 1. Use the dll directly by adding the 'bin' path to the link line + gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx + + However, as the dll's often have version numbers appended to their + names ('cygncurses-5.dll') this will often fail, unless one + specifies '-L../bin -lncurses-5' to include the version. Import + libs are generally not versioned, and do not have this difficulty. + + 2. Create a symbolic link from the dll to a file in the 'lib' + directory according to the above mentioned search pattern. This + should be used to avoid unwanted changes in the tools needed for + making the app/dll. + + ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a] + + Then you can link without any make environment changes. + + gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx + + This technique also avoids the version number problems, because the + following is perfectly legal + + bin/ + cygxxx-5.dll + lib/ + libxxx.dll.a -> ../bin/cygxxx-5.dll + + Linking directly to a dll without using an import lib will work + even when auto-import features are exercised, and even when + '--enable-runtime-pseudo-relocs' is used. + + Given the improvements in speed and memory usage, one might + justifiably wonder why import libraries are used at all. There are + three reasons: + + 1. Until recently, the link-directly-to-dll functionality did + _not_ work with auto-imported data. + + 2. Sometimes it is necessary to include pure static objects within + the import library (which otherwise contains only bfd's for + indirection symbols that point to the exports of a dll). Again, + the import lib for the cygwin kernel makes use of this ability, and + it is not possible to do this without an import lib. + + 3. Symbol aliases can only be resolved using an import lib. This + is critical when linking against OS-supplied dll's (eg, the win32 + API) in which symbols are usually exported as undecorated aliases + of their stdcall-decorated assembly names. + + So, import libs are not going away. But the ability to replace + true import libs with a simple symbolic link to (or a copy of) a + dll, in many cases, is a useful addition to the suite of tools + binutils makes available to the win32 developer. Given the massive + improvements in memory requirements during linking, storage + requirements, and linking speed, we expect that many developers + will soon begin to use this feature whenever possible. + +_symbol aliasing_ + _adding additional names_ + Sometimes, it is useful to export symbols with additional + names. A symbol 'foo' will be exported as 'foo', but it can + also be exported as '_foo' by using special directives in the + DEF file when creating the dll. This will affect also the + optional created import library. Consider the following DEF + file: + + LIBRARY "xyz.dll" BASE=0x61000000 + + EXPORTS + foo + _foo = foo + + The line '_foo = foo' maps the symbol 'foo' to '_foo'. + + Another method for creating a symbol alias is to create it in + the source code using the "weak" attribute: + + void foo () { /* Do something. */; } + void _foo () __attribute__ ((weak, alias ("foo"))); + + See the gcc manual for more information about attributes and + weak symbols. + + _renaming symbols_ + Sometimes it is useful to rename exports. For instance, the + cygwin kernel does this regularly. A symbol '_foo' can be + exported as 'foo' but not as '_foo' by using special + directives in the DEF file. (This will also affect the import + library, if it is created). In the following example: + + LIBRARY "xyz.dll" BASE=0x61000000 + + EXPORTS + _foo = foo + + The line '_foo = foo' maps the exported symbol 'foo' to + '_foo'. + + Note: using a DEF file disables the default auto-export behavior, + unless the '--export-all-symbols' command line option is used. If, + however, you are trying to rename symbols, then you should list + _all_ desired exports in the DEF file, including the symbols that + are not being renamed, and do _not_ use the '--export-all-symbols' + option. If you list only the renamed symbols in the DEF file, and + use '--export-all-symbols' to handle the other symbols, then the + both the new names _and_ the original names for the renamed symbols + will be exported. In effect, you'd be aliasing those symbols, not + renaming them, which is probably not what you wanted. + +_weak externals_ + The Windows object format, PE, specifies a form of weak symbols + called weak externals. When a weak symbol is linked and the symbol + is not defined, the weak symbol becomes an alias for some other + symbol. There are three variants of weak externals: + * Definition is searched for in objects and libraries, + historically called lazy externals. + * Definition is searched for only in other objects, not in + libraries. This form is not presently implemented. + * No search; the symbol is an alias. This form is not presently + implemented. + As a GNU extension, weak symbols that do not specify an alternate + symbol are supported. If the symbol is undefined when linking, the + symbol uses a default value. + +4.13 'ld' and Xtensa Processors +=============================== + +The default 'ld' behavior for Xtensa processors is to interpret +'SECTIONS' commands so that lists of explicitly named sections in a +specification with a wildcard file will be interleaved when necessary to +keep literal pools within the range of PC-relative load offsets. For +example, with the command: + + SECTIONS + { + .text : { + *(.literal .text) + } + } + +'ld' may interleave some of the '.literal' and '.text' sections from +different object files to ensure that the literal pools are within the +range of PC-relative load offsets. A valid interleaving might place the +'.literal' sections from an initial group of files followed by the +'.text' sections of that group of files. Then, the '.literal' sections +from the rest of the files and the '.text' sections from the rest of the +files would follow. + + Relaxation is enabled by default for the Xtensa version of 'ld' and +provides two important link-time optimizations. The first optimization +is to combine identical literal values to reduce code size. A redundant +literal will be removed and all the 'L32R' instructions that use it will +be changed to reference an identical literal, as long as the location of +the replacement literal is within the offset range of all the 'L32R' +instructions. The second optimization is to remove unnecessary overhead +from assembler-generated "longcall" sequences of 'L32R'/'CALLXN' when +the target functions are within range of direct 'CALLN' instructions. + + For each of these cases where an indirect call sequence can be +optimized to a direct call, the linker will change the 'CALLXN' +instruction to a 'CALLN' instruction, remove the 'L32R' instruction, and +remove the literal referenced by the 'L32R' instruction if it is not +used for anything else. Removing the 'L32R' instruction always reduces +code size but can potentially hurt performance by changing the alignment +of subsequent branch targets. By default, the linker will always +preserve alignments, either by switching some instructions between +24-bit encodings and the equivalent density instructions or by inserting +a no-op in place of the 'L32R' instruction that was removed. If code +size is more important than performance, the '--size-opt' option can be +used to prevent the linker from widening density instructions or +inserting no-ops, except in a few cases where no-ops are required for +correctness. + + The following Xtensa-specific command-line options can be used to +control the linker: + +'--no-relax' + Since the Xtensa version of 'ld' enables the '--relax' option by + default, the '--no-relax' option is provided to disable relaxation. + +'--size-opt' + When optimizing indirect calls to direct calls, optimize for code + size more than performance. With this option, the linker will not + insert no-ops or widen density instructions to preserve branch + target alignment. There may still be some cases where no-ops are + required to preserve the correctness of the code. + +5 BFD +***** + +The linker accesses object and archive files using the BFD libraries. +These libraries allow the linker to use the same routines to operate on +object files whatever the object file format. A different object file +format can be supported simply by creating a new BFD back end and adding +it to the library. To conserve runtime memory, however, the linker and +associated tools are usually configured to support only a subset of the +object file formats available. You can use 'objdump -i' (*note objdump: +(binutils.info)objdump.) to list all the formats available for your +configuration. + + As with most implementations, BFD is a compromise between several +conflicting requirements. The major factor influencing BFD design was +efficiency: any time used converting between formats is time which would +not have been spent had BFD not been involved. This is partly offset by +abstraction payback; since BFD simplifies applications and back ends, +more time and care may be spent optimizing algorithms for a greater +speed. + + One minor artifact of the BFD solution which you should bear in mind +is the potential for information loss. There are two places where +useful information can be lost using the BFD mechanism: during +conversion and during output. *Note BFD information loss::. + +5.1 How It Works: An Outline of BFD +=================================== + +When an object file is opened, BFD subroutines automatically determine +the format of the input object file. They then build a descriptor in +memory with pointers to routines that will be used to access elements of +the object file's data structures. + + As different information from the object files is required, BFD reads +from different sections of the file and processes them. For example, a +very common operation for the linker is processing symbol tables. Each +BFD back end provides a routine for converting between the object file's +representation of symbols and an internal canonical format. When the +linker asks for the symbol table of an object file, it calls through a +memory pointer to the routine from the relevant BFD back end which reads +and converts the table into a canonical form. The linker then operates +upon the canonical form. When the link is finished and the linker +writes the output file's symbol table, another BFD back end routine is +called to take the newly created symbol table and convert it into the +chosen output format. + +5.1.1 Information Loss +---------------------- + +_Information can be lost during output._ The output formats supported +by BFD do not provide identical facilities, and information which can be +described in one form has nowhere to go in another format. One example +of this is alignment information in 'b.out'. There is nowhere in an +'a.out' format file to store alignment information on the contained +data, so when a file is linked from 'b.out' and an 'a.out' image is +produced, alignment information will not propagate to the output file. +(The linker will still use the alignment information internally, so the +link is performed correctly). + + Another example is COFF section names. COFF files may contain an +unlimited number of sections, each one with a textual section name. If +the target of the link is a format which does not have many sections +(e.g., 'a.out') or has sections without names (e.g., the Oasys format), +the link cannot be done simply. You can circumvent this problem by +describing the desired input-to-output section mapping with the linker +command language. + + _Information can be lost during canonicalization._ The BFD internal +canonical form of the external formats is not exhaustive; there are +structures in input formats for which there is no direct representation +internally. This means that the BFD back ends cannot maintain all +possible data richness through the transformation between external to +internal and back to external formats. + + This limitation is only a problem when an application reads one +format and writes another. Each BFD back end is responsible for +maintaining as much data as possible, and the internal BFD canonical +form has structures which are opaque to the BFD core, and exported only +to the back ends. When a file is read in one format, the canonical form +is generated for BFD and the application. At the same time, the back +end saves away any information which may otherwise be lost. If the data +is then written back in the same format, the back end routine will be +able to use the canonical form provided by the BFD core as well as the +information it prepared earlier. Since there is a great deal of +commonality between back ends, there is no information lost when linking +or copying big endian COFF to little endian COFF, or 'a.out' to 'b.out'. +When a mixture of formats is linked, the information is only lost from +the files whose format differs from the destination. + +5.1.2 The BFD canonical object-file format +------------------------------------------ + +The greatest potential for loss of information occurs when there is the +least overlap between the information provided by the source format, +that stored by the canonical format, and that needed by the destination +format. A brief description of the canonical form may help you +understand which kinds of data you can count on preserving across +conversions. + +_files_ + Information stored on a per-file basis includes target machine + architecture, particular implementation format type, a demand + pageable bit, and a write protected bit. Information like Unix + magic numbers is not stored here--only the magic numbers' meaning, + so a 'ZMAGIC' file would have both the demand pageable bit and the + write protected text bit set. The byte order of the target is + stored on a per-file basis, so that big- and little-endian object + files may be used with one another. + +_sections_ + Each section in the input file contains the name of the section, + the section's original address in the object file, size and + alignment information, various flags, and pointers into other BFD + data structures. + +_symbols_ + Each symbol contains a pointer to the information for the object + file which originally defined it, its name, its value, and various + flag bits. When a BFD back end reads in a symbol table, it + relocates all symbols to make them relative to the base of the + section where they were defined. Doing this ensures that each + symbol points to its containing section. Each symbol also has a + varying amount of hidden private data for the BFD back end. Since + the symbol points to the original file, the private data format for + that symbol is accessible. 'ld' can operate on a collection of + symbols of wildly different formats without problems. + + Normal global and simple local symbols are maintained on output, so + an output file (no matter its format) will retain symbols pointing + to functions and to global, static, and common variables. Some + symbol information is not worth retaining; in 'a.out', type + information is stored in the symbol table as long symbol names. + This information would be useless to most COFF debuggers; the + linker has command line switches to allow users to throw it away. + + There is one word of type information within the symbol, so if the + format supports symbol type information within symbols (for + example, COFF, IEEE, Oasys) and the type is simple enough to fit + within one word (nearly everything but aggregates), the information + will be preserved. + +_relocation level_ + Each canonical BFD relocation record contains a pointer to the + symbol to relocate to, the offset of the data to relocate, the + section the data is in, and a pointer to a relocation type + descriptor. Relocation is performed by passing messages through + the relocation type descriptor and the symbol pointer. Therefore, + relocations can be performed on output data using a relocation + method that is only available in one of the input formats. For + instance, Oasys provides a byte relocation format. A relocation + record requesting this relocation type would point indirectly to a + routine to perform this, so the relocation may be performed on a + byte being written to a 68k COFF file, even though 68k COFF has no + such relocation type. + +_line numbers_ + Object formats can contain, for debugging purposes, some form of + mapping between symbols, source line numbers, and addresses in the + output file. These addresses have to be relocated along with the + symbol information. Each symbol with an associated list of line + number records points to the first record of the list. The head of + a line number list consists of a pointer to the symbol, which + allows finding out the address of the function whose line number is + being described. The rest of the list is made up of pairs: offsets + into the section and line numbers. Any format which can simply + derive this information can pass it successfully between formats + (COFF, IEEE and Oasys). + +6 Reporting Bugs +**************** + +Your bug reports play an essential role in making 'ld' reliable. + + Reporting a bug may help you by bringing a solution to your problem, +or it may not. But in any case the principal function of a bug report +is to help the entire community by making the next version of 'ld' work +better. Bug reports are your contribution to the maintenance of 'ld'. + + In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. + +6.1 Have You Found a Bug? +========================= + +If you are not sure whether you have found a bug, here are some +guidelines: + + * If the linker gets a fatal signal, for any input whatever, that is + a 'ld' bug. Reliable linkers never crash. + + * If 'ld' produces an error message for valid input, that is a bug. + + * If 'ld' does not produce an error message for invalid input, that + may be a bug. In the general case, the linker can not verify that + object files are correct. + + * If you are an experienced user of linkers, your suggestions for + improvement of 'ld' are welcome in any case. + +6.2 How to Report Bugs +====================== + +A number of companies and individuals offer support for GNU products. +If you obtained 'ld' from a support organization, we recommend you +contact that organization first. + + You can find contact information for many support companies and +individuals in the file 'etc/SERVICE' in the GNU Emacs distribution. + + The fundamental principle of reporting bugs usefully is this: *report +all the facts*. If you are not sure whether to state a fact or leave it +out, state it! + + Often people omit facts because they think they know what causes the +problem and assume that some details do not matter. Thus, you might +assume that the name of a symbol you use in an example does not matter. +Well, probably it does not, but one cannot be sure. Perhaps the bug is +a stray memory reference which happens to fetch from the location where +that name is stored in memory; perhaps, if the name were different, the +contents of that location would fool the linker into doing the right +thing despite the bug. Play it safe and give a specific, complete +example. That is the easiest thing for you to do, and the most helpful. + + Keep in mind that the purpose of a bug report is to enable us to fix +the bug if it is new to us. Therefore, always write your bug reports on +the assumption that the bug has not been reported previously. + + Sometimes people give a few sketchy facts and ask, "Does this ring a +bell?" This cannot help us fix a bug, so it is basically useless. We +respond by asking for enough details to enable us to investigate. You +might as well expedite matters by sending them to begin with. + + To enable us to fix the bug, you should include all these things: + + * The version of 'ld'. 'ld' announces it if you start it with the + '--version' argument. + + Without this, we will not know whether there is any point in + looking for the bug in the current version of 'ld'. + + * Any patches you may have applied to the 'ld' source, including any + patches made to the 'BFD' library. + + * The type of machine you are using, and the operating system name + and version number. + + * What compiler (and its version) was used to compile 'ld'--e.g. + "'gcc-2.7'". + + * The command arguments you gave the linker to link your example and + observe the bug. To guarantee you will not omit something + important, list them all. A copy of the Makefile (or the output + from make) is sufficient. + + If we were to try to guess the arguments, we would probably guess + wrong and then we might not encounter the bug. + + * A complete input file, or set of input files, that will reproduce + the bug. It is generally most helpful to send the actual object + files provided that they are reasonably small. Say no more than + 10K. For bigger files you can either make them available by FTP or + HTTP or else state that you are willing to send the object file(s) + to whomever requests them. (Note - your email will be going to a + mailing list, so we do not want to clog it up with large + attachments). But small attachments are best. + + If the source files were assembled using 'gas' or compiled using + 'gcc', then it may be OK to send the source files rather than the + object files. In this case, be sure to say exactly what version of + 'gas' or 'gcc' was used to produce the object files. Also say how + 'gas' or 'gcc' were configured. + + * A description of what behavior you observe that you believe is + incorrect. For example, "It gets a fatal signal." + + Of course, if the bug is that 'ld' gets a fatal signal, then we + will certainly notice it. But if the bug is incorrect output, we + might not notice unless it is glaringly wrong. You might as well + not give us a chance to make a mistake. + + Even if the problem you experience is a fatal signal, you should + still say so explicitly. Suppose something strange is going on, + such as, your copy of 'ld' is out of sync, or you have encountered + a bug in the C library on your system. (This has happened!) Your + copy might crash and ours would not. If you told us to expect a + crash, then when ours fails to crash, we would know that the bug + was not happening for us. If you had not told us to expect a + crash, then we would not be able to draw any conclusion from our + observations. + + * If you wish to suggest changes to the 'ld' source, send us context + diffs, as generated by 'diff' with the '-u', '-c', or '-p' option. + Always send diffs from the old file to the new file. If you even + discuss something in the 'ld' source, refer to it by context, not + by line number. + + The line numbers in our development sources will not match those in + your sources. Your line numbers would convey no useful information + to us. + + Here are some things that are not necessary: + + * A description of the envelope of the bug. + + Often people who encounter a bug spend a lot of time investigating + which changes to the input file will make the bug go away and which + changes will not affect it. + + This is often time consuming and not very useful, because the way + we will find the bug is by running a single example under the + debugger with breakpoints, not by pure deduction from a series of + examples. We recommend that you save your time for something else. + + Of course, if you can find a simpler example to report _instead_ of + the original one, that is a convenience for us. Errors in the + output will be easier to spot, running under the debugger will take + less time, and so on. + + However, simplification is not vital; if you do not want to do + this, report the bug anyway and send us the entire test case you + used. + + * A patch for the bug. + + A patch for the bug does help us if it is a good one. But do not + omit the necessary information, such as the test case, on the + assumption that a patch is all we need. We might see problems with + your patch and decide to fix the problem another way, or we might + not understand it at all. + + Sometimes with a program as complicated as 'ld' it is very hard to + construct an example that will make the program follow a certain + path through the code. If you do not send us the example, we will + not be able to construct one, so we will not be able to verify that + the bug is fixed. + + And if we cannot understand what bug you are trying to fix, or why + your patch should be an improvement, we will not install it. A + test case will help us to understand. + + * A guess about what the bug is or what it depends on. + + Such guesses are usually wrong. Even we cannot guess right about + such things without first using the debugger to find the facts. + +Appendix A MRI Compatible Script Files +************************************** + +To aid users making the transition to GNU 'ld' from the MRI linker, 'ld' +can use MRI compatible linker scripts as an alternative to the more +general-purpose linker scripting language described in *note Scripts::. +MRI compatible linker scripts have a much simpler command set than the +scripting language otherwise used with 'ld'. GNU 'ld' supports the most +commonly used MRI linker commands; these commands are described here. + + In general, MRI scripts aren't of much use with the 'a.out' object +file format, since it only has three sections and MRI scripts lack some +features to make use of them. + + You can specify a file containing an MRI-compatible script using the +'-c' command-line option. + + Each command in an MRI-compatible script occupies its own line; each +command line starts with the keyword that identifies the command (though +blank lines are also allowed for punctuation). If a line of an +MRI-compatible script begins with an unrecognized keyword, 'ld' issues a +warning message, but continues processing the script. + + Lines beginning with '*' are comments. + + You can write these commands using all upper-case letters, or all +lower case; for example, 'chip' is the same as 'CHIP'. The following +list shows only the upper-case form of each command. + +'ABSOLUTE SECNAME' +'ABSOLUTE SECNAME, SECNAME, ... SECNAME' + Normally, 'ld' includes in the output file all sections from all + the input files. However, in an MRI-compatible script, you can use + the 'ABSOLUTE' command to restrict the sections that will be + present in your output program. If the 'ABSOLUTE' command is used + at all in a script, then only the sections named explicitly in + 'ABSOLUTE' commands will appear in the linker output. You can + still use other input sections (whatever you select on the command + line, or using 'LOAD') to resolve addresses in the output file. + +'ALIAS OUT-SECNAME, IN-SECNAME' + Use this command to place the data from input section IN-SECNAME in + a section called OUT-SECNAME in the linker output file. + + IN-SECNAME may be an integer. + +'ALIGN SECNAME = EXPRESSION' + Align the section called SECNAME to EXPRESSION. The EXPRESSION + should be a power of two. + +'BASE EXPRESSION' + Use the value of EXPRESSION as the lowest address (other than + absolute addresses) in the output file. + +'CHIP EXPRESSION' +'CHIP EXPRESSION, EXPRESSION' + This command does nothing; it is accepted only for compatibility. + +'END' + This command does nothing whatever; it's only accepted for + compatibility. + +'FORMAT OUTPUT-FORMAT' + Similar to the 'OUTPUT_FORMAT' command in the more general linker + language, but restricted to one of these output formats: + + 1. S-records, if OUTPUT-FORMAT is 'S' + + 2. IEEE, if OUTPUT-FORMAT is 'IEEE' + + 3. COFF (the 'coff-m68k' variant in BFD), if OUTPUT-FORMAT is + 'COFF' + +'LIST ANYTHING...' + Print (to the standard output file) a link map, as produced by the + 'ld' command-line option '-M'. + + The keyword 'LIST' may be followed by anything on the same line, + with no change in its effect. + +'LOAD FILENAME' +'LOAD FILENAME, FILENAME, ... FILENAME' + Include one or more object file FILENAME in the link; this has the + same effect as specifying FILENAME directly on the 'ld' command + line. + +'NAME OUTPUT-NAME' + OUTPUT-NAME is the name for the program produced by 'ld'; the + MRI-compatible command 'NAME' is equivalent to the command-line + option '-o' or the general script language command 'OUTPUT'. + +'ORDER SECNAME, SECNAME, ... SECNAME' +'ORDER SECNAME SECNAME SECNAME' + Normally, 'ld' orders the sections in its output file in the order + in which they first appear in the input files. In an + MRI-compatible script, you can override this ordering with the + 'ORDER' command. The sections you list with 'ORDER' will appear + first in your output file, in the order specified. + +'PUBLIC NAME=EXPRESSION' +'PUBLIC NAME,EXPRESSION' +'PUBLIC NAME EXPRESSION' + Supply a value (EXPRESSION) for external symbol NAME used in the + linker input files. + +'SECT SECNAME, EXPRESSION' +'SECT SECNAME=EXPRESSION' +'SECT SECNAME EXPRESSION' + You can use any of these three forms of the 'SECT' command to + specify the start address (EXPRESSION) for section SECNAME. If you + have more than one 'SECT' statement for the same SECNAME, only the + _first_ sets the start address. + +Appendix B GNU Free Documentation License +***************************************** + + Version 1.1, March 2000 + + Copyright (C) 2000, 2003 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + written document "free" in the sense of freedom: to assure everyone + the effective freedom to copy and redistribute it, with or without + modifying it, either commercially or noncommercially. Secondarily, + this License preserves for the author and publisher a way to get + credit for their work, while not being considered responsible for + modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work that contains a + notice placed by the copyright holder saying it can be distributed + under the terms of this License. The "Document", below, refers to + any such manual or work. Any member of the public is a licensee, + and is addressed as "you." + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (For example, if the + Document is in part a textbook of mathematics, a Secondary Section + may not explain any mathematics.) The relationship could be a + matter of historical connection with the subject or with related + matters, or of legal, commercial, philosophical, ethical or + political position regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, whose contents can be viewed and edited directly + and straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup has been designed to + thwart or discourage subsequent modification by readers is not + Transparent. A copy that is not "Transparent" is called "Opaque." + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML designed for human modification. Opaque formats + include PostScript, PDF, proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML produced by some word processors for + output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies of the Document numbering more than + 100, and the Document's license notice requires Cover Texts, you + must enclose the copies in covers that carry, clearly and legibly, + all these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a publicly-accessible computer-network location + containing a complete Transparent copy of the Document, free of + added material, which the general network-using public has access + to download anonymously at no charge using public-standard network + protocols. If you use the latter option, you must take reasonably + prudent steps, when you begin distribution of Opaque copies in + quantity, to ensure that this Transparent copy will remain thus + accessible at the stated location until at least one year after the + last time you distribute an Opaque copy (directly or through your + agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the History + section of the Document). You may use the same title as a previous + version if the original publisher of that version gives permission. + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in the + Modified Version, together with at least five of the principal + authors of the Document (all of its principal authors, if it has + less than five). + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + D. Preserve all the copyright notices of the Document. + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified Version + under the terms of this License, in the form shown in the Addendum + below. + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's license + notice. + H. Include an unaltered copy of this License. + I. Preserve the section entitled "History", and its title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. + J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + K. In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + M. Delete any section entitled "Endorsements." Such a section may + not be included in the Modified Version. + N. Do not retitle any existing section as "Endorsements" or to + conflict in title with any Invariant Section. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties-for example, statements of peer review or that the text has + been approved by an organization as the authoritative definition of + a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections entitled + "History" in the various original documents, forming one section + entitled "History"; likewise combine any sections entitled + "Acknowledgements", and any sections entitled "Dedications." You + must delete all sections entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, does not as a whole count as a + Modified Version of the Document, provided no compilation copyright + is claimed for the compilation. Such a compilation is called an + "aggregate", and this License does not apply to the other + self-contained works thus compiled with the Document, on account of + their being thus compiled, if they are not themselves derivative + works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one + quarter of the entire aggregate, the Document's Cover Texts may be + placed on covers that surround only the Document within the + aggregate. Otherwise they must appear on covers around the whole + aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License provided that you also include the + original English version of this License. In case of a + disagreement between the translation and the original English + version of this License, the original English version will prevail. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided for under this License. Any other + attempt to copy, modify, sublicense or distribute the Document is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses terminated + so long as such parties remain in full compliance. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + http://www.gnu.org/copyleft/. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License." + + If you have no Invariant Sections, write "with no Invariant Sections" +instead of saying which ones are invariant. If you have no Front-Cover +Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being +LIST"; likewise for Back-Cover Texts. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + +LD Index +******** + +* Menu: + +* ": Symbols. (line 3620) +* -(: Options. (line 756) +* --accept-unknown-input-arch: Options. (line 774) +* --add-needed: Options. (line 796) +* --add-stdcall-alias: Options. (line 1532) +* --allow-multiple-definition: Options. (line 1004) +* --allow-shlib-undefined: Options. (line 1010) +* --architecture=ARCH: Options. (line 227) +* --as-needed: Options. (line 784) +* --auxiliary: Options. (line 328) +* --bank-window: Options. (line 1867) +* --base-file: Options. (line 1537) +* --be8: ARM. (line 4205) +* --bss-plt: PowerPC ELF32. (line 4376) +* --check-sections: Options. (line 877) +* --cref: Options. (line 887) +* --default-imported-symver: Options. (line 1038) +* --default-script=SCRIPT: Options. (line 601) +* --default-symver: Options. (line 1034) +* --defsym SYMBOL=EXP: Options. (line 915) +* --demangle[=STYLE]: Options. (line 928) +* --disable-auto-image-base: Options. (line 1682) +* --disable-auto-import: Options. (line 1810) +* --disable-new-dtags: Options. (line 1479) +* --disable-runtime-pseudo-reloc: Options. (line 1823) +* --disable-stdcall-fixup: Options. (line 1547) +* --discard-all: Options. (line 647) +* --discard-locals: Options. (line 651) +* --dll: Options. (line 1542) +* --dll-search-prefix: Options. (line 1688) +* --dotsyms: PowerPC64 ELF64. (line 4446) +* --dynamic-linker FILE: Options. (line 941) +* --dynamic-list-cpp-new: Options. (line 869) +* --dynamic-list-cpp-typeinfo: Options. (line 873) +* --dynamic-list-data: Options. (line 866) +* --dynamic-list=DYNAMIC-LIST-FILE: Options. (line 853) +* --eh-frame-hdr: Options. (line 1475) +* --emit-relocs: Options. (line 537) +* --emit-stack-syms: SPU ELF. (line 4541) +* --emit-stub-syms: PowerPC ELF32. (line 4407) +* --emit-stub-syms <1>: PowerPC64 ELF64. (line 4442) +* --emit-stub-syms <2>: SPU ELF. (line 4510) +* --enable-auto-image-base: Options. (line 1674) +* --enable-auto-import: Options. (line 1697) +* --enable-extra-pe-debug: Options. (line 1828) +* --enable-new-dtags: Options. (line 1479) +* --enable-runtime-pseudo-reloc: Options. (line 1815) +* --enable-stdcall-fixup: Options. (line 1547) +* --entry=ENTRY: Options. (line 281) +* --error-unresolved-symbols: Options. (line 1428) +* --exclude-libs: Options. (line 291) +* --exclude-symbols: Options. (line 1588) +* --export-all-symbols: Options. (line 1564) +* --export-dynamic: Options. (line 302) +* --extra-overlay-stubs: SPU ELF. (line 4514) +* --fatal-warnings: Options. (line 947) +* --file-alignment: Options. (line 1594) +* --filter: Options. (line 349) +* --fix-v4bx: ARM. (line 4224) +* --force-dynamic: Options. (line 546) +* --force-exe-suffix: Options. (line 950) +* --format=FORMAT: Options. (line 238) +* --format=VERSION: TI COFF. (line 4554) +* --gc-sections: Options. (line 960) +* --gpsize: Options. (line 381) +* --hash-size=NUMBER: Options. (line 1488) +* --hash-style=STYLE: Options. (line 1496) +* --heap: Options. (line 1600) +* --help: Options. (line 977) +* --image-base: Options. (line 1607) +* --just-symbols=FILE: Options. (line 568) +* --kill-at: Options. (line 1616) +* --large-address-aware: Options. (line 1621) +* --library-path=DIR: Options. (line 440) +* --library=NAMESPEC: Options. (line 407) +* --local-store=lo:hi: SPU ELF. (line 4519) +* --major-image-version: Options. (line 1630) +* --major-os-version: Options. (line 1635) +* --major-subsystem-version: Options. (line 1639) +* --minor-image-version: Options. (line 1644) +* --minor-os-version: Options. (line 1649) +* --minor-subsystem-version: Options. (line 1653) +* --mri-script=MRI-CMDFILE: Options. (line 262) +* --multi-subspace: HPPA ELF32. (line 4285) +* --nmagic: Options. (line 506) +* --no-accept-unknown-input-arch: Options. (line 774) +* --no-add-needed: Options. (line 796) +* --no-allow-shlib-undefined: Options. (line 1010) +* --no-as-needed: Options. (line 784) +* --no-check-sections: Options. (line 877) +* --no-define-common: Options. (line 899) +* --no-demangle: Options. (line 928) +* --no-dotsyms: PowerPC64 ELF64. (line 4446) +* --no-enum-size-warning: ARM. (line 4275) +* --no-gc-sections: Options. (line 960) +* --no-keep-memory: Options. (line 989) +* --no-multi-toc: PowerPC64 ELF64. (line 4487) +* --no-omagic: Options. (line 520) +* --no-opd-optimize: PowerPC64 ELF64. (line 4461) +* --no-overlays: SPU ELF. (line 4504) +* --no-print-gc-sections: Options. (line 968) +* --no-relax: Xtensa. (line 5005) +* --no-tls-optimize: PowerPC ELF32. (line 4411) +* --no-tls-optimize <1>: PowerPC64 ELF64. (line 4456) +* --no-toc-optimize: PowerPC64 ELF64. (line 4473) +* --no-trampoline: Options. (line 1861) +* --no-undefined: Options. (line 996) +* --no-undefined-version: Options. (line 1029) +* --no-warn-mismatch: Options. (line 1042) +* --no-warn-search-mismatch: Options. (line 1051) +* --no-whole-archive: Options. (line 1055) +* --noinhibit-exec: Options. (line 1059) +* --non-overlapping-opd: PowerPC64 ELF64. (line 4467) +* --oformat: Options. (line 1070) +* --omagic: Options. (line 511) +* --out-implib: Options. (line 1666) +* --output-def: Options. (line 1658) +* --output=OUTPUT: Options. (line 526) +* --pic-executable: Options. (line 1083) +* --pic-veneer: M68HC11/68HC12. (line 4180) +* --plugin: SPU ELF. (line 4501) +* --print-gc-sections: Options. (line 968) +* --print-map: Options. (line 472) +* --reduce-memory-overheads: Options. (line 1502) +* --relax: Options. (line 1099) +* '--relax' on i960: i960. (line 4138) +* --relax on PowerPC: PowerPC ELF32. (line 4369) +* '--relax' on Xtensa: Xtensa. (line 4977) +* --relocatable: Options. (line 550) +* --script=SCRIPT: Options. (line 592) +* --sdata-got: PowerPC ELF32. (line 4393) +* --section-alignment: Options. (line 1833) +* --section-start SECTIONNAME=ORG: Options. (line 1265) +* --secure-plt: PowerPC ELF32. (line 4386) +* --sort-common: Options. (line 1212) +* --sort-section alignment: Options. (line 1222) +* --sort-section name: Options. (line 1218) +* --split-by-file: Options. (line 1226) +* --split-by-reloc: Options. (line 1231) +* --stack: Options. (line 1839) +* --stack-analysis: SPU ELF. (line 4524) +* --stats: Options. (line 1244) +* --strip-all: Options. (line 579) +* --strip-debug: Options. (line 583) +* --stub-group-size: PowerPC64 ELF64. (line 4419) +* --stub-group-size=N: HPPA ELF32. (line 4291) +* --subsystem: Options. (line 1846) +* --support-old-code: ARM. (line 4188) +* --sysroot: Options. (line 1248) +* --target-help: Options. (line 981) +* --target1-abs: ARM. (line 4209) +* --target1-rel: ARM. (line 4209) +* --target2=TYPE: ARM. (line 4214) +* --thumb-entry=ENTRY: ARM. (line 4199) +* --trace: Options. (line 588) +* --trace-symbol=SYMBOL: Options. (line 657) +* --traditional-format: Options. (line 1253) +* --undefined=SYMBOL: Options. (line 614) +* --unique[=SECTION]: Options. (line 632) +* --unresolved-symbols: Options. (line 1280) +* --use-blx: ARM. (line 4237) +* --verbose: Options. (line 1309) +* --version: Options. (line 641) +* --version-script=VERSION-SCRIPTFILE: Options. (line 1315) +* --vfp11-denorm-fix: ARM. (line 4246) +* --warn-common: Options. (line 1322) +* --warn-constructors: Options. (line 1390) +* --warn-multiple-gp: Options. (line 1395) +* --warn-once: Options. (line 1409) +* --warn-section-align: Options. (line 1413) +* --warn-shared-textrel: Options. (line 1420) +* --warn-unresolved-symbols: Options. (line 1423) +* --whole-archive: Options. (line 1432) +* --wrap: Options. (line 1446) +* -AARCH: Options. (line 226) +* -aKEYWORD: Options. (line 219) +* -assert KEYWORD: Options. (line 806) +* -b FORMAT: Options. (line 238) +* -Bdynamic: Options. (line 809) +* -Bgroup: Options. (line 819) +* -Bshareable: Options. (line 1204) +* -Bstatic: Options. (line 826) +* -Bsymbolic: Options. (line 840) +* -Bsymbolic-functions: Options. (line 847) +* -c MRI-CMDFILE: Options. (line 262) +* -call_shared: Options. (line 809) +* -d: Options. (line 272) +* -dc: Options. (line 272) +* -dn: Options. (line 826) +* -dp: Options. (line 272) +* -dT SCRIPT: Options. (line 601) +* -dy: Options. (line 809) +* -E: Options. (line 302) +* -e ENTRY: Options. (line 281) +* -EB: Options. (line 321) +* -EL: Options. (line 324) +* -f: Options. (line 328) +* -F: Options. (line 349) +* -fini: Options. (line 372) +* -g: Options. (line 378) +* -G: Options. (line 381) +* -hNAME: Options. (line 389) +* -i: Options. (line 398) +* -IFILE: Options. (line 941) +* -init: Options. (line 401) +* -LDIR: Options. (line 440) +* -lNAMESPEC: Options. (line 407) +* -M: Options. (line 472) +* -m EMULATION: Options. (line 462) +* -Map: Options. (line 985) +* -n: Options. (line 506) +* -N: Options. (line 511) +* -non_shared: Options. (line 826) +* -nostdlib: Options. (line 1065) +* -O LEVEL: Options. (line 532) +* -o OUTPUT: Options. (line 526) +* -pie: Options. (line 1083) +* -q: Options. (line 537) +* -qmagic: Options. (line 1093) +* -Qy: Options. (line 1096) +* -r: Options. (line 550) +* -R FILE: Options. (line 568) +* -rpath: Options. (line 1134) +* -rpath-link: Options. (line 1156) +* -s: Options. (line 579) +* -S: Options. (line 583) +* -shared: Options. (line 1204) +* -soname=NAME: Options. (line 389) +* -static: Options. (line 826) +* -t: Options. (line 588) +* -T SCRIPT: Options. (line 592) +* -Tbss ORG: Options. (line 1274) +* -Tdata ORG: Options. (line 1274) +* -Ttext ORG: Options. (line 1274) +* -u SYMBOL: Options. (line 614) +* -Ur: Options. (line 622) +* -v: Options. (line 641) +* -V: Options. (line 641) +* -x: Options. (line 647) +* -X: Options. (line 651) +* -Y PATH: Options. (line 666) +* -y SYMBOL: Options. (line 657) +* -z defs: Options. (line 996) +* -z KEYWORD: Options. (line 670) +* -z muldefs: Options. (line 1004) +* .: Location Counter. (line 3650) +* /DISCARD/: Output Section Discarding. + (line 2932) +* :PHDR: Output Section Phdr. + (line 3065) +* =FILLEXP: Output Section Fill. + (line 3079) +* >REGION: Output Section Region. + (line 3055) +* [COMMON]: Input Section Common. + (line 2744) +* 'ABSOLUTE' (MRI): MRI. (line 5391) +* absolute and relocatable symbols: Expression Section. (line 3828) +* absolute expressions: Expression Section. (line 3828) +* ABSOLUTE(EXP): Builtin Functions. (line 3864) +* ADDR(SECTION): Builtin Functions. (line 3871) +* address, section: Output Section Address. + (line 2522) +* 'ALIAS' (MRI): MRI. (line 5402) +* 'ALIGN' (MRI): MRI. (line 5408) +* align expression: Builtin Functions. (line 3890) +* align location counter: Builtin Functions. (line 3890) +* ALIGN(ALIGN): Builtin Functions. (line 3890) +* ALIGN(EXP,ALIGN): Builtin Functions. (line 3890) +* ALIGN(SECTION_ALIGN): Forced Output Alignment. + (line 3043) +* ALIGNOF(SECTION): Builtin Functions. (line 3915) +* allocating memory: MEMORY. (line 3196) +* architecture: Miscellaneous Commands. + (line 2254) +* architectures: Options. (line 226) +* archive files, from cmd line: Options. (line 407) +* archive search path in linker script: File Commands. (line 2158) +* arithmetic: Expressions. (line 3591) +* arithmetic operators: Operators. (line 3773) +* ARM interworking support: ARM. (line 4188) +* ASSERT: Miscellaneous Commands. + (line 2217) +* assertion in linker script: Miscellaneous Commands. + (line 2217) +* assignment in scripts: Assignments. (line 2262) +* AS_NEEDED(FILES): File Commands. (line 2138) +* AT(LMA): Output Section LMA. (line 2983) +* AT>LMA_REGION: Output Section LMA. (line 2983) +* automatic data imports: WIN32. (line 4723) +* back end: BFD. (line 5019) +* 'BASE' (MRI): MRI. (line 5412) +* BE8: ARM. (line 4205) +* BFD canonical format: Canonical format. (line 5114) +* BFD requirements: BFD. (line 5029) +* big-endian objects: Options. (line 321) +* binary input format: Options. (line 238) +* BLOCK(EXP): Builtin Functions. (line 3928) +* bug criteria: Bug Criteria. (line 5201) +* bug reports: Bug Reporting. (line 5219) +* bugs in 'ld': Reporting Bugs. (line 5188) +* BYTE(EXPRESSION): Output Section Data. + (line 2788) +* C++ constructors, arranging in link: Output Section Keywords. + (line 2857) +* 'CHIP' (MRI): MRI. (line 5416) +* COLLECT_NO_DEMANGLE: Environment. (line 1899) +* combining symbols, warnings on: Options. (line 1322) +* command files: Scripts. (line 1908) +* command line: Options. (line 130) +* common allocation: Options. (line 272) +* common allocation <1>: Options. (line 899) +* common allocation in linker script: Miscellaneous Commands. + (line 2228) +* common allocation in linker script <1>: Miscellaneous Commands. + (line 2233) +* common symbol placement: Input Section Common. + (line 2721) +* compatibility, MRI: Options. (line 262) +* constants in linker scripts: Constants. (line 3604) +* constructors: Options. (line 622) +* CONSTRUCTORS: Output Section Keywords. + (line 2857) +* constructors, arranging in link: Output Section Keywords. + (line 2857) +* crash of linker: Bug Criteria. (line 5204) +* CREATE_OBJECT_SYMBOLS: Output Section Keywords. + (line 2847) +* creating a DEF file: WIN32. (line 4691) +* cross reference table: Options. (line 887) +* cross references: Miscellaneous Commands. + (line 2238) +* current output location: Location Counter. (line 3650) +* data: Output Section Data. + (line 2788) +* DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE): Builtin Functions. + (line 3933) +* DATA_SEGMENT_END(EXP): Builtin Functions. (line 3954) +* DATA_SEGMENT_RELRO_END(OFFSET, EXP): Builtin Functions. (line 3960) +* dbx: Options. (line 1258) +* DEF files, creating: Options. (line 1658) +* default emulation: Environment. (line 1891) +* default input format: Environment. (line 1879) +* DEFINED(SYMBOL): Builtin Functions. (line 3971) +* deleting local symbols: Options. (line 647) +* demangling, default: Environment. (line 1899) +* demangling, from command line: Options. (line 928) +* direct linking to a dll: WIN32. (line 4771) +* discarding sections: Output Section Discarding. + (line 2917) +* discontinuous memory: MEMORY. (line 3196) +* DLLs, creating: Options. (line 1564) +* DLLs, creating <1>: Options. (line 1658) +* DLLs, creating <2>: Options. (line 1666) +* DLLs, linking to: Options. (line 1688) +* dot: Location Counter. (line 3650) +* dot inside sections: Location Counter. (line 3680) +* dot outside sections: Location Counter. (line 3710) +* dynamic linker, from command line: Options. (line 941) +* dynamic symbol table: Options. (line 302) +* ELF program headers: PHDRS. (line 3293) +* emulation: Options. (line 462) +* emulation, default: Environment. (line 1891) +* 'END' (MRI): MRI. (line 5420) +* endianness: Options. (line 321) +* entry point: Entry Point. (line 2076) +* entry point, from command line: Options. (line 281) +* entry point, thumb: ARM. (line 4199) +* ENTRY(SYMBOL): Entry Point. (line 2076) +* error on valid input: Bug Criteria. (line 5207) +* example of linker script: Simple Example. (line 2005) +* exporting DLL symbols: WIN32. (line 4576) +* expression evaluation order: Evaluation. (line 3794) +* expression sections: Expression Section. (line 3828) +* expression, absolute: Builtin Functions. (line 3864) +* expressions: Expressions. (line 3591) +* EXTERN: Miscellaneous Commands. + (line 2221) +* fatal signal: Bug Criteria. (line 5204) +* file name wildcard patterns: Input Section Wildcards. + (line 2616) +* FILEHDR: PHDRS. (line 3348) +* filename symbols: Output Section Keywords. + (line 2847) +* fill pattern, entire section: Output Section Fill. + (line 3079) +* FILL(EXPRESSION): Output Section Data. + (line 2821) +* finalization function: Options. (line 372) +* first input file: File Commands. (line 2166) +* first instruction: Entry Point. (line 2076) +* FIX_V4BX: ARM. (line 4224) +* FORCE_COMMON_ALLOCATION: Miscellaneous Commands. + (line 2228) +* forcing input section alignment: Forced Input Alignment. + (line 3048) +* forcing output section alignment: Forced Output Alignment. + (line 3043) +* forcing the creation of dynamic sections: Options. (line 546) +* 'FORMAT' (MRI): MRI. (line 5424) +* functions in expressions: Builtin Functions. (line 3860) +* garbage collection: Options. (line 960) +* garbage collection <1>: Options. (line 968) +* garbage collection <2>: Input Section Keep. (line 2750) +* generating optimized output: Options. (line 532) +* GNU linker: Overview. (line 100) +* GNUTARGET: Environment. (line 1879) +* GROUP(FILES): File Commands. (line 2131) +* grouping input files: File Commands. (line 2131) +* groups of archives: Options. (line 756) +* H8/300 support: H8/300. (line 4078) +* header size: Builtin Functions. (line 4035) +* heap size: Options. (line 1600) +* help: Options. (line 977) +* holes: Location Counter. (line 3656) +* holes, filling: Output Section Data. + (line 2821) +* HPPA multiple sub-space stubs: HPPA ELF32. (line 4285) +* HPPA stub grouping: HPPA ELF32. (line 4291) +* i960 support: i960. (line 4112) +* image base: Options. (line 1607) +* implicit linker scripts: Implicit Linker Scripts. + (line 4054) +* import libraries: WIN32. (line 4567) +* INCLUDE FILENAME: File Commands. (line 2096) +* including a linker script: File Commands. (line 2096) +* including an entire archive: Options. (line 1432) +* incremental link: Options. (line 398) +* INHIBIT_COMMON_ALLOCATION: Miscellaneous Commands. + (line 2233) +* initialization function: Options. (line 401) +* initialized data in ROM: Output Section LMA. (line 3003) +* input file format in linker script: Format Commands. (line 2204) +* input filename symbols: Output Section Keywords. + (line 2847) +* input files in linker scripts: File Commands. (line 2103) +* input files, displaying: Options. (line 588) +* input format: Options. (line 238) +* input format <1>: Options. (line 238) +* input object files in linker scripts: File Commands. (line 2103) +* input section alignment: Forced Input Alignment. + (line 3048) +* input section basics: Input Section Basics. + (line 2568) +* input section wildcards: Input Section Wildcards. + (line 2616) +* input sections: Input Section. (line 2558) +* INPUT(FILES): File Commands. (line 2103) +* integer notation: Constants. (line 3604) +* integer suffixes: Constants. (line 3610) +* internal object-file format: Canonical format. (line 5114) +* invalid input: Bug Criteria. (line 5209) +* K and M integer suffixes: Constants. (line 3610) +* KEEP: Input Section Keep. (line 2750) +* l =: MEMORY. (line 3256) +* lazy evaluation: Evaluation. (line 3794) +* 'ld' bugs, reporting: Bug Reporting. (line 5219) +* LDEMULATION: Environment. (line 1891) +* len =: MEMORY. (line 3256) +* LENGTH =: MEMORY. (line 3256) +* LENGTH(MEMORY): Builtin Functions. (line 3988) +* library search path in linker script: File Commands. (line 2158) +* link map: Options. (line 472) +* link-time runtime library search path: Options. (line 1156) +* linker crash: Bug Criteria. (line 5204) +* linker script concepts: Basic Script Concepts. + (line 1935) +* linker script example: Simple Example. (line 2005) +* linker script file commands: File Commands. (line 2093) +* linker script format: Script Format. (line 1985) +* linker script input object files: File Commands. (line 2103) +* linker script simple commands: Simple Commands. (line 2071) +* linker scripts: Scripts. (line 1908) +* 'LIST' (MRI): MRI. (line 5435) +* little-endian objects: Options. (line 324) +* 'LOAD' (MRI): MRI. (line 5442) +* load address: Output Section LMA. (line 2983) +* LOADADDR(SECTION): Builtin Functions. (line 3991) +* loading, preventing: Output Section Type. + (line 2969) +* local symbols, deleting: Options. (line 651) +* location counter: Location Counter. (line 3650) +* LONG(EXPRESSION): Output Section Data. + (line 2788) +* M and K integer suffixes: Constants. (line 3610) +* M68HC11 and 68HC12 support: M68HC11/68HC12. (line 4148) +* machine architecture: Miscellaneous Commands. + (line 2254) +* machine dependencies: Machine Dependent. (line 4071) +* mapping input sections to output sections: Input Section. (line 2558) +* MAX: Builtin Functions. (line 3995) +* MEMORY: MEMORY. (line 3196) +* memory region attributes: MEMORY. (line 3222) +* memory regions: MEMORY. (line 3196) +* memory regions and sections: Output Section Region. + (line 3055) +* memory usage: Options. (line 989) +* MIN: Builtin Functions. (line 3998) +* MRI compatibility: MRI. (line 5365) +* MSP430 extra sections: MSP430. (line 4343) +* 'NAME' (MRI): MRI. (line 5448) +* name, section: Output Section Name. + (line 2506) +* names: Symbols. (line 3620) +* naming the output file: Options. (line 526) +* NEXT(EXP): Builtin Functions. (line 4002) +* NMAGIC: Options. (line 506) +* NOCROSSREFS(SECTIONS): Miscellaneous Commands. + (line 2238) +* NOLOAD: Output Section Type. + (line 2969) +* not enough room for program headers: Builtin Functions. (line 4040) +* NO_ENUM_SIZE_WARNING: ARM. (line 4275) +* o =: MEMORY. (line 3251) +* objdump -i: BFD. (line 5019) +* object file management: BFD. (line 5019) +* object files: Options. (line 153) +* object formats available: BFD. (line 5019) +* object size: Options. (line 381) +* OMAGIC: Options. (line 511) +* OMAGIC <1>: Options. (line 520) +* opening object files: BFD outline. (line 5045) +* operators for arithmetic: Operators. (line 3773) +* options: Options. (line 130) +* 'ORDER' (MRI): MRI. (line 5453) +* org =: MEMORY. (line 3251) +* ORIGIN =: MEMORY. (line 3251) +* ORIGIN(MEMORY): Builtin Functions. (line 4008) +* orphan: Orphan Sections. (line 3635) +* output file after errors: Options. (line 1059) +* output file format in linker script: Format Commands. (line 2179) +* output file name in linker script: File Commands. (line 2148) +* output section alignment: Forced Output Alignment. + (line 3043) +* output section attributes: Output Section Attributes. + (line 2939) +* output section data: Output Section Data. + (line 2788) +* OUTPUT(FILENAME): File Commands. (line 2148) +* OUTPUT_ARCH(BFDARCH): Miscellaneous Commands. + (line 2254) +* OUTPUT_FORMAT(BFDNAME): Format Commands. (line 2179) +* OVERLAY: Overlay Description. + (line 3101) +* overlays: Overlay Description. + (line 3101) +* partial link: Options. (line 550) +* PHDRS: PHDRS. (line 3293) +* PHDRS <1>: PHDRS. (line 3348) +* PIC_VENEER: M68HC11/68HC12. (line 4180) +* position independent executables: Options. (line 1085) +* PowerPC ELF32 options: PowerPC ELF32. (line 4376) +* PowerPC GOT: PowerPC ELF32. (line 4393) +* PowerPC long branches: PowerPC ELF32. (line 4369) +* PowerPC PLT: PowerPC ELF32. (line 4376) +* PowerPC stub symbols: PowerPC ELF32. (line 4407) +* PowerPC TLS optimization: PowerPC ELF32. (line 4411) +* PowerPC64 dot symbols: PowerPC64 ELF64. (line 4446) +* PowerPC64 ELF64 options: PowerPC64 ELF64. (line 4419) +* PowerPC64 multi-TOC: PowerPC64 ELF64. (line 4487) +* PowerPC64 OPD optimization: PowerPC64 ELF64. (line 4461) +* PowerPC64 OPD spacing: PowerPC64 ELF64. (line 4467) +* PowerPC64 stub grouping: PowerPC64 ELF64. (line 4419) +* PowerPC64 stub symbols: PowerPC64 ELF64. (line 4442) +* PowerPC64 TLS optimization: PowerPC64 ELF64. (line 4456) +* PowerPC64 TOC optimization: PowerPC64 ELF64. (line 4473) +* precedence in expressions: Operators. (line 3773) +* prevent unnecessary loading: Output Section Type. + (line 2969) +* program headers: PHDRS. (line 3293) +* program headers and sections: Output Section Phdr. + (line 3065) +* program headers, not enough room: Builtin Functions. (line 4040) +* program segments: PHDRS. (line 3293) +* PROVIDE: PROVIDE. (line 2321) +* PROVIDE_HIDDEN: PROVIDE_HIDDEN. (line 2350) +* 'PUBLIC' (MRI): MRI. (line 5461) +* QUAD(EXPRESSION): Output Section Data. + (line 2788) +* quoted symbol names: Symbols. (line 3620) +* read-only text: Options. (line 506) +* read/write from cmd line: Options. (line 511) +* regions of memory: MEMORY. (line 3196) +* relative expressions: Expression Section. (line 3828) +* relaxing addressing modes: Options. (line 1099) +* relaxing on H8/300: H8/300. (line 4081) +* relaxing on i960: i960. (line 4138) +* relaxing on M68HC11: M68HC11/68HC12. (line 4155) +* relaxing on Xtensa: Xtensa. (line 4977) +* relocatable and absolute symbols: Expression Section. (line 3828) +* relocatable output: Options. (line 550) +* removing sections: Output Section Discarding. + (line 2917) +* reporting bugs in 'ld': Reporting Bugs. (line 5188) +* requirements for BFD: BFD. (line 5029) +* retain relocations in final executable: Options. (line 537) +* retaining specified symbols: Options. (line 1120) +* ROM initialized data: Output Section LMA. (line 3003) +* round up expression: Builtin Functions. (line 3890) +* round up location counter: Builtin Functions. (line 3890) +* runtime library name: Options. (line 389) +* runtime library search path: Options. (line 1134) +* runtime pseudo-relocation: WIN32. (line 4749) +* scaled integers: Constants. (line 3610) +* scommon section: Input Section Common. + (line 2735) +* script files: Options. (line 592) +* script files <1>: Options. (line 601) +* scripts: Scripts. (line 1908) +* search directory, from cmd line: Options. (line 440) +* search path in linker script: File Commands. (line 2158) +* SEARCH_DIR(PATH): File Commands. (line 2158) +* 'SECT' (MRI): MRI. (line 5467) +* section address: Output Section Address. + (line 2522) +* section address in expression: Builtin Functions. (line 3871) +* section alignment: Builtin Functions. (line 3915) +* section alignment, warnings on: Options. (line 1413) +* section data: Output Section Data. + (line 2788) +* section fill pattern: Output Section Fill. + (line 3079) +* section load address: Output Section LMA. (line 2983) +* section load address in expression: Builtin Functions. (line 3991) +* section name: Output Section Name. + (line 2506) +* section name wildcard patterns: Input Section Wildcards. + (line 2616) +* section size: Builtin Functions. (line 4019) +* section, assigning to memory region: Output Section Region. + (line 3055) +* section, assigning to program header: Output Section Phdr. + (line 3065) +* SECTIONS: SECTIONS. (line 2443) +* sections, discarding: Output Section Discarding. + (line 2917) +* segment origins, cmd line: Options. (line 1274) +* segments, ELF: PHDRS. (line 3293) +* SEGMENT_START(SEGMENT, DEFAULT): Builtin Functions. (line 4011) +* shared libraries: Options. (line 1206) +* SHORT(EXPRESSION): Output Section Data. + (line 2788) +* SIZEOF(SECTION): Builtin Functions. (line 4019) +* SIZEOF_HEADERS: Builtin Functions. (line 4035) +* small common symbols: Input Section Common. + (line 2735) +* SORT: Input Section Wildcards. + (line 2665) +* SORT_BY_ALIGNMENT: Input Section Wildcards. + (line 2661) +* SORT_BY_NAME: Input Section Wildcards. + (line 2653) +* SPU: SPU ELF. (line 4524) +* SPU <1>: SPU ELF. (line 4541) +* SPU ELF options: SPU ELF. (line 4501) +* SPU extra overlay stubs: SPU ELF. (line 4514) +* SPU local store size: SPU ELF. (line 4519) +* SPU overlay stub symbols: SPU ELF. (line 4510) +* SPU overlays: SPU ELF. (line 4504) +* SPU plugins: SPU ELF. (line 4501) +* SQUAD(EXPRESSION): Output Section Data. + (line 2788) +* stack size: Options. (line 1839) +* standard Unix system: Options. (line 131) +* start of execution: Entry Point. (line 2076) +* STARTUP(FILENAME): File Commands. (line 2166) +* strip all symbols: Options. (line 579) +* strip debugger symbols: Options. (line 583) +* stripping all but some symbols: Options. (line 1120) +* SUBALIGN(SUBSECTION_ALIGN): Forced Input Alignment. + (line 3048) +* suffixes for integers: Constants. (line 3610) +* symbol defaults: Builtin Functions. (line 3971) +* symbol definition, scripts: Assignments. (line 2262) +* symbol names: Symbols. (line 3620) +* symbol tracing: Options. (line 657) +* symbol versions: VERSION. (line 3424) +* symbol-only input: Options. (line 568) +* symbols, from command line: Options. (line 915) +* symbols, relocatable and absolute: Expression Section. (line 3828) +* symbols, retaining selectively: Options. (line 1120) +* synthesizing linker: Options. (line 1099) +* synthesizing on H8/300: H8/300. (line 4086) +* TARGET(BFDNAME): Format Commands. (line 2204) +* TARGET1: ARM. (line 4209) +* TARGET2: ARM. (line 4214) +* thumb entry point: ARM. (line 4199) +* TI COFF versions: TI COFF. (line 4554) +* traditional format: Options. (line 1253) +* trampoline generation on M68HC11: M68HC11/68HC12. (line 4173) +* trampoline generation on M68HC12: M68HC11/68HC12. (line 4173) +* unallocated address, next: Builtin Functions. (line 4002) +* undefined symbol: Options. (line 614) +* undefined symbol in linker script: Miscellaneous Commands. + (line 2221) +* undefined symbols, warnings on: Options. (line 1409) +* uninitialized data placement: Input Section Common. + (line 2721) +* unspecified memory: Output Section Data. + (line 2821) +* usage: Options. (line 977) +* USE_BLX: ARM. (line 4237) +* using a DEF file: WIN32. (line 4596) +* using auto-export functionality: WIN32. (line 4579) +* Using decorations: WIN32. (line 4695) +* variables, defining: Assignments. (line 2262) +* verbose: Options. (line 1309) +* version: Options. (line 641) +* version script: VERSION. (line 3424) +* version script, symbol versions: Options. (line 1315) +* VERSION {script text}: VERSION. (line 3424) +* versions of symbols: VERSION. (line 3424) +* VFP11_DENORM_FIX: ARM. (line 4246) +* warnings, on combining symbols: Options. (line 1322) +* warnings, on section alignment: Options. (line 1413) +* warnings, on undefined symbols: Options. (line 1409) +* weak externals: WIN32. (line 4938) +* what is this?: Overview. (line 100) +* wildcard file name patterns: Input Section Wildcards. + (line 2616) +* Xtensa options: Xtensa. (line 5005) +* Xtensa processors: Xtensa. (line 4956) + diff --git a/etc/mtree/BSD.usr.dist b/etc/mtree/BSD.usr.dist index c24d5c4e606b..57509847bf22 100644 --- a/etc/mtree/BSD.usr.dist +++ b/etc/mtree/BSD.usr.dist @@ -175,6 +175,8 @@ .. atm .. + binutils + .. legal intel_ipw .. diff --git a/gnu/usr.bin/binutils/Makefile b/gnu/usr.bin/binutils/Makefile index 3cf4810b01ed..a41e72e98f2b 100644 --- a/gnu/usr.bin/binutils/Makefile +++ b/gnu/usr.bin/binutils/Makefile @@ -2,7 +2,8 @@ .include <src.opts.mk> -SUBDIR= libiberty \ +SUBDIR= doc\ + libiberty \ libbfd \ libopcodes \ libbinutils \ diff --git a/gnu/usr.bin/binutils/doc/Makefile b/gnu/usr.bin/binutils/doc/Makefile new file mode 100644 index 000000000000..897ddd43bcf1 --- /dev/null +++ b/gnu/usr.bin/binutils/doc/Makefile @@ -0,0 +1,12 @@ +# $FreeBSD$ + +.include "../Makefile.inc0" + +.PATH: ${SRCDIR}/gas/doc ${SRCDIR}/ld + +FILESGROUPS= TOP + +TOPDIR= ${SHAREDIR}/doc/binutils +TOP= as.txt ld.txt + +.include <bsd.prog.mk> |