| This is as.info, produced by makeinfo version 5.2 from as.texinfo. |
| |
| This file documents the GNU Assembler "as". |
| |
| Copyright (C) 1991-2014 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.3 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". |
| |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * As: (as). The GNU assembler. |
| * Gas: (as). The GNU assembler. |
| END-INFO-DIR-ENTRY |
| |
| |
| 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.25. |
| |
| 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 |
| * Object Attributes:: Object Attributes |
| * 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[cdghlns][=FILE]] [-alternate] [-D] |
| [-compress-debug-sections] [-nocompress-debug-sections] |
| [-debug-prefix-map OLD=NEW] |
| [-defsym SYM=VAL] [-f] [-g] [-gstabs] |
| [-gstabs+] [-gdwarf-2] [-gdwarf-sections] |
| [-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] |
| [-sectname-subst] [-size-check=[error|warning]] |
| [-target-help] [TARGET-OPTIONS] |
| [-|FILES ...] |
| |
| _Target AArch64 options:_ |
| [-EB|-EL] |
| [-mabi=ABI] |
| |
| _Target Alpha options:_ |
| [-mCPU] |
| [-mdebug | -no-mdebug] |
| [-replace | -noreplace] |
| [-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 Blackfin options:_ |
| [-mcpu=PROCESSOR[-SIREVISION]] |
| [-mfdpic] |
| [-mno-fdpic] |
| [-mnopic] |
| |
| _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 EPIPHANY options:_ |
| [-mepiphany|-mepiphany16] |
| |
| _Target H8/300 options:_ |
| [-h-tick-hex] |
| |
| _Target i386 options:_ |
| [-32|-x32|-64] [-n] |
| [-march=CPU[+EXTENSION...]] [-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] [-relax] [-h-tick-hex] |
| |
| _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|-mm9s12x|-mm9s12xg] |
| [-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 Meta options:_ |
| [-mcpu=CPU] [-mfpu=CPU] [-mdsp=CPU] |
| _Target MICROBLAZE options:_ |
| |
| _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] |
| [-mfp64] [-mgp64] [-mfpxx] |
| [-modd-spreg] [-mno-odd-spreg] |
| [-march=CPU] [-mtune=CPU] [-mips1] [-mips2] |
| [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2] |
| [-mips32r3] [-mips32r5] [-mips32r6] [-mips64] [-mips64r2] |
| [-mips64r3] [-mips64r5] [-mips64r6] |
| [-construct-floats] [-no-construct-floats] |
| [-mnan=ENCODING] |
| [-trap] [-no-break] [-break] [-no-trap] |
| [-mips16] [-no-mips16] |
| [-mmicromips] [-mno-micromips] |
| [-msmartmips] [-mno-smartmips] |
| [-mips3d] [-no-mips3d] |
| [-mdmx] [-no-mdmx] |
| [-mdsp] [-mno-dsp] |
| [-mdspr2] [-mno-dspr2] |
| [-mmsa] [-mno-msa] |
| [-mxpa] [-mno-xpa] |
| [-mmt] [-mno-mt] |
| [-mmcu] [-mno-mcu] |
| [-minsn32] [-mno-insn32] |
| [-mfix7000] [-mno-fix7000] |
| [-mfix-rm7000] [-mno-fix-rm7000] |
| [-mfix-vr4120] [-mno-fix-vr4120] |
| [-mfix-vr4130] [-mno-fix-vr4130] |
| [-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 Nios II options:_ |
| [-relax-all] [-relax-section] [-no-relax] |
| [-EB] [-EL] |
| |
| _Target NDS32 options:_ |
| [-EL] [-EB] [-O] [-Os] [-mcpu=CPU] |
| [-misa=ISA] [-mabi=ABI] [-mall-ext] |
| [-m[no-]16-bit] [-m[no-]perf-ext] [-m[no-]perf2-ext] |
| [-m[no-]string-ext] [-m[no-]dsp-ext] [-m[no-]mac] [-m[no-]div] |
| [-m[no-]audio-isa-ext] [-m[no-]fpu-sp-ext] [-m[no-]fpu-dp-ext] |
| [-m[no-]fpu-fma] [-mfpu-freg=FREG] [-mreduced-regs] |
| [-mfull-regs] [-m[no-]dx-regs] [-mpic] [-mno-relax] |
| [-mb2bb] |
| |
| _Target PDP11 options:_ |
| [-mpic|-mno-pic] [-mall] [-mno-extensions] |
| [-mEXTENSION|-mno-EXTENSION] |
| [-mCPU] [-mMACHINE] |
| |
| _Target picoJava options:_ |
| [-mb|-me] |
| |
| _Target PowerPC options:_ |
| [-a32|-a64] |
| [-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604|-m403|-m405| |
| -m440|-m464|-m476|-m7400|-m7410|-m7450|-m7455|-m750cl|-mppc64| |
| -m620|-me500|-e500x2|-me500mc|-me500mc64|-me5500|-me6500|-mppc64bridge| |
| -mbooke|-mpower4|-mpwr4|-mpower5|-mpwr5|-mpwr5x|-mpower6|-mpwr6| |
| -mpower7|-mpwr7|-mpower8|-mpwr8|-ma2|-mcell|-mspe|-mtitan|-me300|-mcom] |
| [-many] [-maltivec|-mvsx|-mhtm|-mvle] |
| [-mregnames|-mno-regnames] |
| [-mrelocatable|-mrelocatable-lib|-K PIC] [-memb] |
| [-mlittle|-mlittle-endian|-le|-mbig|-mbig-endian|-be] |
| [-msolaris|-mno-solaris] |
| [-nops=COUNT] |
| |
| _Target RL78 options:_ |
| [-mg10] |
| [-m32bit-doubles|-m64bit-doubles] |
| |
| _Target RX options:_ |
| [-mlittle-endian|-mbig-endian] |
| [-m32bit-doubles|-m64bit-doubles] |
| [-muse-conventional-section-names] |
| [-msmall-data-limit] |
| [-mpid] |
| [-mrelax] |
| [-mint-register=NUMBER] |
| [-mgcc-abi|-mrx-abi] |
| |
| _Target s390 options:_ |
| [-m31|-m64] [-mesa|-mzarch] [-march=CPU] |
| [-mregnames|-mno-regnames] |
| [-mwarn-areg-zero] |
| |
| _Target SCORE options:_ |
| [-EB][-EL][-FIXDD][-NWARN] |
| [-SCORE5][-SCORE5U][-SCORE7][-SCORE3] |
| [-march=score7][-march=score3] |
| [-USE_R1][-KPIC][-O0][-G NUM][-V] |
| |
| _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 <FILENAME>|-me <FILENAME>] |
| |
| |
| _Target TIC6X options:_ |
| [-march=ARCH] [-mbig-endian|-mlittle-endian] |
| [-mdsbt|-mno-dsbt] [-mpid=no|-mpid=near|-mpid=far] |
| [-mpic|-mno-pic] |
| |
| _Target TILE-Gx options:_ |
| [-m32|-m64][-EB][-EL] |
| |
| |
| _Target Xtensa options:_ |
| [-[no-]text-section-literals] [-[no-]absolute-literals] |
| [-[no-]target-align] [-[no-]longcalls] |
| [-[no-]transform] |
| [-rename-section OLDNAME=NEWNAME] |
| [-[no-]trampolines] |
| |
| |
| _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] |
| |
| |
| |
| '@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[cdghlmns]' |
| Turn on listings, in any of a variety of ways: |
| |
| '-ac' |
| omit false conditionals |
| |
| '-ad' |
| omit debugging directives |
| |
| '-ag' |
| include general information, like as version and options |
| passed |
| |
| '-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. |
| |
| '--compress-debug-sections' |
| Compress DWARF debug sections using zlib. The debug sections are |
| renamed to begin with '.zdebug', and the resulting object file may |
| not be compatible with older linkers and object file utilities. |
| |
| '--nocompress-debug-sections' |
| Do not compress DWARF debug sections. This is the default. |
| |
| '-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. |
| |
| '--gdwarf-sections' |
| Instead of creating a .debug_line section, create a series of |
| .debug_line.FOO sections where FOO is the name of the corresponding |
| code section. For example a code section called .TEXT.FUNC will |
| have its dwarf line number information placed into a section called |
| .DEBUG_LINE.TEXT.FUNC. If the code section is just called .TEXT |
| then debug line section will still be called just .DEBUG_LINE |
| without any suffix. |
| |
| '--size-check=error' |
| '--size-check=warning' |
| Issue an error or warning for invalid ELF .size directive. |
| |
| '--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. |
| |
| '--sectname-subst' |
| Honor substitution sequences in section names. *Note '.section |
| NAME': Section Name Substitutions. |
| |
| '--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. |
| |
| *Note AArch64 Options::, for the options available when as is |
| configured for the 64-bit mode of the ARM Architecture (AArch64). |
| |
| *Note Alpha Options::, for the options available when as is |
| configured for an Alpha processor. |
| |
| 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. |
| '-mccs' |
| Turns on CodeComposer Studio assembly syntax compatibility mode. |
| '-k' |
| Specify that PIC code has been generated. |
| |
| *Note Blackfin Options::, for the options available when as is |
| configured for the Blackfin processor family. |
| |
| 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 |
| Adapteva EPIPHANY series. |
| |
| *Note Epiphany Options::, for the options available when as is |
| configured for an Epiphany processor. |
| |
| *Note i386-Options::, for the options available when as is configured |
| for an i386 processor. |
| |
| 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). |
| |
| '-relax' |
| Enable support for link-time relaxations. |
| |
| '-h-tick-hex' |
| Support H'00 style hex constants in addition to 0x00 style. |
| |
| 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. |
| |
| *Note Nios II Options::, for the options available when as is |
| configured for an Altera Nios II processor. |
| |
| 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 | -mm9s12x | -mm9s12xg' |
| Specify what processor is the target. The default is defined by |
| the configuration option when building the assembler. |
| |
| '--xgate-ramoffset' |
| Instruct the linker to offset RAM addresses from S12X address space |
| into XGATE address space. |
| |
| '-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' |
| '-mips32r3' |
| '-mips32r5' |
| '-mips32r6' |
| '-mips64' |
| '-mips64r2' |
| '-mips64r3' |
| '-mips64r5' |
| '-mips64r6' |
| 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', '-mips32r3', '-mips32r5', '-mips32r6', '-mips64', |
| '-mips64r2', '-mips64r3', '-mips64r5', and '-mips64r6' correspond |
| to generic MIPS V, MIPS32, MIPS32 Release 2, MIPS32 Release 3, |
| MIPS32 Release 5, MIPS32 Release 6, MIPS64, MIPS64 Release 2, |
| MIPS64 Release 3, MIPS64 Release 5, and MIPS64 Release 6 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. |
| |
| '-mfix-rm7000' |
| '-mno-fix-rm7000' |
| Cause nops to be inserted if a dmult or dmultu instruction is |
| followed by a load instruction. |
| |
| '-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. |
| |
| '-mgp64' |
| '-mfp64' |
| The register sizes are normally inferred from the ISA and ABI, but |
| these flags force a certain group of registers to be treated as 64 |
| bits wide at all times. '-mgp64' controls the size of |
| general-purpose registers and '-mfp64' controls the size of |
| floating-point registers. |
| |
| '-mfpxx' |
| The register sizes are normally inferred from the ISA and ABI, but |
| using this flag in combination with '-mabi=32' enables an ABI |
| variant which will operate correctly with floating-point registers |
| which are 32 or 64 bits wide. |
| |
| '-modd-spreg' |
| '-mno-odd-spreg' |
| Enable use of floating-point operations on odd-numbered |
| single-precision registers when supported by the ISA. '-mfpxx' |
| implies '-mno-odd-spreg', otherwise the default is '-modd-spreg'. |
| |
| '-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. |
| |
| '-mmicromips' |
| '-mno-micromips' |
| Generate code for the microMIPS processor. This is equivalent to |
| putting '.set micromips' at the start of the assembly file. |
| '-mno-micromips' turns off this option. This is equivalent to |
| putting '.set nomicromips' at the start of the assembly file. |
| |
| '-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. |
| |
| '-mmsa' |
| '-mno-msa' |
| Generate code for the MIPS SIMD Architecture Extension. This tells |
| the assembler to accept MSA instructions. '-mno-msa' turns off |
| this option. |
| |
| '-mxpa' |
| '-mno-xpa' |
| Generate code for the MIPS eXtended Physical Address (XPA) |
| Extension. This tells the assembler to accept XPA instructions. |
| '-mno-xpa' 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. |
| |
| '-mmcu' |
| '-mno-mcu' |
| Generate code for the MCU Application Specific Extension. This |
| tells the assembler to accept MCU instructions. '-mno-mcu' turns |
| off this option. |
| |
| '-minsn32' |
| '-mno-insn32' |
| Only use 32-bit instruction encodings when generating code for the |
| microMIPS processor. This option inhibits the use of any 16-bit |
| instructions. This is equivalent to putting '.set insn32' at the |
| start of the assembly file. '-mno-insn32' turns off this option. |
| This is equivalent to putting '.set noinsn32' at the start of the |
| assembly file. By default '-mno-insn32' is selected, allowing all |
| instructions to be used. |
| |
| '--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. |
| |
| '--relax-branch' |
| '--no-relax-branch' |
| The '--relax-branch' option enables the relaxation of out-of-range |
| branches. By default '--no-relax-branch' is selected, causing any |
| out-of-range branches to produce an error. |
| |
| '-mnan=ENCODING' |
| Select between the IEEE 754-2008 ('-mnan=2008') or the legacy |
| ('-mnan=legacy') NaN encoding format. The latter is the default. |
| |
| '--emulation=NAME' |
| This option was formerly used to switch between ELF and ECOFF |
| output on targets like IRIX 5 that supported both. MIPS ECOFF |
| support was removed in GAS 2.24, so the option now serves little |
| purpose. It is retained for backwards compatibility. |
| |
| The available configuration names are: 'mipself', 'mipslelf' and |
| 'mipsbelf'. Choosing 'mipself' now has no effect, since the output |
| is always ELF. 'mipslelf' and 'mipsbelf' select little- and |
| big-endian output respectively, but '-EL' and '-EB' are now the |
| preferred options instead. |
| |
| '-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. |
| |
| *Note Meta Options::, for the options available when as is configured |
| for a Meta processor. |
| |
| See the info pages for documentation of the MMIX-specific options. |
| |
| *Note NDS32 Options::, for the options available when as is |
| configured for a NDS32 processor. |
| |
| *Note PowerPC-Opts::, for the options available when as is configured |
| for a PowerPC processor. |
| |
| See the info pages for documentation of the RX-specific options. |
| |
| The following options are available when as is configured for the |
| s390 processor family. |
| |
| '-m31' |
| '-m64' |
| Select the word size, either 31/32 bits or 64 bits. |
| '-mesa' |
| '-mzarch' |
| Select the architecture mode, either the Enterprise System |
| Architecture (esa) or the z/Architecture mode (zarch). |
| '-march=PROCESSOR' |
| Specify which s390 processor variant is the target, 'g6', 'g6', |
| 'z900', 'z990', 'z9-109', 'z9-ec', 'z10', 'z196', or 'zEC12'. |
| '-mregnames' |
| '-mno-regnames' |
| Allow or disallow symbolic names for registers. |
| '-mwarn-areg-zero' |
| Warn whenever the operand for a base or index register has been |
| specified but evaluates to zero. |
| |
| *Note TIC6X Options::, for the options available when as is |
| configured for a TMS320C6000 processor. |
| |
| *Note TILE-Gx Options::, for the options available when as is |
| configured for a TILE-Gx processor. |
| |
| *Note Xtensa Options::, for the options available when as is |
| configured for an Xtensa processor. |
| |
| 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 <ctl-D> to tell 'as' there is no more program to assemble. |
| |
| Use '--' if you need to explicitly name the standard input file in |
| your command line. |
| |
| If the source is empty, 'as' produces a small, empty object file. |
| |
| Filenames and Line-numbers |
| -------------------------- |
| |
| There are two ways of locating a line in the input file (or files) and |
| either may be used in reporting error messages. One way refers to a |
| line number in a physical file; the other refers to a line number in a |
| "logical" file. *Note Error and Warning Messages: Errors. |
| |
| "Physical files" are those files named in the command line given to |
| 'as'. |
| |
| "Logical files" are simply names declared explicitly by assembler |
| directives; they bear no relation to physical files. Logical file names |
| help error messages reflect the original source file, when 'as' source |
| is itself synthesized from other files. 'as' understands the '#' |
| directives emitted by the 'gcc' preprocessor. See also *note '.file': |
| File. |
| |
| |
| 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[cdghlns] 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[cdghlns]' |
| ================================== |
| |
| 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 '-ag' option to print a first section with general assembly |
| information, like as version, switches passed, or time stamp. |
| |
| 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 a "line comment" character up to the next newline is |
| considered a comment and is ignored. The line comment character is |
| target specific, and some targets multiple comment characters. Some |
| targets also have line comment characters that only work if they are the |
| first character on a line. Some targets use a sequence of two |
| characters to introduce a line comment. Some targets can also change |
| their line comment characters depending upon command line options that |
| have been used. For more details see the _Syntax_ section in the |
| documentation for individual targets. |
| |
| If the line comment character is the hash sign ('#') then it still |
| has the special ability to enable and disable preprocessing (*note |
| Preprocessing::) and to specify logical line numbers: |
| |
| 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. Multibyte characters are supported. 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 a "line separator |
| character". The line separator character is target specific and |
| described in the _Syntax_ section of each target's documentation. Not |
| all targets support a line separator character. The newline or line |
| separator character is considered to be 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. |
| |
| Blackfin does not support symbol assignment with '='. |
| |
| |
| 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'. |
| |
| Multibyte characters are supported. To generate a symbol name |
| containing multibyte characters enclose it within double quotes and use |
| escape codes. cf *Note Strings::. Generating a multibyte symbol name |
| from a label is not currently supported. |
| |
| 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 they have a dollar sign suffix to their numeric |
| value, e.g., '55$:'. |
| |
| They can also be distinguished from ordinary local labels by their |
| transformed names which use ASCII character '\001' (control-A) as the |
| magic character to distinguish them from ordinary labels. For example, |
| the fifth definition of '6$' may be named '.L6'C-A'5'. |
| |
| |
| 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: Object Attributes, 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' |
| * Bundle directives:: '.bundle_align_mode ABS-EXPR', '.bundle_lock', '.bundle_unlock' |
| * Byte:: '.byte EXPRESSIONS' |
| * CFI directives:: '.cfi_startproc [simple]', '.cfi_endproc', etc. |
| * Comm:: '.comm SYMBOL , LENGTH ' |
| * 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' |
| * Fill:: '.fill REPEAT , SIZE , VALUE' |
| * Float:: '.float FLONUMS' |
| * Func:: '.func' |
| * Global:: '.global SYMBOL', '.globl SYMBOL' |
| * Gnu_attribute:: '.gnu_attribute TAG,VALUE' |
| * 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' |
| * Loc:: '.loc FILENO LINENO' |
| * Loc_mark_labels:: '.loc_mark_labels ENABLE' |
| * Local:: '.local NAMES' |
| |
| * Long:: '.long EXPRESSIONS' |
| |
| * Macro:: '.macro NAME ARGS'... |
| * MRI:: '.mri VAL' |
| * Noaltmacro:: '.noaltmacro' |
| * Nolist:: '.nolist' |
| * Octa:: '.octa BIGNUMS' |
| * Offset:: '.offset LOC' |
| * 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[, FLAGS]' |
| |
| * 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"', '.string8 "STR"', '.string16 "STR"', '.string32 "STR"', '.string64 "STR"' |
| * Struct:: '.struct EXPRESSION' |
| * SubSection:: '.subsection' |
| * Symver:: '.symver NAME,NAME2@NODENAME' |
| |
| * Tag:: '.tag STRUCTNAME' |
| |
| * Text:: '.text SUBSECTION' |
| * Title:: '.title "HEADING"' |
| * Type:: '.type <INT | NAME , TYPE DESCRIPTION>' |
| |
| * 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, or1k, |
| 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 ppc, i386 using a.out format, 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: Altmacro, Next: Ascii, Prev: Align, Up: Pseudo Ops |
| |
| 7.4 '.altmacro' |
| =============== |
| |
| Enable alternate macro mode, enabling: |
| |
| 'LOCAL NAME [ , ... ]' |
| One additional directive, 'LOCAL', is available. It is used to |
| generate a string replacement for each of the NAME arguments, and |
| replace any instances of NAME in each macro expansion. The |
| replacement string is unique in the assembly, and different for |
| each separate macro expansion. 'LOCAL' allows you to write macros |
| that define symbols, without fear of conflict between separate |
| macro expansions. |
| |
| 'String delimiters' |
| You can write strings delimited in these other ways besides |
| '"STRING"': |
| |
| ''STRING'' |
| You can delimit strings with single-quote characters. |
| |
| '<STRING>' |
| You can delimit strings with matching angle brackets. |
| |
| 'single-character string escape' |
| To include any single character literally in a string (even if the |
| character would otherwise have some special meaning), you can |
| prefix the character with '!' (an exclamation mark). For example, |
| you can write '<4.3 !> 5.4!!>' to get the literal text '4.3 > |
| 5.4!'. |
| |
| 'Expression results as strings' |
| You can write '%EXPR' to evaluate the expression EXPR and use the |
| result as a string. |
| |
| |
| File: as.info, Node: Ascii, Next: Asciz, Prev: Altmacro, Up: Pseudo Ops |
| |
| 7.5 '.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.6 '.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: Bundle directives, Prev: Asciz, Up: Pseudo Ops |
| |
| 7.7 '.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: Bundle directives, Next: Byte, Prev: Balign, Up: Pseudo Ops |
| |
| 7.8 '.bundle_align_mode ABS-EXPR' |
| ================================= |
| |
| '.bundle_align_mode' enables or disables "aligned instruction bundle" |
| mode. In this mode, sequences of adjacent instructions are grouped into |
| fixed-sized "bundles". If the argument is zero, this mode is disabled |
| (which is the default state). If the argument it not zero, it gives the |
| size of an instruction bundle as a power of two (as for the '.p2align' |
| directive, *note P2align::). |
| |
| For some targets, it's an ABI requirement that no instruction may |
| span a certain aligned boundary. A "bundle" is simply a sequence of |
| instructions that starts on an aligned boundary. For example, if |
| ABS-EXPR is '5' then the bundle size is 32, so each aligned chunk of 32 |
| bytes is a bundle. When aligned instruction bundle mode is in effect, |
| no single instruction may span a boundary between bundles. If an |
| instruction would start too close to the end of a bundle for the length |
| of that particular instruction to fit within the bundle, then the space |
| at the end of that bundle is filled with no-op instructions so the |
| instruction starts in the next bundle. As a corollary, it's an error if |
| any single instruction's encoding is longer than the bundle size. |
| |
| 7.9 '.bundle_lock' and '.bundle_unlock' |
| ======================================= |
| |
| The '.bundle_lock' and directive '.bundle_unlock' directives allow |
| explicit control over instruction bundle padding. These directives are |
| only valid when '.bundle_align_mode' has been used to enable aligned |
| instruction bundle mode. It's an error if they appear when |
| '.bundle_align_mode' has not been used at all, or when the last |
| directive was '.bundle_align_mode 0'. |
| |
| For some targets, it's an ABI requirement that certain instructions |
| may appear only as part of specified permissible sequences of multiple |
| instructions, all within the same bundle. A pair of '.bundle_lock' and |
| '.bundle_unlock' directives define a "bundle-locked" instruction |
| sequence. For purposes of aligned instruction bundle mode, a sequence |
| starting with '.bundle_lock' and ending with '.bundle_unlock' is treated |
| as a single instruction. That is, the entire sequence must fit into a |
| single bundle and may not span a bundle boundary. If necessary, no-op |
| instructions will be inserted before the first instruction of the |
| sequence so that the whole sequence starts on an aligned bundle |
| boundary. It's an error if the sequence is longer than the bundle size. |
| |
| For convenience when using '.bundle_lock' and '.bundle_unlock' inside |
| assembler macros (*note Macro::), bundle-locked sequences may be nested. |
| That is, a second '.bundle_lock' directive before the next |
| '.bundle_unlock' directive has no effect except that it must be matched |
| by another closing '.bundle_unlock' so that there is the same number of |
| '.bundle_lock' and '.bundle_unlock' directives. |
| |
| |
| File: as.info, Node: Byte, Next: CFI directives, Prev: Bundle directives, Up: Pseudo Ops |
| |
| 7.10 '.byte EXPRESSIONS' |
| ======================== |
| |
| '.byte' expects zero or more expressions, separated by commas. Each |
| expression is assembled into the next byte. |
| |
| |
| File: as.info, Node: CFI directives, Next: Comm, Prev: Byte, Up: Pseudo Ops |
| |
| 7.11 '.cfi_sections SECTION_LIST' |
| ================================= |
| |
| '.cfi_sections' may be used to specify whether CFI directives should |
| emit '.eh_frame' section and/or '.debug_frame' section. If SECTION_LIST |
| is '.eh_frame', '.eh_frame' is emitted, if SECTION_LIST is |
| '.debug_frame', '.debug_frame' is emitted. To emit both use '.eh_frame, |
| .debug_frame'. The default if this directive is not used is |
| '.cfi_sections .eh_frame'. |
| |
| 7.12 '.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.13 '.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.14 '.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.15 '.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.16 '.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.17 '.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.18 '.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.19 '.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.20 '.cfi_offset REGISTER, OFFSET' |
| =================================== |
| |
| Previous value of REGISTER is saved at offset OFFSET from CFA. |
| |
| 7.21 '.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.22 '.cfi_register REGISTER1, REGISTER2' |
| ========================================= |
| |
| Previous value of REGISTER1 is saved in register REGISTER2. |
| |
| 7.23 '.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.24 '.cfi_undefined REGISTER' |
| ============================== |
| |
| From now on the previous value of REGISTER can't be restored anymore. |
| |
| 7.25 '.cfi_same_value REGISTER' |
| =============================== |
| |
| Current value of REGISTER is the same like in the previous frame, i.e. |
| no restoration needed. |
| |
| 7.26 '.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.27 '.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.28 '.cfi_signal_frame' |
| ======================== |
| |
| Mark current function as signal trampoline. |
| |
| 7.29 '.cfi_window_save' |
| ======================= |
| |
| SPARC register window has been saved. |
| |
| 7.30 '.cfi_escape' EXPRESSION[, ...] |
| ==================================== |
| |
| Allows the user to add arbitrary bytes to the unwind info. One might |
| use this to add OS-specific CFI opcodes, or generic CFI opcodes that GAS |
| does not yet support. |
| |
| 7.31 '.cfi_val_encoded_addr REGISTER, ENCODING, LABEL' |
| ====================================================== |
| |
| The current value of REGISTER is LABEL. The value of LABEL will be |
| encoded in the output file according to ENCODING; see the description of |
| '.cfi_personality' for details on this encoding. |
| |
| The usefulness of equating a register to a fixed label is probably |
| limited to the return address register. Here, it can be useful to mark |
| a code segment that has only one return address which is reached by a |
| direct branch and no copy of the return address exists in memory or |
| another register. |
| |
| |
| File: as.info, Node: Comm, Next: Data, Prev: CFI directives, Up: Pseudo Ops |
| |
| 7.32 '.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 or (as a GNU extension) PE, the '.comm' directive |
| takes an optional third argument. This is the desired alignment of the |
| symbol, specified for ELF as a byte boundary (for example, an alignment |
| of 16 means that the least significant 4 bits of the address should be |
| zero), and for PE as a power of two (for example, an alignment of 5 |
| means aligned to a 32-byte boundary). 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 on ELF, or the default section |
| alignment of 4 on PE(1). |
| |
| The syntax for '.comm' differs slightly on the HPPA. The syntax is |
| 'SYMBOL .comm, LENGTH'; SYMBOL is optional. |
| |
| ---------- Footnotes ---------- |
| |
| (1) This is not the same as the executable image file alignment |
| controlled by 'ld''s '--section-alignment' option; image file sections |
| in PE are aligned to multiples of 4096, which is far too large an |
| alignment for ordinary variables. It is rather the default alignment |
| for (non-debug) sections within object ('*.o') files, which are less |
| strictly aligned. |
| |
| |
| File: as.info, Node: Data, Next: Def, Prev: Comm, Up: Pseudo Ops |
| |
| 7.33 '.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.34 '.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.35 '.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.36 '.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.37 '.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.38 '.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.39 '.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.40 '.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.41 '.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.42 '.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.43 '.endfunc' |
| =============== |
| |
| '.endfunc' marks the end of a function specified with '.func'. |
| |
| |
| File: as.info, Node: Endif, Next: Equ, Prev: Endfunc, Up: Pseudo Ops |
| |
| 7.44 '.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.45 '.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.46 '.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.47 '.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.48 '.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.49 '.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.50 '.exitm' |
| ============= |
| |
| Exit early from the current macro definition. *Note Macro::. |
| |
| |
| File: as.info, Node: Extern, Next: Fail, Prev: Exitm, Up: Pseudo Ops |
| |
| 7.51 '.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.52 '.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.53 '.file' |
| ============ |
| |
| There are two different versions of the '.file' directive. Targets that |
| support DWARF2 line number information use the DWARF2 version of |
| '.file'. Other targets use the default version. |
| |
| Default Version |
| --------------- |
| |
| This version of the '.file' directive tells 'as' that we are about to |
| start a new logical file. The syntax is: |
| |
| .file STRING |
| |
| 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. |
| |
| DWARF2 Version |
| -------------- |
| |
| When emitting DWARF2 line number information, '.file' assigns filenames |
| to the '.debug_line' file name table. The syntax is: |
| |
| .file FILENO FILENAME |
| |
| 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. |
| |
| |
| File: as.info, Node: Fill, Next: Float, Prev: File, Up: Pseudo Ops |
| |
| 7.54 '.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.55 '.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.56 '.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: Gnu_attribute, Prev: Func, Up: Pseudo Ops |
| |
| 7.57 '.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: Gnu_attribute, Next: Hidden, Prev: Global, Up: Pseudo Ops |
| |
| 7.58 '.gnu_attribute TAG,VALUE' |
| =============================== |
| |
| Record a GNU object attribute for this file. *Note Object Attributes::. |
| |
| |
| File: as.info, Node: Hidden, Next: hword, Prev: Gnu_attribute, Up: Pseudo Ops |
| |
| 7.59 '.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.60 '.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.61 '.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.62 '.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.63 '.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.64 '.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.65 '.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.66 '.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.67 '.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.68 '.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.69 '.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.70 '.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.71 '.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.72 '.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: List, Next: Ln, Prev: Linkonce, Up: Pseudo Ops |
| |
| 7.73 '.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: Ln, Next: Loc, Prev: List, Up: Pseudo Ops |
| |
| 7.74 '.ln LINE-NUMBER' |
| ====================== |
| |
| '.ln' is a synonym for '.line'. |
| |
| |
| File: as.info, Node: Loc, Next: Loc_mark_labels, Prev: Ln, Up: Pseudo Ops |
| |
| 7.75 '.loc FILENO LINENO [COLUMN] [OPTIONS]' |
| ============================================ |
| |
| When emitting DWARF2 line number information, the '.loc' directive will |
| add a 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. |
| |
| 'discriminator VALUE' |
| This directive will set the 'discriminator' register in the |
| '.debug_line' state machine to VALUE, which must be an unsigned |
| integer. |
| |
| |
| File: as.info, Node: Loc_mark_labels, Next: Local, Prev: Loc, Up: Pseudo Ops |
| |
| 7.76 '.loc_mark_labels ENABLE' |
| ============================== |
| |
| When emitting DWARF2 line number information, the '.loc_mark_labels' |
| 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: Local, Next: Long, Prev: Loc_mark_labels, Up: Pseudo Ops |
| |
| 7.77 '.local NAMES' |
| =================== |
| |
| This directive, which is available for ELF targets, marks each symbol in |
| the comma-separated list of 'names' as a local symbol so that it will |
| not be externally visible. If the symbols do not already exist, they |
| will be created. |
| |
| For targets where the '.lcomm' directive (*note Lcomm::) does not |
| accept an alignment argument, which is the case for most ELF targets, |
| the '.local' directive can be used in combination with '.comm' (*note |
| Comm::) to define aligned local common data. |
| |
| |
| File: as.info, Node: Long, Next: Macro, Prev: Local, Up: Pseudo Ops |
| |
| 7.78 '.long EXPRESSIONS' |
| ======================== |
| |
| '.long' is the same as '.int'. *Note '.int': Int. |
| |
| |
| File: as.info, Node: Macro, Next: MRI, Prev: Long, Up: Pseudo Ops |
| |
| 7.79 '.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: MRI, Next: Noaltmacro, Prev: Macro, Up: Pseudo Ops |
| |
| 7.80 '.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: Noaltmacro, Next: Nolist, Prev: MRI, Up: Pseudo Ops |
| |
| 7.81 '.noaltmacro' |
| ================== |
| |
| Disable alternate macro mode. *Note Altmacro::. |
| |
| |
| File: as.info, Node: Nolist, Next: Octa, Prev: Noaltmacro, Up: Pseudo Ops |
| |
| 7.82 '.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: Offset, Prev: Nolist, Up: Pseudo Ops |
| |
| 7.83 '.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: Offset, Next: Org, Prev: Octa, Up: Pseudo Ops |
| |
| 7.84 '.offset LOC' |
| ================== |
| |
| Set the location counter to LOC in the absolute section. LOC must be an |
| absolute expression. This directive may be useful for defining symbols |
| with absolute values. Do not confuse it with the '.org' directive. |
| |
| |
| File: as.info, Node: Org, Next: P2align, Prev: Offset, Up: Pseudo Ops |
| |
| 7.85 '.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.86 '.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: PopSection, Next: Previous, Prev: P2align, Up: Pseudo Ops |
| |
| 7.87 '.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: Previous, Next: Print, Prev: PopSection, Up: Pseudo Ops |
| |
| 7.88 '.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/subsection pair prior to this one. Multiple |
| '.previous' directives in a row will flip between two sections (and |
| their subsections). For example: |
| |
| .section A |
| .subsection 1 |
| .word 0x1234 |
| .subsection 2 |
| .word 0x5678 |
| .previous |
| .word 0x9abc |
| |
| Will place 0x1234 and 0x9abc into subsection 1 and 0x5678 into |
| subsection 2 of section A. Whilst: |
| |
| .section A |
| .subsection 1 |
| # Now in section A subsection 1 |
| .word 0x1234 |
| .section B |
| .subsection 0 |
| # Now in section B subsection 0 |
| .word 0x5678 |
| .subsection 1 |
| # Now in section B subsection 1 |
| .word 0x9abc |
| .previous |
| # Now in section B subsection 0 |
| .word 0xdef0 |
| |
| Will place 0x1234 into section A, 0x5678 and 0xdef0 into subsection 0 |
| of section B and 0x9abc into subsection 1 of section B. |
| |
| In terms of the section stack, this directive swaps the current |
| section with the top section on the section stack. |
| |
| |
| File: as.info, Node: Print, Next: Protected, Prev: Previous, Up: Pseudo Ops |
| |
| 7.89 '.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.90 '.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.91 '.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.92 '.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.93 '.pushsection NAME [, SUBSECTION] [, "FLAGS"[, @TYPE[,ARGUMENTS]]]' |
| ======================================================================== |
| |
| 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'. The optional 'flags', 'type' |
| and 'arguments' are treated the same as in the '.section' (*note |
| Section::) directive. |
| |
| |
| File: as.info, Node: Quad, Next: Reloc, Prev: PushSection, Up: Pseudo Ops |
| |
| 7.94 '.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.95 '.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.96 '.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.97 '.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.98 '.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.99 '.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[, SUBSECTION] |
| |
| 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 |
| 'e' |
| exclude section from linking |
| 'r' |
| read-only section |
| 'x' |
| executable section |
| 's' |
| shared section (meaningful for PE targets) |
| 'a' |
| ignored. (For compatibility with the ELF version) |
| 'y' |
| section is not readable (meaningful for PE targets) |
| '0-9' |
| single-digit power-of-two section alignment (GNU extension) |
| |
| 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 subsection 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]]] |
| |
| If the '--sectname-subst' command-line option is provided, the NAME |
| argument may contain a substitution sequence. Only '%S' is supported at |
| the moment, and substitutes the current section name. For example: |
| |
| .macro exception_code |
| .section %S.exception |
| [exception code here] |
| .previous |
| .endm |
| |
| .text |
| [code] |
| exception_code |
| [...] |
| |
| .section .init |
| [init code] |
| exception_code |
| [...] |
| |
| The two 'exception_code' invocations above would create the |
| '.text.exception' and '.init.exception' sections respectively. This is |
| useful e.g. to discriminate between anciliary sections that are tied to |
| setup code to be discarded after use from anciliary sections that need |
| to stay resident without having to define multiple 'exception_code' |
| macros just for that purpose. |
| |
| The optional FLAGS argument is a quoted string which may contain any |
| combination of the following characters: |
| 'a' |
| section is allocatable |
| 'e' |
| section is excluded from executable and shared library. |
| '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 |
| '?' |
| section is a member of the previously-current section's group, if |
| any |
| |
| 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. For sections with both 'M' and 'S', a string which is a |
| suffix of a larger string is considered a duplicate. Thus '"def"' will |
| be merged with '"abcdef"'; A reference to the first '"def"' will be |
| changed to a reference to '"abcdef"+3'. |
| |
| 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 FLAGS contains the '?' symbol then it may not also contain the 'G' |
| symbol and the GROUPNAME or LINKAGE fields should not be present. |
| Instead, '?' says to consider the section that's current before this |
| directive. If that section used 'G', then the new section will use 'G' |
| with those same GROUPNAME and LINKAGE fields implicitly. If not, then |
| the '?' symbol has no effect. |
| |
| 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 |
| '#exclude' |
| section is excluded from executable and shared library. |
| '#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.100 '.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. |
| |
| 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.101 '.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.102 '.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.103 '.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: Skip, Next: Sleb128, Prev: Size, Up: Pseudo Ops |
| |
| 7.104 '.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: Sleb128, Next: Space, Prev: Skip, Up: Pseudo Ops |
| |
| 7.105 '.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: Space, Next: Stab, Prev: Sleb128, Up: Pseudo Ops |
| |
| 7.106 '.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.107 '.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.108 '.string' "STR", '.string8' "STR", '.string16' |
| ==================================================== |
| |
| "STR", '.string32' "STR", '.string64' "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. |
| |
| The variants 'string16', 'string32' and 'string64' differ from the |
| 'string' pseudo opcode in that each 8-bit character from STR is copied |
| and expanded to 16, 32 or 64 bits respectively. The expanded characters |
| are stored in target endianness byte order. |
| |
| Example: |
| .string32 "BYE" |
| expands to: |
| .string "B\0\0\0Y\0\0\0E\0\0\0" /* On little endian targets. */ |
| .string "\0\0\0B\0\0\0Y\0\0\0E" /* On big endian targets. */ |
| |
| |
| File: as.info, Node: Struct, Next: SubSection, Prev: String, Up: Pseudo Ops |
| |
| 7.109 '.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.110 '.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.111 '.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.112 '.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.113 '.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.114 '.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.115 '.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 <name> STT_<TYPE_IN_UPPER_CASE> |
| .type <name>,#<type> |
| .type <name>,@<type> |
| .type <name>,%<type> |
| .type <name>,"<type>" |
| |
| The types supported are: |
| |
| 'STT_FUNC' |
| 'function' |
| Mark the symbol as being a function name. |
| |
| 'STT_GNU_IFUNC' |
| 'gnu_indirect_function' |
| Mark the symbol as an indirect function when evaluated during reloc |
| processing. (This is only supported on assemblers targeting GNU |
| systems). |
| |
| 'STT_OBJECT' |
| 'object' |
| Mark the symbol as being a data object. |
| |
| 'STT_TLS' |
| 'tls_object' |
| Mark the symbol as being a thead-local data object. |
| |
| 'STT_COMMON' |
| 'common' |
| Mark the symbol as being a common data object. |
| |
| 'STT_NOTYPE' |
| 'notype' |
| Does not mark the symbol in any way. It is supported just for |
| completeness. |
| |
| 'gnu_unique_object' |
| Marks the symbol as being a globally unique data object. The |
| dynamic linker will make sure that in the entire process there is |
| just one symbol with this name and type in use. (This is only |
| supported on assemblers targeting GNU systems). |
| |
| Note: Some targets support extra types in addition to those listed |
| above. |
| |
| |
| File: as.info, Node: Uleb128, Next: Val, Prev: Type, Up: Pseudo Ops |
| |
| 7.116 '.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.117 '.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.118 '.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.119 '.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.120 '.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.121 '.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.122 '.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.123 '.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.124 '.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.125 Deprecated Directives |
| =========================== |
| |
| One day these directives won't work. They are included for |
| compatibility with older assemblers. |
| .abort |
| .line |
| |
| |
| File: as.info, Node: Object Attributes, Next: Machine Dependencies, Prev: Pseudo Ops, Up: Top |
| |
| 8 Object Attributes |
| ******************* |
| |
| 'as' assembles source files written for a specific architecture into |
| object files for that architecture. But not all object files are alike. |
| Many architectures support incompatible variations. For instance, |
| floating point arguments might be passed in floating point registers if |
| the object file requires hardware floating point support--or floating |
| point arguments might be passed in integer registers if the object file |
| supports processors with no hardware floating point unit. Or, if two |
| objects are built for different generations of the same architecture, |
| the combination may require the newer generation at run-time. |
| |
| This information is useful during and after linking. At link time, |
| 'ld' can warn about incompatible object files. After link time, tools |
| like 'gdb' can use it to process the linked file correctly. |
| |
| Compatibility information is recorded as a series of object |
| attributes. Each attribute has a "vendor", "tag", and "value". The |
| vendor is a string, and indicates who sets the meaning of the tag. The |
| tag is an integer, and indicates what property the attribute describes. |
| The value may be a string or an integer, and indicates how the property |
| affects this object. Missing attributes are the same as attributes with |
| a zero value or empty string value. |
| |
| Object attributes were developed as part of the ABI for the ARM |
| Architecture. The file format is documented in 'ELF for the ARM |
| Architecture'. |
| |
| * Menu: |
| |
| * GNU Object Attributes:: GNU Object Attributes |
| * Defining New Object Attributes:: Defining New Object Attributes |
| |
| |
| File: as.info, Node: GNU Object Attributes, Next: Defining New Object Attributes, Up: Object Attributes |
| |
| 8.1 GNU Object Attributes |
| ========================= |
| |
| The '.gnu_attribute' directive records an object attribute with vendor |
| 'gnu'. |
| |
| Except for 'Tag_compatibility', which has both an integer and a |
| string for its value, GNU attributes have a string value if the tag |
| number is odd and an integer value if the tag number is even. The |
| second bit ('TAG & 2' is set for architecture-independent attributes and |
| clear for architecture-dependent ones. |
| |
| 8.1.1 Common GNU attributes |
| --------------------------- |
| |
| These attributes are valid on all architectures. |
| |
| Tag_compatibility (32) |
| The compatibility attribute takes an integer flag value and a |
| vendor name. If the flag value is 0, the file is compatible with |
| other toolchains. If it is 1, then the file is only compatible |
| with the named toolchain. If it is greater than 1, the file can |
| only be processed by other toolchains under some private |
| arrangement indicated by the flag value and the vendor name. |
| |
| 8.1.2 MIPS Attributes |
| --------------------- |
| |
| Tag_GNU_MIPS_ABI_FP (4) |
| The floating-point ABI used by this object file. The value will |
| be: |
| |
| * 0 for files not affected by the floating-point ABI. |
| * 1 for files using the hardware floating-point ABI with a |
| standard double-precision FPU. |
| * 2 for files using the hardware floating-point ABI with a |
| single-precision FPU. |
| * 3 for files using the software floating-point ABI. |
| * 4 for files using the deprecated hardware floating-point ABI |
| which used 64-bit floating-point registers, 32-bit |
| general-purpose registers and increased the number of |
| callee-saved floating-point registers. |
| * 5 for files using the hardware floating-point ABI with a |
| double-precision FPU with either 32-bit or 64-bit |
| floating-point registers and 32-bit general-purpose registers. |
| * 6 for files using the hardware floating-point ABI with 64-bit |
| floating-point registers and 32-bit general-purpose registers. |
| * 7 for files using the hardware floating-point ABI with 64-bit |
| floating-point registers, 32-bit general-purpose registers and |
| a rule that forbids the direct use of odd-numbered |
| single-precision floating-point registers. |
| |
| 8.1.3 PowerPC Attributes |
| ------------------------ |
| |
| Tag_GNU_Power_ABI_FP (4) |
| The floating-point ABI used by this object file. The value will |
| be: |
| |
| * 0 for files not affected by the floating-point ABI. |
| * 1 for files using double-precision hardware floating-point |
| ABI. |
| * 2 for files using the software floating-point ABI. |
| * 3 for files using single-precision hardware floating-point |
| ABI. |
| |
| Tag_GNU_Power_ABI_Vector (8) |
| The vector ABI used by this object file. The value will be: |
| |
| * 0 for files not affected by the vector ABI. |
| * 1 for files using general purpose registers to pass vectors. |
| * 2 for files using AltiVec registers to pass vectors. |
| * 3 for files using SPE registers to pass vectors. |
| |
| |
| File: as.info, Node: Defining New Object Attributes, Prev: GNU Object Attributes, Up: Object Attributes |
| |
| 8.2 Defining New Object Attributes |
| ================================== |
| |
| If you want to define a new GNU object attribute, here are the places |
| you will need to modify. New attributes should be discussed on the |
| 'binutils' mailing list. |
| |
| * This manual, which is the official register of attributes. |
| * The header for your architecture 'include/elf', to define the tag. |
| * The 'bfd' support file for your architecture, to merge the |
| attribute and issue any appropriate link warnings. |
| * Test cases in 'ld/testsuite' for merging and link warnings. |
| * 'binutils/readelf.c' to display your attribute. |
| * GCC, if you want the compiler to mark the attribute automatically. |
| |
| |
| File: as.info, Node: Machine Dependencies, Next: Reporting Bugs, Prev: Object Attributes, Up: Top |
| |
| 9 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: |
| |
| * AArch64-Dependent:: AArch64 Dependent Features |
| * Alpha-Dependent:: Alpha Dependent Features |
| * ARC-Dependent:: ARC Dependent Features |
| * ARM-Dependent:: ARM Dependent Features |
| * AVR-Dependent:: AVR Dependent Features |
| * Blackfin-Dependent:: Blackfin Dependent Features |
| * CR16-Dependent:: CR16 Dependent Features |
| * CRIS-Dependent:: CRIS Dependent Features |
| * D10V-Dependent:: D10V Dependent Features |
| * D30V-Dependent:: D30V Dependent Features |
| * Epiphany-Dependent:: EPIPHANY 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 |
| * LM32-Dependent:: LM32 Dependent Features |
| * M32C-Dependent:: M32C Dependent Features |
| * M32R-Dependent:: M32R Dependent Features |
| * M68K-Dependent:: M680x0 Dependent Features |
| * M68HC11-Dependent:: M68HC11 and 68HC12 Dependent Features |
| * Meta-Dependent :: Meta Dependent Features |
| * MicroBlaze-Dependent:: MICROBLAZE Dependent Features |
| * MIPS-Dependent:: MIPS Dependent Features |
| * MMIX-Dependent:: MMIX Dependent Features |
| * MSP430-Dependent:: MSP430 Dependent Features |
| * NDS32-Dependent:: Andes NDS32 Dependent Features |
| * NiosII-Dependent:: Altera Nios II Dependent Features |
| * NS32K-Dependent:: NS32K 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 |
| * RL78-Dependent:: RL78 Dependent Features |
| * RX-Dependent:: RX Dependent Features |
| * S/390-Dependent:: IBM S/390 Dependent Features |
| * SCORE-Dependent:: SCORE Dependent Features |
| * Sparc-Dependent:: SPARC Dependent Features |
| * TIC54X-Dependent:: TI TMS320C54x Dependent Features |
| * TIC6X-Dependent :: TI TMS320C6x Dependent Features |
| * TILE-Gx-Dependent :: Tilera TILE-Gx Dependent Features |
| * TILEPro-Dependent :: Tilera TILEPro Dependent Features |
| * V850-Dependent:: V850 Dependent Features |
| * XGATE-Dependent:: XGATE Features |
| * XSTORMY16-Dependent:: XStormy16 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: AArch64-Dependent, Next: Alpha-Dependent, Up: Machine Dependencies |
| |
| 9.1 AArch64 Dependent Features |
| ============================== |
| |
| * Menu: |
| |
| * AArch64 Options:: Options |
| * AArch64 Extensions:: Extensions |
| * AArch64 Syntax:: Syntax |
| * AArch64 Floating Point:: Floating Point |
| * AArch64 Directives:: AArch64 Machine Directives |
| * AArch64 Opcodes:: Opcodes |
| * AArch64 Mapping Symbols:: Mapping Symbols |
| |
| |
| File: as.info, Node: AArch64 Options, Next: AArch64 Extensions, Up: AArch64-Dependent |
| |
| 9.1.1 Options |
| ------------- |
| |
| '-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. |
| |
| '-mabi=ABI' |
| Specify which ABI the source code uses. The recognized arguments |
| are: 'ilp32' and 'lp64', which decides the generated object file in |
| ELF32 and ELF64 format respectively. The default is 'lp64'. |
| |
| '-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: 'cortex-a53', |
| 'cortex-a57', 'xgene1', and 'xgene2'. The special name 'all' may |
| be used to allow the assembler to accept instructions valid for any |
| supported processor, including all optional extensions. |
| |
| In addition to the basic instruction set, the assembler can be told |
| to accept, or restrict, various extension mnemonics that extend the |
| processor. *Note AArch64 Extensions::. |
| |
| If some implementations of a particular processor can have an |
| extension, then then those extensions are automatically enabled. |
| Consequently, you will not normally have to specify any additional |
| extensions. |
| |
| '-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: 'armv8-a' and |
| 'armv8.1-a'. |
| |
| If both '-mcpu' and '-march' are specified, the assembler will use |
| the setting for '-mcpu'. If neither are specified, the assembler |
| will default to '-mcpu=all'. |
| |
| The architecture option can be extended with the same instruction |
| set extension options as the '-mcpu' option. Unlike '-mcpu', |
| extensions are not always enabled by default, *Note AArch64 |
| Extensions::. |
| |
| '-mverbose-error' |
| This option enables verbose error messages for AArch64 gas. This |
| option is enabled by default. |
| |
| '-mno-verbose-error' |
| This option disables verbose error messages in AArch64 gas. |
| |
| |
| File: as.info, Node: AArch64 Extensions, Next: AArch64 Syntax, Prev: AArch64 Options, Up: AArch64-Dependent |
| |
| 9.1.2 Architecture Extensions |
| ----------------------------- |
| |
| The table below lists the permitted architecture extensions that are |
| supported by the assembler and the conditions under which they are |
| automatically enabled. |
| |
| Multiple extensions may be specified, separated by a '+'. Extension |
| mnemonics may also be removed from those the assembler accepts. This is |
| done by prepending 'no' to the option that adds the extension. |
| Extensions that are removed must be listed after all extensions that |
| have been added. |
| |
| Enabling an extension that requires other extensions will |
| automatically cause those extensions to be enabled. Similarly, |
| disabling an extension that is required by other extensions will |
| automatically cause those extensions to be disabled. |
| |
| Extension Minimum Enabled by Description |
| Architecture default |
| ---------------------------------------------------------------------------- |
| 'crc' ARMv8-A No Enable CRC instructions. |
| 'crypto' ARMv8-A No Enable cryptographic extensions. |
| This implies 'fp' and 'simd'. |
| 'fp' ARMv8-A ARMv8-A or Enable floating-point extensions. |
| later |
| 'simd' ARMv8-A ARMv8-A or Enable Advanced SIMD extensions. |
| later This implies 'fp'. |
| 'pan' ARMv8-A ARMv8-A or Enable Privileged Access Never |
| later support. |
| 'lor' ARMv8-A ARMv8-A or Enable Limited Ordering Regions |
| later extensions. |
| 'rdma' ARMv8-A ARMv8-A or Enable ARMv8.1 Advanced SIMD |
| later extensions. This implies 'simd'. |
| |
| |
| File: as.info, Node: AArch64 Syntax, Next: AArch64 Floating Point, Prev: AArch64 Extensions, Up: AArch64-Dependent |
| |
| 9.1.3 Syntax |
| ------------ |
| |
| * Menu: |
| |
| * AArch64-Chars:: Special Characters |
| * AArch64-Regs:: Register Names |
| * AArch64-Relocations:: Relocations |
| |
| |
| File: as.info, Node: AArch64-Chars, Next: AArch64-Regs, Up: AArch64 Syntax |
| |
| 9.1.3.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. |
| |
| The '#' can be optionally used to indicate immediate operands. |
| |
| |
| File: as.info, Node: AArch64-Regs, Next: AArch64-Relocations, Prev: AArch64-Chars, Up: AArch64 Syntax |
| |
| 9.1.3.2 Register Names |
| ...................... |
| |
| Please refer to the section '4.4 Register Names' of 'ARMv8 Instruction |
| Set Overview', which is available at <http://infocenter.arm.com>. |
| |
| |
| File: as.info, Node: AArch64-Relocations, Prev: AArch64-Regs, Up: AArch64 Syntax |
| |
| 9.1.3.3 Relocations |
| ................... |
| |
| Relocations for 'MOVZ' and 'MOVK' instructions can be generated by |
| prefixing the label with '#:abs_g2:' etc. For example to load the |
| 48-bit absolute address of FOO into x0: |
| |
| movz x0, #:abs_g2:foo // bits 32-47, overflow check |
| movk x0, #:abs_g1_nc:foo // bits 16-31, no overflow check |
| movk x0, #:abs_g0_nc:foo // bits 0-15, no overflow check |
| |
| Relocations for 'ADRP', and 'ADD', 'LDR' or 'STR' instructions can be |
| generated by prefixing the label with ':pg_hi21:' and '#:lo12:' |
| respectively. |
| |
| For example to use 33-bit (+/-4GB) pc-relative addressing to load the |
| address of FOO into x0: |
| |
| adrp x0, :pg_hi21:foo |
| add x0, x0, #:lo12:foo |
| |
| Or to load the value of FOO into x0: |
| |
| adrp x0, :pg_hi21:foo |
| ldr x0, [x0, #:lo12:foo] |
| |
| Note that ':pg_hi21:' is optional. |
| |
| adrp x0, foo |
| |
| is equivalent to |
| |
| adrp x0, :pg_hi21:foo |
| |
| |
| File: as.info, Node: AArch64 Floating Point, Next: AArch64 Directives, Prev: AArch64 Syntax, Up: AArch64-Dependent |
| |
| 9.1.4 Floating Point |
| -------------------- |
| |
| The AArch64 architecture uses IEEE floating-point numbers. |
| |
| |
| File: as.info, Node: AArch64 Directives, Next: AArch64 Opcodes, Prev: AArch64 Floating Point, Up: AArch64-Dependent |
| |
| 9.1.5 AArch64 Machine Directives |
| -------------------------------- |
| |
| '.arch NAME' |
| Select the target architecture. Valid values for NAME are the same |
| as for the '-march' commandline option. |
| |
| Specifying '.arch' clears any previously selected architecture |
| extensions. |
| |
| '.arch_extension NAME' |
| Add or remove an architecture extension to the target architecture. |
| Valid values for NAME are the same as those accepted as |
| architectural extensions by the '-mcpu' commandline option. |
| |
| '.arch_extension' may be used multiple times to add or remove |
| extensions incrementally to the architecture being compiled for. |
| |
| '.bss' |
| This directive switches to the '.bss' section. |
| |
| '.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. |
| |
| 'NAME .req REGISTER NAME' |
| This creates an alias for REGISTER NAME called NAME. For example: |
| |
| foo .req w0 |
| |
| '.unreq ALIAS-NAME' |
| This undefines a register alias which was previously defined using |
| the 'req' directive. For example: |
| |
| foo .req w0 |
| .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 'w0'). |
| This should only be done if it is really necessary. |
| |
| |
| File: as.info, Node: AArch64 Opcodes, Next: AArch64 Mapping Symbols, Prev: AArch64 Directives, Up: AArch64-Dependent |
| |
| 9.1.6 Opcodes |
| ------------- |
| |
| GAS implements all the standard AArch64 opcodes. It also implements |
| several pseudo opcodes, including several synthetic load instructions. |
| |
| 'LDR =' |
| ldr <register> , =<expression> |
| |
| The constant expression will be placed into the nearest literal |
| pool (if it not already there) and a PC-relative LDR instruction |
| will be generated. |
| |
| For more information on the AArch64 instruction set and assembly |
| language notation, see 'ARMv8 Instruction Set Overview' available at |
| <http://infocenter.arm.com>. |
| |
| |
| File: as.info, Node: AArch64 Mapping Symbols, Prev: AArch64 Opcodes, Up: AArch64-Dependent |
| |
| 9.1.7 Mapping Symbols |
| --------------------- |
| |
| The AArch64 ELF specification requires that special symbols be inserted |
| into object files to mark certain features: |
| |
| '$x' |
| At the start of a region of code containing AArch64 instructions. |
| |
| '$d' |
| At the start of a region of data. |
| |
| |
| File: as.info, Node: Alpha-Dependent, Next: ARC-Dependent, Prev: AArch64-Dependent, Up: Machine Dependencies |
| |
| 9.2 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 |
| |
| 9.2.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 |
| |
| 9.2.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. |
| |
| '-replace' |
| '-noreplace' |
| Enables or disables the optimization of procedure calls, both at |
| assemblage and at link time. These options are only available for |
| VMS targets and '-replace' is the default. See section 1.4.1 of |
| the OpenVMS Linker Utility Manual. |
| |
| '-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 |
| |
| 9.2.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 |
| |
| 9.2.3.1 Special Characters |
| .......................... |
| |
| '#' is the line comment character. Note that if '#' is the first |
| character on a line then it can also be a logical line number directive |
| (*note Comments::) or a preprocessor control command (*note |
| Preprocessing::). |
| |
| ';' 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 |
| |
| 9.2.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 |
| |
| 9.2.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 |
| |
| 9.2.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 |
| |
| 9.2.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 |
| |
| 9.2.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 |
| |
| 9.3 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 |
| |
| 9.3.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 |
| |
| 9.3.2 Syntax |
| ------------ |
| |
| * Menu: |
| |
| * ARC-Chars:: Special Characters |
| * ARC-Regs:: Register Names |
| |
| |
| File: as.info, Node: ARC-Chars, Next: ARC-Regs, Up: ARC Syntax |
| |
| 9.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. Note that if a line starts with |
| a '#' character then it can also be a logical line number directive |
| (*note Comments::) or a preprocessor control command (*note |
| Preprocessing::). |
| |
| The ARC assembler does not support a line separator character. |
| |
| |
| File: as.info, Node: ARC-Regs, Prev: ARC-Chars, Up: ARC Syntax |
| |
| 9.3.2.2 Register Names |
| ...................... |
| |
| *TODO* |
| |
| |
| File: as.info, Node: ARC Floating Point, Next: ARC Directives, Prev: ARC Syntax, Up: ARC-Dependent |
| |
| 9.3.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 |
| |
| 9.3.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 conditional 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 |
| |
| 9.3.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 |
| |
| 9.4 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 |
| * ARM Unwinding Tutorial:: Unwinding |
| |
| |
| File: as.info, Node: ARM Options, Next: ARM Syntax, Up: ARM-Dependent |
| |
| 9.4.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', 'fa526' (Faraday FA526 |
| processor), 'fa626' (Faraday FA626 processor), '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', 'fa606te' (Faraday FA606TE processor), 'fa616te' |
| (Faraday FA616TE processor), 'fa626te' (Faraday FA626TE processor), |
| 'fmp626' (Faraday FMP626 processor), 'fa726te' (Faraday FA726TE |
| processor), 'arm1136j-s', 'arm1136jf-s', 'arm1156t2-s', |
| 'arm1156t2f-s', 'arm1176jz-s', 'arm1176jzf-s', 'mpcore', |
| 'mpcorenovfp', 'cortex-a5', 'cortex-a7', 'cortex-a8', 'cortex-a9', |
| 'cortex-a15', 'cortex-r4', 'cortex-r4f', 'cortex-r5', 'cortex-r7', |
| 'cortex-m4', 'cortex-m3', 'cortex-m1', 'cortex-m0', |
| 'cortex-m0plus', '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'. |
| |
| Multiple extensions may be specified, separated by a '+'. The |
| extensions should be specified in ascending alphabetical order. |
| |
| Some extensions may be restricted to particular architectures; this |
| is documented in the list of extensions below. |
| |
| Extension mnemonics may also be removed from those the assembler |
| accepts. This is done be prepending 'no' to the option that adds |
| the extension. Extensions that are removed should be listed after |
| all extensions which have been added, again in ascending |
| alphabetical order. For example, '-mcpu=ep9312+nomaverick' is |
| equivalent to specifying '-mcpu=arm920'. |
| |
| The following extensions are currently supported: 'crypto' |
| (Cryptography Extensions for v8-A architecture, implies 'fp+simd'), |
| 'fp' (Floating Point Extensions for v8-A architecture), 'idiv' |
| (Integer Divide Extensions for v7-A and v7-R architectures), |
| 'iwmmxt', 'iwmmxt2', 'maverick', 'mp' (Multiprocessing Extensions |
| for v7-A and v7-R architectures), 'os' (Operating System for v6M |
| architecture), 'sec' (Security Extensions for v6K and v7-A |
| architectures), 'simd' (Advanced SIMD Extensions for v8-A |
| architecture, implies 'fp'), 'virt' (Virtualization Extensions for |
| v7-A architecture, implies 'idiv'), 'pan' (Priviliged Access Never |
| Extensions for v8-A architecture), 'rdma' (ARMv8.1 Advanced SIMD |
| extensions for v8-A architecture, implies 'simd') 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', |
| 'armv6-m', 'armv6s-m', 'armv7', 'armv7-a', 'armv7ve', 'armv7-r', |
| 'armv7-m', 'armv7e-m', 'armv8-a', 'armv8.1-a', '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', 'vfpv2', 'vfpv3', 'vfpv3-fp16', 'vfpv3-d16', |
| 'vfpv3-d16-fp16', 'vfpv3xd', 'vfpv3xd-d16', 'vfpv4', 'vfpv4-d16', |
| 'fpv4-sp-d16', 'fp-armv8', 'arm1020t', 'arm1020e', 'arm1136jf-s', |
| 'maverick', 'neon', 'neon-vfpv4', 'neon-fp-armv8', |
| 'crypto-neon-fp-armv8', 'neon-fp-armv8.1' and |
| 'crypto-neon-fp-armv8.1'. |
| |
| 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. |
| |
| '-mimplicit-it=never' |
| '-mimplicit-it=always' |
| '-mimplicit-it=arm' |
| '-mimplicit-it=thumb' |
| The '-mimplicit-it' option controls the behavior of the assembler |
| when conditional instructions are not enclosed in IT blocks. There |
| are four possible behaviors. If 'never' is specified, such |
| constructs cause a warning in ARM code and an error in Thumb-2 |
| code. If 'always' is specified, such constructs are accepted in |
| both ARM and Thumb-2 code, where the IT instruction is added |
| implicitly. If 'arm' is specified, such constructs are accepted in |
| ARM code and cause an error in Thumb-2 code. If 'thumb' is |
| specified, such constructs cause a warning in ARM code and are |
| accepted in Thumb-2 code. If you omit this option, the behavior is |
| equivalent to '-mimplicit-it=arm'. |
| |
| '-mapcs-26' |
| '-mapcs-32' |
| These options specify 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). |
| |
| '--fix-v4bx' |
| Allow 'BX' instructions in ARMv4 code. This is intended for use |
| with the linker option of the same name. |
| |
| '-mwarn-deprecated' |
| '-mno-warn-deprecated' |
| Enable or disable warnings about using deprecated options or |
| features. The default is to warn. |
| |
| '-mccs' |
| Turns on CodeComposer Studio assembly syntax compatibility mode. |
| |
| |
| File: as.info, Node: ARM Syntax, Next: ARM Floating Point, Prev: ARM Options, Up: ARM-Dependent |
| |
| 9.4.2 Syntax |
| ------------ |
| |
| * Menu: |
| |
| * ARM-Instruction-Set:: Instruction Set |
| * ARM-Chars:: Special Characters |
| * ARM-Regs:: Register Names |
| * ARM-Relocations:: Relocations |
| * ARM-Neon-Alignment:: NEON Alignment Specifiers |
| |
| |
| File: as.info, Node: ARM-Instruction-Set, Next: ARM-Chars, Up: ARM Syntax |
| |
| 9.4.2.1 Instruction Set Syntax |
| .............................. |
| |
| Two slightly different syntaxes are support for ARM and THUMB |
| instructions. The default, 'divided', uses the old style where ARM and |
| THUMB instructions had their own, separate syntaxes. The new, 'unified' |
| syntax, which can be selected via the '.syntax' directive, and has the |
| following main features: |
| |
| * Immediate operands do not require a '#' prefix. |
| |
| * The 'IT' instruction may appear, and if it does it is validated |
| against subsequent conditional affixes. In ARM mode it does not |
| generate machine code, in THUMB mode it does. |
| |
| * For ARM instructions the conditional affixes always appear at the |
| end of the instruction. For THUMB instructions conditional affixes |
| can be used, but only inside the scope of an 'IT' instruction. |
| |
| * All of the instructions new to the V6T2 architecture (and later) |
| are available. (Only a few such instructions can be written in the |
| 'divided' syntax). |
| |
| * The '.N' and '.W' suffixes are recognized and honored. |
| |
| * All instructions set the flags if and only if they have an 's' |
| affix. |
| |
| |
| File: as.info, Node: ARM-Chars, Next: ARM-Regs, Prev: ARM-Instruction-Set, Up: ARM Syntax |
| |
| 9.4.2.2 Special Characters |
| .......................... |
| |
| The presence of a '@' anywhere on a line indicates the start of a |
| comment that extends to the end of that line. |
| |
| If a '#' appears as the first character of a line then the whole line |
| is treated as a comment, but in this case the line could also be a |
| logical line number directive (*note Comments::) or a preprocessor |
| control command (*note Preprocessing::). |
| |
| 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 |
| |
| 9.4.2.3 Register Names |
| ...................... |
| |
| *TODO* Explain about ARM register naming, and the predefined names. |
| |
| |
| File: as.info, Node: ARM-Relocations, Next: ARM-Neon-Alignment, Prev: ARM-Regs, Up: ARM Syntax |
| |
| 9.4.2.4 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', 'TLSDESC', |
| 'TLSCALL', 'GOTTPOFF', 'GOT_PREL' and 'TPOFF'. |
| |
| For compatibility with older toolchains the assembler also accepts |
| '(PLT)' after branch targets. On legacy targets this will generate the |
| deprecated 'R_ARM_PLT32' relocation. On EABI targets it will encode |
| either the 'R_ARM_CALL' or 'R_ARM_JUMP24' relocation, as appropriate. |
| |
| 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-Neon-Alignment, Prev: ARM-Relocations, Up: ARM Syntax |
| |
| 9.4.2.5 NEON Alignment Specifiers |
| ................................. |
| |
| Some NEON load/store instructions allow an optional address alignment |
| qualifier. The ARM documentation specifies that this is indicated by '@ |
| ALIGN'. However GAS already interprets the '@' character as a "line |
| comment" start, so ': ALIGN' is used instead. For example: |
| |
| vld1.8 {q0}, [r0, :128] |
| |
| |
| File: as.info, Node: ARM Floating Point, Next: ARM Directives, Prev: ARM Syntax, Up: ARM-Dependent |
| |
| 9.4.3 Floating Point |
| -------------------- |
| |
| The ARM family uses IEEE floating-point numbers. |
| |
| |
| File: as.info, Node: ARM Directives, Next: ARM Opcodes, Prev: ARM Floating Point, Up: ARM-Dependent |
| |
| 9.4.4 ARM Machine Directives |
| ---------------------------- |
| |
| '.2byte EXPRESSION [, EXPRESSION]*' |
| '.4byte EXPRESSION [, EXPRESSION]*' |
| '.8byte EXPRESSION [, EXPRESSION]*' |
| These directives write 2, 4 or 8 byte values to the output section. |
| |
| '.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. |
| |
| '.arch NAME' |
| Select the target architecture. Valid values for NAME are the same |
| as for the '-march' commandline option. |
| |
| Specifying '.arch' clears any previously selected architecture |
| extensions. |
| |
| '.arch_extension NAME' |
| Add or remove an architecture extension to the target architecture. |
| Valid values for NAME are the same as those accepted as |
| architectural extensions by the '-mcpu' commandline option. |
| |
| '.arch_extension' may be used multiple times to add or remove |
| extensions incrementally to the architecture being compiled for. |
| |
| '.arm' |
| This performs the same action as .CODE 32. |
| |
| '.bss' |
| This directive switches to the '.bss' section. |
| |
| '.cantunwind' |
| Prevents unwinding through the current function. No personality |
| routine or exception table data is required or permitted. |
| |
| '.code [16|32]' |
| This directive selects the instruction set being generated. The |
| value 16 selects Thumb, with the value 32 selecting ARM. |
| |
| '.cpu NAME' |
| Select the target processor. Valid values for NAME are the same as |
| for the '-mcpu' commandline option. |
| |
| Specifying '.cpu' clears any previously selected architecture |
| extensions. |
| |
| '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'. |
| |
| '.eabi_attribute TAG, VALUE' |
| Set the EABI object attribute TAG to VALUE. |
| |
| The TAG is either an attribute number, or one of the following: |
| 'Tag_CPU_raw_name', 'Tag_CPU_name', 'Tag_CPU_arch', |
| 'Tag_CPU_arch_profile', 'Tag_ARM_ISA_use', 'Tag_THUMB_ISA_use', |
| 'Tag_FP_arch', 'Tag_WMMX_arch', 'Tag_Advanced_SIMD_arch', |
| 'Tag_PCS_config', 'Tag_ABI_PCS_R9_use', 'Tag_ABI_PCS_RW_data', |
| 'Tag_ABI_PCS_RO_data', 'Tag_ABI_PCS_GOT_use', |
| 'Tag_ABI_PCS_wchar_t', 'Tag_ABI_FP_rounding', |
| 'Tag_ABI_FP_denormal', 'Tag_ABI_FP_exceptions', |
| 'Tag_ABI_FP_user_exceptions', 'Tag_ABI_FP_number_model', |
| 'Tag_ABI_align_needed', 'Tag_ABI_align_preserved', |
| 'Tag_ABI_enum_size', 'Tag_ABI_HardFP_use', 'Tag_ABI_VFP_args', |
| 'Tag_ABI_WMMX_args', 'Tag_ABI_optimization_goals', |
| 'Tag_ABI_FP_optimization_goals', 'Tag_compatibility', |
| 'Tag_CPU_unaligned_access', 'Tag_FP_HP_extension', |
| 'Tag_ABI_FP_16bit_format', 'Tag_MPextension_use', 'Tag_DIV_use', |
| 'Tag_nodefaults', 'Tag_also_compatible_with', 'Tag_conformance', |
| 'Tag_T2EE_use', 'Tag_Virtualization_use' |
| |
| The VALUE is either a 'number', '"string"', or 'number, "string"' |
| depending on the tag. |
| |
| Note - the following legacy values are also accepted by TAG: |
| 'Tag_VFP_arch', 'Tag_ABI_align8_needed', |
| 'Tag_ABI_align8_preserved', 'Tag_VFP_HP_extension', |
| |
| '.even' |
| This directive aligns to an even-numbered address. |
| |
| '.extend EXPRESSION [, EXPRESSION]*' |
| '.ldouble EXPRESSION [, EXPRESSION]*' |
| These directives write 12byte long double floating-point values to |
| the output section. These are not compatible with current ARM |
| processors or ABIs. |
| |
| '.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. |
| |
| '.fnstart' |
| Marks the start of a function with an unwind table entry. |
| |
| '.force_thumb' |
| This directive forces the selection of Thumb instructions, even if |
| the target processor does not support those instructions |
| |
| '.fpu NAME' |
| Select the floating-point unit to assemble for. Valid values for |
| NAME are the same as for the '-mfpu' commandline option. |
| |
| '.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. |
| |
| '.inst OPCODE [ , ... ]' |
| '.inst.n OPCODE [ , ... ]' |
| '.inst.w OPCODE [ , ... ]' |
| Generates the instruction corresponding to the numerical value |
| OPCODE. '.inst.n' and '.inst.w' allow the Thumb instruction size |
| to be specified explicitly, overriding the normal encoding rules. |
| |
| '.ldouble EXPRESSION [, EXPRESSION]*' |
| See '.extend'. |
| |
| '.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. |
| |
| '.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. |
| |
| '.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. |
| |
| '.packed EXPRESSION [, EXPRESSION]*' |
| This directive writes 12-byte packed floating-point values to the |
| output section. These are not compatible with current ARM |
| processors or ABIs. |
| |
| '.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. |
| |
| '.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 |
| |
| '.pool' |
| This is a synonym for .ltorg. |
| |
| 'NAME .req REGISTER NAME' |
| This creates an alias for REGISTER NAME called NAME. For example: |
| |
| foo .req r0 |
| |
| '.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]! |
| |
| '.setfp FPREG, SPREG [, #OFFSET]' |
| Make all unwinder annotations relative 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 'add' 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 |
| add fp, ip, #4 |
| |
| '.secrel32 EXPRESSION [, EXPRESSION]*' |
| This directive emits relocations that evaluate to the |
| section-relative offset of each expression's symbol. This |
| directive is only supported for PE targets. |
| |
| '.syntax [unified | divided]' |
| This directive sets the Instruction Set Syntax as described in the |
| *note ARM-Instruction-Set:: section. |
| |
| '.thumb' |
| This performs the same action as .CODE 16. |
| |
| '.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. |
| |
| '.tlsdescseq TLS-VARIABLE' |
| This directive is used to annotate parts of an inlined TLS |
| descriptor trampoline. Normally the trampoline is provided by the |
| linker, and this directive is not needed. |
| |
| '.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. |
| |
| '.unwind_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}' |
| |
| '.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. |
| |
| |
| File: as.info, Node: ARM Opcodes, Next: ARM Mapping Symbols, Prev: ARM Directives, Up: ARM-Dependent |
| |
| 9.4.5 Opcodes |
| ------------- |
| |
| 'as' implements all the standard ARM opcodes. It also implements |
| several pseudo opcodes, including several synthetic load instructions. |
| |
| 'NOP' |
| nop |
| |
| This pseudo op will always evaluate to a legal ARM instruction that |
| does nothing. Currently it will evaluate to MOV r0, r0. |
| |
| 'LDR' |
| ldr <register> , = <expression> |
| |
| If expression evaluates to a numeric constant then a MOV or MVN |
| instruction will be used in place of the LDR instruction, if the |
| constant can be generated by either of these instructions. |
| Otherwise the constant will be placed into the nearest literal pool |
| (if it not already there) and a PC relative LDR instruction will be |
| generated. |
| |
| 'ADR' |
| adr <register> <label> |
| |
| This instruction will load the address of LABEL into the indicated |
| register. The instruction will evaluate to a PC relative ADD or |
| SUB instruction depending upon where the label is located. If the |
| label is out of range, or if it is not defined in the same file |
| (and section) as the ADR instruction, then an error will be |
| generated. This instruction will not make use of the literal pool. |
| |
| 'ADRL' |
| adrl <register> <label> |
| |
| This instruction will load the address of LABEL into the indicated |
| register. The instruction will evaluate to one or two PC relative |
| ADD or SUB instructions depending upon where the label is located. |
| If a second instruction is not needed a NOP instruction will be |
| generated in its place, so that this instruction is always 8 bytes |
| long. |
| |
| If the label is out of range, or if it is not defined in the same |
| file (and section) as the ADRL instruction, then an error will be |
| generated. This instruction will not make use of the literal pool. |
| |
| For information on the ARM or Thumb instruction sets, see 'ARM |
| Software Development Toolkit Reference Manual', Advanced RISC Machines |
| Ltd. |
| |
| |
| File: as.info, Node: ARM Mapping Symbols, Next: ARM Unwinding Tutorial, Prev: ARM Opcodes, Up: ARM-Dependent |
| |
| 9.4.6 Mapping Symbols |
| --------------------- |
| |
| The ARM ELF specification requires that special symbols be inserted into |
| object files to mark certain features: |
| |
| '$a' |
| At the start of a region of code containing ARM instructions. |
| |
| '$t' |
| At the start of a region of code containing THUMB instructions. |
| |
| '$d' |
| At the start of a region of data. |
| |
| The assembler will automatically insert these symbols for you - there |
| is no need to code them yourself. Support for tagging symbols ($b, $f, |
| $p and $m) which is also mentioned in the current ARM ELF specification |
| is not implemented. This is because they have been dropped from the new |
| EABI and so tools cannot rely upon their presence. |
| |
| |
| File: as.info, Node: ARM Unwinding Tutorial, Prev: ARM Mapping Symbols, Up: ARM-Dependent |
| |
| 9.4.7 Unwinding |
| --------------- |
| |
| The ABI for the ARM Architecture specifies a standard format for |
| exception unwind information. This information is used when an |
| exception is thrown to determine where control should be transferred. |
| In particular, the unwind information is used to determine which |
| function called the function that threw the exception, and which |
| function called that one, and so forth. This information is also used |
| to restore the values of callee-saved registers in the function catching |
| the exception. |
| |
| If you are writing functions in assembly code, and those functions |
| call other functions that throw exceptions, you must use assembly pseudo |
| ops to ensure that appropriate exception unwind information is |
| generated. Otherwise, if one of the functions called by your assembly |
| code throws an exception, the run-time library will be unable to unwind |
| the stack through your assembly code and your program will not behave |
| correctly. |
| |
| To illustrate the use of these pseudo ops, we will examine the code |
| that G++ generates for the following C++ input: |
| |
| void callee (int *); |
| |
| int |
| caller () |
| { |
| int i; |
| callee (&i); |
| return i; |
| } |
| |
| This example does not show how to throw or catch an exception from |
| assembly code. That is a much more complex operation and should always |
| be done in a high-level language, such as C++, that directly supports |
| exceptions. |
| |
| The code generated by one particular version of G++ when compiling |
| the example above is: |
| |
| _Z6callerv: |
| .fnstart |
| .LFB2: |
| @ Function supports interworking. |
| @ args = 0, pretend = 0, frame = 8 |
| @ frame_needed = 1, uses_anonymous_args = 0 |
| stmfd sp!, {fp, lr} |
| .save {fp, lr} |
| .LCFI0: |
| .setfp fp, sp, #4 |
| add fp, sp, #4 |
| .LCFI1: |
| .pad #8 |
| sub sp, sp, #8 |
| .LCFI2: |
| sub r3, fp, #8 |
| mov r0, r3 |
| bl _Z6calleePi |
| ldr r3, [fp, #-8] |
| mov r0, r3 |
| sub sp, fp, #4 |
| ldmfd sp!, {fp, lr} |
| bx lr |
| .LFE2: |
| .fnend |
| |
| Of course, the sequence of instructions varies based on the options |
| you pass to GCC and on the version of GCC in use. The exact |
| instructions are not important since we are focusing on the pseudo ops |
| that are used to generate unwind information. |
| |
| An important assumption made by the unwinder is that the stack frame |
| does not change during the body of the function. In particular, since |
| we assume that the assembly code does not itself throw an exception, the |
| only point where an exception can be thrown is from a call, such as the |
| 'bl' instruction above. At each call site, the same saved registers |
| (including 'lr', which indicates the return address) must be located in |
| the same locations relative to the frame pointer. |
| |
| The '.fnstart' (*note .fnstart pseudo op: arm_fnstart.) pseudo op |
| appears immediately before the first instruction of the function while |
| the '.fnend' (*note .fnend pseudo op: arm_fnend.) pseudo op appears |
| immediately after the last instruction of the function. These pseudo |
| ops specify the range of the function. |
| |
| Only the order of the other pseudos ops (e.g., '.setfp' or '.pad') |
| matters; their exact locations are irrelevant. In the example above, |
| the compiler emits the pseudo ops with particular instructions. That |
| makes it easier to understand the code, but it is not required for |
| correctness. It would work just as well to emit all of the pseudo ops |
| other than '.fnend' in the same order, but immediately after '.fnstart'. |
| |
| The '.save' (*note .save pseudo op: arm_save.) pseudo op indicates |
| registers that have been saved to the stack so that they can be restored |
| before the function returns. The argument to the '.save' pseudo op is a |
| list of registers to save. If a register is "callee-saved" (as |
| specified by the ABI) and is modified by the function you are writing, |
| then your code must save the value before it is modified and restore the |
| original value before the function returns. If an exception is thrown, |
| the run-time library restores the values of these registers from their |
| locations on the stack before returning control to the exception |
| handler. (Of course, if an exception is not thrown, the function that |
| contains the '.save' pseudo op restores these registers in the function |
| epilogue, as is done with the 'ldmfd' instruction above.) |
| |
| You do not have to save callee-saved registers at the very beginning |
| of the function and you do not need to use the '.save' pseudo op |
| immediately following the point at which the registers are saved. |
| However, if you modify a callee-saved register, you must save it on the |
| stack before modifying it and before calling any functions which might |
| throw an exception. And, you must use the '.save' pseudo op to indicate |
| that you have done so. |
| |
| The '.pad' (*note .pad: arm_pad.) pseudo op indicates a modification |
| of the stack pointer that does not save any registers. The argument is |
| the number of bytes (in decimal) that are subtracted from the stack |
| pointer. (On ARM CPUs, the stack grows downwards, so subtracting from |
| the stack pointer increases the size of the stack.) |
| |
| The '.setfp' (*note .setfp pseudo op: arm_setfp.) pseudo op indicates |
| the register that contains the frame pointer. The first argument is the |
| register that is set, which is typically 'fp'. The second argument |
| indicates the register from which the frame pointer takes its value. |
| The third argument, if present, is the value (in decimal) added to the |
| register specified by the second argument to compute the value of the |
| frame pointer. You should not modify the frame pointer in the body of |
| the function. |
| |
| If you do not use a frame pointer, then you should not use the |
| '.setfp' pseudo op. If you do not use a frame pointer, then you should |
| avoid modifying the stack pointer outside of the function prologue. |
| Otherwise, the run-time library will be unable to find saved registers |
| when it is unwinding the stack. |
| |
| The pseudo ops described above are sufficient for writing assembly |
| code that calls functions which may throw exceptions. If you need to |
| know more about the object-file format used to represent unwind |
| information, you may consult the 'Exception Handling ABI for the ARM |
| Architecture' available from <http://infocenter.arm.com>. |
| |
| |
| File: as.info, Node: AVR-Dependent, Next: Blackfin-Dependent, Prev: ARM-Dependent, Up: Machine Dependencies |
| |
| 9.5 AVR Dependent Features |
| ========================== |
| |
| * Menu: |
| |
| * AVR Options:: Options |
| * AVR Syntax:: Syntax |
| * AVR Opcodes:: Opcodes |
| |
| |
| File: as.info, Node: AVR Options, Next: AVR Syntax, Up: AVR-Dependent |
| |
| 9.5.1 Options |
| ------------- |
| |
| '-mmcu=MCU' |
| Specify ATMEL AVR instruction set or MCU type. |
| |
| Instruction set avr1 is for the minimal AVR core, not supported by |
| the C compiler, only for assembler programs (MCU types: at90s1200, |
| attiny11, attiny12, attiny15, attiny28). |
| |
| Instruction set avr2 (default) is for the classic AVR core with up |
| to 8K program memory space (MCU types: at90s2313, at90s2323, |
| at90s2333, at90s2343, attiny22, attiny26, at90s4414, at90s4433, |
| at90s4434, at90s8515, at90c8534, at90s8535). |
| |
| Instruction set avr25 is for the classic AVR core with up to 8K |
| program memory space plus the MOVW instruction (MCU types: |
| attiny13, attiny13a, attiny2313, attiny2313a, attiny24, attiny24a, |
| attiny4313, attiny44, attiny44a, attiny84, attiny84a, attiny25, |
| attiny45, attiny85, attiny261, attiny261a, attiny461, attiny461a, |
| attiny861, attiny861a, attiny87, attiny43u, attiny48, attiny88, |
| attiny828, at86rf401, ata6289, ata5272). |
| |
| Instruction set avr3 is for the classic AVR core with up to 128K |
| program memory space (MCU types: at43usb355, at76c711). |
| |
| Instruction set avr31 is for the classic AVR core with exactly 128K |
| program memory space (MCU types: atmega103, at43usb320). |
| |
| Instruction set avr35 is for classic AVR core plus MOVW, CALL, and |
| JMP instructions (MCU types: attiny167, attiny1634, at90usb82, |
| at90usb162, atmega8u2, atmega16u2, atmega32u2, ata5505). |
| |
| Instruction set avr4 is for the enhanced AVR core with up to 8K |
| program memory space (MCU types: atmega48, atmega48a, atmega48pa, |
| atmega48p, atmega8, atmega8a, atmega88, atmega88a, atmega88p, |
| atmega88pa, atmega8515, atmega8535, atmega8hva, at90pwm1, at90pwm2, |
| at90pwm2b, at90pwm3, at90pwm3b, at90pwm81, ata6285, ata6286). |
| |
| Instruction set avr5 is for the enhanced AVR core with up to 128K |
| program memory space (MCU types: at90pwm161, atmega16, atmega16a, |
| atmega161, atmega162, atmega163, atmega164a, atmega164p, |
| atmega164pa, atmega165, atmega165a, atmega165p, atmega165pa, |
| atmega168, atmega168a, atmega168p, atmega168pa, atmega169, |
| atmega169a, atmega169p, atmega169pa, atmega32, atmega323, |
| atmega324a, atmega324p, atmega324pa, atmega325, atmega325a, |
| atmega32, atmega32a, atmega323, atmega324a, atmega324p, |
| atmega324pa, atmega325, atmega325a, atmega325p, atmega325p, |
| atmega325pa, atmega3250, atmega3250a, atmega3250p, atmega3250pa, |
| atmega328, atmega328p, atmega329, atmega329a, atmega329p, |
| atmega329pa, atmega3290a, atmega3290p, atmega3290pa, atmega406, |
| atmega64, atmega64a, atmega64rfr2, atmega644rfr2, atmega640, |
| atmega644, atmega644a, atmega644p, atmega644pa, atmega645, |
| atmega645a, atmega645p, atmega6450, atmega6450a, atmega6450p, |
| atmega649, atmega649a, atmega649p, atmega6490, atmega6490a, |
| atmega6490p, atmega16hva, atmega16hva2, atmega16hvb, |
| atmega16hvbrevb, atmega32hvb, atmega32hvbrevb, atmega64hve, |
| at90can32, at90can64, at90pwm161, at90pwm216, at90pwm316, |
| atmega32c1, atmega64c1, atmega16m1, atmega32m1, atmega64m1, |
| atmega16u4, atmega32u4, atmega32u6, at90usb646, at90usb647, at94k, |
| at90scr100, ata5790, ata5795). |
| |
| Instruction set avr51 is for the enhanced AVR core with exactly |
| 128K program memory space (MCU types: atmega128, atmega128a, |
| atmega1280, atmega1281, atmega1284, atmega1284p, atmega128rfa1, |
| atmega128rfr2, atmega1284rfr2, at90can128, at90usb1286, |
| at90usb1287, m3000). |
| |
| Instruction set avr6 is for the enhanced AVR core with a 3-byte PC |
| (MCU types: atmega2560, atmega2561, atmega256rfr2, atmega2564rfr2). |
| |
| Instruction set avrxmega2 is for the XMEGA AVR core with 8K to 64K |
| program memory space and less than 64K data space (MCU types: |
| atxmega16a4, atxmega16a4u, atxmega16c4, atxmega16d4, atxmega16x1, |
| atxmega32a4, atxmega32a4u, atxmega32c4, atxmega32d4, atxmega16e5, |
| atxmega8e5, atxmega32e5, atxmega32x1). |
| |
| Instruction set avrxmega3 is for the XMEGA AVR core with 8K to 64K |
| program memory space and greater than 64K data space (MCU types: |
| none). |
| |
| Instruction set avrxmega4 is for the XMEGA AVR core with up to 64K |
| program memory space and less than 64K data space (MCU types: |
| atxmega64a3, atxmega64a3u, atxmega64a4u, atxmega64b1, atxmega64b3, |
| atxmega64c3, atxmega64d3, atxmega64d4). |
| |
| Instruction set avrxmega5 is for the XMEGA AVR core with up to 64K |
| program memory space and greater than 64K data space (MCU types: |
| atxmega64a1, atxmega64a1u). |
| |
| Instruction set avrxmega6 is for the XMEGA AVR core with larger |
| than 64K program memory space and less than 64K data space (MCU |
| types: atxmega128a3, atxmega128a3u, atxmega128c3, atxmega128d3, |
| atxmega128d4, atxmega192a3, atxmega192a3u, atxmega128b1, |
| atxmega128b3, atxmega192c3, atxmega192d3, atxmega256a3, |
| atxmega256a3u, atxmega256a3b, atxmega256a3bu, atxmega256c3, |
| atxmega256d3, atxmega384c3, atxmega256d3). |
| |
| Instruction set avrxmega7 is for the XMEGA AVR core with larger |
| than 64K program memory space and greater than 64K data space (MCU |
| types: atxmega128a1, atxmega128a1u, atxmega128a4u). |
| |
| Instruction set avrtiny is for the ATtiny4/5/9/10/20/40 |
| microcontrollers. |
| |
| '-mall-opcodes' |
| Accept all AVR opcodes, even if not supported by '-mmcu'. |
| |
| '-mno-skip-bug' |
| This option disable warnings for skipping two-word instructions. |
| |
| '-mno-wrap' |
| This option reject 'rjmp/rcall' instructions with 8K wrap-around. |
| |
| '-mrmw' |
| Accept Read-Modify-Write ('XCH,LAC,LAS,LAT') instructions. |
| |
| |
| File: as.info, Node: AVR Syntax, Next: AVR Opcodes, Prev: AVR Options, Up: AVR-Dependent |
| |
| 9.5.2 Syntax |
| ------------ |
| |
| * Menu: |
| |
| * AVR-Chars:: Special Characters |
| * AVR-Regs:: Register Names |
| * AVR-Modifiers:: Relocatable Expression Modifiers |
| |
| |
| File: as.info, Node: AVR-Chars, Next: AVR-Regs, Up: AVR Syntax |
| |
| 9.5.2.1 Special Characters |
| .......................... |
| |
| The presence of a ';' anywhere on a line indicates the start of a |
| comment that extends to the end of that line. |
| |
| If a '#' appears as the first character of a line, the whole line is |
| treated as a comment, but in this case the line can also be a logical |
| line number directive (*note Comments::) or a preprocessor control |
| command (*note Preprocessing::). |
| |
| The '$' character can be used instead of a newline to separate |
| statements. |
| |
| |
| File: as.info, Node: AVR-Regs, Next: AVR-Modifiers, Prev: AVR-Chars, Up: AVR Syntax |
| |
| 9.5.2.2 Register Names |
| ...................... |
| |
| The AVR has 32 x 8-bit general purpose working registers 'r0', 'r1', ... |
| 'r31'. Six of the 32 registers can be used as three 16-bit indirect |
| address register pointers for Data Space addressing. One of the these |
| address pointers can also be used as an address pointer for look up |
| tables in Flash program memory. These added function registers are the |
| 16-bit 'X', 'Y' and 'Z' - registers. |
| |
| X = r26:r27 |
| Y = r28:r29 |
| Z = r30:r31 |
| |
| |
| File: as.info, Node: AVR-Modifiers, Prev: AVR-Regs, Up: AVR Syntax |
| |
| 9.5.2.3 Relocatable Expression Modifiers |
| ........................................ |
| |
| The assembler supports several modifiers when using relocatable |
| addresses in AVR instruction operands. The general syntax is the |
| following: |
| |
| modifier(relocatable-expression) |
| |
| 'lo8' |
| |
| This modifier allows you to use bits 0 through 7 of an address |
| expression as 8 bit relocatable expression. |
| |
| 'hi8' |
| |
| This modifier allows you to use bits 7 through 15 of an address |
| expression as 8 bit relocatable expression. This is useful with, |
| for example, the AVR 'ldi' instruction and 'lo8' modifier. |
| |
| For example |
| |
| ldi r26, lo8(sym+10) |
| ldi r27, hi8(sym+10) |
| |
| 'hh8' |
| |
| This modifier allows you to use bits 16 through 23 of an address |
| expression as 8 bit relocatable expression. Also, can be useful |
| for loading 32 bit constants. |
| |
| 'hlo8' |
| |
| Synonym of 'hh8'. |
| |
| 'hhi8' |
| |
| This modifier allows you to use bits 24 through 31 of an expression |
| as 8 bit expression. This is useful with, for example, the AVR |
| 'ldi' instruction and 'lo8', 'hi8', 'hlo8', 'hhi8', modifier. |
| |
| For example |
| |
| ldi r26, lo8(285774925) |
| ldi r27, hi8(285774925) |
| ldi r28, hlo8(285774925) |
| ldi r29, hhi8(285774925) |
| ; r29,r28,r27,r26 = 285774925 |
| |
| 'pm_lo8' |
| |
| This modifier allows you to use bits 0 through 7 of an address |
| expression as 8 bit relocatable expression. This modifier useful |
| for addressing data or code from Flash/Program memory. The using |
| of 'pm_lo8' similar to 'lo8'. |
| |
| 'pm_hi8' |
| |
| This modifier allows you to use bits 8 through 15 of an address |
| expression as 8 bit relocatable expression. This modifier useful |
| for addressing data or code from Flash/Program memory. |
| |
| 'pm_hh8' |
| |
| This modifier allows you to use bits 15 through 23 of an address |
| expression as 8 bit relocatable expression. This modifier useful |
| for addressing data or code from Flash/Program memory. |
| |
| |
| File: as.info, Node: AVR Opcodes, Prev: AVR Syntax, Up: AVR-Dependent |
| |
| 9.5.3 Opcodes |
| ------------- |
| |
| For detailed information on the AVR machine instruction set, see |
| <www.atmel.com/products/AVR>. |
| |
| 'as' implements all the standard AVR opcodes. The following table |
| summarizes the AVR opcodes, and their arguments. |
| |
| Legend: |
| r any register |
| d 'ldi' register (r16-r31) |
| v 'movw' even register (r0, r2, ..., r28, r30) |
| a 'fmul' register (r16-r23) |
| w 'adiw' register (r24,r26,r28,r30) |
| e pointer registers (X,Y,Z) |
| b base pointer register and displacement ([YZ]+disp) |
| z Z pointer register (for [e]lpm Rd,Z[+]) |
| M immediate value from 0 to 255 |
| n immediate value from 0 to 255 ( n = ~M ). Relocation impossible |
| s immediate value from 0 to 7 |
| P Port address value from 0 to 63. (in, out) |
| p Port address value from 0 to 31. (cbi, sbi, sbic, sbis) |
| K immediate value from 0 to 63 (used in 'adiw', 'sbiw') |
| i immediate value |
| l signed pc relative offset from -64 to 63 |
| L signed pc relative offset from -2048 to 2047 |
| h absolute code address (call, jmp) |
| S immediate value from 0 to 7 (S = s << 4) |
| ? use this opcode entry if no parameters, else use next opcode entry |
| |
| 1001010010001000 clc |
| 1001010011011000 clh |
| 1001010011111000 cli |
| 1001010010101000 cln |
| 1001010011001000 cls |
| 1001010011101000 clt |
| 1001010010111000 clv |
| 1001010010011000 clz |
| 1001010000001000 sec |
| 1001010001011000 seh |
| 1001010001111000 sei |
| 1001010000101000 sen |
| 1001010001001000 ses |
| 1001010001101000 set |
| 1001010000111000 sev |
| 1001010000011000 sez |
| 100101001SSS1000 bclr S |
| 100101000SSS1000 bset S |
| 1001010100001001 icall |
| 1001010000001001 ijmp |
| 1001010111001000 lpm ? |
| 1001000ddddd010+ lpm r,z |
| 1001010111011000 elpm ? |
| 1001000ddddd011+ elpm r,z |
| 0000000000000000 nop |
| 1001010100001000 ret |
| 1001010100011000 reti |
| 1001010110001000 sleep |
| 1001010110011000 break |
| 1001010110101000 wdr |
| 1001010111101000 spm |
| 000111rdddddrrrr adc r,r |
| 000011rdddddrrrr add r,r |
| 001000rdddddrrrr and r,r |
| 000101rdddddrrrr cp r,r |
| 000001rdddddrrrr cpc r,r |
| 000100rdddddrrrr cpse r,r |
| 001001rdddddrrrr eor r,r |
| 001011rdddddrrrr mov r,r |
| 100111rdddddrrrr mul r,r |
| 001010rdddddrrrr or r,r |
| 000010rdddddrrrr sbc r,r |
| 000110rdddddrrrr sub r,r |
| 001001rdddddrrrr clr r |
| 000011rdddddrrrr lsl r |
| 000111rdddddrrrr rol r |
| 001000rdddddrrrr tst r |
| 0111KKKKddddKKKK andi d,M |
| 0111KKKKddddKKKK cbr d,n |
| 1110KKKKddddKKKK ldi d,M |
| 11101111dddd1111 ser d |
| 0110KKKKddddKKKK ori d,M |
| 0110KKKKddddKKKK sbr d,M |
| 0011KKKKddddKKKK cpi d,M |
| 0100KKKKddddKKKK sbci d,M |
| 0101KKKKddddKKKK subi d,M |
| 1111110rrrrr0sss sbrc r,s |
| 1111111rrrrr0sss sbrs r,s |
| 1111100ddddd0sss bld r,s |
| 1111101ddddd0sss bst r,s |
| 10110PPdddddPPPP in r,P |
| 10111PPrrrrrPPPP out P,r |
| 10010110KKddKKKK adiw w,K |
| 10010111KKddKKKK sbiw w,K |
| 10011000pppppsss cbi p,s |
| 10011010pppppsss sbi p,s |
| 10011001pppppsss sbic p,s |
| 10011011pppppsss sbis p,s |
| 111101lllllll000 brcc l |
| 111100lllllll000 brcs l |
| 111100lllllll001 breq l |
| 111101lllllll100 brge l |
| 111101lllllll101 brhc l |
| 111100lllllll101 brhs l |
| 111101lllllll111 brid l |
| 111100lllllll111 brie l |
| 111100lllllll000 brlo l |
| 111100lllllll100 brlt l |
| 111100lllllll010 brmi l |
| 111101lllllll001 brne l |
| 111101lllllll010 brpl l |
| 111101lllllll000 brsh l |
| 111101lllllll110 brtc l |
| 111100lllllll110 brts l |
| 111101lllllll011 brvc l |
| 111100lllllll011 brvs l |
| 111101lllllllsss brbc s,l |
| 111100lllllllsss brbs s,l |
| 1101LLLLLLLLLLLL rcall L |
| 1100LLLLLLLLLLLL rjmp L |
| 1001010hhhhh111h call h |
| 1001010hhhhh110h jmp h |
| 1001010rrrrr0101 asr r |
| 1001010rrrrr0000 com r |
| 1001010rrrrr1010 dec r |
| 1001010rrrrr0011 inc r |
| 1001010rrrrr0110 lsr r |
| 1001010rrrrr0001 neg r |
| 1001000rrrrr1111 pop r |
| 1001001rrrrr1111 push r |
| 1001010rrrrr0111 ror r |
| 1001010rrrrr0010 swap r |
| 00000001ddddrrrr movw v,v |
| 00000010ddddrrrr muls d,d |
| 000000110ddd0rrr mulsu a,a |
| 000000110ddd1rrr fmul a,a |
| 000000111ddd0rrr fmuls a,a |
| 000000111ddd1rrr fmulsu a,a |
| 1001001ddddd0000 sts i,r |
| 1001000ddddd0000 lds r,i |
| 10o0oo0dddddbooo ldd r,b |
| 100!000dddddee-+ ld r,e |
| 10o0oo1rrrrrbooo std b,r |
| 100!001rrrrree-+ st e,r |
| 1001010100011001 eicall |
| 1001010000011001 eijmp |
| |
| |
| File: as.info, Node: Blackfin-Dependent, Next: CR16-Dependent, Prev: AVR-Dependent, Up: Machine Dependencies |
| |
| 9.6 Blackfin Dependent Features |
| =============================== |
| |
| * Menu: |
| |
| * Blackfin Options:: Blackfin Options |
| * Blackfin Syntax:: Blackfin Syntax |
| * Blackfin Directives:: Blackfin Directives |
| |
| |
| File: as.info, Node: Blackfin Options, Next: Blackfin Syntax, Up: Blackfin-Dependent |
| |
| 9.6.1 Options |
| ------------- |
| |
| '-mcpu=PROCESSOR[-SIREVISION]' |
| This option specifies the target processor. The optional |
| SIREVISION is not used in assembler. It's here such that GCC can |
| easily pass down its '-mcpu=' option. 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: 'bf504', 'bf506', 'bf512', 'bf514', |
| 'bf516', 'bf518', 'bf522', 'bf523', 'bf524', 'bf525', 'bf526', |
| 'bf527', 'bf531', 'bf532', 'bf533', 'bf534', 'bf535' (not |
| implemented yet), 'bf536', 'bf537', 'bf538', 'bf539', 'bf542', |
| 'bf542m', 'bf544', 'bf544m', 'bf547', 'bf547m', 'bf548', 'bf548m', |
| 'bf549', 'bf549m', 'bf561', and 'bf592'. |
| |
| '-mfdpic' |
| Assemble for the FDPIC ABI. |
| |
| '-mno-fdpic' |
| '-mnopic' |
| Disable -mfdpic. |
| |
| |
| File: as.info, Node: Blackfin Syntax, Next: Blackfin Directives, Prev: Blackfin Options, Up: Blackfin-Dependent |
| |
| 9.6.2 Syntax |
| ------------ |
| |
| 'Special Characters' |
| Assembler input is free format and may appear anywhere on the line. |
| One instruction may extend across multiple lines or more than one |
| instruction may appear on the same line. White space (space, tab, |
| comments or newline) may appear anywhere between tokens. A token |
| must not have embedded spaces. Tokens include numbers, register |
| names, keywords, user identifiers, and also some multicharacter |
| special symbols like "+=", "/*" or "||". |
| |
| Comments are introduced by the '#' character and extend to the end |
| of the current line. If the '#' appears as the first character of |
| a line, the whole line is treated as a comment, but in this case |
| the line can also be a logical line number directive (*note |
| Comments::) or a preprocessor control command (*note |
| Preprocessing::). |
| |
| 'Instruction Delimiting' |
| A semicolon must terminate every instruction. Sometimes a complete |
| instruction will consist of more than one operation. There are two |
| cases where this occurs. The first is when two general operations |
| are combined. Normally a comma separates the different parts, as |
| in |
| |
| a0= r3.h * r2.l, a1 = r3.l * r2.h ; |
| |
| The second case occurs when a general instruction is combined with |
| one or two memory references for joint issue. The latter portions |
| are set off by a "||" token. |
| |
| a0 = r3.h * r2.l || r1 = [p3++] || r4 = [i2++]; |
| |
| Multiple instructions can occur on the same line. Each must be |
| terminated by a semicolon character. |
| |
| 'Register Names' |
| |
| The assembler treats register names and instruction keywords in a |
| case insensitive manner. User identifiers are case sensitive. |
| Thus, R3.l, R3.L, r3.l and r3.L are all equivalent input to the |
| assembler. |
| |
| Register names are reserved and may not be used as program |
| identifiers. |
| |
| Some operations (such as "Move Register") require a register pair. |
| Register pairs are always data registers and are denoted using a |
| colon, eg., R3:2. The larger number must be written firsts. Note |
| that the hardware only supports odd-even pairs, eg., R7:6, R5:4, |
| R3:2, and R1:0. |
| |
| Some instructions (such as -SP (Push Multiple)) require a group of |
| adjacent registers. Adjacent registers are denoted in the syntax |
| by the range enclosed in parentheses and separated by a colon, eg., |
| (R7:3). Again, the larger number appears first. |
| |
| Portions of a particular register may be individually specified. |
| This is written with a dot (".") following the register name and |
| then a letter denoting the desired portion. For 32-bit registers, |
| ".H" denotes the most significant ("High") portion. ".L" denotes |
| the least-significant portion. The subdivisions of the 40-bit |
| registers are described later. |
| |
| 'Accumulators' |
| The set of 40-bit registers A1 and A0 that normally contain data |
| that is being manipulated. Each accumulator can be accessed in |
| four ways. |
| |
| 'one 40-bit register' |
| The register will be referred to as A1 or A0. |
| 'one 32-bit register' |
| The registers are designated as A1.W or A0.W. |
| 'two 16-bit registers' |
| The registers are designated as A1.H, A1.L, A0.H or A0.L. |
| 'one 8-bit register' |
| The registers are designated as A1.X or A0.X for the bits that |
| extend beyond bit 31. |
| |
| 'Data Registers' |
| The set of 32-bit registers (R0, R1, R2, R3, R4, R5, R6 and R7) |
| that normally contain data for manipulation. These are abbreviated |
| as D-register or Dreg. Data registers can be accessed as 32-bit |
| registers or as two independent 16-bit registers. The least |
| significant 16 bits of each register is called the "low" half and |
| is designated with ".L" following the register name. The most |
| significant 16 bits are called the "high" half and is designated |
| with ".H" following the name. |
| |
| R7.L, r2.h, r4.L, R0.H |
| |
| 'Pointer Registers' |
| The set of 32-bit registers (P0, P1, P2, P3, P4, P5, SP and FP) |
| that normally contain byte addresses of data structures. These are |
| abbreviated as P-register or Preg. |
| |
| p2, p5, fp, sp |
| |
| 'Stack Pointer SP' |
| The stack pointer contains the 32-bit address of the last occupied |
| byte location in the stack. The stack grows by decrementing the |
| stack pointer. |
| |
| 'Frame Pointer FP' |
| The frame pointer contains the 32-bit address of the previous frame |
| pointer in the stack. It is located at the top of a frame. |
| |
| 'Loop Top' |
| LT0 and LT1. These registers contain the 32-bit address of the top |
| of a zero overhead loop. |
| |
| 'Loop Count' |
| LC0 and LC1. These registers contain the 32-bit counter of the |
| zero overhead loop executions. |
| |
| 'Loop Bottom' |
| LB0 and LB1. These registers contain the 32-bit address of the |
| bottom of a zero overhead loop. |
| |
| 'Index Registers' |
| The set of 32-bit registers (I0, I1, I2, I3) that normally contain |
| byte addresses of data structures. Abbreviated I-register or Ireg. |
| |
| 'Modify Registers' |
| The set of 32-bit registers (M0, M1, M2, M3) that normally contain |
| offset values that are added and subtracted to one of the index |
| registers. Abbreviated as Mreg. |
| |
| 'Length Registers' |
| The set of 32-bit registers (L0, L1, L2, L3) that normally contain |
| the length in bytes of the circular buffer. Abbreviated as Lreg. |
| Clear the Lreg to disable circular addressing for the corresponding |
| Ireg. |
| |
| 'Base Registers' |
| The set of 32-bit registers (B0, B1, B2, B3) that normally contain |
| the base address in bytes of the circular buffer. Abbreviated as |
| Breg. |
| |
| 'Floating Point' |
| The Blackfin family has no hardware floating point but the .float |
| directive generates ieee floating point numbers for use with |
| software floating point libraries. |
| |
| 'Blackfin Opcodes' |
| For detailed information on the Blackfin machine instruction set, |
| see the Blackfin(r) Processor Instruction Set Reference. |
| |