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

Syntax
------

   This syntax for the Motorola 680x0 was developed at MIT.

   The 680x0 version of `as' uses instructions names and syntax
compatible with the Sun assembler.  Intervening periods are ignored;
for example, `movl' is equivalent to `mov.l'.

   In the following table APC stands for any of the address registers
(`%a0' through `%a7'), the program counter (`%pc'), the zero-address
relative to the program counter (`%zpc'), a suppressed address register
(`%za0' through `%za7'), or it may be omitted entirely.  The use of
SIZE means one of `w' or `l', and it may be omitted, along with the
leading colon, unless a scale is also specified.  The use of SCALE
means one of `1', `2', `4', or `8', and it may always be omitted along
with the leading colon.

   The following addressing modes are understood:
"Immediate"
     `#NUMBER'

"Data Register"
     `%d0' through `%d7'

"Address Register"
     `%a0' through `%a7'
     `%a7' is also known as `%sp', i.e. the Stack Pointer.  `%a6' is
     also known as `%fp', the Frame Pointer.

"Address Register Indirect"
     `%a0@' through `%a7@'

"Address Register Postincrement"
     `%a0@+' through `%a7@+'

"Address Register Predecrement"
     `%a0@-' through `%a7@-'

"Indirect Plus Offset"
     `APC@(NUMBER)'

"Index"
     `APC@(NUMBER,REGISTER:SIZE:SCALE)'

     The NUMBER may be omitted.

"Postindex"
     `APC@(NUMBER)@(ONUMBER,REGISTER:SIZE:SCALE)'

     The ONUMBER or the REGISTER, but not both, may be omitted.

"Preindex"
     `APC@(NUMBER,REGISTER:SIZE:SCALE)@(ONUMBER)'

     The NUMBER may be omitted.  Omitting the REGISTER produces the
     Postindex addressing mode.

"Absolute"
     `SYMBOL', or `DIGITS', optionally followed by `:b', `:w', or `:l'.

Motorola Syntax
---------------

   The standard Motorola syntax for this chip differs from the syntax
already discussed (see Syntax).  `as' can accept
Motorola syntax for operands, even if MIT syntax is used for other
operands in the same instruction.  The two kinds of syntax are fully
compatible.

   In the following table APC stands for any of the address registers
(`%a0' through `%a7'), the program counter (`%pc'), the zero-address
relative to the program counter (`%zpc'), or a suppressed address
register (`%za0' through `%za7').  The use of SIZE means one of `w' or
`l', and it may always be omitted along with the leading dot.  The use
of SCALE means one of `1', `2', `4', or `8', and it may always be
omitted along with the leading asterisk.

   The following additional addressing modes are understood:

"Address Register Indirect"
     `(%a0)' through `(%a7)'
     `%a7' is also known as `%sp', i.e. the Stack Pointer.  `%a6' is
     also known as `%fp', the Frame Pointer.

"Address Register Postincrement"
     `(%a0)+' through `(%a7)+'

"Address Register Predecrement"
     `-(%a0)' through `-(%a7)'

"Indirect Plus Offset"
     `NUMBER(%A0)' through `NUMBER(%A7)', or `NUMBER(%PC)'.

     The NUMBER may also appear within the parentheses, as in
     `(NUMBER,%A0)'.  When used with the PC, the NUMBER may be omitted
     (with an address register, omitting the NUMBER produces Address
     Register Indirect mode).

"Index"
     `NUMBER(APC,REGISTER.SIZE*SCALE)'

     The NUMBER may be omitted, or it may appear within the
     parentheses.  The APC may be omitted.  The REGISTER and the APC
     may appear in either order.  If both APC and REGISTER are address
     registers, and the SIZE and SCALE are omitted, then the first
     register is taken as the base register, and the second as the
     index register.

"Postindex"
     `([NUMBER,APC],REGISTER.SIZE*SCALE,ONUMBER)'

     The ONUMBER, or the REGISTER, or both, may be omitted.  Either the
     NUMBER or the APC may be omitted, but not both.

"Preindex"
     `([NUMBER,APC,REGISTER.SIZE*SCALE],ONUMBER)'

     The NUMBER, or the APC, or the REGISTER, or any two of them, may
     be omitted.  The ONUMBER may be omitted.  The REGISTER and the APC
     may appear in either order.  If both APC and REGISTER are address
     registers, and the SIZE and SCALE are omitted, then the first
     register is taken as the base register, and the second as the
     index register.

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

   Packed decimal (P) format floating literals are not supported.  Feel
free to add the code!

   The floating point formats generated by directives are these.

`.float'
     `Single' precision floating point constants.

`.double'
     `Double' precision floating point constants.

`.extend'
`.ldouble'
     `Extended' precision (`long double') floating point constants.

680x0 Machine Directives
------------------------

   In order to be compatible with the Sun assembler the 680x0 assembler
understands the following directives.

`.data1'
     This directive is identical to a `.data 1' directive.

`.data2'
     This directive is identical to a `.data 2' directive.

`.even'
     This directive is a special case of the `.align' directive; it
     aligns the output to an even byte boundary.

`.skip'
     This directive is identical to a `.space' directive.

Opcodes
-------

Branch Improvement
..................

   Certain pseudo opcodes are permitted for branch instructions.  They
expand to the shortest branch instruction that reach the target.
Generally these mnemonics are made by substituting `j' for `b' at the
start of a Motorola mnemonic.

   The following table summarizes the pseudo-operations.  A `*' flags
cases that are more fully described after the table:

               Displacement
               +------------------------------------------------------------
               |                68020           68000/10, not PC-relative OK
     Pseudo-Op |BYTE    WORD    LONG            ABSOLUTE LONG JUMP    **
               +------------------------------------------------------------
          jbsr |bsrs    bsrw    bsrl            jsr
           jra |bras    braw    bral            jmp
     *     jXX |bXXs    bXXw    bXXl            bNXs;jmp
     *    dbXX | N/A    dbXXw   dbXX;bras;bral  dbXX;bras;jmp
          fjXX | N/A    fbXXw   fbXXl            N/A

     XX: condition
     NX: negative of condition XX
                       `*'--see full description below
         `**'--this expansion mode is disallowed by `--pcrel'
`jbsr'
`jra'
     These are the simplest jump pseudo-operations; they always map to
     one particular machine instruction, depending on the displacement
     to the branch target.  This instruction will be a byte or word
     branch is that is sufficient.  Otherwise, a long branch will be
     emitted if available.  If no long branches are available and the
     `--pcrel' option is not given, an absolute long jump will be
     emitted instead.  If no long branches are available, the `--pcrel'
     option is given, and a word branch cannot reach the target, an
     error message is generated.

     In addition to standard branch operands, `as' allows these
     pseudo-operations to have all operands that are allowed for jsr
     and jmp, substituting these instructions if the operand given is
     not valid for a branch instruction.

`jXX'
     Here, `jXX' stands for an entire family of pseudo-operations,
     where XX is a conditional branch or condition-code test.  The full
     list of pseudo-ops in this family is:
           jhi   jls   jcc   jcs   jne   jeq   jvc
           jvs   jpl   jmi   jge   jlt   jgt   jle

     Usually, each of these pseudo-operations expands to a single branch
     instruction.  However, if a word branch is not sufficient, no long
     branches are available, and the `--pcrel' option is not given, `as'
     issues a longer code fragment in terms of NX, the opposite
     condition to XX.  For example, under these conditions:
              jXX foo
     gives
               bNXs oof
               jmp foo
           oof:

`dbXX'
     The full family of pseudo-operations covered here is
           dbhi   dbls   dbcc   dbcs   dbne   dbeq   dbvc
           dbvs   dbpl   dbmi   dbge   dblt   dbgt   dble
           dbf    dbra   dbt

     Motorola `dbXX' instructions allow word displacements only.  When
     a word displacement is sufficient, each of these pseudo-operations
     expands to the corresponding Motorola instruction.  When a word
     displacement is not sufficient and long branches are available,
     when the source reads `dbXX foo', `as' emits
               dbXX oo1
               bras oo2
           oo1:bral foo
           oo2:

     If, however, long branches are not available and the `--pcrel'
     option is not given, `as' emits
               dbXX oo1
               bras oo2
           oo1:jmp foo
           oo2:

`fjXX'
     This family includes
           fjne   fjeq   fjge   fjlt   fjgt   fjle   fjf
           fjt    fjgl   fjgle  fjnge  fjngl  fjngle fjngt
           fjnle  fjnlt  fjoge  fjogl  fjogt  fjole  fjolt
           fjor   fjseq  fjsf   fjsne  fjst   fjueq  fjuge
           fjugt  fjule  fjult  fjun

     Each of these pseudo-operations always expands to a single Motorola
     coprocessor branch instruction, word or long.  All Motorola
     coprocessor branch instructions allow both word and long
     displacements.

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

The immediate character is `#' for Sun compatibility.  The line-comment
character is `|' (unless the `--bitwise-or' option is used).  If a `#'
appears at the beginning of a line, it is treated as a comment unless
it looks like `# line file', in which case it is treated normally.

M68HC11 and M68HC12 Dependent Features
======================================

M68HC11 and M68HC12 Options
---------------------------

   The Motorola 68HC11 and 68HC12 version of `as' has a few machine
dependent options.

   This option switches the assembler in the M68HC11 mode. In this mode,
the assembler only accepts 68HC11 operands and mnemonics. It produces
code for the 68HC11.

   This option switches the assembler in the M68HC12 mode. In this mode,
the assembler also accepts 68HC12 operands and mnemonics. It produces
code for the 68HC12. A fiew 68HC11 instructions are replaced by some
68HC12 instructions as recommended by Motorola specifications.

   You can use the `--strict-direct-mode' option to disable the
automatic translation of direct page mode addressing into extended mode
when the instruction does not support direct mode.  For example, the
`clr' instruction does not support direct page mode addressing. When it
is used with the direct page mode, `as' will ignore it and generate an
absolute addressing.  This option prevents `as' from doing this, and
the wrong usage of the direct page mode will raise an error.

   The `--short-branchs' option turns off the translation of relative
branches into absolute branches when the branch offset is out of range.
By default `as' transforms the relative branch (`bsr', `bgt', `bge',
`beq', `bne', `ble', `blt', `bhi', `bcc', `bls', `bcs', `bmi', `bvs',
`bvs', `bra') into an absolute branch when the offset is out of the
-128 .. 127 range.  In that case, the `bsr' instruction is translated
into a `jsr', the `bra' instruction is translated into a `jmp' and the
conditional branchs instructions are inverted and followed by a `jmp'.
This option disables these translations and `as' will generate an error
if a relative branch is out of range. This option does not affect the
optimization associated to the `jbra', `jbsr' and `jbXX' pseudo opcodes.

   The `--force-long-branchs' option forces the translation of relative
branches into absolute branches. This option does not affect the
optimization associated to the `jbra', `jbsr' and `jbXX' pseudo opcodes.

   You can use the `--print-insn-syntax' option to obtain the syntax
description of the instruction when an error is detected.

   The `--print-opcodes' option prints the list of all the instructions
with their syntax. The first item of each line represents the
instruction name and the rest of the line indicates the possible
operands for that instruction. The list is printed in alphabetical
order. Once the list is printed `as' exits.

   The `--generate-example' option is similar to `--print-opcodes' but
it generates an example for each instruction instead.

Syntax
------

   In the M68HC11 syntax, the instruction name comes first and it may
be followed by one or several operands (up to three). Operands are
separated by comma (`,'). In the normal mode, `as' will complain if too
many operands are specified for a given instruction. In the MRI mode
(turned on with `-M' option), it will treat them as comments. Example:

     inx
     lda  #23
     bset 2,x #4
     brclr *bot #8 foo

   The following addressing modes are understood:
"Immediate"
     `#NUMBER'

"Address Register"
     `NUMBER,X', `NUMBER,Y'

     The NUMBER may be omitted in which case 0 is assumed.

"Direct Addressing mode"
     `*SYMBOL', or `*DIGITS'

"Absolute"
     `SYMBOL', or `DIGITS'

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

   Packed decimal (P) format floating literals are not supported.  Feel
free to add the code!

   The floating point formats generated by directives are these.

`.float'
     `Single' precision floating point constants.

`.double'
     `Double' precision floating point constants.

`.extend'
`.ldouble'
     `Extended' precision (`long double') floating point constants.

Opcodes
-------

Branch Improvement
..................

   Certain pseudo opcodes are permitted for branch instructions.  They
expand to the shortest branch instruction that reach the target.
Generally these mnemonics are made by prepending `j' to the start of
Motorola mnemonic. These pseudo opcodes are not affected by the
`--short-branchs' or `--force-long-branchs' options.

   The following table summarizes the pseudo-operations.

                                   Displacement Width
               +-------------------------------------------------------------+
               |                     Options                                 |
               |    --short-branchs            --force-long-branchs          |
               +--------------------------+----------------------------------+
     Pseudo-Op |BYTE             WORD     | BYTE          WORD               |
               +--------------------------+----------------------------------+
           bsr | bsr <pc-rel>    <error>  |               jsr <abs>          |
           bra | bra <pc-rel>    <error>  |               jmp <abs>          |
          jbsr | bsr <pc-rel>   jsr <abs> | bsr <pc-rel>  jsr <abs>          |
          jbra | bra <pc-rel>   jmp <abs> | bra <pc-rel>  jmp <abs>          |
           bXX | bXX <pc-rel>    <error>  |               bNX +3; jmp <abs>  |
          jbXX | bXX <pc-rel>   bNX +3;   | bXX <pc-rel>  bNX +3; jmp <abs>  |
               |                jmp <abs> |                                  |
               +--------------------------+----------------------------------+
     XX: condition
     NX: negative of condition XX

`jbsr'
`jbra'
     These are the simplest jump pseudo-operations; they always map to
     one particular machine instruction, depending on the displacement
     to the branch target.

`jbXX'
     Here, `jbXX' stands for an entire family of pseudo-operations,
     where XX is a conditional branch or condition-code test.  The full
     list of pseudo-ops in this family is:
           jbcc   jbeq   jbge   jbgt   jbhi   jbvs   jbpl  jblo
           jbcs   jbne   jblt   jble   jbls   jbvc   jbmi

     For the cases of non-PC relative displacements and long
     displacements, `as' issues a longer code fragment in terms of NX,
     the opposite condition to XX.  For example, for the non-PC
     relative case:
              jbXX foo
     gives
               bNXs oof
               jmp foo
           oof:

Motorola M88K Dependent Features
================================

M88K Machine Directives
-----------------------

   The M88K version of the assembler supports the following machine
directives:

`.align'
     This directive aligns the section program counter on the next
     4-byte boundary.

`.dfloat EXPR'
     This assembles a double precision (64-bit) floating point constant.

`.ffloat EXPR'
     This assembles a single precision (32-bit) floating point constant.

`.half EXPR'
     This directive assembles a half-word (16-bit) constant.

`.word EXPR'
     This assembles a word (32-bit) constant.

`.string "STR"'
     This directive behaves like the standard `.ascii' directive for
     copying STR into the object file.  The string is not terminated
     with a null byte.

`.set SYMBOL, VALUE'
     This directive creates a symbol named SYMBOL which is an alias for
     another symbol (possibly not yet defined).  This should not be
     confused with the mnemonic `set', which is a legitimate M88K
     instruction.

`.def SYMBOL, VALUE'
     This directive is synonymous with `.set' and is presumably provided
     for compatibility with other M88K assemblers.

`.bss SYMBOL, LENGTH, ALIGN'
     Reserve LENGTH bytes in the bss section for a local SYMBOL,
     aligned to the power of two specified by ALIGN.  LENGTH and ALIGN
     must be positive absolute expressions.  This directive differs
     from `.lcomm' only in that it permits you to specify an alignment.
     See `.lcomm'.

MIPS Dependent Features
=======================

   GNU `as' for MIPS architectures supports several different MIPS
processors, and MIPS ISA levels I through V, MIPS32, and MIPS64.  For
information about the MIPS instruction set, see `MIPS RISC
Architecture', by Kane and Heindrich (Prentice-Hall).  For an overview
of MIPS assembly conventions, see "Appendix D: Assembly Language
Programming" in the same work.

Assembler options
-----------------

   The MIPS configurations of GNU `as' support these special options:

`-G NUM'
     This option sets the largest size of an object that can be
     referenced implicitly with the `gp' register.  It is only accepted
     for targets that use ECOFF format.  The default value is 8.

`-EB'
`-EL'
     Any MIPS configuration of `as' can select big-endian or
     little-endian output at run time (unlike the other GNU development
     tools, which must be configured for one or the other).  Use `-EB'
     to select big-endian output, and `-EL' for little-endian.

`-mips1'
`-mips2'
`-mips3'
`-mips4'
`-mips5'
`-mips32'
`-mips64'
     Generate code for a particular MIPS Instruction Set Architecture
     level.  `-mips1' corresponds to the R2000 and R3000 processors,
     `-mips2' to the R6000 processor, `-mips3' to the R4000 processor,
     and `-mips4' to the R8000 and R10000 processors.  `-mips5',
     `-mips32', and `-mips64' correspond to generic MIPS V, MIPS32, and
     MIPS64 ISA processors, respectively.  You can also switch
     instruction sets during the assembly; see Directives to override the ISA level.

`-mgp32'
`-mfp32'
     Some macros have different expansions for 32-bit and 64-bit
     registers.  The register sizes are normally inferred from the ISA
     and ABI, but these flags force a certain group of registers to be
     treated as 32 bits wide at all times.  `-mgp32' controls the size
     of general-purpose registers and `-mfp32' controls the size of
     floating-point registers.

     On some MIPS variants there is a 32-bit mode flag; when this flag
     is set, 64-bit instructions generate a trap.  Also, some 32-bit
     OSes only save the 32-bit registers on a context switch, so it is
     essential never to use the 64-bit registers.

`-mgp64'
     Assume that 64-bit general purpose registers are available.  This
     is provided in the interests of symmetry with -gp32.

`-mips16'
`-no-mips16'
     Generate code for the MIPS 16 processor.  This is equivalent to
     putting `.set mips16' at the start of the assembly file.
     `-no-mips16' turns off this option.

`-mips3d'
`-no-mips3d'
     Generate code for the MIPS-3D Application Specific Extension.
     This tells the assembler to accept MIPS-3D instructions.
     `-no-mips3d' turns off this option.

`-mfix7000'
`-no-mfix7000'
     Cause nops to be inserted if the read of the destination register
     of an mfhi or mflo instruction occurs in the following two
     instructions.

`-m4010'
`-no-m4010'
     Generate code for the LSI R4010 chip.  This tells the assembler to
     accept the R4010 specific instructions (`addciu', `ffc', etc.),
     and to not schedule `nop' instructions around accesses to the `HI'
     and `LO' registers.  `-no-m4010' turns off this option.

`-m4650'
`-no-m4650'
     Generate code for the MIPS R4650 chip.  This tells the assembler
     to accept the `mad' and `madu' instruction, and to not schedule
     `nop' instructions around accesses to the `HI' and `LO' registers.
     `-no-m4650' turns off this option.

`-m3900'
`-no-m3900'
`-m4100'
`-no-m4100'
     For each option `-mNNNN', generate code for the MIPS RNNNN chip.
     This tells the assembler to accept instructions specific to that
     chip, and to schedule for that chip's hazards.

`-march=CPU'
     Generate code for a particular MIPS cpu.  It is exactly equivalent
     to `-mCPU', except that there are more value of CPU understood.
     Valid CPU value are:

          2000, 3000, 3900, 4000, 4010, 4100, 4111, 4300, 4400, 4600,
          4650, 5000, rm5200, rm5230, rm5231, rm5261, rm5721, 6000,
          rm7000, 8000, 10000, 12000, mips32-4k, sb1

`-mtune=CPU'
     Schedule and tune for a particular MIPS cpu.  Valid CPU values are
     identical to `-march=CPU'.

`-mcpu=CPU'
     Generate code and schedule for a particular MIPS cpu.  This is
     exactly equivalent to `-march=CPU' and `-mtune=CPU'.  Valid CPU
     values are identical to `-march=CPU'.  Use of this option is
     discouraged.

`-nocpp'
     This option is ignored.  It is accepted for command-line
     compatibility with other assemblers, which use it to turn off C
     style preprocessing.  With GNU `as', there is no need for
     `-nocpp', because the GNU assembler itself never runs the C
     preprocessor.

`--construct-floats'
`--no-construct-floats'
     The `--no-construct-floats' option disables the construction of
     double width floating point constants by loading the two halves of
     the value into the two single width floating point registers that
     make up the double width register.  This feature is useful if the
     processor support the FR bit in its status  register, and this bit
     is known (by the programmer) to be set.  This bit prevents the
     aliasing of the double width register by the single width
     registers.

     By default `--construct-floats' is selected, allowing construction
     of these floating point constants.

`--trap'
`--no-break'
     `as' automatically macro expands certain division and
     multiplication instructions to check for overflow and division by
     zero.  This option causes `as' to generate code to take a trap
     exception rather than a break exception when an error is detected.
     The trap instructions are only supported at Instruction Set
     Architecture level 2 and higher.

`--break'
`--no-trap'
     Generate code to take a break exception rather than a trap
     exception when an error is detected.  This is the default.

`-n'
     When this option is used, `as' will issue a warning every time it
     generates a nop instruction from a macro.

MIPS ECOFF object code
----------------------

   Assembling for a MIPS ECOFF target supports some additional sections
besides the usual `.text', `.data' and `.bss'.  The additional sections
are `.rdata', used for read-only data, `.sdata', used for small data,
and `.sbss', used for small common objects.

   When assembling for ECOFF, the assembler uses the `$gp' (`$28')
register to form the address of a "small object".  Any object in the
`.sdata' or `.sbss' sections is considered "small" in this sense.  For
external objects, or for objects in the `.bss' section, you can use the
`gcc' `-G' option to control the size of objects addressed via `$gp';
the default value is 8, meaning that a reference to any object eight
bytes or smaller uses `$gp'.  Passing `-G 0' to `as' prevents it from
using the `$gp' register on the basis of object size (but the assembler
uses `$gp' for objects in `.sdata' or `sbss' in any case).  The size of
an object in the `.bss' section is set by the `.comm' or `.lcomm'
directive that defines it.  The size of an external object may be set
with the `.extern' directive.  For example, `.extern sym,4' declares
that the object at `sym' is 4 bytes in length, whie leaving `sym'
otherwise undefined.

   Using small ECOFF objects requires linker support, and assumes that
the `$gp' register is correctly initialized (normally done
automatically by the startup code).  MIPS ECOFF assembly code must not
modify the `$gp' register.

Directives for debugging information
------------------------------------

   MIPS ECOFF `as' supports several directives used for generating
debugging information which are not support by traditional MIPS
assemblers.  These are `.def', `.endef', `.dim', `.file', `.scl',
`.size', `.tag', `.type', `.val', `.stabd', `.stabn', and `.stabs'.
The debugging information generated by the three `.stab' directives can
only be read by GDB, not by traditional MIPS debuggers (this
enhancement is required to fully support C++ debugging).  These
directives are primarily used by compilers, not assembly language
programmers!

Directives to override the ISA level
------------------------------------

   GNU `as' supports an additional directive to change the MIPS
Instruction Set Architecture level on the fly: `.set mipsN'.  N should
be a number from 0 to 5, or 32 or 64.  The values 1 to 5, 32, and 64
make the assembler accept instructions for the corresponding ISA level,
from that point on in the assembly.  `.set mipsN' affects not only
which instructions are permitted, but also how certain macros are
expanded.  `.set mips0' restores the ISA level to its original level:
either the level you selected with command line options, or the default
for your configuration.  You can use this feature to permit specific
R4000 instructions while assembling in 32 bit mode.  Use this directive
with care!

   The directive `.set mips16' puts the assembler into MIPS 16 mode, in
which it will assemble instructions for the MIPS 16 processor.  Use
`.set nomips16' to return to normal 32 bit mode.

   Traditional MIPS assemblers do not support this directive.

Directives for extending MIPS 16 bit instructions
-------------------------------------------------

   By default, MIPS 16 instructions are automatically extended to 32
bits when necessary.  The directive `.set noautoextend' will turn this
off.  When `.set noautoextend' is in effect, any 32 bit instruction
must be explicitly extended with the `.e' modifier (e.g., `li.e
$4,1000').  The directive `.set autoextend' may be used to once again
automatically extend instructions when necessary.

   This directive is only meaningful when in MIPS 16 mode.  Traditional
MIPS assemblers do not support this directive.

Directive to mark data as an instruction
----------------------------------------

   The `.insn' directive tells `as' that the following data is actually
instructions.  This makes a difference in MIPS 16 mode: when loading
the address of a label which precedes instructions, `as' automatically
adds 1 to the value, so that jumping to the loaded address will do the
right thing.

Directives to save and restore options
--------------------------------------

   The directives `.set push' and `.set pop' may be used to save and
restore the current settings for all the options which are controlled
by `.set'.  The `.set push' directive saves the current settings on a
stack.  The `.set pop' directive pops the stack and restores the
settings.

   These directives can be useful inside an macro which must change an
option such as the ISA level or instruction reordering but does not want
to change the state of the code which invoked the macro.

   Traditional MIPS assemblers do not support these directives.

Directives to control generation of MIPS ASE instructions
---------------------------------------------------------

   The directive `.set mips3d' makes the assembler accept instructions
from the MIPS-3D Application Specific Extension from that point on in
the assembly.  The `.set nomips3d' directive prevents MIPS-3D
instructions from being accepted.

   Traditional MIPS assemblers do not support these directives.

MMIX Dependent Features
=======================

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

   The MMIX version of `as' has some machine-dependent options.

   When `--fixed-special-register-names' is specified, only the register
names specified in MMIX-Regs are recognized in the instructions
`PUT' and `GET'.

   You can use the `--globalize-symbols' to make all symbols global.
This option is useful when splitting up a `mmixal' program into several
files.

   The `--gnu-syntax' turns off most syntax compatibility with
`mmixal'.  Its usability is currently doubtful.

   The `--relax' option is not fully supported, but will eventually make
the object file prepared for linker relaxation.

   If you want to avoid inadvertently calling a predefined symbol and
would rather get an error, for example when using `as' with a compiler
or other machine-generated code, specify `--no-predefined-syms'.  This
turns off built-in predefined definitions of all such symbols,
including rounding-mode symbols, segment symbols, `BIT' symbols, and
`TRAP' symbols used in `mmix' "system calls".  It also turns off
predefined special-register names, except when used in `PUT' and `GET'
instructions.

   By default, some instructions are expanded to fit the size of the
operand or an external symbol (see MMIX-Expand).  By passing
`--no-expand', no such expansion will be done, instead causing errors
at link time if the operand does not fit.

   The `mmixal' documentation (see mmixsite) specifies that global
registers allocated with the `GREG' directive (see MMIX-greg) and
initialized to the same non-zero value, will refer to the same global
register.  This isn't strictly enforcable in `as' since the final
addresses aren't known until link-time, but it will do an effort unless
the `--no-merge-gregs' option is specified.  (Register merging isn't
yet implemented in `ld'.)

   `as' will warn every time it expands an instruction to fit an
operand unless the option `-x' is specified.  It is believed that this
behaviour is more useful than just mimicking `mmixal''s behaviour, in
which instructions are only expanded if the `-x' option is specified,
and assembly fails otherwise, when an instruction needs to be expanded.
It needs to be kept in mind that `mmixal' is both an assembler and
linker, while `as' will expand instructions that at link stage can be
contracted.  (Though linker relaxation isn't yet implemented in `ld'.)
The option `-x' also imples `--linker-allocated-gregs'.

   Usually a two-operand-expression (see GREG-base) without a
matching `GREG' directive is treated as an error by `as'.  When the
option `--linker-allocated-gregs' is in effect, they are instead passed
through to the linker, which will allocate as many global registers as
is needed.

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

   When `as' encounters an instruction with an operand that is either
not known or does not fit the operand size of the instruction, `as'
(and `ld') will expand the instruction into a sequence of instructions
semantically equivalent to the operand fitting the instruction.
Expansion will take place for the following instructions:

`GETA'
     Expands to a sequence of four instructions: `SETL', `INCML',
     `INCMH' and `INCH'.  The operand must be a multiple of four.

Conditional branches
     A branch instruction is turned into a branch with the complemented
     condition and prediction bit over five instructions; four
     instructions setting `$255' to the operand value, which like with
     `GETA' must be a multiple of four, and a final `GO $255,$255,0'.

`PUSHJ'
     Similar to expansion for conditional branches; four instructions
     set `$255' to the operand value, followed by a `PUSHGO
     $255,$255,0'.

`JMP'
     Similar to conditional branches and `PUSHJ'.  The final instruction
     is `GO $255,$255,0'.

   The linker `ld' is expected to shrink these expansions for code
assembled with `--relax' (though not currently implemented).

Syntax
------

   The assembly syntax is supposed to be upward compatible with that
described in Sections 1.3 and 1.4 of `The Art of Computer Programming,
Volume 1'.  Draft versions of those chapters as well as other MMIX
information is located at
<http://www-cs-faculty.stanford.edu/~knuth/mmix-news.html>.  Most code
examples from the mmixal package located there should work unmodified
when assembled and linked as single files, with a few noteworthy
exceptions (see MMIX-mmixal).

   Before an instruction is emitted, the current location is aligned to
the next four-byte boundary.  If a label is defined at the beginning of
the line, its value will be the aligned value.

   In addition to the traditional hex-prefix `0x', a hexadecimal number
can also be specified by the prefix character `#'.

   After all operands to an MMIX instruction or directive have been
specified, the rest of the line is ignored, treated as a comment.

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

   The characters `*' and `#' are line comment characters; each start a
comment at the beginning of a line, but only at the beginning of a
line.  A `#' prefixes a hexadecimal number if found elsewhere on a line.

   Two other characters, `%' and `!', each start a comment anywhere on
the line.  Thus you can't use the `modulus' and `not' operators in
expressions normally associated with these two characters.

   A `;' is a line separator, treated as a new-line, so separate
instructions can be specified on a single line.

Symbols
.......

   The character `:' is permitted in identifiers.  There are two
exceptions to it being treated as any other symbol character: if a
symbol begins with `:', it means that the symbol is in the global
namespace and that the current prefix should not be prepended to that
symbol (see MMIX-prefix).  The `:' is then not considered part of
the symbol.  For a symbol in the label position (first on a line), a `:'
at the end of a symbol is silently stripped off.  A label is permitted,
but not required, to be followed by a `:', as with many other assembly
formats.

   The character `@' in an expression, is a synonym for `.', the
current location.

   In addition to the common forward and backward local symbol formats
(see Symbol Names), they can be specified with upper-case `B' and
`F', as in `8B' and `9F'.  A local label defined for the current
position is written with a `H' appended to the number:
     3H LDB $0,$1,2
   This and traditional local-label formats cannot be mixed: a label
must be defined and referred to using the same format.

   There's a minor caveat: just as for the ordinary local symbols, the
local symbols are translated into ordinary symbols using control
characters are to hide the ordinal number of the symbol.
Unfortunately, these symbols are not translated back in error messages.
Thus you may see confusing error messages when local symbols are used.
Control characters `\003' (control-C) and `\004' (control-D) are used
for the MMIX-specific local-symbol syntax.

   The symbol `Main' is handled specially; it is always global.

   By defining the symbols `__.MMIX.start..text' and
`__.MMIX.start..data', the address of respectively the `.text' and
`.data' segments of the final program can be defined, though when
linking more than one object file, the code or data in the object file
containing the symbol is not guaranteed to be start at that position;
just the final executable.  See MMIX-loc.

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

   Local and global registers are specified as `$0' to `$255'.  The
recognized special register names are `rJ', `rA', `rB', `rC', `rD',
`rE', `rF', `rG', `rH', `rI', `rK', `rL', `rM', `rN', `rO', `rP', `rQ',
`rR', `rS', `rT', `rU', `rV', `rW', `rX', `rY', `rZ', `rBB', `rTT',
`rWW', `rXX', `rYY' and `rZZ'.  A leading `:' is optional for special
register names.

   Local and global symbols can be equated to register names and used in
place of ordinary registers.

   Similarly for special registers, local and global symbols can be
used.  Also, symbols equated from numbers and constant expressions are
allowed in place of a special register, except when either of the
options `--no-predefined-syms' and `--fixed-special-register-names' are
specified.  Then only the special register names above are allowed for
the instructions having a special register operand; `GET' and `PUT'.

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

`LOC'
     The `LOC' directive sets the current location to the value of the
     operand field, which may include changing sections.  If the
     operand is a constant, the section is set to either `.data' if the
     value is `0x2000000000000000' or larger, else it is set to `.text'.
     Within a section, the current location may only be changed to
     monotonically higher addresses.  A LOC expression must be a
     previously defined symbol or a "pure" constant.

     An example, which sets the label PREV to the current location, and
     updates the current location to eight bytes forward:
          prev LOC @+8

     When a LOC has a constant as its operand, a symbol
     `__.MMIX.start..text' or `__.MMIX.start..data' is defined
     depending on the address as mentioned above.  Each such symbol is
     interpreted as special by the linker, locating the section at that
     address.  Note that if multiple files are linked, the first object
     file with that section will be mapped to that address (not
     necessarily the file with the LOC definition).

`LOCAL'
     Example:
           LOCAL external_symbol
           LOCAL 42
           .local asymbol

     This directive-operation generates a link-time assertion that the
     operand does not correspond to a global register.  The operand is
     an expression that at link-time resolves to a register symbol or a
     number.  A number is treated as the register having that number.
     There is one restriction on the use of this directive: the
     pseudo-directive must be placed in a section with contents, code
     or data.

`IS'
     The `IS' directive:
          asymbol IS an_expression
     sets the symbol `asymbol' to `an_expression'.  A symbol may not be
     set more than once using this directive.  Local labels may be set
     using this directive, for example:
          5H IS @+4

`GREG'
     This directive reserves a global register, gives it an initial
     value and optionally gives it a symbolic name.  Some examples:

          areg GREG
          breg GREG data_value
               GREG data_buffer
               .greg creg, another_data_value

     The symbolic register name can be used in place of a (non-special)
     register.  If a value isn't provided, it defaults to zero.  Unless
     the option `--no-merge-gregs' is specified, non-zero registers
     allocated with this directive may be eliminated by `as'; another
     register with the same value used in its place.  Any of the
     instructions `CSWAP', `GO', `LDA', `LDBU', `LDB', `LDHT', `LDOU',
     `LDO', `LDSF', `LDTU', `LDT', `LDUNC', `LDVTS', `LDWU', `LDW',
     `PREGO', `PRELD', `PREST', `PUSHGO', `STBU', `STB', `STCO', `STHT',
     `STOU', `STSF', `STTU', `STT', `STUNC', `SYNCD', `SYNCID', can
     have a value nearby an initial value in place of its second and
     third operands.  Here, "nearby" is defined as within the range
     0...255 from the initial value of such an allocated register.

          buffer1 BYTE 0,0,0,0,0
          buffer2 BYTE 0,0,0,0,0
           ...
           GREG buffer1
           LDOU $42,buffer2
     In the example above, the `Y' field of the `LDOUI' instruction
     (LDOU with a constant Z) will be replaced with the global register
     allocated for `buffer1', and the `Z' field will have the value 5,
     the offset from `buffer1' to `buffer2'.  The result is equivalent
     to this code:
          buffer1 BYTE 0,0,0,0,0
          buffer2 BYTE 0,0,0,0,0
           ...
          tmpreg GREG buffer1
           LDOU $42,tmpreg,(buffer2-buffer1)

     Global registers allocated with this directive are allocated in
     order higher-to-lower within a file.  Other than that, the exact
     order of register allocation and elimination is undefined.  For
     example, the order is undefined when more than one file with such
     directives are linked together.  With the options `-x' and
     `--linker-allocated-gregs', `GREG' directives for two-operand
     cases like the one mentioned above can be omitted.  Sufficient
     global registers will then be allocated by the linker.

`BYTE'
     The `BYTE' directive takes a series of operands separated by a
     comma.  If an operand is a string (see Strings), each
     character of that string is emitted as a byte.  Other operands
     must be constant expressions without forward references, in the
     range 0...255.  If you need operands having expressions with
     forward references, use `.byte' (see Byte).  An operand can be
     omitted, defaulting to a zero value.

`WYDE'
`TETRA'
`OCTA'
     The directives `WYDE', `TETRA' and `OCTA' emit constants of two,
     four and eight bytes size respectively.  Before anything else
     happens for the directive, the current location is aligned to the
     respective constant-size bondary.  If a label is defined at the
     beginning of the line, its value will be that after the alignment.
     A single operand can be omitted, defaulting to a zero value
     emitted for the directive.  Operands can be expressed as strings
     (see Strings), in which case each character in the string is
     emitted as a separate constant of the size indicated by the
     directive.

`PREFIX'
     The `PREFIX' directive sets a symbol name prefix to be prepended to
     all symbols (except local symbols, see MMIX-Symbols), that are
     not prefixed with `:', until the next `PREFIX' directive.  Such
     prefixes accumulate.  For example,
           PREFIX a
           PREFIX b
          c IS 0
     defines a symbol `abc' with the value 0.

`BSPEC'
`ESPEC'
     A pair of `BSPEC' and `ESPEC' directives delimit a section of
     special contents (without specified semantics).  Example:
           BSPEC 42
           TETRA 1,2,3
           ESPEC
     The single operand to `BSPEC' must be number in the range 0...255.
     The `BSPEC' number 80 is used by the GNU binutils implementation.