aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBaptiste Daroussin <bapt@FreeBSD.org>2015-03-02 17:25:03 +0000
committerBaptiste Daroussin <bapt@FreeBSD.org>2015-03-02 17:25:03 +0000
commit1d0f6813acadfb6a48623a511a0ec820f125ee34 (patch)
tree791351b8d3b3cf85d7d4497915b844cdec9c449a
parent9ddafbe2766bfd4514295df152412f8abc3e97cb (diff)
downloadsrc-1d0f6813acadfb6a48623a511a0ec820f125ee34.tar.gz
src-1d0f6813acadfb6a48623a511a0ec820f125ee34.zip
Remove pregenerated text version of the texinfo documentation
Notes
Notes: svn path=/head/; revision=279530
-rw-r--r--contrib/binutils/gas/doc/as.txt13924
-rw-r--r--contrib/binutils/ld/ld.txt6564
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) al