Index: head/contrib/binutils/gas/doc/as.txt =================================================================== --- head/contrib/binutils/gas/doc/as.txt (revision 279529) +++ head/contrib/binutils/gas/doc/as.txt (nonexistent) @@ -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 to tell 'as' there is no more program to assemble. - - Use '--' if you need to explicitly name the standard input file in -your command line. - - If the source is empty, 'as' produces a small, empty object file. - -Filenames and Line-numbers --------------------------- - -There are two ways of locating a line in the input file (or files) and -either may be used in reporting error messages. One way refers to a -line number in a physical file; the other refers to a line number in a -"logical" file. *Note Error and Warning Messages: Errors. - - "Physical files" are those files named in the command line given to -'as'. - - "Logical files" are simply names declared explicitly by assembler -directives; they bear no relation to physical files. Logical file names -help error messages reflect the original source file, when 'as' source -is itself synthesized from other files. 'as' understands the '#' -directives emitted by the 'gcc' preprocessor. See also *note '.file': -File. - -1.6 Output (Object) File -======================== - -Every time you run 'as' it produces an output file, which is your -assembly language program translated into numbers. This file is the -object file. Its default name is 'a.out'. You can give it another name -by using the '-o' option. Conventionally, object file names end with -'.o'. The default name is used for historical reasons: older assemblers -were capable of assembling self-contained programs directly into a -runnable program. (For some formats, this isn't currently possible, but -it can be done for the 'a.out' format.) - - The object file is meant for input to the linker 'ld'. It contains -assembled program code, information to help 'ld' integrate the assembled -program into a runnable file, and (optionally) symbolic information for -the debugger. - -1.7 Error and Warning Messages -============================== - -'as' may write warnings and error messages to the standard error file -(usually your terminal). This should not happen when a compiler runs -'as' automatically. Warnings report an assumption made so that 'as' -could keep assembling a flawed program; errors report a grave problem -that stops the assembly. - - Warning messages have the format - - file_name:NNN:Warning Message Text - -(where NNN is a line number). If a logical file name has been given -(*note '.file': File.) it is used for the filename, otherwise the name -of the current input file is used. If a logical line number was given -then it is used to calculate the number printed, otherwise the actual -line in the current source file is printed. The message text is -intended to be self explanatory (in the grand Unix tradition). - - Error messages have the format - file_name:NNN:FATAL:Error Message Text - The file name and line number are derived as for warning messages. -The actual message text may be rather less explanatory because many of -them aren't supposed to happen. - -2 Command-Line Options -********************** - -This chapter describes command-line options available in _all_ versions -of the GNU assembler; see *note Machine Dependencies::, for options -specific to the machine specific target. - - If you are invoking 'as' via the GNU C compiler, you can use the -'-Wa' option to pass arguments through to the assembler. The assembler -arguments must be separated from each other (and the '-Wa') by commas. -For example: - - gcc -c -g -O -Wa,-alh,-L file.c - -This passes two options to the assembler: '-alh' (emit a listing to -standard output with high-level and assembly source) and '-L' (retain -local symbols in the symbol table). - - Usually you do not need to use this '-Wa' mechanism, since many -compiler command-line options are automatically passed to the assembler -by the compiler. (You can call the GNU compiler driver with the '-v' -option to see precisely what options it passes to each compilation pass, -including the assembler.) - -2.1 Enable Listings: '-a[cdhlns]' -================================= - -These options enable listing output from the assembler. By itself, '-a' -requests high-level, assembly, and symbols listing. You can use other -letters to select specific options for the list: '-ah' requests a -high-level language listing, '-al' requests an output-program assembly -listing, and '-as' requests a symbol table listing. High-level listings -require that a compiler debugging option like '-g' be used, and that -assembly listings ('-al') be requested also. - - Use the '-ac' option to omit false conditionals from a listing. Any -lines which are not assembled because of a false '.if' (or '.ifdef', or -any other conditional), or a true '.if' followed by an '.else', will be -omitted from the listing. - - Use the '-ad' option to omit debugging directives from the listing. - - Once you have specified one of these options, you can further control -listing output and its appearance using the directives '.list', -'.nolist', '.psize', '.eject', '.title', and '.sbttl'. The '-an' option -turns off all forms processing. If you do not request listing output -with one of the '-a' options, the listing-control directives have no -effect. - - The letters after '-a' may be combined into one option, _e.g._, -'-aln'. - - Note if the assembler source is coming from the standard input (e.g., -because it is being created by 'gcc' and the '-pipe' command line switch -is being used) then the listing will not contain any comments or -preprocessor directives. This is because the listing code buffers input -source lines from stdin only after they have been preprocessed by the -assembler. This reduces memory usage and makes the code more efficient. - -2.2 '--alternate' -================= - -Begin in alternate macro mode, see *note '.altmacro': Altmacro. - -2.3 '-D' -======== - -This option has no effect whatsoever, but it is accepted to make it more -likely that scripts written for other assemblers also work with 'as'. - -2.4 Work Faster: '-f' -===================== - -'-f' should only be used when assembling programs written by a (trusted) -compiler. '-f' stops the assembler from doing whitespace and comment -preprocessing on the input file(s) before assembling them. *Note -Preprocessing: Preprocessing. - - _Warning:_ if you use '-f' when the files actually need to be - preprocessed (if they contain comments, for example), 'as' does not - work correctly. - -2.5 '.include' Search Path: '-I' PATH -===================================== - -Use this option to add a PATH to the list of directories 'as' searches -for files specified in '.include' directives (*note '.include': -Include.). You may use '-I' as many times as necessary to include a -variety of paths. The current working directory is always searched -first; after that, 'as' searches any '-I' directories in the same order -as they were specified (left to right) on the command line. - -2.6 Difference Tables: '-K' -=========================== - -On the machine specific family, this option is allowed, but has no -effect. It is permitted for compatibility with the GNU assembler on -other platforms, where it can be used to warn when the assembler alters -the machine code generated for '.word' directives in difference tables. -The machine specific family does not have the addressing limitations -that sometimes lead to this alteration on other platforms. - -2.7 Include Local Symbols: '-L' -=============================== - -Symbols beginning with system-specific local label prefixes, typically -'.L' for ELF systems or 'L' for traditional a.out systems, are called -"local symbols". *Note Symbol Names::. Normally you do not see such -symbols when debugging, because they are intended for the use of -programs (like compilers) that compose assembler programs, not for your -notice. Normally both 'as' and 'ld' discard such symbols, so you do not -normally debug with them. - - This option tells 'as' to retain those local symbols in the object -file. Usually if you do this you also tell the linker 'ld' to preserve -those symbols. - -2.8 Configuring listing output: '--listing' -=========================================== - -The listing feature of the assembler can be enabled via the command line -switch '-a' (*note a::). This feature combines the input source file(s) -with a hex dump of the corresponding locations in the output object -file, and displays them as a listing file. The format of this listing -can be controlled by directives inside the assembler source (i.e., -'.list' (*note List::), '.title' (*note Title::), '.sbttl' (*note -Sbttl::), '.psize' (*note Psize::), and '.eject' (*note Eject::) and -also by the following switches: - -'--listing-lhs-width='number'' - Sets the maximum width, in words, of the first line of the hex byte - dump. This dump appears on the left hand side of the listing - output. - -'--listing-lhs-width2='number'' - Sets the maximum width, in words, of any further lines of the hex - byte dump for a given input source line. If this value is not - specified, it defaults to being the same as the value specified for - '--listing-lhs-width'. If neither switch is used the default is to - one. - -'--listing-rhs-width='number'' - Sets the maximum width, in characters, of the source line that is - displayed alongside the hex dump. The default value for this - parameter is 100. The source line is displayed on the right hand - side of the listing output. - -'--listing-cont-lines='number'' - Sets the maximum number of continuation lines of hex dump that will - be displayed for a given single line of source input. The default - value is 4. - -2.9 Assemble in MRI Compatibility Mode: '-M' -============================================ - -The '-M' or '--mri' option selects MRI compatibility mode. This changes -the syntax and pseudo-op handling of 'as' to make it compatible with the -'ASM68K' or the 'ASM960' (depending upon the configured target) -assembler from Microtec Research. The exact nature of the MRI syntax -will not be documented here; see the MRI manuals for more information. -Note in particular that the handling of macros and macro arguments is -somewhat different. The purpose of this option is to permit assembling -existing MRI assembler code using 'as'. - - The MRI compatibility is not complete. Certain operations of the MRI -assembler depend upon its object file format, and can not be supported -using other object file formats. Supporting these would require -enhancing each object file format individually. These are: - - * global symbols in common section - - The m68k MRI assembler supports common sections which are merged by - the linker. Other object file formats do not support this. 'as' - handles common sections by treating them as a single common symbol. - It permits local symbols to be defined within a common section, but - it can not support global symbols, since it has no way to describe - them. - - * complex relocations - - The MRI assemblers support relocations against a negated section - address, and relocations which combine the start addresses of two - or more sections. These are not support by other object file - formats. - - * 'END' pseudo-op specifying start address - - The MRI 'END' pseudo-op permits the specification of a start - address. This is not supported by other object file formats. The - start address may instead be specified using the '-e' option to the - linker, or in a linker script. - - * 'IDNT', '.ident' and 'NAME' pseudo-ops - - The MRI 'IDNT', '.ident' and 'NAME' pseudo-ops assign a module name - to the output file. This is not supported by other object file - formats. - - * 'ORG' pseudo-op - - The m68k MRI 'ORG' pseudo-op begins an absolute section at a given - address. This differs from the usual 'as' '.org' pseudo-op, which - changes the location within the current section. Absolute sections - are not supported by other object file formats. The address of a - section may be assigned within a linker script. - - There are some other features of the MRI assembler which are not -supported by 'as', typically either because they are difficult or -because they seem of little consequence. Some of these may be supported -in future releases. - - * EBCDIC strings - - EBCDIC strings are not supported. - - * packed binary coded decimal - - Packed binary coded decimal is not supported. This means that the - 'DC.P' and 'DCB.P' pseudo-ops are not supported. - - * 'FEQU' pseudo-op - - The m68k 'FEQU' pseudo-op is not supported. - - * 'NOOBJ' pseudo-op - - The m68k 'NOOBJ' pseudo-op is not supported. - - * 'OPT' branch control options - - The m68k 'OPT' branch control options--'B', 'BRS', 'BRB', 'BRL', - and 'BRW'--are ignored. 'as' automatically relaxes all branches, - whether forward or backward, to an appropriate size, so these - options serve no purpose. - - * 'OPT' list control options - - The following m68k 'OPT' list control options are ignored: 'C', - 'CEX', 'CL', 'CRE', 'E', 'G', 'I', 'M', 'MEX', 'MC', 'MD', 'X'. - - * other 'OPT' options - - The following m68k 'OPT' options are ignored: 'NEST', 'O', 'OLD', - 'OP', 'P', 'PCO', 'PCR', 'PCS', 'R'. - - * 'OPT' 'D' option is default - - The m68k 'OPT' 'D' option is the default, unlike the MRI assembler. - 'OPT NOD' may be used to turn it off. - - * 'XREF' pseudo-op. - - The m68k 'XREF' pseudo-op is ignored. - - * '.debug' pseudo-op - - The i960 '.debug' pseudo-op is not supported. - - * '.extended' pseudo-op - - The i960 '.extended' pseudo-op is not supported. - - * '.list' pseudo-op. - - The various options of the i960 '.list' pseudo-op are not - supported. - - * '.optimize' pseudo-op - - The i960 '.optimize' pseudo-op is not supported. - - * '.output' pseudo-op - - The i960 '.output' pseudo-op is not supported. - - * '.setreal' pseudo-op - - The i960 '.setreal' pseudo-op is not supported. - -2.10 Dependency Tracking: '--MD' -================================ - -'as' can generate a dependency file for the file it creates. This file -consists of a single rule suitable for 'make' describing the -dependencies of the main source file. - - The rule is written to the file named in its argument. - - This feature is used in the automatic updating of makefiles. - -2.11 Name the Object File: '-o' -=============================== - -There is always one object file output when you run 'as'. By default it -has the name 'a.out'. You use this option (which takes exactly one -filename) to give the object file a different name. - - Whatever the object file is called, 'as' overwrites any existing file -of the same name. - -2.12 Join Data and Text Sections: '-R' -====================================== - -'-R' tells 'as' to write the object file as if all data-section data -lives in the text section. This is only done at the very last moment: -your binary data are the same, but data section parts are relocated -differently. The data section part of your object file is zero bytes -long because all its bytes are appended to the text section. (*Note -Sections and Relocation: Sections.) - - When you specify '-R' it would be possible to generate shorter -address displacements (because we do not have to cross between text and -data section). We refrain from doing this simply for compatibility with -older versions of 'as'. In future, '-R' may work this way. - - When 'as' is configured for COFF or ELF output, this option is only -useful if you use sections named '.text' and '.data'. - -2.13 Display Assembly Statistics: '--statistics' -================================================ - -Use '--statistics' to display two statistics about the resources used by -'as': the maximum amount of space allocated during the assembly (in -bytes), and the total execution time taken for the assembly (in CPU -seconds). - -2.14 Compatible Output: '--traditional-format' -============================================== - -For some targets, the output of 'as' is different in some ways from the -output of some existing assembler. This switch requests 'as' to use the -traditional format instead. - - For example, it disables the exception frame optimizations which 'as' -normally does by default on 'gcc' output. - -2.15 Announce Version: '-v' -=========================== - -You can find out what version of as is running by including the option -'-v' (which you can also spell as '-version') on the command line. - -2.16 Control Warnings: '-W', '--warn', '--no-warn', '--fatal-warnings' -====================================================================== - -'as' should never give a warning or error message when assembling -compiler output. But programs written by people often cause 'as' to -give a warning that a particular assumption was made. All such warnings -are directed to the standard error file. - - If you use the '-W' and '--no-warn' options, no warnings are issued. -This only affects the warning messages: it does not change any -particular of how 'as' assembles your file. Errors, which stop the -assembly, are still reported. - - If you use the '--fatal-warnings' option, 'as' considers files that -generate warnings to be in error. - - You can switch these options off again by specifying '--warn', which -causes warnings to be output as usual. - -2.17 Generate Object File in Spite of Errors: '-Z' -================================================== - -After an error message, 'as' normally produces no output. If for some -reason you are interested in object file output even after 'as' gives an -error message on your program, use the '-Z' option. If there are any -errors, 'as' continues anyways, and writes an object file after a final -warning message of the form 'N errors, M warnings, generating bad object -file.' - -3 Syntax -******** - -This chapter describes the machine-independent syntax allowed in a -source file. 'as' syntax is similar to what many other assemblers use; -it is inspired by the BSD 4.2 assembler. - -3.1 Preprocessing -================= - -The 'as' internal preprocessor: - * adjusts and removes extra whitespace. It leaves one space or tab - before the keywords on a line, and turns any other whitespace on - the line into a single space. - - * removes all comments, replacing them with a single space, or an - appropriate number of newlines. - - * converts character constants into the appropriate numeric values. - - It does not do macro processing, include file handling, or anything -else you may get from your C compiler's preprocessor. You can do -include file processing with the '.include' directive (*note '.include': -Include.). You can use the GNU C compiler driver to get other "CPP" -style preprocessing by giving the input file a '.S' suffix. *Note -Options Controlling the Kind of Output: (gcc.info)Overall Options. - - Excess whitespace, comments, and character constants cannot be used -in the portions of the input text that are not preprocessed. - - If the first line of an input file is '#NO_APP' or if you use the -'-f' option, whitespace and comments are not removed from the input -file. Within an input file, you can ask for whitespace and comment -removal in specific portions of the by putting a line that says '#APP' -before the text that may contain whitespace or comments, and putting a -line that says '#NO_APP' after this text. This feature is mainly intend -to support 'asm' statements in compilers whose output is otherwise free -of comments and whitespace. - -3.2 Whitespace -============== - -"Whitespace" is one or more blanks or tabs, in any order. Whitespace is -used to separate symbols, and to make programs neater for people to -read. Unless within character constants (*note Character Constants: -Characters.), any whitespace means the same as exactly one space. - -3.3 Comments -============ - -There are two ways of rendering comments to 'as'. In both cases the -comment is equivalent to one space. - - Anything from '/*' through the next '*/' is a comment. This means -you may not nest these comments. - - /* - The only way to include a newline ('\n') in a comment - is to use this sort of comment. - */ - - /* This sort of comment does not nest. */ - - Anything from the "line comment" character to the next newline is -considered a comment and is ignored. The line comment character is '@' -on the ARM; '#' on the i386 and x86-64; '#' for Motorola PowerPC; '!' on -the SPARC; see *note Machine Dependencies::. - - To be compatible with past assemblers, lines that begin with '#' have -a special interpretation. Following the '#' should be an absolute -expression (*note Expressions::): the logical line number of the _next_ -line. Then a string (*note Strings: Strings.) is allowed: if present it -is a new logical file name. The rest of the line, if any, should be -whitespace. - - If the first non-whitespace characters on the line are not numeric, -the line is ignored. (Just like a comment.) - - # This is an ordinary comment. - # 42-6 "new_file_name" # New logical file name - # This is logical line # 36. - This feature is deprecated, and may disappear from future versions of -'as'. - -3.4 Symbols -=========== - -A "symbol" is one or more characters chosen from the set of all letters -(both upper and lower case), digits and the three characters '_.$'. No -symbol may begin with a digit. Case is significant. There is no length -limit: all characters are significant. Symbols are delimited by -characters not in that set, or by the beginning of a file (since the -source program must end with a newline, the end of a file is not a -possible symbol delimiter). *Note Symbols::. - -3.5 Statements -============== - -A "statement" ends at a newline character ('\n') or at a semicolon -(';'). The newline or semicolon is considered part of the preceding -statement. Newlines and semicolons within character constants are an -exception: they do not end statements. - - It is an error to end any statement with end-of-file: the last -character of any input file should be a newline. - - An empty statement is allowed, and may include whitespace. It is -ignored. - - A statement begins with zero or more labels, optionally followed by a -key symbol which determines what kind of statement it is. The key -symbol determines the syntax of the rest of the statement. If the -symbol begins with a dot '.' then the statement is an assembler -directive: typically valid for any computer. If the symbol begins with -a letter the statement is an assembly language "instruction": it -assembles into a machine language instruction. - - A label is a symbol immediately followed by a colon (':'). -Whitespace before a label or after a colon is permitted, but you may not -have whitespace between a label's symbol and its colon. *Note Labels::. - - label: .directive followed by something - another_label: # This is an empty statement. - instruction operand_1, operand_2, ... - -3.6 Constants -============= - -A constant is a number, written so that its value is known by -inspection, without knowing any context. Like this: - .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value. - .ascii "Ring the bell\7" # A string constant. - .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum. - .float 0f-314159265358979323846264338327\ - 95028841971.693993751E-40 # - pi, a flonum. - -3.6.1 Character Constants -------------------------- - -There are two kinds of character constants. A "character" stands for -one character in one byte and its value may be used in numeric -expressions. String constants (properly called string _literals_) are -potentially many bytes and their values may not be used in arithmetic -expressions. - -3.6.1.1 Strings -............... - -A "string" is written between double-quotes. It may contain -double-quotes or null characters. The way to get special characters -into a string is to "escape" these characters: precede them with a -backslash '\' character. For example '\\' represents one backslash: the -first '\' is an escape which tells 'as' to interpret the second -character literally as a backslash (which prevents 'as' from recognizing -the second '\' as an escape character). The complete list of escapes -follows. - -'\b' - Mnemonic for backspace; for ASCII this is octal code 010. - -'\f' - Mnemonic for FormFeed; for ASCII this is octal code 014. - -'\n' - Mnemonic for newline; for ASCII this is octal code 012. - -'\r' - Mnemonic for carriage-Return; for ASCII this is octal code 015. - -'\t' - Mnemonic for horizontal Tab; for ASCII this is octal code 011. - -'\ DIGIT DIGIT DIGIT' - An octal character code. The numeric code is 3 octal digits. For - compatibility with other Unix systems, 8 and 9 are accepted as - digits: for example, '\008' has the value 010, and '\009' the value - 011. - -'\x HEX-DIGITS...' - A hex character code. All trailing hex digits are combined. - Either upper or lower case 'x' works. - -'\\' - Represents one '\' character. - -'\"' - Represents one '"' character. Needed in strings to represent this - character, because an unescaped '"' would end the string. - -'\ ANYTHING-ELSE' - Any other character when escaped by '\' gives a warning, but - assembles as if the '\' was not present. The idea is that if you - used an escape sequence you clearly didn't want the literal - interpretation of the following character. However 'as' has no - other interpretation, so 'as' knows it is giving you the wrong code - and warns you of the fact. - - Which characters are escapable, and what those escapes represent, -varies widely among assemblers. The current set is what we think the -BSD 4.2 assembler recognizes, and is a subset of what most C compilers -recognize. If you are in doubt, do not use an escape sequence. - -3.6.1.2 Characters -.................. - -A single character may be written as a single quote immediately followed -by that character. The same escapes apply to characters as to strings. -So if you want to write the character backslash, you must write ''\\' -where the first '\' escapes the second '\'. As you can see, the quote -is an acute accent, not a grave accent. A newline (or semicolon ';') -immediately following an acute accent is taken as a literal character -and does not count as the end of a statement. The value of a character -constant in a numeric expression is the machine's byte-wide code for -that character. 'as' assumes your character code is ASCII: ''A' means -65, ''B' means 66, and so on. - -3.6.2 Number Constants ----------------------- - -'as' distinguishes three kinds of numbers according to how they are -stored in the target machine. _Integers_ are numbers that would fit -into an 'int' in the C language. _Bignums_ are integers, but they are -stored in more than 32 bits. _Flonums_ are floating point numbers, -described below. - -3.6.2.1 Integers -................ - -A binary integer is '0b' or '0B' followed by zero or more of the binary -digits '01'. - - An octal integer is '0' followed by zero or more of the octal digits -('01234567'). - - A decimal integer starts with a non-zero digit followed by zero or -more digits ('0123456789'). - - A hexadecimal integer is '0x' or '0X' followed by one or more -hexadecimal digits chosen from '0123456789abcdefABCDEF'. - - Integers have the usual values. To denote a negative integer, use -the prefix operator '-' discussed under expressions (*note Prefix -Operators: Prefix Ops.). - -3.6.2.2 Bignums -............... - -A "bignum" has the same syntax and semantics as an integer except that -the number (or its negative) takes more than 32 bits to represent in -binary. The distinction is made because in some places integers are -permitted while bignums are not. - -3.6.2.3 Flonums -............... - -A "flonum" represents a floating point number. The translation is -indirect: a decimal floating point number from the text is converted by -'as' to a generic binary floating point number of more than sufficient -precision. This generic floating point number is converted to a -particular computer's floating point format (or formats) by a portion of -'as' specialized to that computer. - - A flonum is written by writing (in order) - * The digit '0'. - - * A letter, to tell 'as' the rest of the number is a flonum. - - * An optional sign: either '+' or '-'. - - * An optional "integer part": zero or more decimal digits. - - * An optional "fractional part": '.' followed by zero or more decimal - digits. - - * An optional exponent, consisting of: - - * An 'E' or 'e'. - * Optional sign: either '+' or '-'. - * One or more decimal digits. - - At least one of the integer part or the fractional part must be -present. The floating point number has the usual base-10 value. - - 'as' does all processing using integers. Flonums are computed -independently of any floating point hardware in the computer running -'as'. - -4 Sections and Relocation -************************* - -4.1 Background -============== - -Roughly, a section is a range of addresses, with no gaps; all data "in" -those addresses is treated the same for some particular purpose. For -example there may be a "read only" section. - - The linker 'ld' reads many object files (partial programs) and -combines their contents to form a runnable program. When 'as' emits an -object file, the partial program is assumed to start at address 0. 'ld' -assigns the final addresses for the partial program, so that different -partial programs do not overlap. This is actually an -oversimplification, but it suffices to explain how 'as' uses sections. - - 'ld' moves blocks of bytes of your program to their run-time -addresses. These blocks slide to their run-time addresses as rigid -units; their length does not change and neither does the order of bytes -within them. Such a rigid unit is called a _section_. Assigning -run-time addresses to sections is called "relocation". It includes the -task of adjusting mentions of object-file addresses so they refer to the -proper run-time addresses. - - An object file written by 'as' has at least three sections, any of -which may be empty. These are named "text", "data" and "bss" sections. - - 'as' can also generate whatever other named sections you specify -using the '.section' directive (*note '.section': Section.). If you do -not use any directives that place output in the '.text' or '.data' -sections, these sections still exist, but are empty. - - Within the object file, the text section starts at address '0', the -data section follows, and the bss section follows the data section. - - To let 'ld' know which data changes when the sections are relocated, -and how to change that data, 'as' also writes to the object file details -of the relocation needed. To perform relocation 'ld' must know, each -time an address in the object file is mentioned: - * Where in the object file is the beginning of this reference to an - address? - * How long (in bytes) is this reference? - * Which section does the address refer to? What is the numeric value - of - (ADDRESS) - (START-ADDRESS OF SECTION)? - * Is the reference to an address "Program-Counter relative"? - - In fact, every address 'as' ever uses is expressed as - (SECTION) + (OFFSET INTO SECTION) -Further, most expressions 'as' computes have this section-relative -nature. - - In this manual we use the notation {SECNAME N} to mean "offset N into -section SECNAME." - - Apart from text, data and bss sections you need to know about the -"absolute" section. When 'ld' mixes partial programs, addresses in the -absolute section remain unchanged. For example, address '{absolute 0}' -is "relocated" to run-time address 0 by 'ld'. Although the linker never -arranges two partial programs' data sections with overlapping addresses -after linking, _by definition_ their absolute sections must overlap. -Address '{absolute 239}' in one part of a program is always the same -address when the program is running as address '{absolute 239}' in any -other part of the program. - - The idea of sections is extended to the "undefined" section. Any -address whose section is unknown at assembly time is by definition -rendered {undefined U}--where U is filled in later. Since numbers are -always defined, the only way to generate an undefined address is to -mention an undefined symbol. A reference to a named common block would -be such a symbol: its value is unknown at assembly time so it has -section _undefined_. - - By analogy the word _section_ is used to describe groups of sections -in the linked program. 'ld' puts all partial programs' text sections in -contiguous addresses in the linked program. It is customary to refer to -the _text section_ of a program, meaning all the addresses of all -partial programs' text sections. Likewise for data and bss sections. - - Some sections are manipulated by 'ld'; others are invented for use of -'as' and have no meaning except during assembly. - -4.2 Linker Sections -=================== - -'ld' deals with just four kinds of sections, summarized below. - -*named sections* - These sections hold your program. 'as' and 'ld' treat them as - separate but equal sections. Anything you can say of one section - is true of another. When the program is running, however, it is - customary for the text section to be unalterable. The text section - is often shared among processes: it contains instructions, - constants and the like. The data section of a running program is - usually alterable: for example, C variables would be stored in the - data section. - -*bss section* - This section contains zeroed bytes when your program begins - running. It is used to hold uninitialized variables or common - storage. The length of each partial program's bss section is - important, but because it starts out containing zeroed bytes there - is no need to store explicit zero bytes in the object file. The - bss section was invented to eliminate those explicit zeros from - object files. - -*absolute section* - Address 0 of this section is always "relocated" to runtime address - 0. This is useful if you want to refer to an address that 'ld' - must not change when relocating. In this sense we speak of - absolute addresses being "unrelocatable": they do not change during - relocation. - -*undefined section* - This "section" is a catch-all for address references to objects not - in the preceding sections. - - An idealized example of three relocatable sections follows. The -example uses the traditional section names '.text' and '.data'. Memory -addresses are on the horizontal axis. - - +-----+----+--+ - partial program # 1: |ttttt|dddd|00| - +-----+----+--+ - - text data bss - seg. seg. seg. - - +---+---+---+ - partial program # 2: |TTT|DDD|000| - +---+---+---+ - - +--+---+-----+--+----+---+-----+~~ - linked program: | |TTT|ttttt| |dddd|DDD|00000| - +--+---+-----+--+----+---+-----+~~ - - addresses: 0 ... - -4.3 Assembler Internal Sections -=============================== - -These sections are meant only for the internal use of 'as'. They have -no meaning at run-time. You do not really need to know about these -sections for most purposes; but they can be mentioned in 'as' warning -messages, so it might be helpful to have an idea of their meanings to -'as'. These sections are used to permit the value of every expression -in your assembly language program to be a section-relative address. - -ASSEMBLER-INTERNAL-LOGIC-ERROR! - An internal assembler logic error has been found. This means there - is a bug in the assembler. - -expr section - The assembler stores complex expression internally as combinations - of symbols. When it needs to represent an expression as a symbol, - it puts it in the expr section. - -4.4 Sub-Sections -================ - -You may have separate groups of data in named sections that you want to -end up near to each other in the object file, even though they are not -contiguous in the assembler source. 'as' allows you to use -"subsections" for this purpose. Within each section, there can be -numbered subsections with values from 0 to 8192. Objects assembled into -the same subsection go into the object file together with other objects -in the same subsection. For example, a compiler might want to store -constants in the text section, but might not want to have them -interspersed with the program being assembled. In this case, the -compiler could issue a '.text 0' before each section of code being -output, and a '.text 1' before each group of constants being output. - - Subsections are optional. If you do not use subsections, everything -goes in subsection number zero. - - Subsections appear in your object file in numeric order, lowest -numbered to highest. (All this to be compatible with other people's -assemblers.) The object file contains no representation of subsections; -'ld' and other programs that manipulate object files see no trace of -them. They just see all your text subsections as a text section, and -all your data subsections as a data section. - - To specify which subsection you want subsequent statements assembled -into, use a numeric argument to specify it, in a '.text EXPRESSION' or a -'.data EXPRESSION' statement. You can also use the '.subsection' -directive (*note SubSection::) to specify a subsection: '.subsection -EXPRESSION'. EXPRESSION should be an absolute expression (*note -Expressions::). If you just say '.text' then '.text 0' is assumed. -Likewise '.data' means '.data 0'. Assembly begins in 'text 0'. For -instance: - .text 0 # The default subsection is text 0 anyway. - .ascii "This lives in the first text subsection. *" - .text 1 - .ascii "But this lives in the second text subsection." - .data 0 - .ascii "This lives in the data section," - .ascii "in the first data subsection." - .text 0 - .ascii "This lives in the first text section," - .ascii "immediately following the asterisk (*)." - - Each section has a "location counter" incremented by one for every -byte assembled into that section. Because subsections are merely a -convenience restricted to 'as' there is no concept of a subsection -location counter. There is no way to directly manipulate a location -counter--but the '.align' directive changes it, and any label definition -captures its current value. The location counter of the section where -statements are being assembled is said to be the "active" location -counter. - -4.5 bss Section -=============== - -The bss section is used for local common variable storage. You may -allocate address space in the bss section, but you may not dictate data -to load into it before your program executes. When your program starts -running, all the contents of the bss section are zeroed bytes. - - The '.lcomm' pseudo-op defines a symbol in the bss section; see *note -'.lcomm': Lcomm. - - The '.comm' pseudo-op may be used to declare a common symbol, which -is another form of uninitialized symbol; see *note '.comm': Comm. - -5 Symbols -********* - -Symbols are a central concept: the programmer uses symbols to name -things, the linker uses symbols to link, and the debugger uses symbols -to debug. - - _Warning:_ 'as' does not place symbols in the object file in the - same order they were declared. This may break some debuggers. - -5.1 Labels -========== - -A "label" is written as a symbol immediately followed by a colon ':'. -The symbol then represents the current value of the active location -counter, and is, for example, a suitable instruction operand. You are -warned if you use the same symbol to represent two different locations: -the first definition overrides any other definitions. - -5.2 Giving Symbols Other Values -=============================== - -A symbol can be given an arbitrary value by writing a symbol, followed -by an equals sign '=', followed by an expression (*note Expressions::). -This is equivalent to using the '.set' directive. *Note '.set': Set. -In the same way, using a double equals sign '=''=' here represents an -equivalent of the '.eqv' directive. *Note '.eqv': Eqv. - -5.3 Symbol Names -================ - -Symbol names begin with a letter or with one of '._'. On most machines, -you can also use '$' in symbol names; exceptions are noted in *note -Machine Dependencies::. That character may be followed by any string of -digits, letters, dollar signs (unless otherwise noted for a particular -target machine), and underscores. - - Case of letters is significant: 'foo' is a different symbol name than -'Foo'. - - Each symbol has exactly one name. Each name in an assembly language -program refers to exactly one symbol. You may use that symbol name any -number of times in a program. - -Local Symbol Names ------------------- - -A local symbol is any symbol beginning with certain local label -prefixes. By default, the local label prefix is '.L' for ELF systems or -'L' for traditional a.out systems, but each target may have its own set -of local label prefixes. - - Local symbols are defined and used within the assembler, but they are -normally not saved in object files. Thus, they are not visible when -debugging. You may use the '-L' option (*note Include Local Symbols: -'-L': L.) to retain the local symbols in the object files. - -Local Labels ------------- - -Local labels help compilers and programmers use names temporarily. They -create symbols which are guaranteed to be unique over the entire scope -of the input source code and which can be referred to by a simple -notation. To define a local label, write a label of the form 'N:' -(where N represents any positive integer). To refer to the most recent -previous definition of that label write 'Nb', using the same number as -when you defined the label. To refer to the next definition of a local -label, write 'Nf'--the 'b' stands for "backwards" and the 'f' stands for -"forwards". - - There is no restriction on how you can use these labels, and you can -reuse them too. So that it is possible to repeatedly define the same -local label (using the same number 'N'), although you can only refer to -the most recently defined local label of that number (for a backwards -reference) or the next definition of a specific local label for a -forward reference. It is also worth noting that the first 10 local -labels ('0:'...'9:') are implemented in a slightly more efficient manner -than the others. - - Here is an example: - - 1: branch 1f - 2: branch 1b - 1: branch 2f - 2: branch 1b - - Which is the equivalent of: - - label_1: branch label_3 - label_2: branch label_1 - label_3: branch label_4 - label_4: branch label_3 - - Local label names are only a notational device. They are immediately -transformed into more conventional symbol names before the assembler -uses them. The symbol names are stored in the symbol table, appear in -error messages, and are optionally emitted to the object file. The -names are constructed using these parts: - -'_local label prefix_' - All local symbols begin with the system-specific local label - prefix. Normally both 'as' and 'ld' forget symbols that start with - the local label prefix. These labels are used for symbols you are - never intended to see. If you use the '-L' option then 'as' - retains these symbols in the object file. If you also instruct - 'ld' to retain these symbols, you may use them in debugging. - -'NUMBER' - This is the number that was used in the local label definition. So - if the label is written '55:' then the number is '55'. - -'C-B' - This unusual character is included so you do not accidentally - invent a symbol of the same name. The character has ASCII value of - '\002' (control-B). - -'_ordinal number_' - This is a serial number to keep the labels distinct. The first - definition of '0:' gets the number '1'. The 15th definition of - '0:' gets the number '15', and so on. Likewise the first - definition of '1:' gets the number '1' and its 15th definition gets - '15' as well. - - So for example, the first '1:' may be named '.L1C-B1', and the 44th -'3:' may be named '.L3C-B44'. - -Dollar Local Labels -------------------- - -'as' also supports an even more local form of local labels called dollar -labels. These labels go out of scope (i.e., they become undefined) as -soon as a non-local label is defined. Thus they remain valid for only a -small region of the input source code. Normal local labels, by -contrast, remain in scope for the entire file, or until they are -redefined by another occurrence of the same local label. - - Dollar labels are defined in exactly the same way as ordinary local -labels, except that instead of being terminated by a colon, they are -terminated by a dollar sign, e.g., '55$'. - - They can also be distinguished from ordinary local labels by their -transformed names which use ASCII character '\001' (control-A) as the -magic character to distinguish them from ordinary labels. For example, -the fifth definition of '6$' may be named '.L6'C-A'5'. - -5.4 The Special Dot Symbol -========================== - -The special symbol '.' refers to the current address that 'as' is -assembling into. Thus, the expression 'melvin: .long .' defines -'melvin' to contain its own address. Assigning a value to '.' is -treated the same as a '.org' directive. Thus, the expression '.=.+4' is -the same as saying '.space 4'. - -5.5 Symbol Attributes -===================== - -Every symbol has, as well as its name, the attributes "Value" and -"Type". Depending on output format, symbols can also have auxiliary -attributes. The detailed definitions are in 'a.out.h'. - - If you use a symbol without defining it, 'as' assumes zero for all -these attributes, and probably won't warn you. This makes the symbol an -externally defined symbol, which is generally what you would want. - -5.5.1 Value ------------ - -The value of a symbol is (usually) 32 bits. For a symbol which labels a -location in the text, data, bss or absolute sections the value is the -number of addresses from the start of that section to the label. -Naturally for text, data and bss sections the value of a symbol changes -as 'ld' changes section base addresses during linking. Absolute -symbols' values do not change during linking: that is why they are -called absolute. - - The value of an undefined symbol is treated in a special way. If it -is 0 then the symbol is not defined in this assembler source file, and -'ld' tries to determine its value from other files linked into the same -program. You make this kind of symbol simply by mentioning a symbol -name without defining it. A non-zero value represents a '.comm' common -declaration. The value is how much common storage to reserve, in bytes -(addresses). The symbol refers to the first address of the allocated -storage. - -5.5.2 Type ----------- - -The type attribute of a symbol contains relocation (section) -information, any flag settings indicating that a symbol is external, and -(optionally), other information for linkers and debuggers. The exact -format depends on the object-code output format in use. - -6 Expressions -************* - -An "expression" specifies an address or numeric value. Whitespace may -precede and/or follow an expression. - - The result of an expression must be an absolute number, or else an -offset into a particular section. If an expression is not absolute, and -there is not enough information when 'as' sees the expression to know -its section, a second pass over the source program might be necessary to -interpret the expression--but the second pass is currently not -implemented. 'as' aborts with an error message in this situation. - -6.1 Empty Expressions -===================== - -An empty expression has no value: it is just whitespace or null. -Wherever an absolute expression is required, you may omit the -expression, and 'as' assumes a value of (absolute) 0. This is -compatible with other assemblers. - -6.2 Integer Expressions -======================= - -An "integer expression" is one or more _arguments_ delimited by -_operators_. - -6.2.1 Arguments ---------------- - -"Arguments" are symbols, numbers or subexpressions. In other contexts -arguments are sometimes called "arithmetic operands". In this manual, -to avoid confusing them with the "instruction operands" of the machine -language, we use the term "argument" to refer to parts of expressions -only, reserving the word "operand" to refer only to machine instruction -operands. - - Symbols are evaluated to yield {SECTION NNN} where SECTION is one of -text, data, bss, absolute, or undefined. NNN is a signed, 2's -complement 32 bit integer. - - Numbers are usually integers. - - A number can be a flonum or bignum. In this case, you are warned -that only the low order 32 bits are used, and 'as' pretends these 32 -bits are an integer. You may write integer-manipulating instructions -that act on exotic constants, compatible with other assemblers. - - Subexpressions are a left parenthesis '(' followed by an integer -expression, followed by a right parenthesis ')'; or a prefix operator -followed by an argument. - -6.2.2 Operators ---------------- - -"Operators" are arithmetic functions, like '+' or '%'. Prefix operators -are followed by an argument. Infix operators appear between their -arguments. Operators may be preceded and/or followed by whitespace. - -6.2.3 Prefix Operator ---------------------- - -'as' has the following "prefix operators". They each take one argument, -which must be absolute. - -'-' - "Negation". Two's complement negation. -'~' - "Complementation". Bitwise not. - -6.2.4 Infix Operators ---------------------- - -"Infix operators" take two arguments, one on either side. Operators -have precedence, but operations with equal precedence are performed left -to right. Apart from '+' or '-', both arguments must be absolute, and -the result is absolute. - - 1. Highest Precedence - - '*' - "Multiplication". - - '/' - "Division". Truncation is the same as the C operator '/' - - '%' - "Remainder". - - '<<' - "Shift Left". Same as the C operator '<<'. - - '>>' - "Shift Right". Same as the C operator '>>'. - - 2. Intermediate precedence - - '|' - - "Bitwise Inclusive Or". - - '&' - "Bitwise And". - - '^' - "Bitwise Exclusive Or". - - '!' - "Bitwise Or Not". - - 3. Low Precedence - - '+' - "Addition". If either argument is absolute, the result has - the section of the other argument. You may not add together - arguments from different sections. - - '-' - "Subtraction". If the right argument is absolute, the result - has the section of the left argument. If both arguments are - in the same section, the result is absolute. You may not - subtract arguments from different sections. - - '==' - "Is Equal To" - '<>' - '!=' - "Is Not Equal To" - '<' - "Is Less Than" - '>' - "Is Greater Than" - '>=' - "Is Greater Than Or Equal To" - '<=' - "Is Less Than Or Equal To" - - The comparison operators can be used as infix operators. A - true results has a value of -1 whereas a false result has a - value of 0. Note, these operators perform signed comparisons. - - 4. Lowest Precedence - - '&&' - "Logical And". - - '||' - "Logical Or". - - These two logical operations can be used to combine the - results of sub expressions. Note, unlike the comparison - operators a true result returns a value of 1 but a false - results does still return 0. Also note that the logical or - operator has a slightly lower precedence than logical and. - - In short, it's only meaningful to add or subtract the _offsets_ in an -address; you can only have a defined section in one of the two -arguments. - -7 Assembler Directives -********************** - -All assembler directives have names that begin with a period ('.'). The -rest of the name is letters, usually in lower case. - - This chapter discusses directives that are available regardless of -the target machine configuration for the GNU assembler. - -7.1 '.abort' -============ - -This directive stops the assembly immediately. It is for compatibility -with other assemblers. The original idea was that the assembly language -source would be piped into the assembler. If the sender of the source -quit, it could use this directive tells 'as' to quit also. One day -'.abort' will not be supported. - -7.2 '.align ABS-EXPR, ABS-EXPR, ABS-EXPR' -========================================= - -Pad the location counter (in the current subsection) to a particular -storage boundary. The first expression (which must be absolute) is the -alignment required, as described below. - - The second expression (also absolute) gives the fill value to be -stored in the padding bytes. It (and the comma) may be omitted. If it -is omitted, the padding bytes are normally zero. However, on some -systems, if the section is marked as containing code and the fill value -is omitted, the space is filled with no-op instructions. - - The third expression is also absolute, and is also optional. If it -is present, it is the maximum number of bytes that should be skipped by -this alignment directive. If doing the alignment would require skipping -more bytes than the specified maximum, then the alignment is not done at -all. You can omit the fill value (the second argument) entirely by -simply using two commas after the required alignment; this can be useful -if you want the alignment to be filled with no-op instructions when -appropriate. - - The way the required alignment is specified varies from system to -system. For the arc, hppa, i386 using ELF, i860, iq2000, m68k, or32, -s390, sparc, tic4x, tic80 and xtensa, the first expression is the -alignment request in bytes. For example '.align 8' advances the -location counter until it is a multiple of 8. If the location counter -is already a multiple of 8, no change is needed. For the tic54x, the -first expression is the alignment request in words. - - For other systems, including the i386 using a.out format, and the arm -and strongarm, it is the number of low-order zero bits the location -counter must have after advancement. For example '.align 3' advances -the location counter until it a multiple of 8. If the location counter -is already a multiple of 8, no change is needed. - - This inconsistency is due to the different behaviors of the various -native assemblers for these systems which GAS must emulate. GAS also -provides '.balign' and '.p2align' directives, described later, which -have a consistent behavior across all architectures (but are specific to -GAS). - -7.3 '.ascii "STRING"'... -======================== - -'.ascii' expects zero or more string literals (*note Strings::) -separated by commas. It assembles each string (with no automatic -trailing zero byte) into consecutive addresses. - -7.4 '.asciz "STRING"'... -======================== - -'.asciz' is just like '.ascii', but each string is followed by a zero -byte. The "z" in '.asciz' stands for "zero". - -7.5 '.balign[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' -============================================== - -Pad the location counter (in the current subsection) to a particular -storage boundary. The first expression (which must be absolute) is the -alignment request in bytes. For example '.balign 8' advances the -location counter until it is a multiple of 8. If the location counter -is already a multiple of 8, no change is needed. - - The second expression (also absolute) gives the fill value to be -stored in the padding bytes. It (and the comma) may be omitted. If it -is omitted, the padding bytes are normally zero. However, on some -systems, if the section is marked as containing code and the fill value -is omitted, the space is filled with no-op instructions. - - The third expression is also absolute, and is also optional. If it -is present, it is the maximum number of bytes that should be skipped by -this alignment directive. If doing the alignment would require skipping -more bytes than the specified maximum, then the alignment is not done at -all. You can omit the fill value (the second argument) entirely by -simply using two commas after the required alignment; this can be useful -if you want the alignment to be filled with no-op instructions when -appropriate. - - The '.balignw' and '.balignl' directives are variants of the -'.balign' directive. The '.balignw' directive treats the fill pattern -as a two byte word value. The '.balignl' directives treats the fill -pattern as a four byte longword value. For example, '.balignw 4,0x368d' -will align to a multiple of 4. If it skips two bytes, they will be -filled in with the value 0x368d (the exact placement of the bytes -depends upon the endianness of the processor). If it skips 1 or 3 -bytes, the fill value is undefined. - -7.6 '.byte EXPRESSIONS' -======================= - -'.byte' expects zero or more expressions, separated by commas. Each -expression is assembled into the next byte. - -7.7 '.comm SYMBOL , LENGTH ' -============================ - -'.comm' declares a common symbol named SYMBOL. When linking, a common -symbol in one object file may be merged with a defined or common symbol -of the same name in another object file. If 'ld' does not see a -definition for the symbol-just one or more common symbols-then it will -allocate LENGTH bytes of uninitialized memory. LENGTH must be an -absolute expression. If 'ld' sees multiple common symbols with the same -name, and they do not all have the same size, it will allocate space -using the largest size. - - When using ELF, the '.comm' directive takes an optional third -argument. This is the desired alignment of the symbol, specified as a -byte boundary (for example, an alignment of 16 means that the least -significant 4 bits of the address should be zero). The alignment must -be an absolute expression, and it must be a power of two. If 'ld' -allocates uninitialized memory for the common symbol, it will use the -alignment when placing the symbol. If no alignment is specified, 'as' -will set the alignment to the largest power of two less than or equal to -the size of the symbol, up to a maximum of 16. - -7.8 '.cfi_startproc [simple]' -============================= - -'.cfi_startproc' is used at the beginning of each function that should -have an entry in '.eh_frame'. It initializes some internal data -structures. Don't forget to close the function by '.cfi_endproc'. - - Unless '.cfi_startproc' is used along with parameter 'simple' it also -emits some architecture dependent initial CFI instructions. - -7.9 '.cfi_endproc' -================== - -'.cfi_endproc' is used at the end of a function where it closes its -unwind entry previously opened by '.cfi_startproc', and emits it to -'.eh_frame'. - -7.10 '.cfi_personality ENCODING [, EXP]' -======================================== - -'.cfi_personality' defines personality routine and its encoding. -ENCODING must be a constant determining how the personality should be -encoded. If it is 255 ('DW_EH_PE_omit'), second argument is not -present, otherwise second argument should be a constant or a symbol -name. When using indirect encodings, the symbol provided should be the -location where personality can be loaded from, not the personality -routine itself. The default after '.cfi_startproc' is '.cfi_personality -0xff', no personality routine. - -7.11 '.cfi_lsda ENCODING [, EXP]' -================================= - -'.cfi_lsda' defines LSDA and its encoding. ENCODING must be a constant -determining how the LSDA should be encoded. If it is 255 -('DW_EH_PE_omit'), second argument is not present, otherwise second -argument should be a constant or a symbol name. The default after -'.cfi_startproc' is '.cfi_lsda 0xff', no LSDA. - -7.12 '.cfi_def_cfa REGISTER, OFFSET' -==================================== - -'.cfi_def_cfa' defines a rule for computing CFA as: take address from -REGISTER and add OFFSET to it. - -7.13 '.cfi_def_cfa_register REGISTER' -===================================== - -'.cfi_def_cfa_register' modifies a rule for computing CFA. From now on -REGISTER will be used instead of the old one. Offset remains the same. - -7.14 '.cfi_def_cfa_offset OFFSET' -================================= - -'.cfi_def_cfa_offset' modifies a rule for computing CFA. Register -remains the same, but OFFSET is new. Note that it is the absolute -offset that will be added to a defined register to compute CFA address. - -7.15 '.cfi_adjust_cfa_offset OFFSET' -==================================== - -Same as '.cfi_def_cfa_offset' but OFFSET is a relative value that is -added/substracted from the previous offset. - -7.16 '.cfi_offset REGISTER, OFFSET' -=================================== - -Previous value of REGISTER is saved at offset OFFSET from CFA. - -7.17 '.cfi_rel_offset REGISTER, OFFSET' -======================================= - -Previous value of REGISTER is saved at offset OFFSET from the current -CFA register. This is transformed to '.cfi_offset' using the known -displacement of the CFA register from the CFA. This is often easier to -use, because the number will match the code it's annotating. - -7.18 '.cfi_register REGISTER1, REGISTER2' -========================================= - -Previous value of REGISTER1 is saved in register REGISTER2. - -7.19 '.cfi_restore REGISTER' -============================ - -'.cfi_restore' says that the rule for REGISTER is now the same as it was -at the beginning of the function, after all initial instruction added by -'.cfi_startproc' were executed. - -7.20 '.cfi_undefined REGISTER' -============================== - -From now on the previous value of REGISTER can't be restored anymore. - -7.21 '.cfi_same_value REGISTER' -=============================== - -Current value of REGISTER is the same like in the previous frame, i.e. -no restoration needed. - -7.22 '.cfi_remember_state', -=========================== - -First save all current rules for all registers by '.cfi_remember_state', -then totally screw them up by subsequent '.cfi_*' directives and when -everything is hopelessly bad, use '.cfi_restore_state' to restore the -previous saved state. - -7.23 '.cfi_return_column REGISTER' -================================== - -Change return column REGISTER, i.e. the return address is either -directly in REGISTER or can be accessed by rules for REGISTER. - -7.24 '.cfi_signal_frame' -======================== - -Mark current function as signal trampoline. - -7.25 '.cfi_window_save' -======================= - -SPARC register window has been saved. - -7.26 '.cfi_escape' EXPRESSION[, ...] -==================================== - -Allows the user to add arbitrary bytes to the unwind info. One might -use this to add OS-specific CFI opcodes, or generic CFI opcodes that GAS -does not yet support. - -7.27 '.file FILENO FILENAME' -============================ - -When emitting dwarf2 line number information '.file' assigns filenames -to the '.debug_line' file name table. The FILENO operand should be a -unique positive integer to use as the index of the entry in the table. -The FILENAME operand is a C string literal. - - The detail of filename indices is exposed to the user because the -filename table is shared with the '.debug_info' section of the dwarf2 -debugging information, and thus the user must know the exact indices -that table entries will have. - -7.28 '.loc FILENO LINENO [COLUMN] [OPTIONS]' -============================================ - -The '.loc' directive will add row to the '.debug_line' line number -matrix corresponding to the immediately following assembly instruction. -The FILENO, LINENO, and optional COLUMN arguments will be applied to the -'.debug_line' state machine before the row is added. - - The OPTIONS are a sequence of the following tokens in any order: - -'basic_block' - This option will set the 'basic_block' register in the - '.debug_line' state machine to 'true'. - -'prologue_end' - This option will set the 'prologue_end' register in the - '.debug_line' state machine to 'true'. - -'epilogue_begin' - This option will set the 'epilogue_begin' register in the - '.debug_line' state machine to 'true'. - -'is_stmt VALUE' - This option will set the 'is_stmt' register in the '.debug_line' - state machine to 'value', which must be either 0 or 1. - -'isa VALUE' - This directive will set the 'isa' register in the '.debug_line' - state machine to VALUE, which must be an unsigned integer. - -7.29 '.loc_mark_blocks ENABLE' -============================== - -The '.loc_mark_blocks' directive makes the assembler emit an entry to -the '.debug_line' line number matrix with the 'basic_block' register in -the state machine set whenever a code label is seen. The ENABLE -argument should be either 1 or 0, to enable or disable this function -respectively. - -7.30 '.data SUBSECTION' -======================= - -'.data' tells 'as' to assemble the following statements onto the end of -the data subsection numbered SUBSECTION (which is an absolute -expression). If SUBSECTION is omitted, it defaults to zero. - -7.31 '.double FLONUMS' -====================== - -'.double' expects zero or more flonums, separated by commas. It -assembles floating point numbers. - -7.32 '.eject' -============= - -Force a page break at this point, when generating assembly listings. - -7.33 '.else' -============ - -'.else' is part of the 'as' support for conditional assembly; see *note -'.if': If. It marks the beginning of a section of code to be assembled -if the condition for the preceding '.if' was false. - -7.34 '.elseif' -============== - -'.elseif' is part of the 'as' support for conditional assembly; see -*note '.if': If. It is shorthand for beginning a new '.if' block that -would otherwise fill the entire '.else' section. - -7.35 '.end' -=========== - -'.end' marks the end of the assembly file. 'as' does not process -anything in the file past the '.end' directive. - -7.36 '.endfunc' -=============== - -'.endfunc' marks the end of a function specified with '.func'. - -7.37 '.endif' -============= - -'.endif' is part of the 'as' support for conditional assembly; it marks -the end of a block of code that is only assembled conditionally. *Note -'.if': If. - -7.38 '.equ SYMBOL, EXPRESSION' -============================== - -This directive sets the value of SYMBOL to EXPRESSION. It is synonymous -with '.set'; see *note '.set': Set. - -7.39 '.equiv SYMBOL, EXPRESSION' -================================ - -The '.equiv' directive is like '.equ' and '.set', except that the -assembler will signal an error if SYMBOL is already defined. Note a -symbol which has been referenced but not actually defined is considered -to be undefined. - - Except for the contents of the error message, this is roughly -equivalent to - .ifdef SYM - .err - .endif - .equ SYM,VAL - plus it protects the symbol from later redefinition. - -7.40 '.eqv SYMBOL, EXPRESSION' -============================== - -The '.eqv' directive is like '.equiv', but no attempt is made to -evaluate the expression or any part of it immediately. Instead each -time the resulting symbol is used in an expression, a snapshot of its -current value is taken. - -7.41 '.err' -=========== - -If 'as' assembles a '.err' directive, it will print an error message -and, unless the '-Z' option was used, it will not generate an object -file. This can be used to signal an error in conditionally compiled -code. - -7.42 '.error "STRING"' -====================== - -Similarly to '.err', this directive emits an error, but you can specify -a string that will be emitted as the error message. If you don't -specify the message, it defaults to '".error directive invoked in source -file"'. *Note Error and Warning Messages: Errors. - - .error "This code has not been assembled and tested." - -7.43 '.exitm' -============= - -Exit early from the current macro definition. *Note Macro::. - -7.44 '.extern' -============== - -'.extern' is accepted in the source program--for compatibility with -other assemblers--but it is ignored. 'as' treats all undefined symbols -as external. - -7.45 '.fail EXPRESSION' -======================= - -Generates an error or a warning. If the value of the EXPRESSION is 500 -or more, 'as' will print a warning message. If the value is less than -500, 'as' will print an error message. The message will include the -value of EXPRESSION. This can occasionally be useful inside complex -nested macros or conditional assembly. - -7.46 '.file STRING' -=================== - -'.file' tells 'as' that we are about to start a new logical file. -STRING is the new file name. In general, the filename is recognized -whether or not it is surrounded by quotes '"'; but if you wish to -specify an empty file name, you must give the quotes-'""'. This -statement may go away in future: it is only recognized to be compatible -with old 'as' programs. - -7.47 '.fill REPEAT , SIZE , VALUE' -================================== - -REPEAT, SIZE and VALUE are absolute expressions. This emits REPEAT -copies of SIZE bytes. REPEAT may be zero or more. SIZE may be zero or -more, but if it is more than 8, then it is deemed to have the value 8, -compatible with other people's assemblers. The contents of each REPEAT -bytes is taken from an 8-byte number. The highest order 4 bytes are -zero. The lowest order 4 bytes are VALUE rendered in the byte-order of -an integer on the computer 'as' is assembling for. Each SIZE bytes in a -repetition is taken from the lowest order SIZE bytes of this number. -Again, this bizarre behavior is compatible with other people's -assemblers. - - SIZE and VALUE are optional. If the second comma and VALUE are -absent, VALUE is assumed zero. If the first comma and following tokens -are absent, SIZE is assumed to be 1. - -7.48 '.float FLONUMS' -===================== - -This directive assembles zero or more flonums, separated by commas. It -has the same effect as '.single'. - -7.49 '.func NAME[,LABEL]' -========================= - -'.func' emits debugging information to denote function NAME, and is -ignored unless the file is assembled with debugging enabled. Only -'--gstabs[+]' is currently supported. LABEL is the entry point of the -function and if omitted NAME prepended with the 'leading char' is used. -'leading char' is usually '_' or nothing, depending on the target. All -functions are currently defined to have 'void' return type. The -function must be terminated with '.endfunc'. - -7.50 '.global SYMBOL', '.globl SYMBOL' -====================================== - -'.global' makes the symbol visible to 'ld'. If you define SYMBOL in -your partial program, its value is made available to other partial -programs that are linked with it. Otherwise, SYMBOL takes its -attributes from a symbol of the same name from another file linked into -the same program. - - Both spellings ('.globl' and '.global') are accepted, for -compatibility with other assemblers. - -7.51 '.hidden NAMES' -==================== - -This is one of the ELF visibility directives. The other two are -'.internal' (*note '.internal': Internal.) and '.protected' (*note -'.protected': Protected.). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to 'hidden' which means that the symbols are not visible to -other components. Such symbols are always considered to be 'protected' -as well. - -7.52 '.hword EXPRESSIONS' -========================= - -This expects zero or more EXPRESSIONS, and emits a 16 bit number for -each. - - This directive is a synonym for '.short'. - -7.53 '.ident' -============= - -This directive is used by some assemblers to place tags in object files. -The behavior of this directive varies depending on the target. When -using the a.out object file format, 'as' simply accepts the directive -for source-file compatibility with existing assemblers, but does not -emit anything for it. When using COFF, comments are emitted to the -'.comment' or '.rdata' section, depending on the target. When using -ELF, comments are emitted to the '.comment' section. - -7.54 '.if ABSOLUTE EXPRESSION' -============================== - -'.if' marks the beginning of a section of code which is only considered -part of the source program being assembled if the argument (which must -be an ABSOLUTE EXPRESSION) is non-zero. The end of the conditional -section of code must be marked by '.endif' (*note '.endif': Endif.); -optionally, you may include code for the alternative condition, flagged -by '.else' (*note '.else': Else.). If you have several conditions to -check, '.elseif' may be used to avoid nesting blocks if/else within each -subsequent '.else' block. - - The following variants of '.if' are also supported: -'.ifdef SYMBOL' - Assembles the following section of code if the specified SYMBOL has - been defined. Note a symbol which has been referenced but not yet - defined is considered to be undefined. - -'.ifb TEXT' - Assembles the following section of code if the operand is blank - (empty). - -'.ifc STRING1,STRING2' - Assembles the following section of code if the two strings are the - same. The strings may be optionally quoted with single quotes. If - they are not quoted, the first string stops at the first comma, and - the second string stops at the end of the line. Strings which - contain whitespace should be quoted. The string comparison is case - sensitive. - -'.ifeq ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is zero. - -'.ifeqs STRING1,STRING2' - Another form of '.ifc'. The strings must be quoted using double - quotes. - -'.ifge ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is greater - than or equal to zero. - -'.ifgt ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is greater - than zero. - -'.ifle ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is less - than or equal to zero. - -'.iflt ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is less - than zero. - -'.ifnb TEXT' - Like '.ifb', but the sense of the test is reversed: this assembles - the following section of code if the operand is non-blank - (non-empty). - -'.ifnc STRING1,STRING2.' - Like '.ifc', but the sense of the test is reversed: this assembles - the following section of code if the two strings are not the same. - -'.ifndef SYMBOL' -'.ifnotdef SYMBOL' - Assembles the following section of code if the specified SYMBOL has - not been defined. Both spelling variants are equivalent. Note a - symbol which has been referenced but not yet defined is considered - to be undefined. - -'.ifne ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is not - equal to zero (in other words, this is equivalent to '.if'). - -'.ifnes STRING1,STRING2' - Like '.ifeqs', but the sense of the test is reversed: this - assembles the following section of code if the two strings are not - the same. - -7.55 '.incbin "FILE"[,SKIP[,COUNT]]' -==================================== - -The 'incbin' directive includes FILE verbatim at the current location. -You can control the search paths used with the '-I' command-line option -(*note Command-Line Options: Invoking.). Quotation marks are required -around FILE. - - The SKIP argument skips a number of bytes from the start of the FILE. -The COUNT argument indicates the maximum number of bytes to read. Note -that the data is not aligned in any way, so it is the user's -responsibility to make sure that proper alignment is provided both -before and after the 'incbin' directive. - -7.56 '.include "FILE"' -====================== - -This directive provides a way to include supporting files at specified -points in your source program. The code from FILE is assembled as if it -followed the point of the '.include'; when the end of the included file -is reached, assembly of the original file continues. You can control -the search paths used with the '-I' command-line option (*note -Command-Line Options: Invoking.). Quotation marks are required around -FILE. - -7.57 '.int EXPRESSIONS' -======================= - -Expect zero or more EXPRESSIONS, of any section, separated by commas. -For each expression, emit a number that, at run time, is the value of -that expression. The byte order and bit size of the number depends on -what kind of target the assembly is for. - -7.58 '.internal NAMES' -====================== - -This is one of the ELF visibility directives. The other two are -'.hidden' (*note '.hidden': Hidden.) and '.protected' (*note -'.protected': Protected.). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to 'internal' which means that the symbols are considered to -be 'hidden' (i.e., not visible to other components), and that some -extra, processor specific processing must also be performed upon the -symbols as well. - -7.59 '.irp SYMBOL,VALUES'... -============================ - -Evaluate a sequence of statements assigning different values to SYMBOL. -The sequence of statements starts at the '.irp' directive, and is -terminated by an '.endr' directive. For each VALUE, SYMBOL is set to -VALUE, and the sequence of statements is assembled. If no VALUE is -listed, the sequence of statements is assembled once, with SYMBOL set to -the null string. To refer to SYMBOL within the sequence of statements, -use \SYMBOL. - - For example, assembling - - .irp param,1,2,3 - move d\param,sp@- - .endr - - is equivalent to assembling - - move d1,sp@- - move d2,sp@- - move d3,sp@- - - For some caveats with the spelling of SYMBOL, see also *note Macro::. - -7.60 '.irpc SYMBOL,VALUES'... -============================= - -Evaluate a sequence of statements assigning different values to SYMBOL. -The sequence of statements starts at the '.irpc' directive, and is -terminated by an '.endr' directive. For each character in VALUE, SYMBOL -is set to the character, and the sequence of statements is assembled. -If no VALUE is listed, the sequence of statements is assembled once, -with SYMBOL set to the null string. To refer to SYMBOL within the -sequence of statements, use \SYMBOL. - - For example, assembling - - .irpc param,123 - move d\param,sp@- - .endr - - is equivalent to assembling - - move d1,sp@- - move d2,sp@- - move d3,sp@- - - For some caveats with the spelling of SYMBOL, see also the discussion -at *Note Macro::. - -7.61 '.lcomm SYMBOL , LENGTH' -============================= - -Reserve LENGTH (an absolute expression) bytes for a local common denoted -by SYMBOL. The section and value of SYMBOL are those of the new local -common. The addresses are allocated in the bss section, so that at -run-time the bytes start off zeroed. SYMBOL is not declared global -(*note '.global': Global.), so is normally not visible to 'ld'. - -7.62 '.lflags' -============== - -'as' accepts this directive, for compatibility with other assemblers, -but ignores it. - -7.63 '.line LINE-NUMBER' -======================== - -Even though this is a directive associated with the 'a.out' or 'b.out' -object-code formats, 'as' still recognizes it when producing COFF -output, and treats '.line' as though it were the COFF '.ln' _if_ it is -found outside a '.def'/'.endef' pair. - - Inside a '.def', '.line' is, instead, one of the directives used by -compilers to generate auxiliary symbol information for debugging. - -7.64 '.linkonce [TYPE]' -======================= - -Mark the current section so that the linker only includes a single copy -of it. This may be used to include the same section in several -different object files, but ensure that the linker will only include it -once in the final output file. The '.linkonce' pseudo-op must be used -for each instance of the section. Duplicate sections are detected based -on the section name, so it should be unique. - - This directive is only supported by a few object file formats; as of -this writing, the only object file format which supports it is the -Portable Executable format used on Windows NT. - - The TYPE argument is optional. If specified, it must be one of the -following strings. For example: - .linkonce same_size - Not all types may be supported on all object file formats. - -'discard' - Silently discard duplicate sections. This is the default. - -'one_only' - Warn if there are duplicate sections, but still keep only one copy. - -'same_size' - Warn if any of the duplicates have different sizes. - -'same_contents' - Warn if any of the duplicates do not have exactly the same - contents. - -7.65 '.ln LINE-NUMBER' -====================== - -'.ln' is a synonym for '.line'. - -7.66 '.mri VAL' -=============== - -If VAL is non-zero, this tells 'as' to enter MRI mode. If VAL is zero, -this tells 'as' to exit MRI mode. This change affects code assembled -until the next '.mri' directive, or until the end of the file. *Note -MRI mode: M. - -7.67 '.list' -============ - -Control (in conjunction with the '.nolist' directive) whether or not -assembly listings are generated. These two directives maintain an -internal counter (which is zero initially). '.list' increments the -counter, and '.nolist' decrements it. Assembly listings are generated -whenever the counter is greater than zero. - - By default, listings are disabled. When you enable them (with the -'-a' command line option; *note Command-Line Options: Invoking.), the -initial value of the listing counter is one. - -7.68 '.long EXPRESSIONS' -======================== - -'.long' is the same as '.int'. *Note '.int': Int. - -7.69 '.macro' -============= - -The commands '.macro' and '.endm' allow you to define macros that -generate assembly output. For example, this definition specifies a -macro 'sum' that puts a sequence of numbers into memory: - - .macro sum from=0, to=5 - .long \from - .if \to-\from - sum "(\from+1)",\to - .endif - .endm - -With that definition, 'SUM 0,5' is equivalent to this assembly input: - - .long 0 - .long 1 - .long 2 - .long 3 - .long 4 - .long 5 - -'.macro MACNAME' -'.macro MACNAME MACARGS ...' - Begin the definition of a macro called MACNAME. If your macro - definition requires arguments, specify their names after the macro - name, separated by commas or spaces. You can qualify the macro - argument to indicate whether all invocations must specify a - non-blank value (through ':'req''), or whether it takes all of the - remaining arguments (through ':'vararg''). You can supply a - default value for any macro argument by following the name with - '=DEFLT'. You cannot define two macros with the same MACNAME - unless it has been subject to the '.purgem' directive (*note - Purgem::) between the two definitions. For example, these are all - valid '.macro' statements: - - '.macro comm' - Begin the definition of a macro called 'comm', which takes no - arguments. - - '.macro plus1 p, p1' - '.macro plus1 p p1' - Either statement begins the definition of a macro called - 'plus1', which takes two arguments; within the macro - definition, write '\p' or '\p1' to evaluate the arguments. - - '.macro reserve_str p1=0 p2' - Begin the definition of a macro called 'reserve_str', with two - arguments. The first argument has a default value, but not - the second. After the definition is complete, you can call - the macro either as 'reserve_str A,B' (with '\p1' evaluating - to A and '\p2' evaluating to B), or as 'reserve_str ,B' (with - '\p1' evaluating as the default, in this case '0', and '\p2' - evaluating to B). - - '.macro m p1:req, p2=0, p3:vararg' - Begin the definition of a macro called 'm', with at least - three arguments. The first argument must always have a value - specified, but not the second, which instead has a default - value. The third formal will get assigned all remaining - arguments specified at invocation time. - - When you call a macro, you can specify the argument values - either by position, or by keyword. For example, 'sum 9,17' is - equivalent to 'sum to=17, from=9'. - - Note that since each of the MACARGS can be an identifier exactly as - any other one permitted by the target architecture, there may be - occasional problems if the target hand-crafts special meanings to - certain characters when they occur in a special position. For - example, if the colon (':') is generally permitted to be part of a - symbol name, but the architecture specific code special-cases it - when occurring as the final character of a symbol (to denote a - label), then the macro parameter replacement code will have no way - of knowing that and consider the whole construct (including the - colon) an identifier, and check only this identifier for being the - subject to parameter substitution. So for example this macro - definition: - - .macro label l - \l: - .endm - - might not work as expected. Invoking 'label foo' might not create - a label called 'foo' but instead just insert the text '\l:' into - the assembler source, probably generating an error about an - unrecognised identifier. - - Similarly problems might occur with the period character ('.') - which is often allowed inside opcode names (and hence identifier - names). So for example constructing a macro to build an opcode - from a base name and a length specifier like this: - - .macro opcode base length - \base.\length - .endm - - and invoking it as 'opcode store l' will not create a 'store.l' - instruction but instead generate some kind of error as the - assembler tries to interpret the text '\base.\length'. - - There are several possible ways around this problem: - - 'Insert white space' - If it is possible to use white space characters then this is - the simplest solution. eg: - - .macro label l - \l : - .endm - - 'Use '\()'' - The string '\()' can be used to separate the end of a macro - argument from the following text. eg: - - .macro opcode base length - \base\().\length - .endm - - 'Use the alternate macro syntax mode' - In the alternative macro syntax mode the ampersand character - ('&') can be used as a separator. eg: - - .altmacro - .macro label l - l&: - .endm - - Note: this problem of correctly identifying string parameters to - pseudo ops also applies to the identifiers used in '.irp' (*note - Irp::) and '.irpc' (*note Irpc::) as well. - -'.endm' - Mark the end of a macro definition. - -'.exitm' - Exit early from the current macro definition. - -'\@' - 'as' maintains a counter of how many macros it has executed in this - pseudo-variable; you can copy that number to your output with '\@', - but _only within a macro definition_. - -'LOCAL NAME [ , ... ]' - _Warning: 'LOCAL' is only available if you select "alternate macro - syntax" with '--alternate' or '.altmacro'._ *Note '.altmacro': - Altmacro. - -7.70 '.altmacro' -================ - -Enable alternate macro mode, enabling: - -'LOCAL NAME [ , ... ]' - One additional directive, 'LOCAL', is available. It is used to - generate a string replacement for each of the NAME arguments, and - replace any instances of NAME in each macro expansion. The - replacement string is unique in the assembly, and different for - each separate macro expansion. 'LOCAL' allows you to write macros - that define symbols, without fear of conflict between separate - macro expansions. - -'String delimiters' - You can write strings delimited in these other ways besides - '"STRING"': - - ''STRING'' - You can delimit strings with single-quote characters. - - '' - You can delimit strings with matching angle brackets. - -'single-character string escape' - To include any single character literally in a string (even if the - character would otherwise have some special meaning), you can - prefix the character with '!' (an exclamation mark). For example, - you can write '<4.3 !> 5.4!!>' to get the literal text '4.3 > - 5.4!'. - -'Expression results as strings' - You can write '%EXPR' to evaluate the expression EXPR and use the - result as a string. - -7.71 '.noaltmacro' -================== - -Disable alternate macro mode. *Note Altmacro::. - -7.72 '.nolist' -============== - -Control (in conjunction with the '.list' directive) whether or not -assembly listings are generated. These two directives maintain an -internal counter (which is zero initially). '.list' increments the -counter, and '.nolist' decrements it. Assembly listings are generated -whenever the counter is greater than zero. - -7.73 '.octa BIGNUMS' -==================== - -This directive expects zero or more bignums, separated by commas. For -each bignum, it emits a 16-byte integer. - - The term "octa" comes from contexts in which a "word" is two bytes; -hence _octa_-word for 16 bytes. - -7.74 '.org NEW-LC , FILL' -========================= - -Advance the location counter of the current section to NEW-LC. NEW-LC -is either an absolute expression or an expression with the same section -as the current subsection. That is, you can't use '.org' to cross -sections: if NEW-LC has the wrong section, the '.org' directive is -ignored. To be compatible with former assemblers, if the section of -NEW-LC is absolute, 'as' issues a warning, then pretends the section of -NEW-LC is the same as the current subsection. - - '.org' may only increase the location counter, or leave it unchanged; -you cannot use '.org' to move the location counter backwards. - - Because 'as' tries to assemble programs in one pass, NEW-LC may not -be undefined. If you really detest this restriction we eagerly await a -chance to share your improved assembler. - - Beware that the origin is relative to the start of the section, not -to the start of the subsection. This is compatible with other people's -assemblers. - - When the location counter (of the current subsection) is advanced, -the intervening bytes are filled with FILL which should be an absolute -expression. If the comma and FILL are omitted, FILL defaults to zero. - -7.75 '.p2align[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' -================================================ - -Pad the location counter (in the current subsection) to a particular -storage boundary. The first expression (which must be absolute) is the -number of low-order zero bits the location counter must have after -advancement. For example '.p2align 3' advances the location counter -until it a multiple of 8. If the location counter is already a multiple -of 8, no change is needed. - - The second expression (also absolute) gives the fill value to be -stored in the padding bytes. It (and the comma) may be omitted. If it -is omitted, the padding bytes are normally zero. However, on some -systems, if the section is marked as containing code and the fill value -is omitted, the space is filled with no-op instructions. - - The third expression is also absolute, and is also optional. If it -is present, it is the maximum number of bytes that should be skipped by -this alignment directive. If doing the alignment would require skipping -more bytes than the specified maximum, then the alignment is not done at -all. You can omit the fill value (the second argument) entirely by -simply using two commas after the required alignment; this can be useful -if you want the alignment to be filled with no-op instructions when -appropriate. - - The '.p2alignw' and '.p2alignl' directives are variants of the -'.p2align' directive. The '.p2alignw' directive treats the fill pattern -as a two byte word value. The '.p2alignl' directives treats the fill -pattern as a four byte longword value. For example, '.p2alignw -2,0x368d' will align to a multiple of 4. If it skips two bytes, they -will be filled in with the value 0x368d (the exact placement of the -bytes depends upon the endianness of the processor). If it skips 1 or 3 -bytes, the fill value is undefined. - -7.76 '.previous' -================ - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.pushsection' (*note PushSection::), and '.popsection' -(*note PopSection::). - - This directive swaps the current section (and subsection) with most -recently referenced section (and subsection) prior to this one. -Multiple '.previous' directives in a row will flip between two sections -(and their subsections). - - In terms of the section stack, this directive swaps the current -section with the top section on the section stack. - -7.77 '.popsection' -================== - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.pushsection' (*note PushSection::), and '.previous' -(*note Previous::). - - This directive replaces the current section (and subsection) with the -top section (and subsection) on the section stack. This section is -popped off the stack. - -7.78 '.print STRING' -==================== - -'as' will print STRING on the standard output during assembly. You must -put STRING in double quotes. - -7.79 '.protected NAMES' -======================= - -This is one of the ELF visibility directives. The other two are -'.hidden' (*note Hidden::) and '.internal' (*note Internal::). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to 'protected' which means that any references to the symbols -from within the components that defines them must be resolved to the -definition in that component, even if a definition in another component -would normally preempt this. - -7.80 '.psize LINES , COLUMNS' -============================= - -Use this directive to declare the number of lines--and, optionally, the -number of columns--to use for each page, when generating listings. - - If you do not use '.psize', listings use a default line-count of 60. -You may omit the comma and COLUMNS specification; the default width is -200 columns. - - 'as' generates formfeeds whenever the specified number of lines is -exceeded (or whenever you explicitly request one, using '.eject'). - - If you specify LINES as '0', no formfeeds are generated save those -explicitly specified with '.eject'. - -7.81 '.purgem NAME' -=================== - -Undefine the macro NAME, so that later uses of the string will not be -expanded. *Note Macro::. - -7.82 '.pushsection NAME , SUBSECTION' -===================================== - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - This directive pushes the current section (and subsection) onto the -top of the section stack, and then replaces the current section and -subsection with 'name' and 'subsection'. - -7.83 '.quad BIGNUMS' -==================== - -'.quad' expects zero or more bignums, separated by commas. For each -bignum, it emits an 8-byte integer. If the bignum won't fit in 8 bytes, -it prints a warning message; and just takes the lowest order 8 bytes of -the bignum. - - The term "quad" comes from contexts in which a "word" is two bytes; -hence _quad_-word for 8 bytes. - -7.84 '.reloc OFFSET, RELOC_NAME[, EXPRESSION]' -============================================== - -Generate a relocation at OFFSET of type RELOC_NAME with value -EXPRESSION. If OFFSET is a number, the relocation is generated in the -current section. If OFFSET is an expression that resolves to a symbol -plus offset, the relocation is generated in the given symbol's section. -EXPRESSION, if present, must resolve to a symbol plus addend or to an -absolute value, but note that not all targets support an addend. e.g. -ELF REL targets such as i386 store an addend in the section contents -rather than in the relocation. This low level interface does not -support addends stored in the section. - -7.85 '.rept COUNT' -================== - -Repeat the sequence of lines between the '.rept' directive and the next -'.endr' directive COUNT times. - - For example, assembling - - .rept 3 - .long 0 - .endr - - is equivalent to assembling - - .long 0 - .long 0 - .long 0 - -7.86 '.sbttl "SUBHEADING"' -========================== - -Use SUBHEADING as the title (third line, immediately after the title -line) when generating assembly listings. - - This directive affects subsequent pages, as well as the current page -if it appears within ten lines of the top of a page. - -7.87 '.section NAME' -==================== - -Use the '.section' directive to assemble the following code into a -section named NAME. - - This directive is only supported for targets that actually support -arbitrarily named sections; on 'a.out' targets, for example, it is not -accepted, even with a standard 'a.out' section name. - - This is one of the ELF section stack manipulation directives. The -others are '.subsection' (*note SubSection::), '.pushsection' (*note -PushSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - For ELF targets, the '.section' directive is used like this: - - .section NAME [, "FLAGS"[, @TYPE[,FLAG_SPECIFIC_ARGUMENTS]]] - - The optional FLAGS argument is a quoted string which may contain any -combination of the following characters: -'a' - section is allocatable -'w' - section is writable -'x' - section is executable -'M' - section is mergeable -'S' - section contains zero terminated strings -'G' - section is a member of a section group -'T' - section is used for thread-local-storage - - The optional TYPE argument may contain one of the following -constants: -'@progbits' - section contains data -'@nobits' - section does not contain data (i.e., section only occupies space) -'@note' - section contains data which is used by things other than the - program -'@init_array' - section contains an array of pointers to init functions -'@fini_array' - section contains an array of pointers to finish functions -'@preinit_array' - section contains an array of pointers to pre-init functions - - Many targets only support the first three section types. - - Note on targets where the '@' character is the start of a comment (eg -ARM) then another character is used instead. For example the ARM port -uses the '%' character. - - If FLAGS contains the 'M' symbol then the TYPE argument must be -specified as well as an extra argument--ENTSIZE--like this: - - .section NAME , "FLAGS"M, @TYPE, ENTSIZE - - Sections with the 'M' flag but not 'S' flag must contain fixed size -constants, each ENTSIZE octets long. Sections with both 'M' and 'S' -must contain zero terminated strings where each character is ENTSIZE -bytes long. The linker may remove duplicates within sections with the -same name, same entity size and same flags. ENTSIZE must be an absolute -expression. - - If FLAGS contains the 'G' symbol then the TYPE argument must be -present along with an additional field like this: - - .section NAME , "FLAGS"G, @TYPE, GROUPNAME[, LINKAGE] - - The GROUPNAME field specifies the name of the section group to which -this particular section belongs. The optional linkage field can -contain: -'comdat' - indicates that only one copy of this section should be retained -'.gnu.linkonce' - an alias for comdat - - Note: if both the M and G flags are present then the fields for the -Merge flag should come first, like this: - - .section NAME , "FLAGS"MG, @TYPE, ENTSIZE, GROUPNAME[, LINKAGE] - - If no flags are specified, the default flags depend upon the section -name. If the section name is not recognized, the default will be for -the section to have none of the above flags: it will not be allocated in -memory, nor writable, nor executable. The section will contain data. - - For ELF targets, the assembler supports another type of '.section' -directive for compatibility with the Solaris assembler: - - .section "NAME"[, FLAGS...] - - Note that the section name is quoted. There may be a sequence of -comma separated flags: -'#alloc' - section is allocatable -'#write' - section is writable -'#execinstr' - section is executable -'#tls' - section is used for thread local storage - - This directive replaces the current section and subsection. See the -contents of the gas testsuite directory 'gas/testsuite/gas/elf' for some -examples of how this directive and the other section stack directives -work. - -7.88 '.set SYMBOL, EXPRESSION' -============================== - -Set the value of SYMBOL to EXPRESSION. This changes SYMBOL's value and -type to conform to EXPRESSION. If SYMBOL was flagged as external, it -remains flagged (*note Symbol Attributes::). - - You may '.set' a symbol many times in the same assembly. - - If you '.set' a global symbol, the value stored in the object file is -the last value stored into it. - -7.89 '.short EXPRESSIONS' -========================= - -This expects zero or more EXPRESSIONS, and emits a 16 bit number for -each. - -7.90 '.single FLONUMS' -====================== - -This directive assembles zero or more flonums, separated by commas. It -has the same effect as '.float'. - -7.91 '.size' -============ - -This directive is used to set the size associated with a symbol. - - For ELF targets, the '.size' directive is used like this: - - .size NAME , EXPRESSION - - This directive sets the size associated with a symbol NAME. The size -in bytes is computed from EXPRESSION which can make use of label -arithmetic. This directive is typically used to set the size of -function symbols. - -7.92 '.sleb128 EXPRESSIONS' -=========================== - -SLEB128 stands for "signed little endian base 128." This is a compact, -variable length representation of numbers used by the DWARF symbolic -debugging format. *Note '.uleb128': Uleb128. - -7.93 '.skip SIZE , FILL' -======================== - -This directive emits SIZE bytes, each of value FILL. Both SIZE and FILL -are absolute expressions. If the comma and FILL are omitted, FILL is -assumed to be zero. This is the same as '.space'. - -7.94 '.space SIZE , FILL' -========================= - -This directive emits SIZE bytes, each of value FILL. Both SIZE and FILL -are absolute expressions. If the comma and FILL are omitted, FILL is -assumed to be zero. This is the same as '.skip'. - -7.95 '.stabd, .stabn, .stabs' -============================= - -There are three directives that begin '.stab'. All emit symbols (*note -Symbols::), for use by symbolic debuggers. The symbols are not entered -in the 'as' hash table: they cannot be referenced elsewhere in the -source file. Up to five fields are required: - -STRING - This is the symbol's name. It may contain any character except - '\000', so is more general than ordinary symbol names. Some - debuggers used to code arbitrarily complex structures into symbol - names using this field. - -TYPE - An absolute expression. The symbol's type is set to the low 8 bits - of this expression. Any bit pattern is permitted, but 'ld' and - debuggers choke on silly bit patterns. - -OTHER - An absolute expression. The symbol's "other" attribute is set to - the low 8 bits of this expression. - -DESC - An absolute expression. The symbol's descriptor is set to the low - 16 bits of this expression. - -VALUE - An absolute expression which becomes the symbol's value. - - If a warning is detected while reading a '.stabd', '.stabn', or -'.stabs' statement, the symbol has probably already been created; you -get a half-formed symbol in your object file. This is compatible with -earlier assemblers! - -'.stabd TYPE , OTHER , DESC' - - The "name" of the symbol generated is not even an empty string. It - is a null pointer, for compatibility. Older assemblers used a null - pointer so they didn't waste space in object files with empty - strings. - - The symbol's value is set to the location counter, relocatably. - When your program is linked, the value of this symbol is the - address of the location counter when the '.stabd' was assembled. - -'.stabn TYPE , OTHER , DESC , VALUE' - The name of the symbol is set to the empty string '""'. - -'.stabs STRING , TYPE , OTHER , DESC , VALUE' - All five fields are specified. - -7.96 '.string' "STR" -==================== - -Copy the characters in STR to the object file. You may specify more -than one string to copy, separated by commas. Unless otherwise -specified for a particular machine, the assembler marks the end of each -string with a 0 byte. You can use any of the escape sequences described -in *note Strings: Strings. - -7.97 '.struct EXPRESSION' -========================= - -Switch to the absolute section, and set the section offset to -EXPRESSION, which must be an absolute expression. You might use this as -follows: - .struct 0 - field1: - .struct field1 + 4 - field2: - .struct field2 + 4 - field3: - This would define the symbol 'field1' to have the value 0, the symbol -'field2' to have the value 4, and the symbol 'field3' to have the value -8. Assembly would be left in the absolute section, and you would need -to use a '.section' directive of some sort to change to some other -section before further assembly. - -7.98 '.subsection NAME' -======================= - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.pushsection' (*note -PushSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - This directive replaces the current subsection with 'name'. The -current section is not changed. The replaced subsection is put onto the -section stack in place of the then current top of stack subsection. - -7.99 '.symver' -============== - -Use the '.symver' directive to bind symbols to specific version nodes -within a source file. This is only supported on ELF platforms, and is -typically used when assembling files to be linked into a shared library. -There are cases where it may make sense to use this in objects to be -bound into an application itself so as to override a versioned symbol -from a shared library. - - For ELF targets, the '.symver' directive can be used like this: - .symver NAME, NAME2@NODENAME - If the symbol NAME is defined within the file being assembled, the -'.symver' directive effectively creates a symbol alias with the name -NAME2@NODENAME, and in fact the main reason that we just don't try and -create a regular alias is that the @ character isn't permitted in symbol -names. The NAME2 part of the name is the actual name of the symbol by -which it will be externally referenced. The name NAME itself is merely -a name of convenience that is used so that it is possible to have -definitions for multiple versions of a function within a single source -file, and so that the compiler can unambiguously know which version of a -function is being mentioned. The NODENAME portion of the alias should -be the name of a node specified in the version script supplied to the -linker when building a shared library. If you are attempting to -override a versioned symbol from a shared library, then NODENAME should -correspond to the nodename of the symbol you are trying to override. - - If the symbol NAME is not defined within the file being assembled, -all references to NAME will be changed to NAME2@NODENAME. If no -reference to NAME is made, NAME2@NODENAME will be removed from the -symbol table. - - Another usage of the '.symver' directive is: - .symver NAME, NAME2@@NODENAME - In this case, the symbol NAME must exist and be defined within the -file being assembled. It is similar to NAME2@NODENAME. The difference -is NAME2@@NODENAME will also be used to resolve references to NAME2 by -the linker. - - The third usage of the '.symver' directive is: - .symver NAME, NAME2@@@NODENAME - When NAME is not defined within the file being assembled, it is -treated as NAME2@NODENAME. When NAME is defined within the file being -assembled, the symbol name, NAME, will be changed to NAME2@@NODENAME. - -7.100 '.text SUBSECTION' -======================== - -Tells 'as' to assemble the following statements onto the end of the text -subsection numbered SUBSECTION, which is an absolute expression. If -SUBSECTION is omitted, subsection number zero is used. - -7.101 '.title "HEADING"' -======================== - -Use HEADING as the title (second line, immediately after the source file -name and pagenumber) when generating assembly listings. - - This directive affects subsequent pages, as well as the current page -if it appears within ten lines of the top of a page. - -7.102 '.type' -============= - -This directive is used to set the type of a symbol. - - For ELF targets, the '.type' directive is used like this: - - .type NAME , TYPE DESCRIPTION - - This sets the type of symbol NAME to be either a function symbol or -an object symbol. There are five different syntaxes supported for the -TYPE DESCRIPTION field, in order to provide compatibility with various -other assemblers. - - Because some of the characters used in these syntaxes (such as '@' -and '#') are comment characters for some architectures, some of the -syntaxes below do not work on all architectures. The first variant will -be accepted by the GNU assembler on all architectures so that variant -should be used for maximum portability, if you do not need to assemble -your code with other assemblers. - - The syntaxes supported are: - - .type STT_FUNCTION - .type STT_OBJECT - - .type ,#function - .type ,#object - - .type ,@function - .type ,@object - - .type ,%function - .type ,%object - - .type ,"function" - .type ,"object" - -7.103 '.uleb128 EXPRESSIONS' -============================ - -ULEB128 stands for "unsigned little endian base 128." This is a -compact, variable length representation of numbers used by the DWARF -symbolic debugging format. *Note '.sleb128': Sleb128. - -7.104 '.version "STRING"' -========================= - -This directive creates a '.note' section and places into it an ELF -formatted note of type NT_VERSION. The note's name is set to 'string'. - -7.105 '.vtable_entry TABLE, OFFSET' -=================================== - -This directive finds or creates a symbol 'table' and creates a -'VTABLE_ENTRY' relocation for it with an addend of 'offset'. - -7.106 '.vtable_inherit CHILD, PARENT' -===================================== - -This directive finds the symbol 'child' and finds or creates the symbol -'parent' and then creates a 'VTABLE_INHERIT' relocation for the parent -whose addend is the value of the child symbol. As a special case the -parent name of '0' is treated as referring to the '*ABS*' section. - -7.107 '.warning "STRING"' -========================= - -Similar to the directive '.error' (*note '.error "STRING"': Error.), but -just emits a warning. - -7.108 '.weak NAMES' -=================== - -This directive sets the weak attribute on the comma separated list of -symbol 'names'. If the symbols do not already exist, they will be -created. - - On COFF targets other than PE, weak symbols are a GNU extension. -This directive sets the weak attribute on the comma separated list of -symbol 'names'. If the symbols do not already exist, they will be -created. - - On the PE target, weak symbols are supported natively as weak -aliases. When a weak symbol is created that is not an alias, GAS -creates an alternate symbol to hold the default value. - -7.109 '.weakref ALIAS, TARGET' -============================== - -This directive creates an alias to the target symbol that enables the -symbol to be referenced with weak-symbol semantics, but without actually -making it weak. If direct references or definitions of the symbol are -present, then the symbol will not be weak, but if all references to it -are through weak references, the symbol will be marked as weak in the -symbol table. - - The effect is equivalent to moving all references to the alias to a -separate assembly source file, renaming the alias to the symbol in it, -declaring the symbol as weak there, and running a reloadable link to -merge the object files resulting from the assembly of the new source -file and the old source file that had the references to the alias -removed. - - The alias itself never makes to the symbol table, and is entirely -handled within the assembler. - -7.110 '.word EXPRESSIONS' -========================= - -This directive expects zero or more EXPRESSIONS, of any section, -separated by commas. For each expression, 'as' emits a 32-bit number. - -7.111 Deprecated Directives -=========================== - -One day these directives won't work. They are included for -compatibility with older assemblers. -.abort -.line - -8 ARM Dependent Features -************************ - -8.1 Options -=========== - -'-mcpu=PROCESSOR[+EXTENSION...]' - This option specifies the target processor. The assembler will - issue an error message if an attempt is made to assemble an - instruction which will not execute on the target processor. The - following processor names are recognized: 'arm1', 'arm2', 'arm250', - 'arm3', 'arm6', 'arm60', 'arm600', 'arm610', 'arm620', 'arm7', - 'arm7m', 'arm7d', 'arm7dm', 'arm7di', 'arm7dmi', 'arm70', 'arm700', - 'arm700i', 'arm710', 'arm710t', 'arm720', 'arm720t', 'arm740t', - 'arm710c', 'arm7100', 'arm7500', 'arm7500fe', 'arm7t', 'arm7tdmi', - 'arm7tdmi-s', 'arm8', 'arm810', 'strongarm', 'strongarm1', - 'strongarm110', 'strongarm1100', 'strongarm1110', 'arm9', 'arm920', - 'arm920t', 'arm922t', 'arm940t', 'arm9tdmi', 'arm9e', 'arm926e', - 'arm926ej-s', 'arm946e-r0', 'arm946e', 'arm946e-s', 'arm966e-r0', - 'arm966e', 'arm966e-s', 'arm968e-s', 'arm10t', 'arm10tdmi', - 'arm10e', 'arm1020', 'arm1020t', 'arm1020e', 'arm1022e', - 'arm1026ej-s', 'arm1136j-s', 'arm1136jf-s', 'arm1156t2-s', - 'arm1156t2f-s', 'arm1176jz-s', 'arm1176jzf-s', 'mpcore', - 'mpcorenovfp', 'cortex-a8', 'cortex-r4', 'cortex-m3', 'ep9312' - (ARM920 with Cirrus Maverick coprocessor), 'i80200' (Intel XScale - processor) 'iwmmxt' (Intel(r) XScale processor with Wireless - MMX(tm) technology coprocessor) and 'xscale'. The special name - 'all' may be used to allow the assembler to accept instructions - valid for any ARM processor. - - In addition to the basic instruction set, the assembler can be told - to accept various extension mnemonics that extend the processor - using the co-processor instruction space. For example, - '-mcpu=arm920+maverick' is equivalent to specifying '-mcpu=ep9312'. - The following extensions are currently supported: '+maverick' - '+iwmmxt' and '+xscale'. - -'-march=ARCHITECTURE[+EXTENSION...]' - This option specifies the target architecture. The assembler will - issue an error message if an attempt is made to assemble an - instruction which will not execute on the target architecture. The - following architecture names are recognized: 'armv1', 'armv2', - 'armv2a', 'armv2s', 'armv3', 'armv3m', 'armv4', 'armv4xm', - 'armv4t', 'armv4txm', 'armv5', 'armv5t', 'armv5txm', 'armv5te', - 'armv5texp', 'armv6', 'armv6j', 'armv6k', 'armv6z', 'armv6zk', - 'armv7', 'armv7-a', 'armv7-r', 'armv7-m', 'iwmmxt' and 'xscale'. - If both '-mcpu' and '-march' are specified, the assembler will use - the setting for '-mcpu'. - - The architecture option can be extended with the same instruction - set extension options as the '-mcpu' option. - -'-mfpu=FLOATING-POINT-FORMAT' - - This option specifies the floating point format to assemble for. - The assembler will issue an error message if an attempt is made to - assemble an instruction which will not execute on the target - floating point unit. The following format options are recognized: - 'softfpa', 'fpe', 'fpe2', 'fpe3', 'fpa', 'fpa10', 'fpa11', - 'arm7500fe', 'softvfp', 'softvfp+vfp', 'vfp', 'vfp10', 'vfp10-r0', - 'vfp9', 'vfpxd', 'arm1020t', 'arm1020e', 'arm1136jf-s' and - 'maverick'. - - In addition to determining which instructions are assembled, this - option also affects the way in which the '.double' assembler - directive behaves when assembling little-endian code. - - The default is dependent on the processor selected. For - Architecture 5 or later, the default is to assembler for VFP - instructions; for earlier architectures the default is to assemble - for FPA instructions. - -'-mthumb' - This option specifies that the assembler should start assembling - Thumb instructions; that is, it should behave as though the file - starts with a '.code 16' directive. - -'-mthumb-interwork' - This option specifies that the output generated by the assembler - should be marked as supporting interworking. - -'-mapcs [26|32]' - This option specifies that the output generated by the assembler - should be marked as supporting the indicated version of the Arm - Procedure. Calling Standard. - -'-matpcs' - This option specifies that the output generated by the assembler - should be marked as supporting the Arm/Thumb Procedure Calling - Standard. If enabled this option will cause the assembler to - create an empty debugging section in the object file called - .arm.atpcs. Debuggers can use this to determine the ABI being used - by. - -'-mapcs-float' - This indicates the floating point variant of the APCS should be - used. In this variant floating point arguments are passed in FP - registers rather than integer registers. - -'-mapcs-reentrant' - This indicates that the reentrant variant of the APCS should be - used. This variant supports position independent code. - -'-mfloat-abi=ABI' - This option specifies that the output generated by the assembler - should be marked as using specified floating point ABI. The - following values are recognized: 'soft', 'softfp' and 'hard'. - -'-meabi=VER' - This option specifies which EABI version the produced object files - should conform to. The following values are recognized: 'gnu', '4' - and '5'. - -'-EB' - This option specifies that the output generated by the assembler - should be marked as being encoded for a big-endian processor. - -'-EL' - This option specifies that the output generated by the assembler - should be marked as being encoded for a little-endian processor. - -'-k' - This option specifies that the output of the assembler should be - marked as position-independent code (PIC). - -8.2 Syntax -========== - -8.2.1 Special Characters ------------------------- - -The presence of a '@' on a line indicates the start of a comment that -extends to the end of the current line. If a '#' appears as the first -character of a line, the whole line is treated as a comment. - - The ';' character can be used instead of a newline to separate -statements. - - Either '#' or '$' can be used to indicate immediate operands. - - *TODO* Explain about /data modifier on symbols. - -8.2.2 Register Names --------------------- - -*TODO* Explain about ARM register naming, and the predefined names. - -8.2.3 ARM relocation generation -------------------------------- - -Specific data relocations can be generated by putting the relocation -name in parentheses after the symbol name. For example: - - .word foo(TARGET1) - - This will generate an 'R_ARM_TARGET1' relocation against the symbol -FOO. The following relocations are supported: 'GOT', 'GOTOFF', -'TARGET1', 'TARGET2', 'SBREL', 'TLSGD', 'TLSLDM', 'TLSLDO', 'GOTTPOFF' -and 'TPOFF'. - - For compatibility with older toolchains the assembler also accepts -'(PLT)' after branch targets. This will generate the deprecated -'R_ARM_PLT32' relocation. - - Relocations for 'MOVW' and 'MOVT' instructions can be generated by -prefixing the value with '#:lower16:' and '#:upper16' respectively. For -example to load the 32-bit address of foo into r0: - - MOVW r0, #:lower16:foo - MOVT r0, #:upper16:foo - -8.3 Floating Point -================== - -The ARM family uses IEEE floating-point numbers. - -8.4 ARM Machine Directives -========================== - -'.align EXPRESSION [, EXPRESSION]' - This is the generic .ALIGN directive. For the ARM however if the - first argument is zero (ie no alignment is needed) the assembler - will behave as if the argument had been 2 (ie pad to the next four - byte boundary). This is for compatibility with ARM's own - assembler. - -'NAME .req REGISTER NAME' - This creates an alias for REGISTER NAME called NAME. For example: - - foo .req r0 - -'.unreq ALIAS-NAME' - This undefines a register alias which was previously defined using - the 'req', 'dn' or 'qn' directives. For example: - - foo .req r0 - .unreq foo - - An error occurs if the name is undefined. Note - this pseudo op - can be used to delete builtin in register name aliases (eg 'r0'). - This should only be done if it is really necessary. - -'NAME .dn REGISTER NAME [.TYPE] [[INDEX]]' -'NAME .qn REGISTER NAME [.TYPE] [[INDEX]]' - - The 'dn' and 'qn' directives are used to create typed and/or - indexed register aliases for use in Advanced SIMD Extension (Neon) - instructions. The former should be used to create aliases of - double-precision registers, and the latter to create aliases of - quad-precision registers. - - If these directives are used to create typed aliases, those aliases - can be used in Neon instructions instead of writing types after the - mnemonic or after each operand. For example: - - x .dn d2.f32 - y .dn d3.f32 - z .dn d4.f32[1] - vmul x,y,z - - This is equivalent to writing the following: - - vmul.f32 d2,d3,d4[1] - - Aliases created using 'dn' or 'qn' can be destroyed using 'unreq'. - -'.code [16|32]' - This directive selects the instruction set being generated. The - value 16 selects Thumb, with the value 32 selecting ARM. - -'.thumb' - This performs the same action as .CODE 16. - -'.arm' - This performs the same action as .CODE 32. - -'.force_thumb' - This directive forces the selection of Thumb instructions, even if - the target processor does not support those instructions - -'.thumb_func' - This directive specifies that the following symbol is the name of a - Thumb encoded function. This information is necessary in order to - allow the assembler and linker to generate correct code for - interworking between Arm and Thumb instructions and should be used - even if interworking is not going to be performed. The presence of - this directive also implies '.thumb' - - This directive is not neccessary when generating EABI objects. On - these targets the encoding is implicit when generating Thumb code. - -'.thumb_set' - This performs the equivalent of a '.set' directive in that it - creates a symbol which is an alias for another symbol (possibly not - yet defined). This directive also has the added property in that - it marks the aliased symbol as being a thumb function entry point, - in the same way that the '.thumb_func' directive does. - -'.ltorg' - This directive causes the current contents of the literal pool to - be dumped into the current section (which is assumed to be the - .text section) at the current location (aligned to a word - boundary). 'GAS' maintains a separate literal pool for each - section and each sub-section. The '.ltorg' directive will only - affect the literal pool of the current section and sub-section. At - the end of assembly all remaining, un-empty literal pools will - automatically be dumped. - - Note - older versions of 'GAS' would dump the current literal pool - any time a section change occurred. This is no longer done, since - it prevents accurate control of the placement of literal pools. - -'.pool' - This is a synonym for .ltorg. - -'.unwind_fnstart' - Marks the start of a function with an unwind table entry. - -'.unwind_fnend' - Marks the end of a function with an unwind table entry. The unwind - index table entry is created when this directive is processed. - - If no personality routine has been specified then standard - personality routine 0 or 1 will be used, depending on the number of - unwind opcodes required. - -'.cantunwind' - Prevents unwinding through the current function. No personality - routine or exception table data is required or permitted. - -'.personality NAME' - Sets the personality routine for the current function to NAME. - -'.personalityindex INDEX' - Sets the personality routine for the current function to the EABI - standard routine number INDEX - -'.handlerdata' - Marks the end of the current function, and the start of the - exception table entry for that function. Anything between this - directive and the '.fnend' directive will be added to the exception - table entry. - - Must be preceded by a '.personality' or '.personalityindex' - directive. - -'.save REGLIST' - Generate unwinder annotations to restore the registers in REGLIST. - The format of REGLIST is the same as the corresponding - store-multiple instruction. - - _core registers_ - .save {r4, r5, r6, lr} - stmfd sp!, {r4, r5, r6, lr} - _FPA registers_ - .save f4, 2 - sfmfd f4, 2, [sp]! - _VFP registers_ - .save {d8, d9, d10} - fstmdx sp!, {d8, d9, d10} - _iWMMXt registers_ - .save {wr10, wr11} - wstrd wr11, [sp, #-8]! - wstrd wr10, [sp, #-8]! - or - .save wr11 - wstrd wr11, [sp, #-8]! - .save wr10 - wstrd wr10, [sp, #-8]! - -'.vsave VFP-REGLIST' - Generate unwinder annotations to restore the VFP registers in - VFP-REGLIST using FLDMD. Also works for VFPv3 registers that are to - be restored using VLDM. The format of VFP-REGLIST is the same as - the corresponding store-multiple instruction. - - _VFP registers_ - .vsave {d8, d9, d10} - fstmdd sp!, {d8, d9, d10} - _VFPv3 registers_ - .vsave {d15, d16, d17} - vstm sp!, {d15, d16, d17} - - Since FLDMX and FSTMX are now deprecated, this directive should be - used in favour of '.save' for saving VFP registers for ARMv6 and - above. - -'.pad #COUNT' - Generate unwinder annotations for a stack adjustment of COUNT - bytes. A positive value indicates the function prologue allocated - stack space by decrementing the stack pointer. - -'.movsp REG [, #OFFSET]' - Tell the unwinder that REG contains an offset from the current - stack pointer. If OFFSET is not specified then it is assumed to be - zero. - -'.setfp FPREG, SPREG [, #OFFSET]' - Make all unwinder annotations relaive to a frame pointer. Without - this the unwinder will use offsets from the stack pointer. - - The syntax of this directive is the same as the 'sub' or 'mov' - instruction used to set the frame pointer. SPREG must be either - 'sp' or mentioned in a previous '.movsp' directive. - - .movsp ip - mov ip, sp - ... - .setfp fp, ip, #4 - sub fp, ip, #4 - -'.raw OFFSET, BYTE1, ...' - Insert one of more arbitary unwind opcode bytes, which are known to - adjust the stack pointer by OFFSET bytes. - - For example '.unwind_raw 4, 0xb1, 0x01' is equivalent to '.save - {r0}' - -'.cpu NAME' - Select the target processor. Valid values for NAME are the same as - for the '-mcpu' commandline option. - -'.arch NAME' - Select the target architecture. Valid values for NAME are the same - as for the '-march' commandline option. - -'.object_arch NAME' - Override the architecture recorded in the EABI object attribute - section. Valid values for NAME are the same as for the '.arch' - directive. Typically this is useful when code uses runtime - detection of CPU features. - -'.fpu NAME' - Select the floating point unit to assemble for. Valid values for - NAME are the same as for the '-mfpu' commandline option. - -'.eabi_attribute TAG, VALUE' - Set the EABI object attribute number TAG to VALUE. The value is - either a 'number', '"string"', or 'number, "string"' depending on - the tag. - -8.5 Opcodes -=========== - -'as' implements all the standard ARM opcodes. It also implements -several pseudo opcodes, including several synthetic load instructions. - -'NOP' - nop - - This pseudo op will always evaluate to a legal ARM instruction that - does nothing. Currently it will evaluate to MOV r0, r0. - -'LDR' - ldr , = - - If expression evaluates to a numeric constant then a MOV or MVN - instruction will be used in place of the LDR instruction, if the - constant can be generated by either of these instructions. - Otherwise the constant will be placed into the nearest literal pool - (if it not already there) and a PC relative LDR instruction will be - generated. - -'ADR' - adr