diff options
| -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 91334b842db9..000000000000 --- 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 e4aa1f17d050..000000000000 --- 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 t |