source: trunk/binutils/gas/doc/as.info-4@ 3822

This is as.info, produced by makeinfo version 4.3 from as.texinfo.

START-INFO-DIR-ENTRY
* As: (as).                     The GNU assembler.
* Gas: (as).                    The GNU assembler.
END-INFO-DIR-ENTRY

   This file documents the GNU Assembler "as".

   Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 2002
Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".


File: as.info,  Node: Tag,  Next: Text,  Prev: Symver,  Up: Pseudo Ops

`.tag STRUCTNAME'
=================

   This directive is generated by compilers to include auxiliary
debugging information in the symbol table.  It is only permitted inside
`.def'/`.endef' pairs.  Tags are used to link structure definitions in
the symbol table with instances of those structures.

   `.tag' is only used when generating COFF format output; when `as' is
generating `b.out', it accepts this directive but ignores it.


File: as.info,  Node: Text,  Next: Title,  Prev: Tag,  Up: Pseudo Ops

`.text SUBSECTION'
==================

   Tells `as' to assemble the following statements onto the end of the
text subsection numbered SUBSECTION, which is an absolute expression.
If SUBSECTION is omitted, subsection number zero is used.


File: as.info,  Node: Title,  Next: Type,  Prev: Text,  Up: Pseudo Ops

`.title "HEADING"'
==================

   Use HEADING as the title (second line, immediately after the source
file name and pagenumber) when generating assembly listings.

   This directive affects subsequent pages, as well as the current page
if it appears within ten lines of the top of a page.


File: as.info,  Node: Type,  Next: Uleb128,  Prev: Title,  Up: Pseudo Ops

`.type'
=======

   This directive is used to set the type of a symbol.

COFF Version
------------

   For COFF targets, this directive is permitted only within
`.def'/`.endef' pairs.  It is used like this:

     .type INT

   This records the integer INT as the type attribute of a symbol table
entry.

   `.type' is associated only with COFF format output; when `as' is
configured for `b.out' output, it accepts this directive but ignores it.

ELF Version
-----------

   For ELF targets, the `.type' directive is used like this:

     .type NAME , TYPE DESCRIPTION

   This sets the type of symbol NAME to be either a function symbol or
an object symbol.  There are five different syntaxes supported for the
TYPE DESCRIPTION field, in order to provide compatibility with various
other assemblers.  The syntaxes supported are:

       .type <name>,#function
       .type <name>,#object
     
       .type <name>,@function
       .type <name>,@object
     
       .type <name>,%function
       .type <name>,%object
     
       .type <name>,"function"
       .type <name>,"object"
     
       .type <name> STT_FUNCTION
       .type <name> STT_OBJECT


File: as.info,  Node: Uleb128,  Next: Val,  Prev: Type,  Up: Pseudo Ops

`.uleb128 EXPRESSIONS'
======================

   ULEB128 stands for "unsigned little endian base 128."  This is a
compact, variable length representation of numbers used by the DWARF
symbolic debugging format.  *Note `.sleb128': Sleb128.


File: as.info,  Node: Val,  Next: Version,  Prev: Uleb128,  Up: Pseudo Ops

`.val ADDR'
===========

   This directive, permitted only within `.def'/`.endef' pairs, records
the address ADDR as the value attribute of a symbol table entry.

   `.val' is used only for COFF output; when `as' is configured for
`b.out', it accepts this directive but ignores it.


File: as.info,  Node: Version,  Next: VTableEntry,  Prev: Val,  Up: Pseudo Ops

`.version "STRING"'
===================

   This directive creates a `.note' section and places into it an ELF
formatted note of type NT_VERSION.  The note's name is set to `string'.


File: as.info,  Node: VTableEntry,  Next: VTableInherit,  Prev: Version,  Up: Pseudo Ops

`.vtable_entry TABLE, OFFSET'
=============================

   This directive finds or creates a symbol `table' and creates a
`VTABLE_ENTRY' relocation for it with an addend of `offset'.


File: as.info,  Node: VTableInherit,  Next: Weak,  Prev: VTableEntry,  Up: Pseudo Ops

`.vtable_inherit CHILD, PARENT'
===============================

   This directive finds the symbol `child' and finds or creates the
symbol `parent' and then creates a `VTABLE_INHERIT' relocation for the
parent whose addend is the value of the child symbol.  As a special
case the parent name of `0' is treated as refering the `*ABS*' section.


File: as.info,  Node: Weak,  Next: Word,  Prev: VTableInherit,  Up: Pseudo Ops

`.weak NAMES'
=============

   This directive sets the weak attribute on the comma separated list
of symbol `names'.  If the symbols do not already exist, they will be
created.


File: as.info,  Node: Word,  Next: Deprecated,  Prev: Weak,  Up: Pseudo Ops

`.word EXPRESSIONS'
===================

   This directive expects zero or more EXPRESSIONS, of any section,
separated by commas.

   The size of the number emitted, and its byte order, depend on what
target computer the assembly is for.

     _Warning: Special Treatment to support Compilers_

   Machines with a 32-bit address space, but that do less than 32-bit
addressing, require the following special treatment.  If the machine of
interest to you does 32-bit addressing (or doesn't require it; *note
Machine Dependencies::), you can ignore this issue.

   In order to assemble compiler output into something that works, `as'
occasionally does strange things to `.word' directives.  Directives of
the form `.word sym1-sym2' are often emitted by compilers as part of
jump tables.  Therefore, when `as' assembles a directive of the form
`.word sym1-sym2', and the difference between `sym1' and `sym2' does
not fit in 16 bits, `as' creates a "secondary jump table", immediately
before the next label.  This secondary jump table is preceded by a
short-jump to the first byte after the secondary table.  This
short-jump prevents the flow of control from accidentally falling into
the new table.  Inside the table is a long-jump to `sym2'.  The
original `.word' contains `sym1' minus the address of the long-jump to
`sym2'.

   If there were several occurrences of `.word sym1-sym2' before the
secondary jump table, all of them are adjusted.  If there was a `.word
sym3-sym4', that also did not fit in sixteen bits, a long-jump to
`sym4' is included in the secondary jump table, and the `.word'
directives are adjusted to contain `sym3' minus the address of the
long-jump to `sym4'; and so on, for as many entries in the original
jump table as necessary.


File: as.info,  Node: Deprecated,  Prev: Word,  Up: Pseudo Ops

Deprecated Directives
=====================

   One day these directives won't work.  They are included for
compatibility with older assemblers.
.abort

.line

File: as.info,  Node: Machine Dependencies,  Next: Reporting Bugs,  Prev: Pseudo Ops,  Up: Top

Machine Dependent Features
**************************

   The machine instruction sets are (almost by definition) different on
each machine where `as' runs.  Floating point representations vary as
well, and `as' often supports a few additional directives or
command-line options for compatibility with other assemblers on a
particular platform.  Finally, some versions of `as' support special
pseudo-instructions for branch optimization.

   This chapter discusses most of these differences, though it does not
include details on any machine's instruction set.  For details on that
subject, see the hardware manufacturer's manual.

* Menu:


* AMD29K-Dependent::            AMD 29K Dependent Features

* Alpha-Dependent::             Alpha Dependent Features

* ARC-Dependent::               ARC Dependent Features

* ARM-Dependent::               ARM Dependent Features

* CRIS-Dependent::              CRIS Dependent Features

* D10V-Dependent::              D10V Dependent Features

* D30V-Dependent::              D30V Dependent Features

* H8/300-Dependent::            Renesas H8/300 Dependent Features

* H8/500-Dependent::            Renesas H8/500 Dependent Features

* HPPA-Dependent::              HPPA Dependent Features

* ESA/390-Dependent::           IBM ESA/390 Dependent Features

* i386-Dependent::              Intel 80386 and AMD x86-64 Dependent Features

* i860-Dependent::              Intel 80860 Dependent Features

* i960-Dependent::              Intel 80960 Dependent Features

* IP2K-Dependent::              IP2K Dependent Features

* M32R-Dependent::              M32R Dependent Features

* M68K-Dependent::              M680x0 Dependent Features

* M68HC11-Dependent::           M68HC11 and 68HC12 Dependent Features

* M88K-Dependent::              M880x0 Dependent Features

* MIPS-Dependent::              MIPS Dependent Features

* MMIX-Dependent::              MMIX Dependent Features

* MSP430-Dependent::            MSP430 Dependent Features

* SH-Dependent::                Renesas / SuperH SH Dependent Features
* SH64-Dependent::              SuperH SH64 Dependent Features

* PDP-11-Dependent::            PDP-11 Dependent Features

* PJ-Dependent::                picoJava Dependent Features

* PPC-Dependent::               PowerPC Dependent Features

* Sparc-Dependent::             SPARC Dependent Features

* TIC54X-Dependent::            TI TMS320C54x Dependent Features

* V850-Dependent::              V850 Dependent Features

* Xtensa-Dependent::            Xtensa Dependent Features

* Z8000-Dependent::             Z8000 Dependent Features

* Vax-Dependent::               VAX Dependent Features


File: as.info,  Node: AMD29K-Dependent,  Next: Alpha-Dependent,  Up: Machine Dependencies

AMD 29K Dependent Features
==========================

* Menu:

* AMD29K Options::              Options
* AMD29K Syntax::               Syntax
* AMD29K Floating Point::       Floating Point
* AMD29K Directives::           AMD 29K Machine Directives
* AMD29K Opcodes::              Opcodes


File: as.info,  Node: AMD29K Options,  Next: AMD29K Syntax,  Up: AMD29K-Dependent

Options
-------

   `as' has no additional command-line options for the AMD 29K family.


File: as.info,  Node: AMD29K Syntax,  Next: AMD29K Floating Point,  Prev: AMD29K Options,  Up: AMD29K-Dependent

Syntax
------

* Menu:

* AMD29K-Macros::               Macros
* AMD29K-Chars::                Special Characters
* AMD29K-Regs::                 Register Names


File: as.info,  Node: AMD29K-Macros,  Next: AMD29K-Chars,  Up: AMD29K Syntax

Macros
......

   The macro syntax used on the AMD 29K is like that described in the
AMD 29K Family Macro Assembler Specification.  Normal `as' macros
should still work.


File: as.info,  Node: AMD29K-Chars,  Next: AMD29K-Regs,  Prev: AMD29K-Macros,  Up: AMD29K Syntax

Special Characters
..................

   `;' is the line comment character.

   The character `?' is permitted in identifiers (but may not begin an
identifier).


File: as.info,  Node: AMD29K-Regs,  Prev: AMD29K-Chars,  Up: AMD29K Syntax

Register Names
..............

   General-purpose registers are represented by predefined symbols of
the form `GRNNN' (for global registers) or `LRNNN' (for local
registers), where NNN represents a number between `0' and `127',
written with no leading zeros.  The leading letters may be in either
upper or lower case; for example, `gr13' and `LR7' are both valid
register names.

   You may also refer to general-purpose registers by specifying the
register number as the result of an expression (prefixed with `%%' to
flag the expression as a register number):
     %%EXPRESSION

--where EXPRESSION must be an absolute expression evaluating to a
number between `0' and `255'.  The range [0, 127] refers to global
registers, and the range [128, 255] to local registers.

   In addition, `as' understands the following protected
special-purpose register names for the AMD 29K family:

       vab    chd    pc0
       ops    chc    pc1
       cps    rbp    pc2
       cfg    tmc    mmu
       cha    tmr    lru

   These unprotected special-purpose register names are also recognized:
       ipc    alu    fpe
       ipa    bp     inte
       ipb    fc     fps
       q      cr     exop


File: as.info,  Node: AMD29K Floating Point,  Next: AMD29K Directives,  Prev: AMD29K Syntax,  Up: AMD29K-Dependent

Floating Point
--------------

   The AMD 29K family uses IEEE floating-point numbers.


File: as.info,  Node: AMD29K Directives,  Next: AMD29K Opcodes,  Prev: AMD29K Floating Point,  Up: AMD29K-Dependent

AMD 29K Machine Directives
--------------------------

`.block SIZE , FILL'
     This directive emits SIZE bytes, each of value FILL.  Both SIZE
     and FILL are absolute expressions.  If the comma and FILL are
     omitted, FILL is assumed to be zero.

     In other versions of the GNU assembler, this directive is called
     `.space'.

`.cputype'
     This directive is ignored; it is accepted for compatibility with
     other AMD 29K assemblers.

`.file'
     This directive is ignored; it is accepted for compatibility with
     other AMD 29K assemblers.

          _Warning:_ in other versions of the GNU assembler, `.file' is
          used for the directive called `.app-file' in the AMD 29K
          support.

`.line'
     This directive is ignored; it is accepted for compatibility with
     other AMD 29K assemblers.

`.sect'
     This directive is ignored; it is accepted for compatibility with
     other AMD 29K assemblers.

`.use SECTION NAME'
     Establishes the section and subsection for the following code;
     SECTION NAME may be one of `.text', `.data', `.data1', or `.lit'.
     With one of the first three SECTION NAME options, `.use' is
     equivalent to the machine directive SECTION NAME; the remaining
     case, `.use .lit', is the same as `.data 200'.


File: as.info,  Node: AMD29K Opcodes,  Prev: AMD29K Directives,  Up: AMD29K-Dependent

Opcodes
-------

   `as' implements all the standard AMD 29K opcodes.  No additional
pseudo-instructions are needed on this family.

   For information on the 29K machine instruction set, see `Am29000
User's Manual', Advanced Micro Devices, Inc.


File: as.info,  Node: Alpha-Dependent,  Next: ARC-Dependent,  Prev: AMD29K-Dependent,  Up: Machine Dependencies

Alpha Dependent Features
========================

* Menu:

* Alpha Notes::                Notes
* Alpha Options::              Options
* Alpha Syntax::               Syntax
* Alpha Floating Point::       Floating Point
* Alpha Directives::           Alpha Machine Directives
* Alpha Opcodes::              Opcodes


File: as.info,  Node: Alpha Notes,  Next: Alpha Options,  Up: Alpha-Dependent

Notes
-----

   The documentation here is primarily for the ELF object format.  `as'
also supports the ECOFF and EVAX formats, but features specific to
these formats are not yet documented.


File: as.info,  Node: Alpha Options,  Next: Alpha Syntax,  Prev: Alpha Notes,  Up: Alpha-Dependent

Options
-------

`-mCPU'
     This option specifies the target processor.  If an attempt is made
     to assemble an instruction which will not execute on the target
     processor, the assembler may either expand the instruction as a
     macro or issue an error message.  This option is equivalent to the
     `.arch' directive.

     The following processor names are recognized: `21064', `21064a',
     `21066', `21068', `21164', `21164a', `21164pc', `21264', `21264a',
     `21264b', `ev4', `ev5', `lca45', `ev5', `ev56', `pca56', `ev6',
     `ev67', `ev68'.  The special name `all' may be used to allow the
     assembler to accept instructions valid for any Alpha processor.

     In order to support existing practice in OSF/1 with respect to
     `.arch', and existing practice within `MILO' (the Linux ARC
     bootloader), the numbered processor names (e.g. 21064) enable the
     processor-specific PALcode instructions, while the
     "electro-vlasic" names (e.g. `ev4') do not.

`-mdebug'
`-no-mdebug'
     Enables or disables the generation of `.mdebug' encapsulation for
     stabs directives and procedure descriptors.  The default is to
     automatically enable `.mdebug' when the first stabs directive is
     seen.

`-relax'
     This option forces all relocations to be put into the object file,
     instead of saving space and resolving some relocations at assembly
     time.  Note that this option does not propagate all symbol
     arithmetic into the object file, because not all symbol arithmetic
     can be represented.  However, the option can still be useful in
     specific applications.

`-g'
     This option is used when the compiler generates debug information.
     When `gcc' is using `mips-tfile' to generate debug information
     for ECOFF, local labels must be passed through to the object file.
     Otherwise this option has no effect.

`-GSIZE'
     A local common symbol larger than SIZE is placed in `.bss', while
     smaller symbols are placed in `.sbss'.

`-F'
`-32addr'
     These options are ignored for backward compatibility.


File: as.info,  Node: Alpha Syntax,  Next: Alpha Floating Point,  Prev: Alpha Options,  Up: Alpha-Dependent

Syntax
------

   The assembler syntax closely follow the Alpha Reference Manual;
assembler directives and general syntax closely follow the OSF/1 and
OpenVMS syntax, with a few differences for ELF.

* Menu:

* Alpha-Chars::                Special Characters
* Alpha-Regs::                 Register Names
* Alpha-Relocs::               Relocations


File: as.info,  Node: Alpha-Chars,  Next: Alpha-Regs,  Up: Alpha Syntax

Special Characters
..................

   `#' is the line comment character.

   `;' can be used instead of a newline to separate statements.


File: as.info,  Node: Alpha-Regs,  Next: Alpha-Relocs,  Prev: Alpha-Chars,  Up: Alpha Syntax

Register Names
..............

   The 32 integer registers are refered to as `$N' or `$rN'.  In
addition, registers 15, 28, 29, and 30 may be refered to by the symbols
`$fp', `$at', `$gp', and `$sp' respectively.

   The 32 floating-point registers are refered to as `$fN'.


File: as.info,  Node: Alpha-Relocs,  Prev: Alpha-Regs,  Up: Alpha Syntax

Relocations
...........

   Some of these relocations are available for ECOFF, but mostly only
for ELF.  They are modeled after the relocation format introduced in
Digial Unix 4.0, but there are additions.

   The format is `!TAG' or `!TAG!NUMBER' where TAG is the name of the
relocation.  In some cases NUMBER is used to relate specific
instructions.

   The relocation is placed at the end of the instruction like so:

     ldah  $0,a($29)    !gprelhigh
     lda   $0,a($0)     !gprellow
     ldq   $1,b($29)    !literal!100
     ldl   $2,0($1)     !lituse_base!100

`!literal'
`!literal!N'
     Used with an `ldq' instruction to load the address of a symbol
     from the GOT.

     A sequence number N is optional, and if present is used to pair
     `lituse' relocations with this `literal' relocation.  The `lituse'
     relocations are used by the linker to optimize the code based on
     the final location of the symbol.

     Note that these optimizations are dependent on the data flow of the
     program.  Therefore, if _any_ `lituse' is paired with a `literal'
     relocation, then _all_ uses of the register set by the `literal'
     instruction must also be marked with `lituse' relocations.  This
     is because the original `literal' instruction may be deleted or
     transformed into another instruction.

     Also note that there may be a one-to-many relationship between
     `literal' and `lituse', but not a many-to-one.  That is, if there
     are two code paths that load up the same address and feed the
     value to a single use, then the use may not use a `lituse'
     relocation.

`!lituse_base!N'
     Used with any memory format instruction (e.g. `ldl') to indicate
     that the literal is used for an address load.  The offset field of
     the instruction must be zero.  During relaxation, the code may be
     altered to use a gp-relative load.

`!lituse_jsr!N'
     Used with a register branch format instruction (e.g. `jsr') to
     indicate that the literal is used for a call.  During relaxation,
     the code may be altered to use a direct branch (e.g. `bsr').

`!lituse_bytoff!N'
     Used with a byte mask instruction (e.g. `extbl') to indicate that
     only the low 3 bits of the address are relevant.  During
     relaxation, the code may be altered to use an immediate instead of
     a register shift.

`!lituse_addr!N'
     Used with any other instruction to indicate that the original
     address is in fact used, and the original `ldq' instruction may
     not be altered or deleted.  This is useful in conjunction with
     `lituse_jsr' to test whether a weak symbol is defined.

          ldq  $27,foo($29)   !literal!1
          beq  $27,is_undef   !lituse_addr!1
          jsr  $26,($27),foo  !lituse_jsr!1

`!lituse_tlsgd!N'
     Used with a register branch format instruction to indicate that the
     literal is the call to `__tls_get_addr' used to compute the
     address of the thread-local storage variable whose descriptor was
     loaded with `!tlsgd!N'.

`!lituse_tlsldm!N'
     Used with a register branch format instruction to indicate that the
     literal is the call to `__tls_get_addr' used to compute the
     address of the base of the thread-local storage block for the
     current module.  The descriptor for the module must have been
     loaded with `!tlsldm!N'.

`!gpdisp!N'
     Used with `ldah' and `lda' to load the GP from the current
     address, a-la the `ldgp' macro.  The source register for the
     `ldah' instruction must contain the address of the `ldah'
     instruction.  There must be exactly one `lda' instruction paired
     with the `ldah' instruction, though it may appear anywhere in the
     instruction stream.  The immediate operands must be zero.

          bsr  $26,foo
          ldah $29,0($26)     !gpdisp!1
          lda  $29,0($29)     !gpdisp!1

`!gprelhigh'
     Used with an `ldah' instruction to add the high 16 bits of a
     32-bit displacement from the GP.

`!gprellow'
     Used with any memory format instruction to add the low 16 bits of a
     32-bit displacement from the GP.

`!gprel'
     Used with any memory format instruction to add a 16-bit
     displacement from the GP.

`!samegp'
     Used with any branch format instruction to skip the GP load at the
     target address.  The referenced symbol must have the same GP as the
     source object file, and it must be declared to either not use `$27'
     or perform a standard GP load in the first two instructions via the
     `.prologue' directive.

`!tlsgd'
`!tlsgd!N'
     Used with an `lda' instruction to load the address of a TLS
     descriptor for a symbol in the GOT.

     The sequence number N is optional, and if present it used to pair
     the descriptor load with both the `literal' loading the address of
     the `__tls_get_addr' function and the `lituse_tlsgd' marking the
     call to that function.

     For proper relaxation, both the `tlsgd', `literal' and `lituse'
     relocations must be in the same extended basic block.  That is,
     the relocation with the lowest address must be executed first at
     runtime.

`!tlsldm'
`!tlsldm!N'
     Used with an `lda' instruction to load the address of a TLS
     descriptor for the current module in the GOT.

     Similar in other respects to `tlsgd'.

`!gotdtprel'
     Used with an `ldq' instruction to load the offset of the TLS
     symbol within its module's thread-local storage block.  Also known
     as the dynamic thread pointer offset or dtp-relative offset.

`!dtprelhi'
`!dtprello'
`!dtprel'
     Like `gprel' relocations except they compute dtp-relative offsets.

`!gottprel'
     Used with an `ldq' instruction to load the offset of the TLS
     symbol from the thread pointer.  Also known as the tp-relative
     offset.

`!tprelhi'
`!tprello'
`!tprel'
     Like `gprel' relocations except they compute tp-relative offsets.


File: as.info,  Node: Alpha Floating Point,  Next: Alpha Directives,  Prev: Alpha Syntax,  Up: Alpha-Dependent

Floating Point
--------------

   The Alpha family uses both IEEE and VAX floating-point numbers.


File: as.info,  Node: Alpha Directives,  Next: Alpha Opcodes,  Prev: Alpha Floating Point,  Up: Alpha-Dependent

Alpha Assembler Directives
--------------------------

   `as' for the Alpha supports many additional directives for
compatibility with the native assembler.  This section describes them
only briefly.

   These are the additional directives in `as' for the Alpha:

`.arch CPU'
     Specifies the target processor.  This is equivalent to the `-mCPU'
     command-line option.  *Note Options: Alpha Options, for a list of
     values for CPU.

`.ent FUNCTION[, N]'
     Mark the beginning of FUNCTION.  An optional number may follow for
     compatibility with the OSF/1 assembler, but is ignored.  When
     generating `.mdebug' information, this will create a procedure
     descriptor for the function.  In ELF, it will mark the symbol as a
     function a-la the generic `.type' directive.

`.end FUNCTION'
     Mark the end of FUNCTION.  In ELF, it will set the size of the
     symbol a-la the generic `.size' directive.

`.mask MASK, OFFSET'
     Indicate which of the integer registers are saved in the current
     function's stack frame.  MASK is interpreted a bit mask in which
     bit N set indicates that register N is saved.  The registers are
     saved in a block located OFFSET bytes from the "canonical frame
     address" (CFA) which is the value of the stack pointer on entry to
     the function.  The registers are saved sequentially, except that
     the return address register (normally `$26') is saved first.

     This and the other directives that describe the stack frame are
     currently only used when generating `.mdebug' information.  They
     may in the future be used to generate DWARF2 `.debug_frame' unwind
     information for hand written assembly.

`.fmask MASK, OFFSET'
     Indicate which of the floating-point registers are saved in the
     current stack frame.  The MASK and OFFSET parameters are
     interpreted as with `.mask'.

`.frame FRAMEREG, FRAMEOFFSET, RETREG[, ARGOFFSET]'
     Describes the shape of the stack frame.  The frame pointer in use
     is FRAMEREG; normally this is either `$fp' or `$sp'.  The frame
     pointer is FRAMEOFFSET bytes below the CFA.  The return address is
     initially located in RETREG until it is saved as indicated in
     `.mask'.  For compatibility with OSF/1 an optional ARGOFFSET
     parameter is accepted and ignored.  It is believed to indicate the
     offset from the CFA to the saved argument registers.

`.prologue N'
     Indicate that the stack frame is set up and all registers have been
     spilled.  The argument N indicates whether and how the function
     uses the incoming "procedure vector" (the address of the called
     function) in `$27'.  0 indicates that `$27' is not used; 1
     indicates that the first two instructions of the function use `$27'
     to perform a load of the GP register; 2 indicates that `$27' is
     used in some non-standard way and so the linker cannot elide the
     load of the procedure vector during relaxation.

`.gprel32 EXPRESSION'
     Computes the difference between the address in EXPRESSION and the
     GP for the current object file, and stores it in 4 bytes.  In
     addition to being smaller than a full 8 byte address, this also
     does not require a dynamic relocation when used in a shared
     library.

`.t_floating EXPRESSION'
     Stores EXPRESSION as an IEEE double precision value.

`.s_floating EXPRESSION'
     Stores EXPRESSION as an IEEE single precision value.

`.f_floating EXPRESSION'
     Stores EXPRESSION as a VAX F format value.

`.g_floating EXPRESSION'
     Stores EXPRESSION as a VAX G format value.

`.d_floating EXPRESSION'
     Stores EXPRESSION as a VAX D format value.

`.set FEATURE'
     Enables or disables various assembler features.  Using the positive
     name of the feature enables while using `noFEATURE' disables.

    `at'
          Indicates that macro expansions may clobber the "assembler
          temporary" (`$at' or `$28') register.  Some macros may not be
          expanded without this and will generate an error message if
          `noat' is in effect.  When `at' is in effect, a warning will
          be generated if `$at' is used by the programmer.

    `macro'
          Enables the expansion of macro instructions.  Note that
          variants of real instructions, such as `br label' vs `br
          $31,label' are considered alternate forms and not macros.

    `move'
    `reorder'
    `volatile'
          These control whether and how the assembler may re-order
          instructions.  Accepted for compatibility with the OSF/1
          assembler, but `as' does not do instruction scheduling, so
          these features are ignored.

   The following directives are recognized for compatibility with the
OSF/1 assembler but are ignored.

     .proc           .aproc
     .reguse         .livereg
     .option         .aent
     .ugen           .eflag
     .alias          .noalias


File: as.info,  Node: Alpha Opcodes,  Prev: Alpha Directives,  Up: Alpha-Dependent

Opcodes
-------

   For detailed information on the Alpha machine instruction set, see
the Alpha Architecture Handbook
(ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf).


File: as.info,  Node: ARC-Dependent,  Next: ARM-Dependent,  Prev: Alpha-Dependent,  Up: Machine Dependencies

ARC Dependent Features
======================

* Menu:

* ARC Options::              Options
* ARC Syntax::               Syntax
* ARC Floating Point::       Floating Point
* ARC Directives::           ARC Machine Directives
* ARC Opcodes::              Opcodes


File: as.info,  Node: ARC Options,  Next: ARC Syntax,  Up: ARC-Dependent

Options
-------

`-marc[5|6|7|8]'
     This option selects the core processor variant. Using `-marc' is
     the same as `-marc6', which is also the default.

    `arc5'
          Base instruction set.

    `arc6'
          Jump-and-link (jl) instruction. No requirement of an
          instruction between setting flags and conditional jump. For
          example:

                 mov.f r0,r1
                 beq   foo

    `arc7'
          Break (brk) and sleep (sleep) instructions.

    `arc8'
          Software interrupt (swi) instruction.

     Note: the `.option' directive can to be used to select a core
     variant from within assembly code.

`-EB'
     This option specifies that the output generated by the assembler
     should be marked as being encoded for a big-endian processor.

`-EL'
     This option specifies that the output generated by the assembler
     should be marked as being encoded for a little-endian processor -
     this is the default.


File: as.info,  Node: ARC Syntax,  Next: ARC Floating Point,  Prev: ARC Options,  Up: ARC-Dependent

Syntax
------

* Menu:

* ARC-Chars::                Special Characters
* ARC-Regs::                 Register Names


File: as.info,  Node: ARC-Chars,  Next: ARC-Regs,  Up: ARC Syntax

Special Characters
..................

   *TODO*


File: as.info,  Node: ARC-Regs,  Prev: ARC-Chars,  Up: ARC Syntax

Register Names
..............

   *TODO*


File: as.info,  Node: ARC Floating Point,  Next: ARC Directives,  Prev: ARC Syntax,  Up: ARC-Dependent

Floating Point
--------------

   The ARC core does not currently have hardware floating point
support. Software floating point support is provided by `GCC' and uses
IEEE floating-point numbers.


File: as.info,  Node: ARC Directives,  Next: ARC Opcodes,  Prev: ARC Floating Point,  Up: ARC-Dependent

ARC Machine Directives
----------------------

   The ARC version of `as' supports the following additional machine
directives:

`.2byte EXPRESSIONS'
     *TODO*

`.3byte EXPRESSIONS'
     *TODO*

`.4byte EXPRESSIONS'
     *TODO*

`.extAuxRegister NAME,ADDRESS,MODE'
     *TODO*

            .extAuxRegister mulhi,0x12,w

`.extCondCode SUFFIX,VALUE'
     *TODO*

            .extCondCode is_busy,0x14

`.extCoreRegister NAME,REGNUM,MODE,SHORTCUT'
     *TODO*

            .extCoreRegister mlo,57,r,can_shortcut

`.extInstruction NAME,OPCODE,SUBOPCODE,SUFFIXCLASS,SYNTAXCLASS'
     *TODO*

            .extInstruction mul64,0x14,0x0,SUFFIX_COND,SYNTAX_3OP|OP1_MUST_BE_IMM

`.half EXPRESSIONS'
     *TODO*

`.long EXPRESSIONS'
     *TODO*

`.option ARC|ARC5|ARC6|ARC7|ARC8'
     The `.option' directive must be followed by the desired core
     version. Again `arc' is an alias for `arc6'.

     Note: the `.option' directive overrides the command line option
     `-marc'; a warning is emitted when the version is not consistent
     between the two - even for the implicit default core version
     (arc6).

`.short EXPRESSIONS'
     *TODO*

`.word EXPRESSIONS'
     *TODO*


File: as.info,  Node: ARC Opcodes,  Prev: ARC Directives,  Up: ARC-Dependent

Opcodes
-------

   For information on the ARC instruction set, see `ARC Programmers
Reference Manual', ARC Cores Ltd.


File: as.info,  Node: ARM-Dependent,  Next: CRIS-Dependent,  Prev: ARC-Dependent,  Up: Machine Dependencies

ARM Dependent Features
======================

* Menu:

* ARM Options::              Options
* ARM Syntax::               Syntax
* ARM Floating Point::       Floating Point
* ARM Directives::           ARM Machine Directives
* ARM Opcodes::              Opcodes


File: as.info,  Node: ARM Options,  Next: ARM Syntax,  Up: ARM-Dependent

Options
-------

`-mcpu=PROCESSOR[+EXTENSION...]'
     This option specifies the target processor.  The assembler will
     issue an error message if an attempt is made to assemble an
     instruction which will not execute on the target processor.  The
     following processor names are recognized: `arm1', `arm2', `arm250',
     `arm3', `arm6', `arm60', `arm600', `arm610', `arm620', `arm7',
     `arm7m', `arm7d', `arm7dm', `arm7di', `arm7dmi', `arm70', `arm700',
     `arm700i', `arm710', `arm710t', `arm720', `arm720t', `arm740t',
     `arm710c', `arm7100', `arm7500', `arm7500fe', `arm7t', `arm7tdmi',
     `arm8', `arm810', `strongarm', `strongarm1', `strongarm110',
     `strongarm1100', `strongarm1110', `arm9', `arm920', `arm920t',
     `arm922t', `arm940t', `arm9tdmi', `arm9e', `arm946e-r0', `arm946e',
     `arm966e-r0', `arm966e', `arm10t', `arm10e', `arm1020', `arm1020t',
     `arm1020e', `ep9312' (ARM920 with Cirrus Maverick coprocessor),
     `i80200' (Intel XScale processor) `iwmmxt' (Intel(r) XScale
     processor with Wireless MMX(tm) technology coprocessor) and
     `xscale'.  The special name `all' may be used to allow the
     assembler to accept instructions valid for any ARM processor.

     In addition to the basic instruction set, the assembler can be
     told to accept various extension mnemonics that extend the
     processor using the co-processor instruction space.  For example,
     `-mcpu=arm920+maverick' is equivalent to specifying
     `-mcpu=ep9312'.  The following extensions are currently supported:
     `+maverick' `+iwmmxt' and `+xscale'.

`-march=ARCHITECTURE[+EXTENSION...]'
     This option specifies the target architecture.  The assembler will
     issue an error message if an attempt is made to assemble an
     instruction which will not execute on the target architecture.
     The following architecture names are recognized: `armv1', `armv2',
     `armv2a', `armv2s', `armv3', `armv3m', `armv4', `armv4xm',
     `armv4t', `armv4txm', `armv5', `armv5t', `armv5txm', `armv5te',
     `armv5texp' `iwmmxt' and `xscale'.  If both `-mcpu' and `-march'
     are specified, the assembler will use the setting for `-mcpu'.

     The architecture option can be extended with the same instruction
     set extension options as the `-mcpu' option.

`-mfpu=FLOATING-POINT-FORMAT'
     This option specifies the floating point format to assemble for.
     The assembler will issue an error message if an attempt is made to
     assemble an instruction which will not execute on the target
     floating point unit.  The following format options are recognized:
     `softfpa', `fpe', `fpe2', `fpe3', `fpa', `fpa10', `fpa11',
     `arm7500fe', `softvfp', `softvfp+vfp', `vfp', `vfp10', `vfp10-r0',
     `vfp9', `vfpxd', `arm1020t' and `arm1020e'.

     In addition to determining which instructions are assembled, this
     option also affects the way in which the `.double' assembler
     directive behaves when assembling little-endian code.

     The default is dependent on the processor selected.  For
     Architecture 5 or later, the default is to assembler for VFP
     instructions; for earlier architectures the default is to assemble
     for FPA instructions.

`-mthumb'
     This option specifies that the assembler should start assembling
     Thumb instructions; that is, it should behave as though the file
     starts with a `.code 16' directive.

`-mthumb-interwork'
     This option specifies that the output generated by the assembler
     should be marked as supporting interworking.

`-mapcs `[26|32]''
     This option specifies that the output generated by the assembler
     should be marked as supporting the indicated version of the Arm
     Procedure.  Calling Standard.

`-matpcs'
     This option specifies that the output generated by the assembler
     should be marked as supporting the Arm/Thumb Procedure Calling
     Standard.  If enabled this option will cause the assembler to
     create an empty debugging section in the object file called
     .arm.atpcs.  Debuggers can use this to determine the ABI being
     used by.

`-mapcs-float'
     This indicates the the floating point variant of the APCS should be
     used.  In this variant floating point arguments are passed in FP
     registers rather than integer registers.

`-mapcs-reentrant'
     This indicates that the reentrant variant of the APCS should be
     used.  This variant supports position independent code.

`-EB'
     This option specifies that the output generated by the assembler
     should be marked as being encoded for a big-endian processor.

`-EL'
     This option specifies that the output generated by the assembler
     should be marked as being encoded for a little-endian processor.

`-k'
     This option specifies that the output of the assembler should be
     marked as position-independent code (PIC).

`-moabi'
     This indicates that the code should be assembled using the old ARM
     ELF conventions, based on a beta release release of the ARM-ELF
     specifications, rather than the default conventions which are
     based on the final release of the ARM-ELF specifications.


File: as.info,  Node: ARM Syntax,  Next: ARM Floating Point,  Prev: ARM Options,  Up: ARM-Dependent

Syntax
------

* Menu:

* ARM-Chars::                Special Characters
* ARM-Regs::                 Register Names


File: as.info,  Node: ARM-Chars,  Next: ARM-Regs,  Up: ARM Syntax

Special Characters
..................

   The presence of a `@' on a line indicates the start of a comment
that extends to the end of the current line.  If a `#' appears as the
first character of a line, the whole line is treated as a comment.

   The `;' character can be used instead of a newline to separate
statements.

   Either `#' or `$' can be used to indicate immediate operands.

   *TODO* Explain about /data modifier on symbols.


File: as.info,  Node: ARM-Regs,  Prev: ARM-Chars,  Up: ARM Syntax

Register Names
..............

   *TODO* Explain about ARM register naming, and the predefined names.


File: as.info,  Node: ARM Floating Point,  Next: ARM Directives,  Prev: ARM Syntax,  Up: ARM-Dependent

Floating Point
--------------

   The ARM family uses IEEE floating-point numbers.


File: as.info,  Node: ARM Directives,  Next: ARM Opcodes,  Prev: ARM Floating Point,  Up: ARM-Dependent

ARM Machine Directives
----------------------

`.align EXPRESSION [, EXPRESSION]'
     This is the generic .ALIGN directive.  For the ARM however if the
     first argument is zero (ie no alignment is needed) the assembler
     will behave as if the argument had been 2 (ie pad to the next four
     byte boundary).  This is for compatibility with ARM's own
     assembler.

`NAME .req REGISTER NAME'
     This creates an alias for REGISTER NAME called NAME.  For example:

                  foo .req r0

`.code `[16|32]''
     This directive selects the instruction set being generated. The
     value 16 selects Thumb, with the value 32 selecting ARM.

`.thumb'
     This performs the same action as .CODE 16.

`.arm'
     This performs the same action as .CODE 32.

`.force_thumb'
     This directive forces the selection of Thumb instructions, even if
     the target processor does not support those instructions

`.thumb_func'
     This directive specifies that the following symbol is the name of a
     Thumb encoded function.  This information is necessary in order to
     allow the assembler and linker to generate correct code for
     interworking between Arm and Thumb instructions and should be used
     even if interworking is not going to be performed.  The presence
     of this directive also implies `.thumb'

`.thumb_set'
     This performs the equivalent of a `.set' directive in that it
     creates a symbol which is an alias for another symbol (possibly
     not yet defined).  This directive also has the added property in
     that it marks the aliased symbol as being a thumb function entry
     point, in the same way that the `.thumb_func' directive does.

`.ltorg'
     This directive causes the current contents of the literal pool to
     be dumped into the current section (which is assumed to be the
     .text section) at the current location (aligned to a word
     boundary).  `GAS' maintains a separate literal pool for each
     section and each sub-section.  The `.ltorg' directive will only
     affect the literal pool of the current section and sub-section.
     At the end of assembly all remaining, un-empty literal pools will
     automatically be dumped.

     Note - older versions of `GAS' would dump the current literal pool
     any time a section change occurred.  This is no longer done, since
     it prevents accurate control of the placement of literal pools.

`.pool'
     This is a synonym for .ltorg.


File: as.info,  Node: ARM Opcodes,  Prev: ARM Directives,  Up: ARM-Dependent

Opcodes
-------

   `as' implements all the standard ARM opcodes.  It also implements
several pseudo opcodes, including several synthetic load instructions.

`NOP'
            nop

     This pseudo op will always evaluate to a legal ARM instruction
     that does nothing.  Currently it will evaluate to MOV r0, r0.

`LDR'
            ldr <register> , = <expression>

     If expression evaluates to a numeric constant then a MOV or MVN
     instruction will be used in place of the LDR instruction, if the
     constant can be generated by either of these instructions.
     Otherwise the constant will be placed into the nearest literal
     pool (if it not already there) and a PC relative LDR instruction
     will be generated.

`ADR'
            adr <register> <label>

     This instruction will load the address of LABEL into the indicated
     register.  The instruction will evaluate to a PC relative ADD or
     SUB instruction depending upon where the label is located.  If the
     label is out of range, or if it is not defined in the same file
     (and section) as the ADR instruction, then an error will be
     generated.  This instruction will not make use of the literal pool.

`ADRL'
            adrl <register> <label>

     This instruction will load the address of LABEL into the indicated
     register.  The instruction will evaluate to one or two PC relative
     ADD or SUB instructions depending upon where the label is located.
     If a second instruction is not needed a NOP instruction will be
     generated in its place, so that this instruction is always 8 bytes
     long.

     If the label is out of range, or if it is not defined in the same
     file (and section) as the ADRL instruction, then an error will be
     generated.  This instruction will not make use of the literal pool.

   For information on the ARM or Thumb instruction sets, see `ARM
Software Development Toolkit Reference Manual', Advanced RISC Machines
Ltd.


File: as.info,  Node: CRIS-Dependent,  Next: D10V-Dependent,  Prev: ARM-Dependent,  Up: Machine Dependencies

CRIS Dependent Features
=======================

* Menu:

* CRIS-Opts::              Command-line Options
* CRIS-Expand::            Instruction expansion
* CRIS-Syntax::            Syntax


File: as.info,  Node: CRIS-Opts,  Next: CRIS-Expand,  Up: CRIS-Dependent

Command-line Options
--------------------

   The CRIS version of `as' has these machine-dependent command-line
options.

   The format of the generated object files can be either ELF or a.out,
specified by the command-line options `--emulation=crisaout' and
`--emulation=criself'.  The default is ELF (criself), unless `as' has
been configured specifically for a.out by using the configuration name
`cris-axis-aout'.

   There are two different link-incompatible ELF object file variants
for CRIS, for use in environments where symbols are expected to be
prefixed by a leading `_' character and for environments without such a
symbol prefix.  The variant used for GNU/Linux port has no symbol
prefix.  Which variant to produce is specified by either of the options
`--underscore' and `--no-underscore'.  The default is `--underscore'.
Since symbols in CRIS a.out objects are expected to have a `_' prefix,
specifying `--no-underscore' when generating a.out objects is an error.
Besides the object format difference, the effect of this option is to
parse register names differently (*note crisnous::).  The
`--no-underscore' option makes a `$' register prefix mandatory.

   The option `--pic' must be passed to `as' in order to recognize the
symbol syntax used for ELF (SVR4 PIC) position-independent-code (*note
crispic::).  This will also affect expansion of instructions.  The
expansion with `--pic' will use PC-relative rather than (slightly
faster) absolute addresses in those expansions.

   When `-N' is specified, `as' will emit a warning when a 16-bit
branch instruction is expanded into a 32-bit multiple-instruction
construct (*note CRIS-Expand::).


File: as.info,  Node: CRIS-Expand,  Next: CRIS-Syntax,  Prev: CRIS-Opts,  Up: CRIS-Dependent

Instruction expansion
---------------------

   `as' will silently choose an instruction that fits the operand size
for `[register+constant]' operands.  For example, the offset `127' in
`move.d [r3+127],r4' fits in an instruction using a signed-byte offset.
Similarly, `move.d [r2+32767],r1' will generate an instruction using a
16-bit offset.  For symbolic expressions and constants that do not fit
in 16 bits including the sign bit, a 32-bit offset is generated.

   For branches, `as' will expand from a 16-bit branch instruction into
a sequence of instructions that can reach a full 32-bit address.  Since
this does not correspond to a single instruction, such expansions can
optionally be warned about.  *Note CRIS-Opts::.


File: as.info,  Node: CRIS-Syntax,  Prev: CRIS-Expand,  Up: CRIS-Dependent

Syntax
------

   There are different aspects of the CRIS assembly syntax.

* Menu:

* CRIS-Chars::                  Special Characters
* CRIS-Pic::                    Position-Independent Code Symbols
* CRIS-Regs::                   Register Names
* CRIS-Pseudos::                Assembler Directives


File: as.info,  Node: CRIS-Chars,  Next: CRIS-Pic,  Up: CRIS-Syntax

Special Characters
..................

   The character `#' is a line comment character.  It starts a comment
if and only if it is placed at the beginning of a line.

   A `;' character starts a comment anywhere on the line, causing all
characters up to the end of the line to be ignored.

   A `@' character is handled as a line separator equivalent to a
logical new-line character (except in a comment), so separate
instructions can be specified on a single line.


File: as.info,  Node: CRIS-Pic,  Next: CRIS-Regs,  Prev: CRIS-Chars,  Up: CRIS-Syntax

Symbols in position-independent code
....................................

   When generating position-independent code (SVR4 PIC) for use in
cris-axis-linux-gnu shared libraries, symbol suffixes are used to
specify what kind of run-time symbol lookup will be used, expressed in
the object as different _relocation types_.  Usually, all absolute
symbol values must be located in a table, the _global offset table_,
leaving the code position-independent; independent of values of global
symbols and independent of the address of the code.  The suffix
modifies the value of the symbol, into for example an index into the
global offset table where the real symbol value is entered, or a
PC-relative value, or a value relative to the start of the global
offset table.  All symbol suffixes start with the character `:'
(omitted in the list below).  Every symbol use in code or a read-only
section must therefore have a PIC suffix to enable a useful shared
library to be created.  Usually, these constructs must not be used with
an additive constant offset as is usually allowed, i.e. no 4 as in
`symbol + 4' is allowed.  This restriction is checked at link-time, not
at assembly-time.

`GOT'
     Attaching this suffix to a symbol in an instruction causes the
     symbol to be entered into the global offset table.  The value is a
     32-bit index for that symbol into the global offset table.  The
     name of the corresponding relocation is `R_CRIS_32_GOT'.  Example:
     `move.d [$r0+extsym:GOT],$r9'

`GOT16'
     Same as for `GOT', but the value is a 16-bit index into the global
     offset table.  The corresponding relocation is `R_CRIS_16_GOT'.
     Example: `move.d [$r0+asymbol:GOT16],$r10'

`PLT'
     This suffix is used for function symbols.  It causes a _procedure
     linkage table_, an array of code stubs, to be created at the time
     the shared object is created or linked against, together with a
     global offset table entry.  The value is a pc-relative offset to
     the corresponding stub code in the procedure linkage table.  This
     arrangement causes the run-time symbol resolver to be called to
     look up and set the value of the symbol the first time the
     function is called (at latest; depending environment variables).
     It is only safe to leave the symbol unresolved this way if all
     references are function calls.  The name of the relocation is
     `R_CRIS_32_PLT_PCREL'.  Example: `add.d fnname:PLT,$pc'

`PLTG'
     Like PLT, but the value is relative to the beginning of the global
     offset table.  The relocation is `R_CRIS_32_PLT_GOTREL'.  Example:
     `move.d fnname:PLTG,$r3'

`GOTPLT'
     Similar to `PLT', but the value of the symbol is a 32-bit index
     into the global offset table.  This is somewhat of a mix between
     the effect of the `GOT' and the `PLT' suffix; the difference to
     `GOT' is that there will be a procedure linkage table entry
     created, and that the symbol is assumed to be a function entry and
     will be resolved by the run-time resolver as with `PLT'.  The
     relocation is `R_CRIS_32_GOTPLT'.  Example: `jsr
     [$r0+fnname:GOTPLT]'

`GOTPLT16'
     A variant of `GOTPLT' giving a 16-bit value.  Its relocation name
     is `R_CRIS_16_GOTPLT'.  Example: `jsr [$r0+fnname:GOTPLT16]'

`GOTOFF'
     This suffix must only be attached to a local symbol, but may be
     used in an expression adding an offset.  The value is the address
     of the symbol relative to the start of the global offset table.
     The relocation name is `R_CRIS_32_GOTREL'.  Example: `move.d
     [$r0+localsym:GOTOFF],r3'