   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".

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.

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

Options
-------

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

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.

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

   `;' is the line comment character.

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

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

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

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

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'.

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.

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

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.

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', `ev4',
     `ev5', `lca45', `ev5', `ev56', `pca56', `ev6'.  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.

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.

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

   `#' is the line comment character.

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

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'.

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

`!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.

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

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

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.  See 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 expasion 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

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).

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

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.

Syntax
------

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

   *TODO*

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

   *TODO*

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.

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*

Opcodes
-------

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

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

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) 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' 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' 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.

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.

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

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

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

   The ARM family uses IEEE floating-point numbers.

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 compatability 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).

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

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.

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

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 (see 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 (see
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 (see CRIS-Expand).

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.  See CRIS-Opts.

Syntax
------

   There are different aspects of the CRIS assembly 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.

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'

Register names
..............

   A `$' character may always prefix a general or special register name
in an instruction operand but is mandatory when the option
`--no-underscore' is specified or when the `.syntax register_prefix'
directive is in effect (see crisnous).  Register names are
case-insensitive.

Assembler Directives
....................

   There are a few CRIS-specific pseudo-directives in addition to the
generic ones.  See Pseudo Ops.  Constants emitted by
pseudo-directives are in little-endian order for CRIS.  There is no
support for floating-point-specific directives for CRIS.

`.dword EXPRESSIONS'
     The `.dword' directive is a synonym for `.int', expecting zero or
     more EXPRESSIONS, separated by commas.  For each expression, a
     32-bit little-endian constant is emitted.

`.syntax ARGUMENT'
     The `.syntax' directive takes as ARGUMENT one of the following
     case-sensitive choices.

    `no_register_prefix'
          The `.syntax no_register_prefix' directive makes a `$'
          character prefix on all registers optional.  It overrides a
          previous setting, including the corresponding effect of the
          option `--no-underscore'.  If this directive is used when
          ordinary symbols do not have a `_' character prefix, care
          must be taken to avoid ambiguities whether an operand is a
          register or a symbol; using symbols with names the same as
          general or special registers then invoke undefined behavior.

    `register_prefix'
          This directive makes a `$' character prefix on all registers
          mandatory.  It overrides a previous setting, including the
          corresponding effect of the option `--underscore'.

    `leading_underscore'
          This is an assertion directive, emitting an error if the
          `--no-underscore' option is in effect.

    `no_leading_underscore'
          This is the opposite of the `.syntax leading_underscore'
          directive and emits an error if the option `--underscore' is
          in effect.

D10V Dependent Features
=======================

D10V Options
------------

   The Mitsubishi D10V version of `as' has a few machine dependent
options.

`-O'
     The D10V can often execute two sub-instructions in parallel. When
     this option is used, `as' will attempt to optimize its output by
     detecting when instructions can be executed in parallel.

`--nowarnswap'
     To optimize execution performance, `as' will sometimes swap the
     order of instructions. Normally this generates a warning. When
     this option is used, no warning will be generated when
     instructions are swapped.

`--gstabs-packing'

`--no-gstabs-packing'
     `as' packs adjacent short instructions into a single packed
     instruction. `--no-gstabs-packing' turns instruction packing off if
     `--gstabs' is specified as well; `--gstabs-packing' (the default)
     turns instruction packing on even when `--gstabs' is specified.

Syntax
------

   The D10V syntax is based on the syntax in Mitsubishi's D10V
architecture manual.  The differences are detailed below.

Size Modifiers
..............

   The D10V version of `as' uses the instruction names in the D10V
Architecture Manual.  However, the names in the manual are sometimes
ambiguous.  There are instruction names that can assemble to a short or
long form opcode.  How does the assembler pick the correct form?  `as'
will always pick the smallest form if it can.  When dealing with a
symbol that is not defined yet when a line is being assembled, it will
always use the long form.  If you need to force the assembler to use
either the short or long form of the instruction, you can append either
`.s' (short) or `.l' (long) to it.  For example, if you are writing an
assembly program and you want to do a branch to a symbol that is
defined later in your program, you can write `bra.s   foo'.  Objdump
and GDB will always append `.s' or `.l' to instructions which have both
short and long forms.

Sub-Instructions
................

   The D10V assembler takes as input a series of instructions, either
one-per-line, or in the special two-per-line format described in the
next section.  Some of these instructions will be short-form or
sub-instructions.  These sub-instructions can be packed into a single
instruction.  The assembler will do this automatically.  It will also
detect when it should not pack instructions.  For example, when a label
is defined, the next instruction will never be packaged with the
previous one.  Whenever a branch and link instruction is called, it
will not be packaged with the next instruction so the return address
will be valid.  Nops are automatically inserted when necessary.

   If you do not want the assembler automatically making these
decisions, you can control the packaging and execution type (parallel
or sequential) with the special execution symbols described in the next
section.

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

   `;' and `#' are the line comment characters.  Sub-instructions may
be executed in order, in reverse-order, or in parallel.  Instructions
listed in the standard one-per-line format will be executed
sequentially.  To specify the executing order, use the following
symbols:
`->'
     Sequential with instruction on the left first.

`<-'
     Sequential with instruction on the right first.

`||'
     Parallel The D10V syntax allows either one instruction per line,
one instruction per line with the execution symbol, or two instructions
per line.  For example
`abs       a1      ->      abs     r0'
     Execute these sequentially.  The instruction on the right is in
     the right container and is executed second.

`abs       r0      <-      abs     a1'
     Execute these reverse-sequentially.  The instruction on the right
     is in the right container, and is executed first.

`ld2w    r2,@r8+         ||      mac     a0,r0,r7'
     Execute these in parallel.

`ld2w    r2,@r8+         ||'
`mac     a0,r0,r7'
     Two-line format. Execute these in parallel.

`ld2w    r2,@r8+'
`mac     a0,r0,r7'
     Two-line format. Execute these sequentially.  Assembler will put
     them in the proper containers.

`ld2w    r2,@r8+         ->'
`mac     a0,r0,r7'
     Two-line format. Execute these sequentially.  Same as above but
     second instruction will always go into right container.  Since `$'
has no special meaning, you may use it in symbol names.