| This is as.info, produced by makeinfo version 4.8 from as.texinfo. |
| |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * As: (as). The GNU assembler. |
| * Gas: (as). The GNU assembler. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU Assembler "as". |
| |
| Copyright (C) 1991-2013 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". |
| |
| |
| 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.23.91. |
| |
| 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] |
| [-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] |
| [-march=CPU] [-mtune=CPU] [-mips1] [-mips2] |
| [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2] |
| [-mips64] [-mips64r2] |
| [-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] |
| [-mmt] [-mno-mt] |
| [-mmcu] [-mno-mcu] |
| [-minsn32] [-mno-insn32] |
| [-mfix7000] [-mno-fix7000] |
| [-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 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 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] |
| |
| |
| _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. |
| |
| `--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. |
| |
| `-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' |
| `-mips64' |
| `-mips64r2' |
| Generate code for a particular MIPS Instruction Set Architecture |
| level. `-mips1' is an alias for `-march=r3000', `-mips2' is an |
| alias for `-march=r6000', `-mips3' is an alias for `-march=r4000' |
| and `-mips4' is an alias for `-march=r8000'. `-mips5', `-mips32', |
| `-mips32r2', `-mips64', and `-mips64r2' correspond to generic MIPS |
| V, MIPS32, MIPS32 Release 2, MIPS64, and MIPS64 Release 2 ISA |
| processors, respectively. |
| |
| `-march=CPU' |
| Generate code for a particular MIPS CPU. |
| |
| `-mtune=CPU' |
| Schedule and tune for a particular MIPS CPU. |
| |
| `-mfix7000' |
| `-mno-fix7000' |
| Cause nops to be inserted if the read of the destination register |
| of an mfhi or mflo instruction occurs in the following two |
| instructions. |
| |
| `-mdebug' |
| `-no-mdebug' |
| Cause stabs-style debugging output to go into an ECOFF-style |
| .mdebug section instead of the standard ELF .stabs sections. |
| |
| `-mpdr' |
| `-mno-pdr' |
| Control generation of `.pdr' sections. |
| |
| `-mgp32' |
| `-mfp32' |
| The register sizes are normally inferred from the ISA and ABI, but |
| these flags force a certain group of registers to be treated as 32 |
| bits wide at all times. `-mgp32' controls the size of |
| general-purpose registers and `-mfp32' controls the size of |
| floating-point registers. |
| |
| `-mips16' |
| `-no-mips16' |
| Generate code for the MIPS 16 processor. This is equivalent to |
| putting `.set mips16' at the start of the assembly file. |
| `-no-mips16' turns off this option. |
| |
| `-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. |
| |
| `-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 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 `.L6C-A5'. |
| |
| |
| File: as.info, Node: Dot, Next: Symbol Attributes, Prev: Symbol Names, Up: Symbols |
| |
| 5.4 The Special Dot Symbol |
| ========================== |
| |
| The special symbol `.' refers to the current address that `as' is |
| assembling into. Thus, the expression `melvin: .long .' defines |
| `melvin' to contain its own address. Assigning a value to `.' is |
| treated the same as a `.org' directive. Thus, the expression `.=.+4' |
| is the same as saying `.space 4'. |
| |
| |
| File: as.info, Node: Symbol Attributes, Prev: Dot, Up: Symbols |
| |
| 5.5 Symbol Attributes |
| ===================== |
| |
| Every symbol has, as well as its name, the attributes "Value" and |
| "Type". Depending on output format, symbols can also have auxiliary |
| attributes. |
| |
| If you use a symbol without defining it, `as' assumes zero for all |
| these attributes, and probably won't warn you. This makes the symbol |
| an externally defined symbol, which is generally what you would want. |
| |
| * Menu: |
| |
| * Symbol Value:: Value |
| * Symbol Type:: Type |
| |
| |
| * a.out Symbols:: Symbol Attributes: `a.out' |
| |
| * COFF Symbols:: Symbol Attributes for COFF |
| |
| * SOM Symbols:: Symbol Attributes for SOM |
| |
| |
| File: as.info, Node: Symbol Value, Next: Symbol Type, Up: Symbol Attributes |
| |
| 5.5.1 Value |
| ----------- |
| |
| The value of a symbol is (usually) 32 bits. For a symbol which labels a |
| location in the text, data, bss or absolute sections the value is the |
| number of addresses from the start of that section to the label. |
| Naturally for text, data and bss sections the value of a symbol changes |
| as `ld' changes section base addresses during linking. Absolute |
| symbols' values do not change during linking: that is why they are |
| called absolute. |
| |
| The value of an undefined symbol is treated in a special way. If it |
| is 0 then the symbol is not defined in this assembler source file, and |
| `ld' tries to determine its value from other files linked into the same |
| program. You make this kind of symbol simply by mentioning a symbol |
| name without defining it. A non-zero value represents a `.comm' common |
| declaration. The value is how much common storage to reserve, in bytes |
| (addresses). The symbol refers to the first address of the allocated |
| storage. |
| |
| |
| File: as.info, Node: Symbol Type, Next: a.out Symbols, Prev: Symbol Value, Up: Symbol Attributes |
| |
| 5.5.2 Type |
| ---------- |
| |
| The type attribute of a symbol contains relocation (section) |
| information, any flag settings indicating that a symbol is external, and |
| (optionally), other information for linkers and debuggers. The exact |
| format depends on the object-code output format in use. |
| |
| |
| File: as.info, Node: a.out Symbols, Next: COFF Symbols, Prev: Symbol Type, Up: Symbol Attributes |
| |
| 5.5.3 Symbol Attributes: `a.out' |
| -------------------------------- |
| |
| * Menu: |
| |
| * Symbol Desc:: Descriptor |
| * Symbol Other:: Other |
| |
| |
| File: as.info, Node: Symbol Desc, Next: Symbol Other, Up: a.out Symbols |
| |
| 5.5.3.1 Descriptor |
| .................. |
| |
| This is an arbitrary 16-bit value. You may establish a symbol's |
| descriptor value by using a `.desc' statement (*note `.desc': Desc.). |
| A descriptor value means nothing to `as'. |
| |
| |
| File: as.info, Node: Symbol Other, Prev: Symbol Desc, Up: a.out Symbols |
| |
| 5.5.3.2 Other |
| ............. |
| |
| This is an arbitrary 8-bit value. It means nothing to `as'. |
| |
| |
| File: as.info, Node: COFF Symbols, Next: SOM Symbols, Prev: a.out Symbols, Up: Symbol Attributes |
| |
| 5.5.4 Symbol Attributes for COFF |
| -------------------------------- |
| |
| The COFF format supports a multitude of auxiliary symbol attributes; |
| like the primary symbol attributes, they are set between `.def' and |
| `.endef' directives. |
| |
| 5.5.4.1 Primary Attributes |
| .......................... |
| |
| The symbol name is set with `.def'; the value and type, respectively, |
| with `.val' and `.type'. |
| |
| 5.5.4.2 Auxiliary Attributes |
| ............................ |
| |
| The `as' directives `.dim', `.line', `.scl', `.size', `.tag', and |
| `.weak' can generate auxiliary symbol table information for COFF. |
| |
| |
| File: as.info, Node: SOM Symbols, Prev: COFF Symbols, Up: Symbol Attributes |
| |
| 5.5.5 Symbol Attributes for SOM |
| ------------------------------- |
| |
| The SOM format for the HPPA supports a multitude of symbol attributes |
| set with the `.EXPORT' and `.IMPORT' directives. |
| |
| The attributes are described in `HP9000 Series 800 Assembly Language |
| Reference Manual' (HP 92432-90001) under the `IMPORT' and `EXPORT' |
| assembler directive documentation. |
| |
| |
| File: as.info, Node: Expressions, Next: Pseudo Ops, Prev: Symbols, Up: Top |
| |
| 6 Expressions |
| ************* |
| |
| An "expression" specifies an address or numeric value. Whitespace may |
| precede and/or follow an expression. |
| |
| The result of an expression must be an absolute number, or else an |
| offset into a particular section. If an expression is not absolute, |
| and there is not enough information when `as' sees the expression to |
| know its section, a second pass over the source program might be |
| necessary to interpret the expression--but the second pass is currently |
| not implemented. `as' aborts with an error message in this situation. |
| |
| * Menu: |
| |
| * Empty Exprs:: Empty Expressions |
| * Integer Exprs:: Integer Expressions |
| |
| |
| File: as.info, Node: Empty Exprs, Next: Integer Exprs, Up: Expressions |
| |
| 6.1 Empty Expressions |
| ===================== |
| |
| An empty expression has no value: it is just whitespace or null. |
| Wherever an absolute expression is required, you may omit the |
| expression, and `as' assumes a value of (absolute) 0. This is |
| compatible with other assemblers. |
| |
| |
| File: as.info, Node: Integer Exprs, Prev: Empty Exprs, Up: Expressions |
| |
| 6.2 Integer Expressions |
| ======================= |
| |
| An "integer expression" is one or more _arguments_ delimited by |
| _operators_. |
| |
| * Menu: |
| |
| * Arguments:: Arguments |
| * Operators:: Operators |
| * Prefix Ops:: Prefix Operators |
| * Infix Ops:: Infix Operators |
| |
| |
| File: as.info, Node: Arguments, Next: Operators, Up: Integer Exprs |
| |
| 6.2.1 Arguments |
| --------------- |
| |
| "Arguments" are symbols, numbers or subexpressions. In other contexts |
| arguments are sometimes called "arithmetic operands". In this manual, |
| to avoid confusing them with the "instruction operands" of the machine |
| language, we use the term "argument" to refer to parts of expressions |
| only, reserving the word "operand" to refer only to machine instruction |
| operands. |
| |
| Symbols are evaluated to yield {SECTION NNN} where SECTION is one of |
| text, data, bss, absolute, or undefined. NNN is a signed, 2's |
| complement 32 bit integer. |
| |
| Numbers are usually integers. |
| |
| A number can be a flonum or bignum. In this case, you are warned |
| that only the low order 32 bits are used, and `as' pretends these 32 |
| bits are an integer. You may write integer-manipulating instructions |
| that act on exotic constants, compatible with other assemblers. |
| |
| Subexpressions are a left parenthesis `(' followed by an integer |
| expression, followed by a right parenthesis `)'; or a prefix operator |
| followed by an argument. |
| |
| |
| File: as.info, Node: Operators, Next: Prefix Ops, Prev: Arguments, Up: Integer Exprs |
| |
| 6.2.2 Operators |
| --------------- |
| |
| "Operators" are arithmetic functions, like `+' or `%'. Prefix |
| operators are followed by an argument. Infix operators appear between |
| their arguments. Operators may be preceded and/or followed by |
| whitespace. |
| |
| |
| File: as.info, Node: Prefix Ops, Next: Infix Ops, Prev: Operators, Up: Integer Exprs |
| |
| 6.2.3 Prefix Operator |
| --------------------- |
| |
| `as' has the following "prefix operators". They each take one |
| argument, which must be absolute. |
| |
| `-' |
| "Negation". Two's complement negation. |
| |
| `~' |
| "Complementation". Bitwise not. |
| |
| |
| File: as.info, Node: Infix Ops, Prev: Prefix Ops, Up: Integer Exprs |
| |
| 6.2.4 Infix Operators |
| --------------------- |
| |
| "Infix operators" take two arguments, one on either side. Operators |
| have precedence, but operations with equal precedence are performed left |
| to right. Apart from `+' or `-', both arguments must be absolute, and |
| the result is absolute. |
| |
| 1. Highest Precedence |
| |
| `*' |
| "Multiplication". |
| |
| `/' |
| "Division". Truncation is the same as the C operator `/' |
| |
| `%' |
| "Remainder". |
| |
| `<<' |
| "Shift Left". Same as the C operator `<<'. |
| |
| `>>' |
| "Shift Right". Same as the C operator `>>'. |
| |
| 2. Intermediate precedence |
| |
| `|' |
| "Bitwise Inclusive Or". |
| |
| `&' |
| "Bitwise And". |
| |
| `^' |
| "Bitwise Exclusive Or". |
| |
| `!' |
| "Bitwise Or Not". |
| |
| 3. Low Precedence |
| |
| `+' |
| "Addition". If either argument is absolute, the result has |
| the section of the other argument. You may not add together |
| arguments from different sections. |
| |
| `-' |
| "Subtraction". If the right argument is absolute, the result |
| has the section of the left argument. If both arguments are |
| in the same section, the result is absolute. You may not |
| subtract arguments from different sections. |
| |
| `==' |
| "Is Equal To" |
| |
| `<>' |
| `!=' |
| "Is Not Equal To" |
| |
| `<' |
| "Is Less Than" |
| |
| `>' |
| "Is Greater Than" |
| |
| `>=' |
| "Is Greater Than Or Equal To" |
| |
| `<=' |
| "Is Less Than Or Equal To" |
| |
| The comparison operators can be used as infix operators. A |
| true results has a value of -1 whereas a false result has a |
| value of 0. Note, these operators perform signed |
| comparisons. |
| |
| 4. Lowest Precedence |
| |
| `&&' |
| "Logical And". |
| |
| `||' |
| "Logical Or". |
| |
| These two logical operations can be used to combine the |
| results of sub expressions. Note, unlike the comparison |
| operators a true result returns a value of 1 but a false |
| results does still return 0. Also note that the logical or |
| operator has a slightly lower precedence than logical and. |
| |
| |
| In short, it's only meaningful to add or subtract the _offsets_ in an |
| address; you can only have a defined section in one of the two |
| arguments. |
| |
| |
| File: as.info, Node: Pseudo Ops, Next: 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, or32, |
| s390, sparc, tic4x, tic80 and xtensa, the first expression is the |
| alignment request in bytes. For example `.align 8' advances the |
| location counter until it is a multiple of 8. If the location counter |
| is already a multiple of 8, no change is needed. For the tic54x, the |
| first expression is the alignment request in words. |
| |
| For other systems, including 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 |
| |