X-Git-Url: https://oss.titaniummirror.com/gitweb/?a=blobdiff_plain;f=gas%2Fdoc%2Fas.info;fp=gas%2Fdoc%2Fas.info;h=0000000000000000000000000000000000000000;hb=2535b36b22dedcdea35e497d38a1c9c735961d28;hp=1508db6f187cf79c0cf404e20a8db05d75d07da8;hpb=47f73751c91775676bb03af53e83c7f49dfda44f;p=msp430-binutils.git diff --git a/gas/doc/as.info b/gas/doc/as.info deleted file mode 100644 index 1508db6..0000000 --- a/gas/doc/as.info +++ /dev/null @@ -1,19168 +0,0 @@ -This is as.info, produced by makeinfo version 4.8 from as.texinfo. - -START-INFO-DIR-ENTRY -* As: (as). The GNU assembler. -* Gas: (as). The GNU assembler. -END-INFO-DIR-ENTRY - - This file documents the GNU Assembler "as". - - Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 2002, -2006, 2007 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled "GNU -Free Documentation License". - - -File: as.info, Node: Top, Next: Overview, Up: (dir) - -Using as -******** - -This file is a user guide to the GNU assembler `as' (GNU Binutils) -version 2.17.90. - - 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". - -* Menu: - -* Overview:: Overview -* Invoking:: Command-Line Options -* Syntax:: Syntax -* Sections:: Sections and Relocation -* Symbols:: Symbols -* Expressions:: Expressions -* Pseudo Ops:: Assembler Directives -* Machine Dependencies:: Machine Dependent Features -* Reporting Bugs:: Reporting Bugs -* Acknowledgements:: Who Did What -* GNU Free Documentation License:: GNU Free Documentation License -* AS Index:: AS Index - - -File: as.info, Node: Overview, Next: Invoking, Prev: Top, Up: Top - -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] - [-debug-prefix-map OLD=NEW] - [-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 Alpha options:_ - [-mCPU] - [-mdebug | -no-mdebug] - [-relax] [-g] [-GSIZE] - [-F] [-32addr] - - _Target ARC options:_ - [-marc[5|6|7|8]] - [-EB|-EL] - - _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 CRIS options:_ - [-underscore | -no-underscore] - [-pic] [-N] - [-emulation=criself | -emulation=crisaout] - [-march=v0_v10 | -march=v10 | -march=v32 | -march=common_v10_v32] - - _Target D10V options:_ - [-O] - - _Target D30V options:_ - [-O|-n|-N] - - _Target i386 options:_ - [-32|-64] [-n] - [-march=CPU] [-mtune=CPU] - - _Target i960 options:_ - [-ACA|-ACA_A|-ACB|-ACC|-AKA|-AKB| - -AKC|-AMC] - [-b] [-no-relax] - - _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 IP2K options:_ - [-mip2022|-mip2022ext] - - _Target M32C options:_ - [-m32c|-m16c] - - _Target M32R options:_ - [-m32rx|-[no-]warn-explicit-parallel-conflicts| - -W[n]p] - - _Target M680X0 options:_ - [-l] [-m68000|-m68010|-m68020|...] - - _Target M68HC11 options:_ - [-m68hc11|-m68hc12|-m68hcs12] - [-mshort|-mlong] - [-mshort-double|-mlong-double] - [-force-long-branches] [-short-branches] - [-strict-direct-mode] [-print-insn-syntax] - [-print-opcodes] [-generate-example] - - _Target MCORE options:_ - [-jsri2bsr] [-sifilter] [-relax] - [-mcpu=[210|340]] - - _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 MMIX options:_ - [-fixed-special-register-names] [-globalize-symbols] - [-gnu-syntax] [-relax] [-no-predefined-symbols] - [-no-expand] [-no-merge-gregs] [-x] - [-linker-allocated-gregs] - - _Target PDP11 options:_ - [-mpic|-mno-pic] [-mall] [-mno-extensions] - [-mEXTENSION|-mno-EXTENSION] - [-mCPU] [-mMACHINE] - - _Target picoJava options:_ - [-mb|-me] - - _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] - - _Target TIC54X options:_ - [-mcpu=54[123589]|-mcpu=54[56]lp] [-mfar-mode|-mf] - [-merrors-to-file |-me ] - - - _Target Z80 options:_ - [-z80] [-r800] - [ -ignore-undocumented-instructions] [-Wnud] - [ -ignore-unportable-instructions] [-Wnup] - [ -warn-undocumented-instructions] [-Wud] - [ -warn-unportable-instructions] [-Wup] - [ -forbid-undocumented-instructions] [-Fud] - [ -forbid-unportable-instructions] [-Fup] - - - _Target Xtensa options:_ - [-[no-]text-section-literals] [-[no-]absolute-literals] - [-[no-]target-align] [-[no-]longcalls] - [-[no-]transform] - [-rename-section OLDNAME=NEWNAME] - -`@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. - -`--debug-prefix-map OLD=NEW' - When assembling files in directory `OLD', record debugging - information describing them as in `NEW' instead. - -`--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' - Issue warnings when difference tables altered for long - displacements. - -`-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 an ARC -processor. - -`-marc[5|6|7|8]' - This option selects the core processor variant. - -`-EB | -EL' - Select either big-endian (-EB) or little-endian (-EL) output. - - 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. - - See the info pages for documentation of the CRIS-specific options. - - The following options are available when as is configured for a D10V -processor. -`-O' - Optimize output by parallelizing instructions. - - The following options are available when as is configured for a D30V -processor. -`-O' - Optimize output by parallelizing instructions. - -`-n' - Warn when nops are generated. - -`-N' - Warn when a nop after a 32-bit multiply instruction is generated. - - The following options are available when as is configured for the -Intel 80960 processor. - -`-ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC' - Specify which variant of the 960 architecture is the target. - -`-b' - Add code to collect statistics about branches taken. - -`-no-relax' - Do not alter compare-and-branch instructions for long - displacements; error if necessary. - - - The following options are available when as is configured for the -Ubicom IP2K series. - -`-mip2022ext' - Specifies that the extended IP2022 instructions are allowed. - -`-mip2022' - Restores the default behaviour, which restricts the permitted - instructions to just the basic IP2022 ones. - - - The following options are available when as is configured for the -Renesas M32C and M16C processors. - -`-m32c' - Assemble M32C instructions. - -`-m16c' - Assemble M16C instructions (the default). - - - The following options are available when as is configured for the -Renesas M32R (formerly Mitsubishi M32R) series. - -`--m32rx' - Specify which processor in the M32R family is the target. The - default is normally the M32R, but this option changes it to the - M32RX. - -`--warn-explicit-parallel-conflicts or --Wp' - Produce warning messages when questionable parallel constructs are - encountered. - -`--no-warn-explicit-parallel-conflicts or --Wnp' - Do not produce warning messages when questionable parallel - constructs are encountered. - - - The following options are available when as is configured for the -Motorola 68000 series. - -`-l' - Shorten references to undefined symbols, to one word instead of - two. - -`-m68000 | -m68008 | -m68010 | -m68020 | -m68030' -`| -m68040 | -m68060 | -m68302 | -m68331 | -m68332' -`| -m68333 | -m68340 | -mcpu32 | -m5200' - Specify what processor in the 68000 family is the target. The - default is normally the 68020, but this can be changed at - configuration time. - -`-m68881 | -m68882 | -mno-68881 | -mno-68882' - The target machine does (or does not) have a floating-point - coprocessor. The default is to assume a coprocessor for 68020, - 68030, and cpu32. Although the basic 68000 is not compatible with - the 68881, a combination of the two can be specified, since it's - possible to do emulation of the coprocessor instructions with the - main processor. - -`-m68851 | -mno-68851' - The target machine does (or does not) have a memory-management - unit coprocessor. The default is to assume an MMU for 68020 and - up. - - - For details about the PDP-11 machine dependent features options, see -*Note PDP-11-Options::. - -`-mpic | -mno-pic' - Generate position-independent (or position-dependent) code. The - default is `-mpic'. - -`-mall' -`-mall-extensions' - Enable all instruction set extensions. This is the default. - -`-mno-extensions' - Disable all instruction set extensions. - -`-mEXTENSION | -mno-EXTENSION' - Enable (or disable) a particular instruction set extension. - -`-mCPU' - Enable the instruction set extensions supported by a particular - CPU, and disable all other extensions. - -`-mMACHINE' - Enable the instruction set extensions supported by a particular - machine model, and disable all other extensions. - - The following options are available when as is configured for a -picoJava processor. - -`-mb' - Generate "big endian" format output. - -`-ml' - Generate "little endian" format output. - - - The following options are available when as is configured for the -Motorola 68HC11 or 68HC12 series. - -`-m68hc11 | -m68hc12 | -m68hcs12' - Specify what processor is the target. The default is defined by - the configuration option when building the assembler. - -`-mshort' - Specify to use the 16-bit integer ABI. - -`-mlong' - Specify to use the 32-bit integer ABI. - -`-mshort-double' - Specify to use the 32-bit double ABI. - -`-mlong-double' - Specify to use the 64-bit double ABI. - -`--force-long-branches' - Relative branches are turned into absolute ones. This concerns - conditional branches, unconditional branches and branches to a sub - routine. - -`-S | --short-branches' - Do not turn relative branches into absolute ones when the offset - is out of range. - -`--strict-direct-mode' - Do not turn the direct addressing mode into extended addressing - mode when the instruction does not support direct addressing mode. - -`--print-insn-syntax' - Print the syntax of instruction in case of error. - -`--print-opcodes' - print the list of instructions with syntax and then exit. - -`--generate-example' - print an example of instruction for each possible instruction and - then exit. This option is only useful for testing `as'. - - - 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 the -'c54x architecture. - -`-mfar-mode' - Enable extended addressing mode. All addresses and relocations - will assume extended addressing (usually 23 bits). - -`-mcpu=CPU_VERSION' - Sets the CPU version being compiled for. - -`-merrors-to-file FILENAME' - Redirect error output to a file, for broken systems which don't - support such behaviour in the shell. - - 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. - - The following options are available when as is configured for an -MCore processor. - -`-jsri2bsr' -`-nojsri2bsr' - Enable or disable the JSRI to BSR transformation. By default this - is enabled. The command line option `-nojsri2bsr' can be used to - disable it. - -`-sifilter' -`-nosifilter' - Enable or disable the silicon filter behaviour. By default this - is disabled. The default can be overridden by the `-sifilter' - command line option. - -`-relax' - Alter jump instructions for long displacements. - -`-mcpu=[210|340]' - Select the cpu type on the target hardware. This controls which - instructions can be assembled. - -`-EB' - Assemble for a big endian target. - -`-EL' - Assemble for a little endian target. - - - See the info pages for documentation of the MMIX-specific options. - - The following options are available when as is configured for an -Xtensa processor. - -`--text-section-literals | --no-text-section-literals' - With `--text-section-literals', literal pools are interspersed in - the text section. The default is `--no-text-section-literals', - which places literals in a separate section in the output file. - These options only affect literals referenced via PC-relative - `L32R' instructions; literals for absolute mode `L32R' - instructions are handled separately. - -`--absolute-literals | --no-absolute-literals' - Indicate to the assembler whether `L32R' instructions use absolute - or PC-relative addressing. The default is to assume absolute - addressing if the Xtensa processor includes the absolute `L32R' - addressing option. Otherwise, only the PC-relative `L32R' mode - can be used. - -`--target-align | --no-target-align' - Enable or disable automatic alignment to reduce branch penalties - at the expense of some code density. The default is - `--target-align'. - -`--longcalls | --no-longcalls' - Enable or disable transformation of call instructions to allow - calls across a greater range of addresses. The default is - `--no-longcalls'. - -`--transform | --no-transform' - Enable or disable all assembler transformations of Xtensa - instructions. The default is `--transform'; `--no-transform' - should be used only in the rare cases when the instructions must - be exactly as specified in the assembly source. - - The following options are available when as is configured for a Z80 -family processor. -`-z80' - Assemble for Z80 processor. - -`-r800' - Assemble for R800 processor. - -`-ignore-undocumented-instructions' -`-Wnud' - Assemble undocumented Z80 instructions that also work on R800 - without warning. - -`-ignore-unportable-instructions' -`-Wnup' - Assemble all undocumented Z80 instructions without warning. - -`-warn-undocumented-instructions' -`-Wud' - Issue a warning for undocumented Z80 instructions that also work - on R800. - -`-warn-unportable-instructions' -`-Wup' - Issue a warning for undocumented Z80 instructions that do not work - on R800. - -`-forbid-undocumented-instructions' -`-Fud' - Treat all undocumented instructions as errors. - -`-forbid-unportable-instructions' -`-Fup' - Treat undocumented Z80 instructions that do not work on R800 as - errors. - -* Menu: - -* Manual:: Structure of this Manual -* GNU Assembler:: The GNU Assembler -* Object Formats:: Object File Formats -* Command Line:: Command Line -* Input Files:: Input Files -* Object:: Output (Object) File -* Errors:: Error and Warning Messages - - -File: as.info, Node: Manual, Next: GNU Assembler, Up: Overview - -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'. - - This manual also describes some of the machine-dependent features of -various flavors of the assembler. - - 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. You may want to consult the manufacturer's -machine architecture manual for this information. - - -File: as.info, Node: GNU Assembler, Next: Object Formats, Prev: Manual, Up: Overview - -1.2 The GNU Assembler -===================== - -GNU `as' is really a family of assemblers. 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. Any exceptions are documented -explicitly (*note Machine Dependencies::). This doesn't mean `as' -always uses the same syntax as another assembler for the same -architecture; for example, we know of several incompatible versions of -680x0 assembly language syntax. - - 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.). - - -File: as.info, Node: Object Formats, Next: Command Line, Prev: GNU Assembler, Up: Overview - -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. - - -File: as.info, Node: Command Line, Next: Input Files, Prev: Object Formats, Up: Overview - -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 - - -File: as.info, Node: Input Files, Next: Object, Prev: Command Line, Up: Overview - -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. - - -File: as.info, Node: Object, Next: Errors, Prev: Input Files, Up: Overview - -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. - - -File: as.info, Node: Errors, Prev: Object, Up: Overview - -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 -(*note `.line': Line.) 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. - - -File: as.info, Node: Invoking, Next: Syntax, Prev: Overview, Up: Top - -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 particular machine architectures. - - 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.) - -* Menu: - -* a:: -a[cdhlns] enable listings -* alternate:: --alternate enable alternate macro syntax -* D:: -D for compatibility -* f:: -f to work faster -* I:: -I for .include search path - -* K:: -K for difference tables - -* L:: -L to retain local symbols -* listing:: --listing-XXX to configure listing output -* M:: -M or --mri to assemble in MRI compatibility mode -* MD:: --MD for dependency tracking -* o:: -o to name the object file -* R:: -R to join data and text sections -* statistics:: --statistics to see statistics about assembly -* traditional-format:: --traditional-format for compatible output -* v:: -v to announce version -* W:: -W, --no-warn, --warn, --fatal-warnings to control warnings -* Z:: -Z to make object file even after errors - - -File: as.info, Node: a, Next: alternate, Up: Invoking - -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. - - -File: as.info, Node: alternate, Next: D, Prev: a, Up: Invoking - -2.2 `--alternate' -================= - -Begin in alternate macro mode, see *Note `.altmacro': Altmacro. - - -File: as.info, Node: D, Next: f, Prev: alternate, Up: Invoking - -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'. - - -File: as.info, Node: f, Next: I, Prev: D, Up: Invoking - -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. - - -File: as.info, Node: I, Next: K, Prev: f, Up: Invoking - -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. - - -File: as.info, Node: K, Next: L, Prev: I, Up: Invoking - -2.6 Difference Tables: `-K' -=========================== - -`as' sometimes alters the code emitted for directives of the form -`.word SYM1-SYM2'. *Note `.word': Word. You can use the `-K' option -if you want a warning issued when this is done. - - -File: as.info, Node: L, Next: listing, Prev: K, Up: Invoking - -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. - - -File: as.info, Node: listing, Next: M, Prev: L, Up: Invoking - -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. - - -File: as.info, Node: M, Next: MD, Prev: listing, Up: Invoking - -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. - - - -File: as.info, Node: MD, Next: o, Prev: M, Up: Invoking - -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. - - -File: as.info, Node: o, Next: R, Prev: MD, Up: Invoking - -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' (or `b.out', for Intel 960 targets only). 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. - - -File: as.info, Node: R, Next: statistics, Prev: o, Up: Invoking - -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'. - - `-R' is not supported for any of the HPPA targets. Using `-R' -generates a warning from `as'. - - -File: as.info, Node: statistics, Next: traditional-format, Prev: R, Up: Invoking - -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). - - -File: as.info, Node: traditional-format, Next: v, Prev: statistics, Up: Invoking - -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. - - -File: as.info, Node: v, Next: W, Prev: traditional-format, Up: Invoking - -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. - - -File: as.info, Node: W, Next: Z, Prev: v, Up: Invoking - -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. - - -File: as.info, Node: Z, Prev: W, Up: Invoking - -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.' - - -File: as.info, Node: Syntax, Next: Sections, Prev: Invoking, Up: Top - -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, except that `as' does not -assemble Vax bit-fields. - -* Menu: - -* Preprocessing:: Preprocessing -* Whitespace:: Whitespace -* Comments:: Comments -* Symbol Intro:: Symbols -* Statements:: Statements -* Constants:: Constants - - -File: as.info, Node: Preprocessing, Next: Whitespace, Up: Syntax - -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. - - -File: as.info, Node: Whitespace, Next: Comments, Prev: Preprocessing, Up: Syntax - -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. - - -File: as.info, Node: Comments, Next: Symbol Intro, Prev: Whitespace, Up: Syntax - -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 ARC; `@' on the ARM; `;' for the H8/300 family; `;' for the HPPA; -`#' on the i386 and x86-64; `#' on the i960; `;' for the PDP-11; `;' -for picoJava; `#' for Motorola PowerPC; `!' for the Renesas / SuperH SH; -`!' on the SPARC; `#' on the ip2k; `#' on the m32c; `#' on the m32r; -`|' on the 680x0; `#' on the 68HC11 and 68HC12; `#' on the Vax; `;' for -the Z80; `!' for the Z8000; `#' on the V850; `#' for Xtensa systems; -see *Note Machine Dependencies::. - - On some machines there are two different line comment characters. -One character only begins a comment if it is the first non-whitespace -character on a line, while the other always begins a comment. - - The V850 assembler also supports a double dash as starting a comment -that extends to the end of the line. - - `--'; - - 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'. - - -File: as.info, Node: Symbol Intro, Next: Statements, Prev: Comments, Up: Syntax - -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 `_.$'. On -most machines, you can also use `$' in symbol names; exceptions are -noted in *Note Machine Dependencies::. 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::. - - -File: as.info, Node: Statements, Next: Constants, Prev: Symbol Intro, Up: Syntax - -3.5 Statements -============== - -A "statement" ends at a newline character (`\n') or line separator -character. (The line separator is usually `;', unless this conflicts -with the comment character; see *Note Machine Dependencies::.) The -newline or separator character is considered part of the preceding -statement. Newlines and separators 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. Different versions of -`as' for different computers recognize different instructions. In -fact, the same symbol may represent a different instruction in a -different computer's assembly language. - - 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::. - - For HPPA targets, labels need not be immediately followed by a -colon, but the definition of a label must begin in column zero. This -also implies that only one label may be defined on each line. - - label: .directive followed by something - another_label: # This is an empty statement. - instruction operand_1, operand_2, ... - - -File: as.info, Node: Constants, Prev: Statements, Up: Syntax - -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. - -* Menu: - -* Characters:: Character Constants -* Numbers:: Number Constants - - -File: as.info, Node: Characters, Next: Numbers, Up: Constants - -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. - -* Menu: - -* Strings:: Strings -* Chars:: Characters - - -File: as.info, Node: Strings, Next: Chars, Up: Characters - -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. - - -File: as.info, Node: Chars, Prev: Strings, Up: Characters - -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 -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. - - -File: as.info, Node: Numbers, Prev: Characters, Up: Constants - -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. - -* Menu: - -* Integers:: Integers -* Bignums:: Bignums -* Flonums:: Flonums - - -File: as.info, Node: Integers, Next: Bignums, Up: Numbers - -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.). - - -File: as.info, Node: Bignums, Next: Flonums, Prev: Integers, Up: Numbers - -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. - - -File: as.info, Node: Flonums, Prev: Bignums, Up: Numbers - -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'. (`0' is optional on the HPPA.) - - * A letter, to tell `as' the rest of the number is a flonum. `e' is - recommended. Case is not important. - - On the H8/300, Renesas / SuperH SH, and AMD 29K architectures, the - letter must be one of the letters `DFPRSX' (in upper or lower - case). - - On the ARC, the letter must be one of the letters `DFRS' (in upper - or lower case). - - On the Intel 960 architecture, the letter must be one of the - letters `DFT' (in upper or lower case). - - On the HPPA architecture, the letter must be `E' (upper case only). - - * 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'. - - -File: as.info, Node: Sections, Next: Symbols, Prev: Syntax, Up: Top - -4 Sections and Relocation -************************* - -* Menu: - -* Secs Background:: Background -* Ld Sections:: Linker Sections -* As Sections:: Assembler Internal Sections -* Sub-Sections:: Sub-Sections -* bss:: bss Section - - -File: as.info, Node: Secs Background, Next: Ld Sections, Up: Sections - -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. For the H8/300, and for the Renesas / -SuperH SH, `as' pads sections if needed to ensure they end on a word -(sixteen bit) boundary. - - 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. - - When it generates COFF or ELF output, `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. - - When `as' generates SOM or ELF output for the HPPA, `as' can also -generate whatever other named sections you specify using the `.space' -and `.subspace' directives. See `HP9000 Series 800 Assembly Language -Reference Manual' (HP 92432-90001) for details on the `.space' and -`.subspace' assembler directives. - - Additionally, `as' uses different names for the standard text, data, -and bss sections when generating SOM output. Program text is placed -into the `$CODE$' section, data into `$DATA$', and BSS into `$BSS$'. - - Within the object file, the text section starts at address `0', the -data section follows, and the bss section follows the data section. - - When generating either SOM or ELF output files on the HPPA, the text -section starts at address `0', the data section at address `0x4000000', -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. (For some object formats, such as SOM for the HPPA, some -expressions are symbol-relative instead.) - - 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. - - -File: as.info, Node: Ld Sections, Next: As Sections, Prev: Secs Background, Up: Sections - -4.2 Linker Sections -=================== - -`ld' deals with just four kinds of sections, summarized below. - -*named sections* -*text section* -*data section* - 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 ... - - -File: as.info, Node: As Sections, Next: Sub-Sections, Prev: Ld Sections, Up: Sections - -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. - - -File: as.info, Node: Sub-Sections, Next: bss, Prev: As Sections, Up: Sections - -4.4 Sub-Sections -================ - -Assembled bytes conventionally fall into two sections: text and data. -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. - - Each subsection is zero-padded up to a multiple of four bytes. -(Subsections may be padded a different amount on different flavors of -`as'.) - - 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. When generating COFF output, you can -also use an extra subsection argument with arbitrary named sections: -`.section NAME, EXPRESSION'. When generating ELF output, 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. - - -File: as.info, Node: bss, Prev: Sub-Sections, Up: Sections - -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. - - When assembling for a target which supports multiple sections, such -as ELF or COFF, you may switch into the `.bss' section and define -symbols as usual; see *Note `.section': Section. You may only assemble -zero values into the section. Typically the section will only contain -symbol definitions and `.skip' directives (*note `.skip': Skip.). - - -File: as.info, Node: Symbols, Next: Expressions, Prev: Sections, Up: Top - -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. - -* Menu: - -* Labels:: Labels -* Setting Symbols:: Giving Symbols Other Values -* Symbol Names:: Symbol Names -* Dot:: The Special Dot Symbol -* Symbol Attributes:: Symbol Attributes - - -File: as.info, Node: Labels, Next: Setting Symbols, Up: Symbols - -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. - - On the HPPA, the usual form for a label need not be immediately -followed by a colon, but instead must start in column zero. Only one -label may be defined on a single line. To work around this, the HPPA -version of `as' also provides a special directive `.label' for defining -labels more flexibly. - - -File: as.info, Node: Setting Symbols, Next: Symbol Names, Prev: Labels, Up: Symbols - -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. - - -File: as.info, Node: Symbol Names, Next: Dot, Prev: Setting Symbols, Up: Symbols - -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. On the HPPA local symbols begin with `L$'. - - 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 `.L6C-A5'. - - -File: as.info, Node: Dot, Next: Symbol Attributes, Prev: Symbol Names, Up: Symbols - -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'. - - -File: as.info, Node: Symbol Attributes, Prev: Dot, Up: Symbols - -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. - - 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. - -* Menu: - -* Symbol Value:: Value -* Symbol Type:: Type - - -* a.out Symbols:: Symbol Attributes: `a.out' - -* COFF Symbols:: Symbol Attributes for COFF - -* SOM Symbols:: Symbol Attributes for SOM - - -File: as.info, Node: Symbol Value, Next: Symbol Type, Up: Symbol Attributes - -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. - - -File: as.info, Node: Symbol Type, Next: a.out Symbols, Prev: Symbol Value, Up: Symbol Attributes - -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. - - -File: as.info, Node: a.out Symbols, Next: COFF Symbols, Prev: Symbol Type, Up: Symbol Attributes - -5.5.3 Symbol Attributes: `a.out' --------------------------------- - -* Menu: - -* Symbol Desc:: Descriptor -* Symbol Other:: Other - - -File: as.info, Node: Symbol Desc, Next: Symbol Other, Up: a.out Symbols - -5.5.3.1 Descriptor -.................. - -This is an arbitrary 16-bit value. You may establish a symbol's -descriptor value by using a `.desc' statement (*note `.desc': Desc.). -A descriptor value means nothing to `as'. - - -File: as.info, Node: Symbol Other, Prev: Symbol Desc, Up: a.out Symbols - -5.5.3.2 Other -............. - -This is an arbitrary 8-bit value. It means nothing to `as'. - - -File: as.info, Node: COFF Symbols, Next: SOM Symbols, Prev: a.out Symbols, Up: Symbol Attributes - -5.5.4 Symbol Attributes for COFF --------------------------------- - -The COFF format supports a multitude of auxiliary symbol attributes; -like the primary symbol attributes, they are set between `.def' and -`.endef' directives. - -5.5.4.1 Primary Attributes -.......................... - -The symbol name is set with `.def'; the value and type, respectively, -with `.val' and `.type'. - -5.5.4.2 Auxiliary Attributes -............................ - -The `as' directives `.dim', `.line', `.scl', `.size', `.tag', and -`.weak' can generate auxiliary symbol table information for COFF. - - -File: as.info, Node: SOM Symbols, Prev: COFF Symbols, Up: Symbol Attributes - -5.5.5 Symbol Attributes for SOM -------------------------------- - -The SOM format for the HPPA supports a multitude of symbol attributes -set with the `.EXPORT' and `.IMPORT' directives. - - The attributes are described in `HP9000 Series 800 Assembly Language -Reference Manual' (HP 92432-90001) under the `IMPORT' and `EXPORT' -assembler directive documentation. - - -File: as.info, Node: Expressions, Next: Pseudo Ops, Prev: Symbols, Up: Top - -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. - -* Menu: - -* Empty Exprs:: Empty Expressions -* Integer Exprs:: Integer Expressions - - -File: as.info, Node: Empty Exprs, Next: Integer Exprs, Up: Expressions - -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. - - -File: as.info, Node: Integer Exprs, Prev: Empty Exprs, Up: Expressions - -6.2 Integer Expressions -======================= - -An "integer expression" is one or more _arguments_ delimited by -_operators_. - -* Menu: - -* Arguments:: Arguments -* Operators:: Operators -* Prefix Ops:: Prefix Operators -* Infix Ops:: Infix Operators - - -File: as.info, Node: Arguments, Next: Operators, Up: Integer Exprs - -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. - - -File: as.info, Node: Operators, Next: Prefix Ops, Prev: Arguments, Up: Integer Exprs - -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. - - -File: as.info, Node: Prefix Ops, Next: Infix Ops, Prev: Operators, Up: Integer Exprs - -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. - - -File: as.info, Node: Infix Ops, Prev: Prefix Ops, Up: Integer Exprs - -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. - - -File: as.info, Node: Pseudo Ops, Next: Machine Dependencies, Prev: Expressions, Up: Top - -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. Some machine -configurations provide additional directives. *Note Machine -Dependencies::. - -* Menu: - -* Abort:: `.abort' - -* ABORT (COFF):: `.ABORT' - -* Align:: `.align ABS-EXPR , ABS-EXPR' -* Altmacro:: `.altmacro' -* Ascii:: `.ascii "STRING"'... -* Asciz:: `.asciz "STRING"'... -* Balign:: `.balign ABS-EXPR , ABS-EXPR' -* Byte:: `.byte EXPRESSIONS' -* Comm:: `.comm SYMBOL , LENGTH ' - -* CFI directives:: `.cfi_startproc [simple]', `.cfi_endproc', etc. - -* Data:: `.data SUBSECTION' - -* Def:: `.def NAME' - -* Desc:: `.desc SYMBOL, ABS-EXPRESSION' - -* Dim:: `.dim' - -* Double:: `.double FLONUMS' -* Eject:: `.eject' -* Else:: `.else' -* Elseif:: `.elseif' -* End:: `.end' - -* Endef:: `.endef' - -* Endfunc:: `.endfunc' -* Endif:: `.endif' -* Equ:: `.equ SYMBOL, EXPRESSION' -* Equiv:: `.equiv SYMBOL, EXPRESSION' -* Eqv:: `.eqv SYMBOL, EXPRESSION' -* Err:: `.err' -* Error:: `.error STRING' -* Exitm:: `.exitm' -* Extern:: `.extern' -* Fail:: `.fail' - -* File:: `.file STRING' - -* Fill:: `.fill REPEAT , SIZE , VALUE' -* Float:: `.float FLONUMS' -* Func:: `.func' -* Global:: `.global SYMBOL', `.globl SYMBOL' - -* Hidden:: `.hidden NAMES' - -* hword:: `.hword EXPRESSIONS' -* Ident:: `.ident' -* If:: `.if ABSOLUTE EXPRESSION' -* Incbin:: `.incbin "FILE"[,SKIP[,COUNT]]' -* Include:: `.include "FILE"' -* Int:: `.int EXPRESSIONS' - -* Internal:: `.internal NAMES' - -* Irp:: `.irp SYMBOL,VALUES'... -* Irpc:: `.irpc SYMBOL,VALUES'... -* Lcomm:: `.lcomm SYMBOL , LENGTH' -* Lflags:: `.lflags' - -* Line:: `.line LINE-NUMBER' - -* Linkonce:: `.linkonce [TYPE]' -* List:: `.list' -* Ln:: `.ln LINE-NUMBER' - -* LNS directives:: `.file', `.loc', etc. - -* Long:: `.long EXPRESSIONS' - -* Macro:: `.macro NAME ARGS'... -* MRI:: `.mri VAL' -* Noaltmacro:: `.noaltmacro' -* Nolist:: `.nolist' -* Octa:: `.octa BIGNUMS' -* Org:: `.org NEW-LC, FILL' -* P2align:: `.p2align ABS-EXPR, ABS-EXPR, ABS-EXPR' - -* PopSection:: `.popsection' -* Previous:: `.previous' - -* Print:: `.print STRING' - -* Protected:: `.protected NAMES' - -* Psize:: `.psize LINES, COLUMNS' -* Purgem:: `.purgem NAME' - -* PushSection:: `.pushsection NAME' - -* Quad:: `.quad BIGNUMS' -* Reloc:: `.reloc OFFSET, RELOC_NAME[, EXPRESSION]' -* Rept:: `.rept COUNT' -* Sbttl:: `.sbttl "SUBHEADING"' - -* Scl:: `.scl CLASS' - -* Section:: `.section NAME' - -* Set:: `.set SYMBOL, EXPRESSION' -* Short:: `.short EXPRESSIONS' -* Single:: `.single FLONUMS' - -* Size:: `.size [NAME , EXPRESSION]' - -* Skip:: `.skip SIZE , FILL' -* Sleb128:: `.sleb128 EXPRESSIONS' -* Space:: `.space SIZE , FILL' - -* Stab:: `.stabd, .stabn, .stabs' - -* String:: `.string "STR"' -* Struct:: `.struct EXPRESSION' - -* SubSection:: `.subsection' -* Symver:: `.symver NAME,NAME2@NODENAME' - - -* Tag:: `.tag STRUCTNAME' - -* Text:: `.text SUBSECTION' -* Title:: `.title "HEADING"' - -* Type:: `.type ' - -* Uleb128:: `.uleb128 EXPRESSIONS' - -* Val:: `.val ADDR' - - -* Version:: `.version "STRING"' -* VTableEntry:: `.vtable_entry TABLE, OFFSET' -* VTableInherit:: `.vtable_inherit CHILD, PARENT' - -* Warning:: `.warning STRING' -* Weak:: `.weak NAMES' -* Weakref:: `.weakref ALIAS, SYMBOL' -* Word:: `.word EXPRESSIONS' -* Deprecated:: Deprecated Directives - - -File: as.info, Node: Abort, Next: ABORT (COFF), Up: Pseudo Ops - -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. - - -File: as.info, Node: ABORT (COFF), Next: Align, Prev: Abort, Up: Pseudo Ops - -7.2 `.ABORT' (COFF) -=================== - -When producing COFF output, `as' accepts this directive as a synonym -for `.abort'. - - -File: as.info, Node: Align, Next: Altmacro, Prev: ABORT (COFF), Up: Pseudo Ops - -7.3 `.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). - - -File: as.info, Node: Ascii, Next: Asciz, Prev: Altmacro, Up: Pseudo Ops - -7.4 `.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. - - -File: as.info, Node: Asciz, Next: Balign, Prev: Ascii, Up: Pseudo Ops - -7.5 `.asciz "STRING"'... -======================== - -`.asciz' is just like `.ascii', but each string is followed by a zero -byte. The "z" in `.asciz' stands for "zero". - - -File: as.info, Node: Balign, Next: Byte, Prev: Asciz, Up: Pseudo Ops - -7.6 `.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. - - -File: as.info, Node: Byte, Next: Comm, Prev: Balign, Up: Pseudo Ops - -7.7 `.byte EXPRESSIONS' -======================= - -`.byte' expects zero or more expressions, separated by commas. Each -expression is assembled into the next byte. - - -File: as.info, Node: Comm, Next: CFI directives, Prev: Byte, Up: Pseudo Ops - -7.8 `.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. - - The syntax for `.comm' differs slightly on the HPPA. The syntax is -`SYMBOL .comm, LENGTH'; SYMBOL is optional. - - -File: as.info, Node: CFI directives, Next: Data, Prev: Comm, Up: Pseudo Ops - -7.9 `.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.10 `.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.11 `.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.12 `.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.13 `.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.14 `.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.15 `.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.16 `.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.17 `.cfi_offset REGISTER, OFFSET' -=================================== - -Previous value of REGISTER is saved at offset OFFSET from CFA. - -7.18 `.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.19 `.cfi_register REGISTER1, REGISTER2' -========================================= - -Previous value of REGISTER1 is saved in register REGISTER2. - -7.20 `.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.21 `.cfi_undefined REGISTER' -============================== - -From now on the previous value of REGISTER can't be restored anymore. - -7.22 `.cfi_same_value REGISTER' -=============================== - -Current value of REGISTER is the same like in the previous frame, i.e. -no restoration needed. - -7.23 `.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.24 `.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.25 `.cfi_signal_frame' -======================== - -Mark current function as signal trampoline. - -7.26 `.cfi_window_save' -======================= - -SPARC register window has been saved. - -7.27 `.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. - - -File: as.info, Node: LNS directives, Next: Long, Prev: Ln, Up: Pseudo Ops - -7.28 `.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.29 `.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.30 `.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. - - -File: as.info, Node: Data, Next: Def, Prev: CFI directives, Up: Pseudo Ops - -7.31 `.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. - - -File: as.info, Node: Def, Next: Desc, Prev: Data, Up: Pseudo Ops - -7.32 `.def NAME' -================ - -Begin defining debugging information for a symbol NAME; the definition -extends until the `.endef' directive is encountered. - - -File: as.info, Node: Desc, Next: Dim, Prev: Def, Up: Pseudo Ops - -7.33 `.desc SYMBOL, ABS-EXPRESSION' -=================================== - -This directive sets the descriptor of the symbol (*note Symbol -Attributes::) to the low 16 bits of an absolute expression. - - The `.desc' directive is not available when `as' is configured for -COFF output; it is only for `a.out' or `b.out' object format. For the -sake of compatibility, `as' accepts it, but produces no output, when -configured for COFF. - - -File: as.info, Node: Dim, Next: Double, Prev: Desc, Up: Pseudo Ops - -7.34 `.dim' -=========== - -This directive is generated by compilers to include auxiliary debugging -information in the symbol table. It is only permitted inside -`.def'/`.endef' pairs. - - -File: as.info, Node: Double, Next: Eject, Prev: Dim, Up: Pseudo Ops - -7.35 `.double FLONUMS' -====================== - -`.double' expects zero or more flonums, separated by commas. It -assembles floating point numbers. The exact kind of floating point -numbers emitted depends on how `as' is configured. *Note Machine -Dependencies::. - - -File: as.info, Node: Eject, Next: Else, Prev: Double, Up: Pseudo Ops - -7.36 `.eject' -============= - -Force a page break at this point, when generating assembly listings. - - -File: as.info, Node: Else, Next: Elseif, Prev: Eject, Up: Pseudo Ops - -7.37 `.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. - - -File: as.info, Node: Elseif, Next: End, Prev: Else, Up: Pseudo Ops - -7.38 `.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. - - -File: as.info, Node: End, Next: Endef, Prev: Elseif, Up: Pseudo Ops - -7.39 `.end' -=========== - -`.end' marks the end of the assembly file. `as' does not process -anything in the file past the `.end' directive. - - -File: as.info, Node: Endef, Next: Endfunc, Prev: End, Up: Pseudo Ops - -7.40 `.endef' -============= - -This directive flags the end of a symbol definition begun with `.def'. - - -File: as.info, Node: Endfunc, Next: Endif, Prev: Endef, Up: Pseudo Ops - -7.41 `.endfunc' -=============== - -`.endfunc' marks the end of a function specified with `.func'. - - -File: as.info, Node: Endif, Next: Equ, Prev: Endfunc, Up: Pseudo Ops - -7.42 `.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. - - -File: as.info, Node: Equ, Next: Equiv, Prev: Endif, Up: Pseudo Ops - -7.43 `.equ SYMBOL, EXPRESSION' -============================== - -This directive sets the value of SYMBOL to EXPRESSION. It is -synonymous with `.set'; see *Note `.set': Set. - - The syntax for `equ' on the HPPA is `SYMBOL .equ EXPRESSION'. - - The syntax for `equ' on the Z80 is `SYMBOL equ EXPRESSION'. On the -Z80 it is an eror if SYMBOL is already defined, but the symbol is not -protected from later redefinition. Compare *Note Equiv::. - - -File: as.info, Node: Equiv, Next: Eqv, Prev: Equ, Up: Pseudo Ops - -7.44 `.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. - - -File: as.info, Node: Eqv, Next: Err, Prev: Equiv, Up: Pseudo Ops - -7.45 `.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. - - -File: as.info, Node: Err, Next: Error, Prev: Eqv, Up: Pseudo Ops - -7.46 `.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. - - -File: as.info, Node: Error, Next: Exitm, Prev: Err, Up: Pseudo Ops - -7.47 `.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." - - -File: as.info, Node: Exitm, Next: Extern, Prev: Error, Up: Pseudo Ops - -7.48 `.exitm' -============= - -Exit early from the current macro definition. *Note Macro::. - - -File: as.info, Node: Extern, Next: Fail, Prev: Exitm, Up: Pseudo Ops - -7.49 `.extern' -============== - -`.extern' is accepted in the source program--for compatibility with -other assemblers--but it is ignored. `as' treats all undefined symbols -as external. - - -File: as.info, Node: Fail, Next: File, Prev: Extern, Up: Pseudo Ops - -7.50 `.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. - - -File: as.info, Node: File, Next: Fill, Prev: Fail, Up: Pseudo Ops - -7.51 `.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. - - -File: as.info, Node: Fill, Next: Float, Prev: File, Up: Pseudo Ops - -7.52 `.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. - - -File: as.info, Node: Float, Next: Func, Prev: Fill, Up: Pseudo Ops - -7.53 `.float FLONUMS' -===================== - -This directive assembles zero or more flonums, separated by commas. It -has the same effect as `.single'. The exact kind of floating point -numbers emitted depends on how `as' is configured. *Note Machine -Dependencies::. - - -File: as.info, Node: Func, Next: Global, Prev: Float, Up: Pseudo Ops - -7.54 `.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'. - - -File: as.info, Node: Global, Next: Hidden, Prev: Func, Up: Pseudo Ops - -7.55 `.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. - - On the HPPA, `.global' is not always enough to make it accessible to -other partial programs. You may need the HPPA-only `.EXPORT' directive -as well. *Note HPPA Assembler Directives: HPPA Directives. - - -File: as.info, Node: Hidden, Next: hword, Prev: Global, Up: Pseudo Ops - -7.56 `.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. - - -File: as.info, Node: hword, Next: Ident, Prev: Hidden, Up: Pseudo Ops - -7.57 `.hword EXPRESSIONS' -========================= - -This expects zero or more EXPRESSIONS, and emits a 16 bit number for -each. - - This directive is a synonym for `.short'; depending on the target -architecture, it may also be a synonym for `.word'. - - -File: as.info, Node: Ident, Next: If, Prev: hword, Up: Pseudo Ops - -7.58 `.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. - - -File: as.info, Node: If, Next: Incbin, Prev: Ident, Up: Pseudo Ops - -7.59 `.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. - - -File: as.info, Node: Incbin, Next: Include, Prev: If, Up: Pseudo Ops - -7.60 `.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. - - -File: as.info, Node: Include, Next: Int, Prev: Incbin, Up: Pseudo Ops - -7.61 `.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. - - -File: as.info, Node: Int, Next: Internal, Prev: Include, Up: Pseudo Ops - -7.62 `.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. - - -File: as.info, Node: Internal, Next: Irp, Prev: Int, Up: Pseudo Ops - -7.63 `.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. - - -File: as.info, Node: Irp, Next: Irpc, Prev: Internal, Up: Pseudo Ops - -7.64 `.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::. - - -File: as.info, Node: Irpc, Next: Lcomm, Prev: Irp, Up: Pseudo Ops - -7.65 `.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::. - - -File: as.info, Node: Lcomm, Next: Lflags, Prev: Irpc, Up: Pseudo Ops - -7.66 `.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'. - - Some targets permit a third argument to be used with `.lcomm'. This -argument specifies the desired alignment of the symbol in the bss -section. - - The syntax for `.lcomm' differs slightly on the HPPA. The syntax is -`SYMBOL .lcomm, LENGTH'; SYMBOL is optional. - - -File: as.info, Node: Lflags, Next: Line, Prev: Lcomm, Up: Pseudo Ops - -7.67 `.lflags' -============== - -`as' accepts this directive, for compatibility with other assemblers, -but ignores it. - - -File: as.info, Node: Line, Next: Linkonce, Prev: Lflags, Up: Pseudo Ops - -7.68 `.line LINE-NUMBER' -======================== - - Change the logical line number. LINE-NUMBER must be an absolute -expression. The next line has that logical line number. Therefore any -other statements on the current line (after a statement separator -character) are reported as on logical line number LINE-NUMBER - 1. One -day `as' will no longer support this directive: it is recognized only -for compatibility with existing assembler programs. - - 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. - - -File: as.info, Node: Linkonce, Next: List, Prev: Line, Up: Pseudo Ops - -7.69 `.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. - - -File: as.info, Node: Ln, Next: LNS directives, Prev: List, Up: Pseudo Ops - -7.70 `.ln LINE-NUMBER' -====================== - -`.ln' is a synonym for `.line'. - - -File: as.info, Node: MRI, Next: Noaltmacro, Prev: Macro, Up: Pseudo Ops - -7.71 `.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. - - -File: as.info, Node: List, Next: Ln, Prev: Linkonce, Up: Pseudo Ops - -7.72 `.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. - - -File: as.info, Node: Long, Next: Macro, Prev: LNS directives, Up: Pseudo Ops - -7.73 `.long EXPRESSIONS' -======================== - -`.long' is the same as `.int'. *Note `.int': Int. - - -File: as.info, Node: Macro, Next: MRI, Prev: Long, Up: Pseudo Ops - -7.74 `.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. - - -File: as.info, Node: Altmacro, Next: Ascii, Prev: Align, Up: Pseudo Ops - -7.75 `.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. - - -File: as.info, Node: Noaltmacro, Next: Nolist, Prev: MRI, Up: Pseudo Ops - -7.76 `.noaltmacro' -================== - -Disable alternate macro mode. *Note Altmacro::. - - -File: as.info, Node: Nolist, Next: Octa, Prev: Noaltmacro, Up: Pseudo Ops - -7.77 `.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. - - -File: as.info, Node: Octa, Next: Org, Prev: Nolist, Up: Pseudo Ops - -7.78 `.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. - - -File: as.info, Node: Org, Next: P2align, Prev: Octa, Up: Pseudo Ops - -7.79 `.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. - - -File: as.info, Node: P2align, Next: PopSection, Prev: Org, Up: Pseudo Ops - -7.80 `.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. - - -File: as.info, Node: Previous, Next: Print, Prev: PopSection, Up: Pseudo Ops - -7.81 `.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. - - -File: as.info, Node: PopSection, Next: Previous, Prev: P2align, Up: Pseudo Ops - -7.82 `.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. - - -File: as.info, Node: Print, Next: Protected, Prev: Previous, Up: Pseudo Ops - -7.83 `.print STRING' -==================== - -`as' will print STRING on the standard output during assembly. You -must put STRING in double quotes. - - -File: as.info, Node: Protected, Next: Psize, Prev: Print, Up: Pseudo Ops - -7.84 `.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. - - -File: as.info, Node: Psize, Next: Purgem, Prev: Protected, Up: Pseudo Ops - -7.85 `.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'. - - -File: as.info, Node: Purgem, Next: PushSection, Prev: Psize, Up: Pseudo Ops - -7.86 `.purgem NAME' -=================== - -Undefine the macro NAME, so that later uses of the string will not be -expanded. *Note Macro::. - - -File: as.info, Node: PushSection, Next: Quad, Prev: Purgem, Up: Pseudo Ops - -7.87 `.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'. - - -File: as.info, Node: Quad, Next: Reloc, Prev: PushSection, Up: Pseudo Ops - -7.88 `.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. - - -File: as.info, Node: Reloc, Next: Rept, Prev: Quad, Up: Pseudo Ops - -7.89 `.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. - - -File: as.info, Node: Rept, Next: Sbttl, Prev: Reloc, Up: Pseudo Ops - -7.90 `.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 - - -File: as.info, Node: Sbttl, Next: Scl, Prev: Rept, Up: Pseudo Ops - -7.91 `.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. - - -File: as.info, Node: Scl, Next: Section, Prev: Sbttl, Up: Pseudo Ops - -7.92 `.scl CLASS' -================= - -Set the storage-class value for a symbol. This directive may only be -used inside a `.def'/`.endef' pair. Storage class may flag whether a -symbol is static or external, or it may record further symbolic -debugging information. - - -File: as.info, Node: Section, Next: Set, Prev: Scl, Up: Pseudo Ops - -7.93 `.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. - -COFF Version ------------- - - For COFF targets, the `.section' directive is used in one of the -following ways: - - .section NAME[, "FLAGS"] - .section NAME[, SUBSEGMENT] - - If the optional argument is quoted, it is taken as flags to use for -the section. Each flag is a single character. The following flags are -recognized: -`b' - bss section (uninitialized data) - -`n' - section is not loaded - -`w' - writable section - -`d' - data section - -`r' - read-only section - -`x' - executable section - -`s' - shared section (meaningful for PE targets) - -`a' - ignored. (For compatibility with the ELF version) - - 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 be loaded and writable. Note the `n' and `w' flags -remove attributes from the section, rather than adding them, so if they -are used on their own it will be as if no flags had been specified at -all. - - If the optional argument to the `.section' directive is not quoted, -it is taken as a subsegment number (*note Sub-Sections::). - -ELF Version ------------ - - 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. - - -File: as.info, Node: Set, Next: Short, Prev: Section, Up: Pseudo Ops - -7.94 `.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. - - The syntax for `set' on the HPPA is `SYMBOL .set EXPRESSION'. - - On Z80 `set' is a real instruction, use `SYMBOL defl EXPRESSION' -instead. - - -File: as.info, Node: Short, Next: Single, Prev: Set, Up: Pseudo Ops - -7.95 `.short EXPRESSIONS' -========================= - -`.short' is normally the same as `.word'. *Note `.word': Word. - - In some configurations, however, `.short' and `.word' generate -numbers of different lengths. *Note Machine Dependencies::. - - -File: as.info, Node: Single, Next: Size, Prev: Short, Up: Pseudo Ops - -7.96 `.single FLONUMS' -====================== - -This directive assembles zero or more flonums, separated by commas. It -has the same effect as `.float'. The exact kind of floating point -numbers emitted depends on how `as' is configured. *Note Machine -Dependencies::. - - -File: as.info, Node: Size, Next: Skip, Prev: Single, Up: Pseudo Ops - -7.97 `.size' -============ - -This directive is used to set the size associated with a symbol. - -COFF Version ------------- - - For COFF targets, the `.size' directive is only permitted inside -`.def'/`.endef' pairs. It is used like this: - - .size EXPRESSION - -ELF Version ------------ - - 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. - - -File: as.info, Node: Sleb128, Next: Space, Prev: Skip, Up: Pseudo Ops - -7.98 `.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. - - -File: as.info, Node: Skip, Next: Sleb128, Prev: Size, Up: Pseudo Ops - -7.99 `.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'. - - -File: as.info, Node: Space, Next: Stab, Prev: Sleb128, Up: Pseudo Ops - -7.100 `.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'. - - _Warning:_ `.space' has a completely different meaning for HPPA - targets; use `.block' as a substitute. See `HP9000 Series 800 - Assembly Language Reference Manual' (HP 92432-90001) for the - meaning of the `.space' directive. *Note HPPA Assembler - Directives: HPPA Directives, for a summary. - - -File: as.info, Node: Stab, Next: String, Prev: Space, Up: Pseudo Ops - -7.101 `.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. - - -File: as.info, Node: String, Next: Struct, Prev: Stab, Up: Pseudo Ops - -7.102 `.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. - - -File: as.info, Node: Struct, Next: SubSection, Prev: String, Up: Pseudo Ops - -7.103 `.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. - - -File: as.info, Node: SubSection, Next: Symver, Prev: Struct, Up: Pseudo Ops - -7.104 `.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. - - -File: as.info, Node: Symver, Next: Tag, Prev: SubSection, Up: Pseudo Ops - -7.105 `.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. - - -File: as.info, Node: Tag, Next: Text, Prev: Symver, Up: Pseudo Ops - -7.106 `.tag STRUCTNAME' -======================= - -This directive is generated by compilers to include auxiliary debugging -information in the symbol table. It is only permitted inside -`.def'/`.endef' pairs. Tags are used to link structure definitions in -the symbol table with instances of those structures. - - -File: as.info, Node: Text, Next: Title, Prev: Tag, Up: Pseudo Ops - -7.107 `.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. - - -File: as.info, Node: Title, Next: Type, Prev: Text, Up: Pseudo Ops - -7.108 `.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. - - -File: as.info, Node: Type, Next: Uleb128, Prev: Title, Up: Pseudo Ops - -7.109 `.type' -============= - -This directive is used to set the type of a symbol. - -COFF Version ------------- - - For COFF targets, this directive is permitted only within -`.def'/`.endef' pairs. It is used like this: - - .type INT - - This records the integer INT as the type attribute of a symbol table -entry. - -ELF Version ------------ - - 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" - - -File: as.info, Node: Uleb128, Next: Val, Prev: Type, Up: Pseudo Ops - -7.110 `.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. - - -File: as.info, Node: Val, Next: Version, Prev: Uleb128, Up: Pseudo Ops - -7.111 `.val ADDR' -================= - -This directive, permitted only within `.def'/`.endef' pairs, records -the address ADDR as the value attribute of a symbol table entry. - - -File: as.info, Node: Version, Next: VTableEntry, Prev: Val, Up: Pseudo Ops - -7.112 `.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'. - - -File: as.info, Node: VTableEntry, Next: VTableInherit, Prev: Version, Up: Pseudo Ops - -7.113 `.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'. - - -File: as.info, Node: VTableInherit, Next: Warning, Prev: VTableEntry, Up: Pseudo Ops - -7.114 `.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. - - -File: as.info, Node: Warning, Next: Weak, Prev: VTableInherit, Up: Pseudo Ops - -7.115 `.warning "STRING"' -========================= - -Similar to the directive `.error' (*note `.error "STRING"': Error.), -but just emits a warning. - - -File: as.info, Node: Weak, Next: Weakref, Prev: Warning, Up: Pseudo Ops - -7.116 `.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. - - -File: as.info, Node: Weakref, Next: Word, Prev: Weak, Up: Pseudo Ops - -7.117 `.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. - - -File: as.info, Node: Word, Next: Deprecated, Prev: Weakref, Up: Pseudo Ops - -7.118 `.word EXPRESSIONS' -========================= - -This directive expects zero or more EXPRESSIONS, of any section, -separated by commas. - - The size of the number emitted, and its byte order, depend on what -target computer the assembly is for. - - _Warning: Special Treatment to support Compilers_ - - Machines with a 32-bit address space, but that do less than 32-bit -addressing, require the following special treatment. If the machine of -interest to you does 32-bit addressing (or doesn't require it; *note -Machine Dependencies::), you can ignore this issue. - - In order to assemble compiler output into something that works, `as' -occasionally does strange things to `.word' directives. Directives of -the form `.word sym1-sym2' are often emitted by compilers as part of -jump tables. Therefore, when `as' assembles a directive of the form -`.word sym1-sym2', and the difference between `sym1' and `sym2' does -not fit in 16 bits, `as' creates a "secondary jump table", immediately -before the next label. This secondary jump table is preceded by a -short-jump to the first byte after the secondary table. This -short-jump prevents the flow of control from accidentally falling into -the new table. Inside the table is a long-jump to `sym2'. The -original `.word' contains `sym1' minus the address of the long-jump to -`sym2'. - - If there were several occurrences of `.word sym1-sym2' before the -secondary jump table, all of them are adjusted. If there was a `.word -sym3-sym4', that also did not fit in sixteen bits, a long-jump to -`sym4' is included in the secondary jump table, and the `.word' -directives are adjusted to contain `sym3' minus the address of the -long-jump to `sym4'; and so on, for as many entries in the original -jump table as necessary. - - -File: as.info, Node: Deprecated, Prev: Word, Up: Pseudo Ops - -7.119 Deprecated Directives -=========================== - -One day these directives won't work. They are included for -compatibility with older assemblers. -.abort - -.line - - -File: as.info, Node: Machine Dependencies, Next: Reporting Bugs, Prev: Pseudo Ops, Up: Top - -8 Machine Dependent Features -**************************** - -The machine instruction sets are (almost by definition) different on -each machine where `as' runs. Floating point representations vary as -well, and `as' often supports a few additional directives or -command-line options for compatibility with other assemblers on a -particular platform. Finally, some versions of `as' support special -pseudo-instructions for branch optimization. - - This chapter discusses most of these differences, though it does not -include details on any machine's instruction set. For details on that -subject, see the hardware manufacturer's manual. - -* Menu: - - -* Alpha-Dependent:: Alpha Dependent Features - -* ARC-Dependent:: ARC Dependent Features - -* ARM-Dependent:: ARM Dependent Features - -* AVR-Dependent:: AVR Dependent Features - -* BFIN-Dependent:: BFIN Dependent Features - -* CR16-Dependent:: CR16 Dependent Features - -* CRIS-Dependent:: CRIS Dependent Features - -* D10V-Dependent:: D10V Dependent Features - -* D30V-Dependent:: D30V Dependent Features - -* H8/300-Dependent:: Renesas H8/300 Dependent Features - -* HPPA-Dependent:: HPPA Dependent Features - -* ESA/390-Dependent:: IBM ESA/390 Dependent Features - -* i386-Dependent:: Intel 80386 and AMD x86-64 Dependent Features - -* i860-Dependent:: Intel 80860 Dependent Features - -* i960-Dependent:: Intel 80960 Dependent Features - -* IA-64-Dependent:: Intel IA-64 Dependent Features - -* IP2K-Dependent:: IP2K Dependent Features - -* M32C-Dependent:: M32C Dependent Features - -* M32R-Dependent:: M32R Dependent Features - -* M68K-Dependent:: M680x0 Dependent Features - -* M68HC11-Dependent:: M68HC11 and 68HC12 Dependent Features - -* MIPS-Dependent:: MIPS Dependent Features - -* MMIX-Dependent:: MMIX Dependent Features - -* MSP430-Dependent:: MSP430 Dependent Features - -* SH-Dependent:: Renesas / SuperH SH Dependent Features -* SH64-Dependent:: SuperH SH64 Dependent Features - -* PDP-11-Dependent:: PDP-11 Dependent Features - -* PJ-Dependent:: picoJava Dependent Features - -* PPC-Dependent:: PowerPC Dependent Features - -* Sparc-Dependent:: SPARC Dependent Features - -* TIC54X-Dependent:: TI TMS320C54x Dependent Features - -* V850-Dependent:: V850 Dependent Features - -* Xtensa-Dependent:: Xtensa Dependent Features - -* Z80-Dependent:: Z80 Dependent Features - -* Z8000-Dependent:: Z8000 Dependent Features - -* Vax-Dependent:: VAX Dependent Features - - -File: as.info, Node: Alpha-Dependent, Next: ARC-Dependent, Up: Machine Dependencies - -8.1 Alpha Dependent Features -============================ - -* Menu: - -* Alpha Notes:: Notes -* Alpha Options:: Options -* Alpha Syntax:: Syntax -* Alpha Floating Point:: Floating Point -* Alpha Directives:: Alpha Machine Directives -* Alpha Opcodes:: Opcodes - - -File: as.info, Node: Alpha Notes, Next: Alpha Options, Up: Alpha-Dependent - -8.1.1 Notes ------------ - -The documentation here is primarily for the ELF object format. `as' -also supports the ECOFF and EVAX formats, but features specific to -these formats are not yet documented. - - -File: as.info, Node: Alpha Options, Next: Alpha Syntax, Prev: Alpha Notes, Up: Alpha-Dependent - -8.1.2 Options -------------- - -`-mCPU' - This option specifies the target processor. If an attempt is made - to assemble an instruction which will not execute on the target - processor, the assembler may either expand the instruction as a - macro or issue an error message. This option is equivalent to the - `.arch' directive. - - The following processor names are recognized: `21064', `21064a', - `21066', `21068', `21164', `21164a', `21164pc', `21264', `21264a', - `21264b', `ev4', `ev5', `lca45', `ev5', `ev56', `pca56', `ev6', - `ev67', `ev68'. The special name `all' may be used to allow the - assembler to accept instructions valid for any Alpha processor. - - In order to support existing practice in OSF/1 with respect to - `.arch', and existing practice within `MILO' (the Linux ARC - bootloader), the numbered processor names (e.g. 21064) enable the - processor-specific PALcode instructions, while the - "electro-vlasic" names (e.g. `ev4') do not. - -`-mdebug' -`-no-mdebug' - Enables or disables the generation of `.mdebug' encapsulation for - stabs directives and procedure descriptors. The default is to - automatically enable `.mdebug' when the first stabs directive is - seen. - -`-relax' - This option forces all relocations to be put into the object file, - instead of saving space and resolving some relocations at assembly - time. Note that this option does not propagate all symbol - arithmetic into the object file, because not all symbol arithmetic - can be represented. However, the option can still be useful in - specific applications. - -`-g' - This option is used when the compiler generates debug information. - When `gcc' is using `mips-tfile' to generate debug information - for ECOFF, local labels must be passed through to the object file. - Otherwise this option has no effect. - -`-GSIZE' - A local common symbol larger than SIZE is placed in `.bss', while - smaller symbols are placed in `.sbss'. - -`-F' -`-32addr' - These options are ignored for backward compatibility. - - -File: as.info, Node: Alpha Syntax, Next: Alpha Floating Point, Prev: Alpha Options, Up: Alpha-Dependent - -8.1.3 Syntax ------------- - -The assembler syntax closely follow the Alpha Reference Manual; -assembler directives and general syntax closely follow the OSF/1 and -OpenVMS syntax, with a few differences for ELF. - -* Menu: - -* Alpha-Chars:: Special Characters -* Alpha-Regs:: Register Names -* Alpha-Relocs:: Relocations - - -File: as.info, Node: Alpha-Chars, Next: Alpha-Regs, Up: Alpha Syntax - -8.1.3.1 Special Characters -.......................... - -`#' is the line comment character. - - `;' can be used instead of a newline to separate statements. - - -File: as.info, Node: Alpha-Regs, Next: Alpha-Relocs, Prev: Alpha-Chars, Up: Alpha Syntax - -8.1.3.2 Register Names -...................... - -The 32 integer registers are referred to as `$N' or `$rN'. In -addition, registers 15, 28, 29, and 30 may be referred to by the -symbols `$fp', `$at', `$gp', and `$sp' respectively. - - The 32 floating-point registers are referred to as `$fN'. - - -File: as.info, Node: Alpha-Relocs, Prev: Alpha-Regs, Up: Alpha Syntax - -8.1.3.3 Relocations -................... - -Some of these relocations are available for ECOFF, but mostly only for -ELF. They are modeled after the relocation format introduced in -Digital Unix 4.0, but there are additions. - - The format is `!TAG' or `!TAG!NUMBER' where TAG is the name of the -relocation. In some cases NUMBER is used to relate specific -instructions. - - The relocation is placed at the end of the instruction like so: - - ldah $0,a($29) !gprelhigh - lda $0,a($0) !gprellow - ldq $1,b($29) !literal!100 - ldl $2,0($1) !lituse_base!100 - -`!literal' -`!literal!N' - Used with an `ldq' instruction to load the address of a symbol - from the GOT. - - A sequence number N is optional, and if present is used to pair - `lituse' relocations with this `literal' relocation. The `lituse' - relocations are used by the linker to optimize the code based on - the final location of the symbol. - - Note that these optimizations are dependent on the data flow of the - program. Therefore, if _any_ `lituse' is paired with a `literal' - relocation, then _all_ uses of the register set by the `literal' - instruction must also be marked with `lituse' relocations. This - is because the original `literal' instruction may be deleted or - transformed into another instruction. - - Also note that there may be a one-to-many relationship between - `literal' and `lituse', but not a many-to-one. That is, if there - are two code paths that load up the same address and feed the - value to a single use, then the use may not use a `lituse' - relocation. - -`!lituse_base!N' - Used with any memory format instruction (e.g. `ldl') to indicate - that the literal is used for an address load. The offset field of - the instruction must be zero. During relaxation, the code may be - altered to use a gp-relative load. - -`!lituse_jsr!N' - Used with a register branch format instruction (e.g. `jsr') to - indicate that the literal is used for a call. During relaxation, - the code may be altered to use a direct branch (e.g. `bsr'). - -`!lituse_jsrdirect!N' - Similar to `lituse_jsr', but also that this call cannot be vectored - through a PLT entry. This is useful for functions with special - calling conventions which do not allow the normal call-clobbered - registers to be clobbered. - -`!lituse_bytoff!N' - Used with a byte mask instruction (e.g. `extbl') to indicate that - only the low 3 bits of the address are relevant. During - relaxation, the code may be altered to use an immediate instead of - a register shift. - -`!lituse_addr!N' - Used with any other instruction to indicate that the original - address is in fact used, and the original `ldq' instruction may - not be altered or deleted. This is useful in conjunction with - `lituse_jsr' to test whether a weak symbol is defined. - - ldq $27,foo($29) !literal!1 - beq $27,is_undef !lituse_addr!1 - jsr $26,($27),foo !lituse_jsr!1 - -`!lituse_tlsgd!N' - Used with a register branch format instruction to indicate that the - literal is the call to `__tls_get_addr' used to compute the - address of the thread-local storage variable whose descriptor was - loaded with `!tlsgd!N'. - -`!lituse_tlsldm!N' - Used with a register branch format instruction to indicate that the - literal is the call to `__tls_get_addr' used to compute the - address of the base of the thread-local storage block for the - current module. The descriptor for the module must have been - loaded with `!tlsldm!N'. - -`!gpdisp!N' - Used with `ldah' and `lda' to load the GP from the current - address, a-la the `ldgp' macro. The source register for the - `ldah' instruction must contain the address of the `ldah' - instruction. There must be exactly one `lda' instruction paired - with the `ldah' instruction, though it may appear anywhere in the - instruction stream. The immediate operands must be zero. - - bsr $26,foo - ldah $29,0($26) !gpdisp!1 - lda $29,0($29) !gpdisp!1 - -`!gprelhigh' - Used with an `ldah' instruction to add the high 16 bits of a - 32-bit displacement from the GP. - -`!gprellow' - Used with any memory format instruction to add the low 16 bits of a - 32-bit displacement from the GP. - -`!gprel' - Used with any memory format instruction to add a 16-bit - displacement from the GP. - -`!samegp' - Used with any branch format instruction to skip the GP load at the - target address. The referenced symbol must have the same GP as the - source object file, and it must be declared to either not use `$27' - or perform a standard GP load in the first two instructions via the - `.prologue' directive. - -`!tlsgd' -`!tlsgd!N' - Used with an `lda' instruction to load the address of a TLS - descriptor for a symbol in the GOT. - - The sequence number N is optional, and if present it used to pair - the descriptor load with both the `literal' loading the address of - the `__tls_get_addr' function and the `lituse_tlsgd' marking the - call to that function. - - For proper relaxation, both the `tlsgd', `literal' and `lituse' - relocations must be in the same extended basic block. That is, - the relocation with the lowest address must be executed first at - runtime. - -`!tlsldm' -`!tlsldm!N' - Used with an `lda' instruction to load the address of a TLS - descriptor for the current module in the GOT. - - Similar in other respects to `tlsgd'. - -`!gotdtprel' - Used with an `ldq' instruction to load the offset of the TLS - symbol within its module's thread-local storage block. Also known - as the dynamic thread pointer offset or dtp-relative offset. - -`!dtprelhi' -`!dtprello' -`!dtprel' - Like `gprel' relocations except they compute dtp-relative offsets. - -`!gottprel' - Used with an `ldq' instruction to load the offset of the TLS - symbol from the thread pointer. Also known as the tp-relative - offset. - -`!tprelhi' -`!tprello' -`!tprel' - Like `gprel' relocations except they compute tp-relative offsets. - - -File: as.info, Node: Alpha Floating Point, Next: Alpha Directives, Prev: Alpha Syntax, Up: Alpha-Dependent - -8.1.4 Floating Point --------------------- - -The Alpha family uses both IEEE and VAX floating-point numbers. - - -File: as.info, Node: Alpha Directives, Next: Alpha Opcodes, Prev: Alpha Floating Point, Up: Alpha-Dependent - -8.1.5 Alpha Assembler Directives --------------------------------- - -`as' for the Alpha supports many additional directives for -compatibility with the native assembler. This section describes them -only briefly. - - These are the additional directives in `as' for the Alpha: - -`.arch CPU' - Specifies the target processor. This is equivalent to the `-mCPU' - command-line option. *Note Options: Alpha Options, for a list of - values for CPU. - -`.ent FUNCTION[, N]' - Mark the beginning of FUNCTION. An optional number may follow for - compatibility with the OSF/1 assembler, but is ignored. When - generating `.mdebug' information, this will create a procedure - descriptor for the function. In ELF, it will mark the symbol as a - function a-la the generic `.type' directive. - -`.end FUNCTION' - Mark the end of FUNCTION. In ELF, it will set the size of the - symbol a-la the generic `.size' directive. - -`.mask MASK, OFFSET' - Indicate which of the integer registers are saved in the current - function's stack frame. MASK is interpreted a bit mask in which - bit N set indicates that register N is saved. The registers are - saved in a block located OFFSET bytes from the "canonical frame - address" (CFA) which is the value of the stack pointer on entry to - the function. The registers are saved sequentially, except that - the return address register (normally `$26') is saved first. - - This and the other directives that describe the stack frame are - currently only used when generating `.mdebug' information. They - may in the future be used to generate DWARF2 `.debug_frame' unwind - information for hand written assembly. - -`.fmask MASK, OFFSET' - Indicate which of the floating-point registers are saved in the - current stack frame. The MASK and OFFSET parameters are - interpreted as with `.mask'. - -`.frame FRAMEREG, FRAMEOFFSET, RETREG[, ARGOFFSET]' - Describes the shape of the stack frame. The frame pointer in use - is FRAMEREG; normally this is either `$fp' or `$sp'. The frame - pointer is FRAMEOFFSET bytes below the CFA. The return address is - initially located in RETREG until it is saved as indicated in - `.mask'. For compatibility with OSF/1 an optional ARGOFFSET - parameter is accepted and ignored. It is believed to indicate the - offset from the CFA to the saved argument registers. - -`.prologue N' - Indicate that the stack frame is set up and all registers have been - spilled. The argument N indicates whether and how the function - uses the incoming "procedure vector" (the address of the called - function) in `$27'. 0 indicates that `$27' is not used; 1 - indicates that the first two instructions of the function use `$27' - to perform a load of the GP register; 2 indicates that `$27' is - used in some non-standard way and so the linker cannot elide the - load of the procedure vector during relaxation. - -`.usepv FUNCTION, WHICH' - Used to indicate the use of the `$27' register, similar to - `.prologue', but without the other semantics of needing to be - inside an open `.ent'/`.end' block. - - The WHICH argument should be either `no', indicating that `$27' is - not used, or `std', indicating that the first two instructions of - the function perform a GP load. - - One might use this directive instead of `.prologue' if you are - also using dwarf2 CFI directives. - -`.gprel32 EXPRESSION' - Computes the difference between the address in EXPRESSION and the - GP for the current object file, and stores it in 4 bytes. In - addition to being smaller than a full 8 byte address, this also - does not require a dynamic relocation when used in a shared - library. - -`.t_floating EXPRESSION' - Stores EXPRESSION as an IEEE double precision value. - -`.s_floating EXPRESSION' - Stores EXPRESSION as an IEEE single precision value. - -`.f_floating EXPRESSION' - Stores EXPRESSION as a VAX F format value. - -`.g_floating EXPRESSION' - Stores EXPRESSION as a VAX G format value. - -`.d_floating EXPRESSION' - Stores EXPRESSION as a VAX D format value. - -`.set FEATURE' - Enables or disables various assembler features. Using the positive - name of the feature enables while using `noFEATURE' disables. - - `at' - Indicates that macro expansions may clobber the "assembler - temporary" (`$at' or `$28') register. Some macros may not be - expanded without this and will generate an error message if - `noat' is in effect. When `at' is in effect, a warning will - be generated if `$at' is used by the programmer. - - `macro' - Enables the expansion of macro instructions. Note that - variants of real instructions, such as `br label' vs `br - $31,label' are considered alternate forms and not macros. - - `move' - `reorder' - `volatile' - These control whether and how the assembler may re-order - instructions. Accepted for compatibility with the OSF/1 - assembler, but `as' does not do instruction scheduling, so - these features are ignored. - - The following directives are recognized for compatibility with the -OSF/1 assembler but are ignored. - - .proc .aproc - .reguse .livereg - .option .aent - .ugen .eflag - .alias .noalias - - -File: as.info, Node: Alpha Opcodes, Prev: Alpha Directives, Up: Alpha-Dependent - -8.1.6 Opcodes -------------- - -For detailed information on the Alpha machine instruction set, see the -Alpha Architecture Handbook -(ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf). - - -File: as.info, Node: ARC-Dependent, Next: ARM-Dependent, Prev: Alpha-Dependent, Up: Machine Dependencies - -8.2 ARC Dependent Features -========================== - -* Menu: - -* ARC Options:: Options -* ARC Syntax:: Syntax -* ARC Floating Point:: Floating Point -* ARC Directives:: ARC Machine Directives -* ARC Opcodes:: Opcodes - - -File: as.info, Node: ARC Options, Next: ARC Syntax, Up: ARC-Dependent - -8.2.1 Options -------------- - -`-marc[5|6|7|8]' - This option selects the core processor variant. Using `-marc' is - the same as `-marc6', which is also the default. - - `arc5' - Base instruction set. - - `arc6' - Jump-and-link (jl) instruction. No requirement of an - instruction between setting flags and conditional jump. For - example: - - mov.f r0,r1 - beq foo - - `arc7' - Break (brk) and sleep (sleep) instructions. - - `arc8' - Software interrupt (swi) instruction. - - - Note: the `.option' directive can to be used to select a core - variant from within assembly code. - -`-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 - - this is the default. - - - -File: as.info, Node: ARC Syntax, Next: ARC Floating Point, Prev: ARC Options, Up: ARC-Dependent - -8.2.2 Syntax ------------- - -* Menu: - -* ARC-Chars:: Special Characters -* ARC-Regs:: Register Names - - -File: as.info, Node: ARC-Chars, Next: ARC-Regs, Up: ARC Syntax - -8.2.2.1 Special Characters -.......................... - -*TODO* - - -File: as.info, Node: ARC-Regs, Prev: ARC-Chars, Up: ARC Syntax - -8.2.2.2 Register Names -...................... - -*TODO* - - -File: as.info, Node: ARC Floating Point, Next: ARC Directives, Prev: ARC Syntax, Up: ARC-Dependent - -8.2.3 Floating Point --------------------- - -The ARC core does not currently have hardware floating point support. -Software floating point support is provided by `GCC' and uses IEEE -floating-point numbers. - - -File: as.info, Node: ARC Directives, Next: ARC Opcodes, Prev: ARC Floating Point, Up: ARC-Dependent - -8.2.4 ARC Machine Directives ----------------------------- - -The ARC version of `as' supports the following additional machine -directives: - -`.2byte EXPRESSIONS' - *TODO* - -`.3byte EXPRESSIONS' - *TODO* - -`.4byte EXPRESSIONS' - *TODO* - -`.extAuxRegister NAME,ADDRESS,MODE' - The ARCtangent A4 has extensible auxiliary register space. The - auxiliary registers can be defined in the assembler source code by - using this directive. The first parameter is the NAME of the new - auxiallry register. The second parameter is the ADDRESS of the - register in the auxiliary register memory map for the variant of - the ARC. The third parameter specifies the MODE in which the - register can be operated is and it can be one of: - - `r (readonly)' - - `w (write only)' - - `r|w (read or write)' - - For example: - - .extAuxRegister mulhi,0x12,w - - This specifies an extension auxiliary register called _mulhi_ - which is at address 0x12 in the memory space and which is only - writable. - -`.extCondCode SUFFIX,VALUE' - The condition codes on the ARCtangent A4 are extensible and can be - specified by means of this assembler directive. They are specified - by the suffix and the value for the condition code. They can be - used to specify extra condition codes with any values. For - example: - - .extCondCode is_busy,0x14 - - add.is_busy r1,r2,r3 - bis_busy _main - -`.extCoreRegister NAME,REGNUM,MODE,SHORTCUT' - Specifies an extension core register NAME for the application. - This allows a register NAME with a valid REGNUM between 0 and 60, - with the following as valid values for MODE - - `_r_ (readonly)' - - `_w_ (write only)' - - `_r|w_ (read or write)' - - The other parameter gives a description of the register having a - SHORTCUT in the pipeline. The valid values are: - - `can_shortcut' - - `cannot_shortcut' - - For example: - - .extCoreRegister mlo,57,r,can_shortcut - - This defines an extension core register mlo with the value 57 which - can shortcut the pipeline. - -`.extInstruction NAME,OPCODE,SUBOPCODE,SUFFIXCLASS,SYNTAXCLASS' - The ARCtangent A4 allows the user to specify extension - instructions. The extension instructions are not macros. The - assembler creates encodings for use of these instructions - according to the specification by the user. The parameters are: - - *NAME - Name of the extension instruction - - *OPCODE - Opcode to be used. (Bits 27:31 in the encoding). Valid values - 0x10-0x1f or 0x03 - - *SUBOPCODE - Subopcode to be used. Valid values are from 0x09-0x3f. - However the correct value also depends on SYNTAXCLASS - - *SUFFIXCLASS - Determines the kinds of suffixes to be allowed. Valid values - are `SUFFIX_NONE', `SUFFIX_COND', `SUFFIX_FLAG' which - indicates the absence or presence of conditional suffixes and - flag setting by the extension instruction. It is also - possible to specify that an instruction sets the flags and is - condtional by using `SUFFIX_CODE' | `SUFFIX_FLAG'. - - *SYNTAXCLASS - Determines the syntax class for the instruction. It can have - the following values: - - ``SYNTAX_2OP':' - 2 Operand Instruction - - ``SYNTAX_3OP':' - 3 Operand Instruction - - In addition there could be modifiers for the syntax class as - described below: - - Syntax Class Modifiers are: - - - `OP1_MUST_BE_IMM': Modifies syntax class SYNTAX_3OP, - specifying that the first operand of a three-operand - instruction must be an immediate (i.e., the result is - discarded). OP1_MUST_BE_IMM is used by bitwise ORing it - with SYNTAX_3OP as given in the example below. This - could usually be used to set the flags using specific - instructions and not retain results. - - - `OP1_IMM_IMPLIED': Modifies syntax class SYNTAX_20P, it - specifies that there is an implied immediate destination - operand which does not appear in the syntax. For - example, if the source code contains an instruction like: - - inst r1,r2 - - it really means that the first argument is an implied - immediate (that is, the result is discarded). This is - the same as though the source code were: inst 0,r1,r2. - You use OP1_IMM_IMPLIED by bitwise ORing it with - SYNTAX_20P. - - - For example, defining 64-bit multiplier with immediate operands: - - .extInstruction mp64,0x14,0x0,SUFFIX_COND | SUFFIX_FLAG , - SYNTAX_3OP|OP1_MUST_BE_IMM - - The above specifies an extension instruction called mp64 which has - 3 operands, sets the flags, can be used with a condition code, for - which the first operand is an immediate. (Equivalent to - discarding the result of the operation). - - .extInstruction mul64,0x14,0x00,SUFFIX_COND, SYNTAX_2OP|OP1_IMM_IMPLIED - - This describes a 2 operand instruction with an implicit first - immediate operand. The result of this operation would be - discarded. - -`.half EXPRESSIONS' - *TODO* - -`.long EXPRESSIONS' - *TODO* - -`.option ARC|ARC5|ARC6|ARC7|ARC8' - The `.option' directive must be followed by the desired core - version. Again `arc' is an alias for `arc6'. - - Note: the `.option' directive overrides the command line option - `-marc'; a warning is emitted when the version is not consistent - between the two - even for the implicit default core version - (arc6). - -`.short EXPRESSIONS' - *TODO* - -`.word EXPRESSIONS' - *TODO* - - - -File: as.info, Node: ARC Opcodes, Prev: ARC Directives, Up: ARC-Dependent - -8.2.5 Opcodes -------------- - -For information on the ARC instruction set, see `ARC Programmers -Reference Manual', ARC International (www.arc.com) - - -File: as.info, Node: ARM-Dependent, Next: AVR-Dependent, Prev: ARC-Dependent, Up: Machine Dependencies - -8.3 ARM Dependent Features -========================== - -* Menu: - -* ARM Options:: Options -* ARM Syntax:: Syntax -* ARM Floating Point:: Floating Point -* ARM Directives:: ARM Machine Directives -* ARM Opcodes:: Opcodes -* ARM Mapping Symbols:: Mapping Symbols - - -File: as.info, Node: ARM Options, Next: ARM Syntax, Up: ARM-Dependent - -8.3.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). - - - -File: as.info, Node: ARM Syntax, Next: ARM Floating Point, Prev: ARM Options, Up: ARM-Dependent - -8.3.2 Syntax ------------- - -* Menu: - -* ARM-Chars:: Special Characters -* ARM-Regs:: Register Names -* ARM-Relocations:: Relocations - - -File: as.info, Node: ARM-Chars, Next: ARM-Regs, Up: ARM Syntax - -8.3.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. - - -File: as.info, Node: ARM-Regs, Next: ARM-Relocations, Prev: ARM-Chars, Up: ARM Syntax - -8.3.2.2 Register Names -...................... - -*TODO* Explain about ARM register naming, and the predefined names. - - -File: as.info, Node: ARM Floating Point, Next: ARM Directives, Prev: ARM Syntax, Up: ARM-Dependent - -8.3.3 Floating Point --------------------- - -The ARM family uses IEEE floating-point numbers. - - -File: as.info, Node: ARM-Relocations, Prev: ARM-Regs, Up: ARM Syntax - -8.3.3.1 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 - - -File: as.info, Node: ARM Directives, Next: ARM Opcodes, Prev: ARM Floating Point, Up: ARM-Dependent - -8.3.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. - - - -File: as.info, Node: ARM Opcodes, Next: ARM Mapping Symbols, Prev: ARM Directives, Up: ARM-Dependent - -8.3.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