diff options
| author | bapt <bapt@FreeBSD.org> | 2015-03-02 17:25:03 +0000 |
|---|---|---|
| committer | bapt <bapt@FreeBSD.org> | 2015-03-02 17:25:03 +0000 |
| commit | 5ebc3da4580126629bdf2958c3eabd9cf0ccd803 (patch) | |
| tree | 791351b8d3b3cf85d7d4497915b844cdec9c449a /contrib/binutils | |
| parent | 4bf7df989ef18b4641621b174167c5f32d80770b (diff) | |
| download | FreeBSD-src-5ebc3da4580126629bdf2958c3eabd9cf0ccd803.zip FreeBSD-src-5ebc3da4580126629bdf2958c3eabd9cf0ccd803.tar.gz | |
Remove pregenerated text version of the texinfo documentation
Diffstat (limited to 'contrib/binutils')
| -rw-r--r-- | contrib/binutils/gas/doc/as.txt | 13924 | ||||
| -rw-r--r-- | contrib/binutils/ld/ld.txt | 6564 |
2 files changed, 0 insertions, 20488 deletions
diff --git a/contrib/binutils/gas/doc/as.txt b/contrib/binutils/gas/doc/as.txt deleted file mode 100644 index 91334b8..0000000 --- a/contrib/binutils/gas/doc/as.txt +++ /dev/null @@ -1,13924 +0,0 @@ -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/ld/ld.txt b/contrib/binutils/ld/ld.txt deleted file mode 100644 index e4aa1f1..0000000 --- a/contrib/binutils/ld/ld.txt +++ /dev/null @@ -1,6564 +0,0 @@ -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) - |
