aboutsummaryrefslogtreecommitdiff log msg author committer range
diff options
 context: 12345678910152025303540 space: includeignore mode: unifiedssdiffstat only
-rw-r--r--contrib/binutils/gas/doc/as.txt13924
-rw-r--r--contrib/binutils/ld/ld.txt6564
2 files changed, 0 insertions, 20488 deletions
 diff --git a/contrib/binutils/gas/doc/as.txt b/contrib/binutils/gas/doc/as.txtdeleted file mode 100644index 91334b842db9..000000000000--- a/contrib/binutils/gas/doc/as.txt+++ /dev/null@@ -1,13924 +0,0 @@-START-INFO-DIR-ENTRY-* As: (as). The GNU assembler.-* Gas: (as). The GNU assembler.-END-INFO-DIR-ENTRY--Using as-1 Overview- 1.1 Structure of this Manual- 1.2 The GNU Assembler- 1.3 Object File Formats- 1.4 Command Line- 1.5 Input Files- 1.6 Output (Object) File- 1.7 Error and Warning Messages-2 Command-Line Options- 2.1 Enable Listings: '-a[cdhlns]'- 2.2 '--alternate'- 2.3 '-D'- 2.4 Work Faster: '-f'- 2.5 '.include' Search Path: '-I' PATH- 2.6 Difference Tables: '-K'- 2.7 Include Local Symbols: '-L'- 2.8 Configuring listing output: '--listing'- 2.9 Assemble in MRI Compatibility Mode: '-M'- 2.10 Dependency Tracking: '--MD'- 2.11 Name the Object File: '-o'- 2.12 Join Data and Text Sections: '-R'- 2.13 Display Assembly Statistics: '--statistics'- 2.14 Compatible Output: '--traditional-format'- 2.15 Announce Version: '-v'- 2.16 Control Warnings: '-W', '--warn', '--no-warn', '--fatal-warnings'- 2.17 Generate Object File in Spite of Errors: '-Z'-3 Syntax- 3.1 Preprocessing- 3.2 Whitespace- 3.3 Comments- 3.4 Symbols- 3.5 Statements- 3.6 Constants- 3.6.1 Character Constants- 3.6.1.1 Strings- 3.6.1.2 Characters- 3.6.2 Number Constants- 3.6.2.1 Integers- 3.6.2.2 Bignums- 3.6.2.3 Flonums-4 Sections and Relocation- 4.1 Background- 4.2 Linker Sections- 4.3 Assembler Internal Sections- 4.4 Sub-Sections- 4.5 bss Section-5 Symbols- 5.1 Labels- 5.2 Giving Symbols Other Values- 5.3 Symbol Names- 5.4 The Special Dot Symbol- 5.5 Symbol Attributes- 5.5.1 Value- 5.5.2 Type-6 Expressions- 6.1 Empty Expressions- 6.2 Integer Expressions- 6.2.1 Arguments- 6.2.2 Operators- 6.2.3 Prefix Operator- 6.2.4 Infix Operators-7 Assembler Directives- 7.1 '.abort'- 7.2 '.align ABS-EXPR, ABS-EXPR, ABS-EXPR'- 7.3 '.ascii "STRING"'...- 7.4 '.asciz "STRING"'...- 7.5 '.balign[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR'- 7.6 '.byte EXPRESSIONS'- 7.7 '.comm SYMBOL , LENGTH '- 7.8 '.cfi_startproc [simple]'- 7.9 '.cfi_endproc'- 7.10 '.cfi_personality ENCODING [, EXP]'- 7.11 '.cfi_lsda ENCODING [, EXP]'- 7.12 '.cfi_def_cfa REGISTER, OFFSET'- 7.13 '.cfi_def_cfa_register REGISTER'- 7.14 '.cfi_def_cfa_offset OFFSET'- 7.15 '.cfi_adjust_cfa_offset OFFSET'- 7.16 '.cfi_offset REGISTER, OFFSET'- 7.17 '.cfi_rel_offset REGISTER, OFFSET'- 7.18 '.cfi_register REGISTER1, REGISTER2'- 7.19 '.cfi_restore REGISTER'- 7.20 '.cfi_undefined REGISTER'- 7.21 '.cfi_same_value REGISTER'- 7.22 '.cfi_remember_state',- 7.23 '.cfi_return_column REGISTER'- 7.24 '.cfi_signal_frame'- 7.25 '.cfi_window_save'- 7.26 '.cfi_escape' EXPRESSION[, ...]- 7.27 '.file FILENO FILENAME'- 7.28 '.loc FILENO LINENO [COLUMN] [OPTIONS]'- 7.29 '.loc_mark_blocks ENABLE'- 7.30 '.data SUBSECTION'- 7.31 '.double FLONUMS'- 7.32 '.eject'- 7.33 '.else'- 7.34 '.elseif'- 7.35 '.end'- 7.36 '.endfunc'- 7.37 '.endif'- 7.38 '.equ SYMBOL, EXPRESSION'- 7.39 '.equiv SYMBOL, EXPRESSION'- 7.40 '.eqv SYMBOL, EXPRESSION'- 7.41 '.err'- 7.42 '.error "STRING"'- 7.43 '.exitm'- 7.44 '.extern'- 7.45 '.fail EXPRESSION'- 7.46 '.file STRING'- 7.47 '.fill REPEAT , SIZE , VALUE'- 7.48 '.float FLONUMS'- 7.49 '.func NAME[,LABEL]'- 7.50 '.global SYMBOL', '.globl SYMBOL'- 7.51 '.hidden NAMES'- 7.52 '.hword EXPRESSIONS'- 7.53 '.ident'- 7.54 '.if ABSOLUTE EXPRESSION'- 7.55 '.incbin "FILE"[,SKIP[,COUNT]]'- 7.56 '.include "FILE"'- 7.57 '.int EXPRESSIONS'- 7.58 '.internal NAMES'- 7.59 '.irp SYMBOL,VALUES'...- 7.60 '.irpc SYMBOL,VALUES'...- 7.61 '.lcomm SYMBOL , LENGTH'- 7.62 '.lflags'- 7.63 '.line LINE-NUMBER'- 7.64 '.linkonce [TYPE]'- 7.65 '.ln LINE-NUMBER'- 7.66 '.mri VAL'- 7.67 '.list'- 7.68 '.long EXPRESSIONS'- 7.69 '.macro'- 7.70 '.altmacro'- 7.71 '.noaltmacro'- 7.72 '.nolist'- 7.73 '.octa BIGNUMS'- 7.74 '.org NEW-LC , FILL'- 7.75 '.p2align[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR'- 7.76 '.previous'- 7.77 '.popsection'- 7.78 '.print STRING'- 7.79 '.protected NAMES'- 7.80 '.psize LINES , COLUMNS'- 7.81 '.purgem NAME'- 7.82 '.pushsection NAME , SUBSECTION'- 7.83 '.quad BIGNUMS'- 7.84 '.reloc OFFSET, RELOC_NAME[, EXPRESSION]'- 7.85 '.rept COUNT'- 7.86 '.sbttl "SUBHEADING"'- 7.87 '.section NAME'- 7.88 '.set SYMBOL, EXPRESSION'- 7.89 '.short EXPRESSIONS'- 7.90 '.single FLONUMS'- 7.91 '.size'- 7.92 '.sleb128 EXPRESSIONS'- 7.93 '.skip SIZE , FILL'- 7.94 '.space SIZE , FILL'- 7.95 '.stabd, .stabn, .stabs'- 7.96 '.string' "STR"- 7.97 '.struct EXPRESSION'- 7.98 '.subsection NAME'- 7.99 '.symver'- 7.100 '.text SUBSECTION'- 7.101 '.title "HEADING"'- 7.102 '.type'- 7.103 '.uleb128 EXPRESSIONS'- 7.104 '.version "STRING"'- 7.105 '.vtable_entry TABLE, OFFSET'- 7.106 '.vtable_inherit CHILD, PARENT'- 7.107 '.warning "STRING"'- 7.108 '.weak NAMES'- 7.109 '.weakref ALIAS, TARGET'- 7.110 '.word EXPRESSIONS'- 7.111 Deprecated Directives-8 ARM Dependent Features- 8.1 Options- 8.2 Syntax- 8.2.1 Special Characters- 8.2.2 Register Names- 8.2.3 ARM relocation generation- 8.3 Floating Point- 8.4 ARM Machine Directives- 8.5 Opcodes- 8.6 Mapping Symbols-9 80386 Dependent Features- 9.1 Options- 9.2 AT&T Syntax versus Intel Syntax- 9.3 Instruction Naming- 9.4 Register Naming- 9.5 Instruction Prefixes- 9.6 Memory References- 9.7 Handling of Jump Instructions- 9.8 Floating Point- 9.9 Intel's MMX and AMD's 3DNow! SIMD Operations- 9.10 Writing 16-bit Code- 9.11 AT&T Syntax bugs- 9.12 Specifying CPU Architecture- 9.13 Notes-10 IA-64 Dependent Features- 10.1 Options- 10.2 Syntax- 10.2.1 Special Characters- 10.2.2 Register Names- 10.2.3 IA-64 Processor-Status-Register (PSR) Bit Names- 10.3 Opcodes-11 MIPS Dependent Features- 11.1 Assembler options- 11.2 MIPS ECOFF object code- 11.3 Directives for debugging information- 11.4 Directives to override the size of symbols- 11.5 Directives to override the ISA level- 11.6 Directives for extending MIPS 16 bit instructions- 11.7 Directive to mark data as an instruction- 11.8 Directives to save and restore options- 11.9 Directives to control generation of MIPS ASE instructions-12 PowerPC Dependent Features- 12.1 Options- 12.2 PowerPC Assembler Directives-13 SPARC Dependent Features- 13.1 Options- 13.2 Enforcing aligned data- 13.3 Floating Point- 13.4 Sparc Machine Directives-14 Reporting Bugs- 14.1 Have You Found a Bug?- 14.2 How to Report Bugs-15 Acknowledgements-Appendix A GNU Free Documentation License- ADDENDUM: How to use this License for your documents-AS Index-Using as-********--This file is a user guide to the GNU assembler 'as' version "2.17.50-[FreeBSD] 2007-07-03". This version of the file describes 'as'-configured to generate code for machine specific architectures.-- This document is distributed under the terms of the GNU Free-Documentation License. A copy of the license is included in the section-entitled "GNU Free Documentation License".--1 Overview-**********--Here is a brief summary of how to invoke 'as'. For details, see *note-Command-Line Options: Invoking.-- as [-a[cdhlns][=FILE]] [-alternate] [-D]- [-defsym SYM=VAL] [-f] [-g] [-gstabs]- [-gstabs+] [-gdwarf-2] [-help] [-I DIR] [-J]- [-K] [-L] [-listing-lhs-width=NUM]- [-listing-lhs-width2=NUM] [-listing-rhs-width=NUM]- [-listing-cont-lines=NUM] [-keep-locals] [-o- OBJFILE] [-R] [-reduce-memory-overheads] [-statistics]- [-v] [-version] [-version] [-W] [-warn]- [-fatal-warnings] [-w] [-x] [-Z] [@FILE]- [-target-help] [TARGET-OPTIONS]- [-|FILES ...]-- _Target ARM options:_- [-mcpu=PROCESSOR[+EXTENSION...]]- [-march=ARCHITECTURE[+EXTENSION...]]- [-mfpu=FLOATING-POINT-FORMAT]- [-mfloat-abi=ABI]- [-meabi=VER]- [-mthumb]- [-EB|-EL]- [-mapcs-32|-mapcs-26|-mapcs-float|- -mapcs-reentrant]- [-mthumb-interwork] [-k]-- _Target i386 options:_- [-32|-64] [-n]- [-march=CPU] [-mtune=CPU]-- _Target IA-64 options:_- [-mconstant-gp|-mauto-pic]- [-milp32|-milp64|-mlp64|-mp64]- [-mle|mbe]- [-mtune=itanium1|-mtune=itanium2]- [-munwind-check=warning|-munwind-check=error]- [-mhint.b=ok|-mhint.b=warning|-mhint.b=error]- [-x|-xexplicit] [-xauto] [-xdebug]-- _Target MIPS options:_- [-nocpp] [-EL] [-EB] [-O[OPTIMIZATION LEVEL]]- [-g[DEBUG LEVEL]] [-G NUM] [-KPIC] [-call_shared]- [-non_shared] [-xgot [-mvxworks-pic]- [-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32]- [-march=CPU] [-mtune=CPU] [-mips1] [-mips2]- [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2]- [-mips64] [-mips64r2]- [-construct-floats] [-no-construct-floats]- [-trap] [-no-break] [-break] [-no-trap]- [-mfix7000] [-mno-fix7000]- [-mips16] [-no-mips16]- [-msmartmips] [-mno-smartmips]- [-mips3d] [-no-mips3d]- [-mdmx] [-no-mdmx]- [-mdsp] [-mno-dsp]- [-mdspr2] [-mno-dspr2]- [-mmt] [-mno-mt]- [-mdebug] [-no-mdebug]- [-mpdr] [-mno-pdr]-- _Target PowerPC options:_- [-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604|- -m403|-m405|-mppc64|-m620|-mppc64bridge|-mbooke|- -mbooke32|-mbooke64]- [-mcom|-many|-maltivec] [-memb]- [-mregnames|-mno-regnames]- [-mrelocatable|-mrelocatable-lib]- [-mlittle|-mlittle-endian|-mbig|-mbig-endian]- [-msolaris|-mno-solaris]-- _Target SPARC options:_- [-Av6|-Av7|-Av8|-Asparclet|-Asparclite- -Av8plus|-Av8plusa|-Av9|-Av9a]- [-xarch=v8plus|-xarch=v8plusa] [-bump]- [-32|-64]----'@FILE'- Read command-line options from FILE. The options read are inserted- in place of the original @FILE option. If FILE does not exist, or- cannot be read, then the option will be treated literally, and not- removed.-- Options in FILE are separated by whitespace. A whitespace- character may be included in an option by surrounding the entire- option in either single or double quotes. Any character (including- a backslash) may be included by prefixing the character to be- included with a backslash. The FILE may itself contain additional- @FILE options; any such options will be processed recursively.--'-a[cdhlmns]'- Turn on listings, in any of a variety of ways:-- '-ac'- omit false conditionals-- '-ad'- omit debugging directives-- '-ah'- include high-level source-- '-al'- include assembly-- '-am'- include macro expansions-- '-an'- omit forms processing-- '-as'- include symbols-- '=file'- set the name of the listing file-- You may combine these options; for example, use '-aln' for assembly- listing without forms processing. The '=file' option, if used,- must be the last one. By itself, '-a' defaults to '-ahls'.--'--alternate'- Begin in alternate macro mode. *Note '.altmacro': Altmacro.--'-D'- Ignored. This option is accepted for script compatibility with- calls to other assemblers.--'--defsym SYM=VALUE'- Define the symbol SYM to be VALUE before assembling the input file.- VALUE must be an integer constant. As in C, a leading '0x'- indicates a hexadecimal value, and a leading '0' indicates an octal- value. The value of the symbol can be overridden inside a source- file via the use of a '.set' pseudo-op.--'-f'- "fast"--skip whitespace and comment preprocessing (assume source is- compiler output).--'-g'-'--gen-debug'- Generate debugging information for each assembler source line using- whichever debug format is preferred by the target. This currently- means either STABS, ECOFF or DWARF2.--'--gstabs'- Generate stabs debugging information for each assembler line. This- may help debugging assembler code, if the debugger can handle it.--'--gstabs+'- Generate stabs debugging information for each assembler line, with- GNU extensions that probably only gdb can handle, and that could- make other debuggers crash or refuse to read your program. This- may help debugging assembler code. Currently the only GNU- extension is the location of the current working directory at- assembling time.--'--gdwarf-2'- Generate DWARF2 debugging information for each assembler line.- This may help debugging assembler code, if the debugger can handle- it. Note--this option is only supported by some targets, not all- of them.--'--help'- Print a summary of the command line options and exit.--'--target-help'- Print a summary of all target specific options and exit.--'-I DIR'- Add directory DIR to the search list for '.include' directives.--'-J'- Don't warn about signed overflow.--'-K'- This option is accepted but has no effect on the machine specific- family.--'-L'-'--keep-locals'- Keep (in the symbol table) local symbols. These symbols start with- system-specific local label prefixes, typically '.L' for ELF- systems or 'L' for traditional a.out systems. *Note Symbol- Names::.--'--listing-lhs-width=NUMBER'- Set the maximum width, in words, of the output data column for an- assembler listing to NUMBER.--'--listing-lhs-width2=NUMBER'- Set the maximum width, in words, of the output data column for- continuation lines in an assembler listing to NUMBER.--'--listing-rhs-width=NUMBER'- Set the maximum width of an input source line, as displayed in a- listing, to NUMBER bytes.--'--listing-cont-lines=NUMBER'- Set the maximum number of lines printed in a listing for a single- line of input to NUMBER + 1.--'-o OBJFILE'- Name the object-file output from 'as' OBJFILE.--'-R'- Fold the data section into the text section.-- Set the default size of GAS's hash tables to a prime number close- to NUMBER. Increasing this value can reduce the length of time it- takes the assembler to perform its tasks, at the expense of- increasing the assembler's memory requirements. Similarly reducing- this value can reduce the memory requirements at the expense of- speed.--'--reduce-memory-overheads'- This option reduces GAS's memory requirements, at the expense of- making the assembly processes slower. Currently this switch is a- synonym for '--hash-size=4051', but in the future it may have other- effects as well.--'--statistics'- Print the maximum space (in bytes) and total time (in seconds) used- by assembly.--'--strip-local-absolute'- Remove local absolute symbols from the outgoing symbol table.--'-v'-'-version'- Print the 'as' version.--'--version'- Print the 'as' version and exit.--'-W'-'--no-warn'- Suppress warning messages.--'--fatal-warnings'- Treat warnings as errors.--'--warn'- Don't suppress warning messages or treat them as errors.--'-w'- Ignored.--'-x'- Ignored.--'-Z'- Generate an object file even after errors.--'-- | FILES ...'- Standard input, or source files to assemble.-- The following options are available when as is configured for the ARM-processor family.--'-mcpu=PROCESSOR[+EXTENSION...]'- Specify which ARM processor variant is the target.-'-march=ARCHITECTURE[+EXTENSION...]'- Specify which ARM architecture variant is used by the target.-'-mfpu=FLOATING-POINT-FORMAT'- Select which Floating Point architecture is the target.-'-mfloat-abi=ABI'- Select which floating point ABI is in use.-'-mthumb'- Enable Thumb only instruction decoding.-'-mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant'- Select which procedure calling convention is in use.-'-EB | -EL'- Select either big-endian (-EB) or little-endian (-EL) output.-'-mthumb-interwork'- Specify that the code has been generated with interworking between- Thumb and ARM code in mind.-'-k'- Specify that PIC code has been generated.-- The following options are available when 'as' is configured for the-SPARC architecture:--'-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite'-'-Av8plus | -Av8plusa | -Av9 | -Av9a'- Explicitly select a variant of the SPARC architecture.-- '-Av8plus' and '-Av8plusa' select a 32 bit environment. '-Av9' and- '-Av9a' select a 64 bit environment.-- '-Av8plusa' and '-Av9a' enable the SPARC V9 instruction set with- UltraSPARC extensions.--'-xarch=v8plus | -xarch=v8plusa'- For compatibility with the Solaris v9 assembler. These options are- equivalent to -Av8plus and -Av8plusa, respectively.--'-bump'- Warn when the assembler switches to another architecture.-- The following options are available when as is configured for a MIPS-processor.--'-G NUM'- This option sets the largest size of an object that can be- referenced implicitly with the 'gp' register. It is only accepted- for targets that use ECOFF format, such as a DECstation running- Ultrix. The default value is 8.--'-EB'- Generate "big endian" format output.--'-EL'- Generate "little endian" format output.--'-mips1'-'-mips2'-'-mips3'-'-mips4'-'-mips5'-'-mips32'-'-mips32r2'-'-mips64'-'-mips64r2'- Generate code for a particular MIPS Instruction Set Architecture- level. '-mips1' is an alias for '-march=r3000', '-mips2' is an- alias for '-march=r6000', '-mips3' is an alias for '-march=r4000'- and '-mips4' is an alias for '-march=r8000'. '-mips5', '-mips32',- '-mips32r2', '-mips64', and '-mips64r2' correspond to generic 'MIPS- V', 'MIPS32', 'MIPS32 Release 2', 'MIPS64', and 'MIPS64 Release 2'- ISA processors, respectively.--'-march=CPU'- Generate code for a particular MIPS cpu.--'-mtune=CPU'- Schedule and tune for a particular MIPS cpu.--'-mfix7000'-'-mno-fix7000'- Cause nops to be inserted if the read of the destination register- of an mfhi or mflo instruction occurs in the following two- instructions.--'-mdebug'-'-no-mdebug'- Cause stabs-style debugging output to go into an ECOFF-style- .mdebug section instead of the standard ELF .stabs sections.--'-mpdr'-'-mno-pdr'- Control generation of '.pdr' sections.--'-mgp32'-'-mfp32'- The register sizes are normally inferred from the ISA and ABI, but- these flags force a certain group of registers to be treated as 32- bits wide at all times. '-mgp32' controls the size of- general-purpose registers and '-mfp32' controls the size of- floating-point registers.--'-mips16'-'-no-mips16'- Generate code for the MIPS 16 processor. This is equivalent to- putting '.set mips16' at the start of the assembly file.- '-no-mips16' turns off this option.--'-msmartmips'-'-mno-smartmips'- Enables the SmartMIPS extension to the MIPS32 instruction set.- This is equivalent to putting '.set smartmips' at the start of the- assembly file. '-mno-smartmips' turns off this option.--'-mips3d'-'-no-mips3d'- Generate code for the MIPS-3D Application Specific Extension. This- tells the assembler to accept MIPS-3D instructions. '-no-mips3d'- turns off this option.--'-mdmx'-'-no-mdmx'- Generate code for the MDMX Application Specific Extension. This- tells the assembler to accept MDMX instructions. '-no-mdmx' turns- off this option.--'-mdsp'-'-mno-dsp'- Generate code for the DSP Release 1 Application Specific Extension.- This tells the assembler to accept DSP Release 1 instructions.- '-mno-dsp' turns off this option.--'-mdspr2'-'-mno-dspr2'- Generate code for the DSP Release 2 Application Specific Extension.- This option implies -mdsp. This tells the assembler to accept DSP- Release 2 instructions. '-mno-dspr2' turns off this option.--'-mmt'-'-mno-mt'- Generate code for the MT Application Specific Extension. This- tells the assembler to accept MT instructions. '-mno-mt' turns off- this option.--'--construct-floats'-'--no-construct-floats'- The '--no-construct-floats' option disables the construction of- double width floating point constants by loading the two halves of- the value into the two single width floating point registers that- make up the double width register. By default '--construct-floats'- is selected, allowing construction of these floating point- constants.--'--emulation=NAME'- This option causes 'as' to emulate 'as' configured for some other- target, in all respects, including output format (choosing between- ELF and ECOFF only), handling of pseudo-opcodes which may generate- debugging information or store symbol table information, and- default endianness. The available configuration names are:- 'mipsecoff', 'mipself', 'mipslecoff', 'mipsbecoff', 'mipslelf',- 'mipsbelf'. The first two do not alter the default endianness from- that of the primary target for which the assembler was configured;- the others change the default to little- or big-endian as indicated- by the 'b' or 'l' in the name. Using '-EB' or '-EL' will override- the endianness selection in any case.-- This option is currently supported only when the primary target- 'as' is configured for is a MIPS ELF or ECOFF target. Furthermore,- the primary target or others specified with '--enable-targets=...'- at configuration time must include support for the other format, if- both are to be available. For example, the Irix 5 configuration- includes support for both.-- Eventually, this option will support more configurations, with more- fine-grained control over the assembler's behavior, and will be- supported for more processors.--'-nocpp'- 'as' ignores this option. It is accepted for compatibility with- the native tools.--'--trap'-'--no-trap'-'--break'-'--no-break'- Control how to deal with multiplication overflow and division by- zero. '--trap' or '--no-break' (which are synonyms) take a trap- exception (and only work for Instruction Set Architecture level 2- and higher); '--break' or '--no-trap' (also synonyms, and the- default) take a break exception.--'-n'- When this option is used, 'as' will issue a warning every time it- generates a nop instruction from a macro.--1.1 Structure of this Manual-============================--This manual is intended to describe what you need to know to use GNU-'as'. We cover the syntax expected in source files, including notation-for symbols, constants, and expressions; the directives that 'as'-understands; and of course how to invoke 'as'.-- We also cover special features in the machine specific configuration-of 'as', including assembler directives.-- On the other hand, this manual is _not_ intended as an introduction-to programming in assembly language--let alone programming in general!-In a similar vein, we make no attempt to introduce the machine-architecture; we do _not_ describe the instruction set, standard-mnemonics, registers or addressing modes that are standard to a-particular architecture.--1.2 The GNU Assembler-=====================--GNU 'as' is really a family of assemblers. This manual describes 'as',-a member of that family which is configured for the machine specific-architectures. If you use (or have used) the GNU assembler on one-architecture, you should find a fairly similar environment when you use-it on another architecture. Each version has much in common with the-others, including object file formats, most assembler directives (often-called "pseudo-ops") and assembler syntax.-- 'as' is primarily intended to assemble the output of the GNU C-compiler 'gcc' for use by the linker 'ld'. Nevertheless, we've tried to-make 'as' assemble correctly everything that other assemblers for the-same machine would assemble.-- Unlike older assemblers, 'as' is designed to assemble a source-program in one pass of the source file. This has a subtle impact on the-'.org' directive (*note '.org': Org.).--1.3 Object File Formats-=======================--The GNU assembler can be configured to produce several alternative-object file formats. For the most part, this does not affect how you-write assembly language programs; but directives for debugging symbols-are typically different in different file formats. *Note Symbol-Attributes: Symbol Attributes. For the machine specific target, 'as' is-configured to produce ELF format object files.--1.4 Command Line-================--After the program name 'as', the command line may contain options and-file names. Options may appear in any order, and may be before, after,-or between file names. The order of file names is significant.-- '--' (two hyphens) by itself names the standard input file-explicitly, as one of the files for 'as' to assemble.-- Except for '--' any command line argument that begins with a hyphen-('-') is an option. Each option changes the behavior of 'as'. No-option changes the way another option works. An option is a '-'-followed by one or more letters; the case of the letter is important.-All options are optional.-- Some options expect exactly one file name to follow them. The file-name may either immediately follow the option's letter (compatible with-older assemblers) or it may be the next command argument (GNU standard).-These two command lines are equivalent:-- as -o my-object-file.o mumble.s- as -omy-object-file.o mumble.s--1.5 Input Files-===============--We use the phrase "source program", abbreviated "source", to describe-the program input to one run of 'as'. The program may be in one or more-files; how the source is partitioned into files doesn't change the-meaning of the source.-- The source program is a concatenation of the text in all the files,-in the order specified.-- Each time you run 'as' it assembles exactly one source program. The-source program is made up of one or more files. (The standard input is-also a file.)-- You give 'as' a command line that has zero or more input file names.-The input files are read (from left file name to right). A command line-argument (in any position) that has no special meaning is taken to be an-input file name.-- If you give 'as' no file names it attempts to read one input file-from the 'as' standard input, which is normally your terminal. You may-have to type 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