-@node MIPS Object
-@section MIPS ECOFF object code
-
-@cindex ECOFF sections
-@cindex MIPS ECOFF sections
-Assembling for a @sc{mips} @sc{ecoff} target supports some additional sections
-besides the usual @code{.text}, @code{.data} and @code{.bss}. The
-additional sections are @code{.rdata}, used for read-only data,
-@code{.sdata}, used for small data, and @code{.sbss}, used for small
-common objects.
-
-@cindex small objects, MIPS ECOFF
-@cindex @code{gp} register, MIPS
-When assembling for @sc{ecoff}, the assembler uses the @code{$gp} (@code{$28})
-register to form the address of a ``small object''. Any object in the
-@code{.sdata} or @code{.sbss} sections is considered ``small'' in this sense.
-For external objects, or for objects in the @code{.bss} section, you can use
-the @code{@value{GCC}} @samp{-G} option to control the size of objects addressed via
-@code{$gp}; the default value is 8, meaning that a reference to any object
-eight bytes or smaller uses @code{$gp}. Passing @samp{-G 0} to
-@code{@value{AS}} prevents it from using the @code{$gp} register on the basis
-of object size (but the assembler uses @code{$gp} for objects in @code{.sdata}
-or @code{sbss} in any case). The size of an object in the @code{.bss} section
-is set by the @code{.comm} or @code{.lcomm} directive that defines it. The
-size of an external object may be set with the @code{.extern} directive. For
-example, @samp{.extern sym,4} declares that the object at @code{sym} is 4 bytes
-in length, whie leaving @code{sym} otherwise undefined.
-
-Using small @sc{ecoff} objects requires linker support, and assumes that the
-@code{$gp} register is correctly initialized (normally done automatically by
-the startup code). @sc{mips} @sc{ecoff} assembly code must not modify the
-@code{$gp} register.
-
-@node MIPS Stabs
-@section Directives for debugging information
-
-@cindex MIPS debugging directives
-@sc{mips} @sc{ecoff} @code{@value{AS}} supports several directives used for
-generating debugging information which are not support by traditional @sc{mips}
-assemblers. These are @code{.def}, @code{.endef}, @code{.dim}, @code{.file},
-@code{.scl}, @code{.size}, @code{.tag}, @code{.type}, @code{.val},
-@code{.stabd}, @code{.stabn}, and @code{.stabs}. The debugging information
-generated by the three @code{.stab} directives can only be read by @sc{gdb},
-not by traditional @sc{mips} debuggers (this enhancement is required to fully
-support C++ debugging). These directives are primarily used by compilers, not
-assembly language programmers!
-
-@node MIPS symbol sizes
+@node MIPS Macros
+@section High-level assembly macros
+
+MIPS assemblers have traditionally provided a wider range of
+instructions than the MIPS architecture itself. These extra
+instructions are usually referred to as ``macro'' instructions
+@footnote{The term ``macro'' is somewhat overloaded here, since
+these macros have no relation to those defined by @code{.macro},
+@pxref{Macro,, @code{.macro}}.}.
+
+Some MIPS macro instructions extend an underlying architectural instruction
+while others are entirely new. An example of the former type is @code{and},
+which allows the third operand to be either a register or an arbitrary
+immediate value. Examples of the latter type include @code{bgt}, which
+branches to the third operand when the first operand is greater than
+the second operand, and @code{ulh}, which implements an unaligned
+2-byte load.
+
+One of the most common extensions provided by macros is to expand
+memory offsets to the full address range (32 or 64 bits) and to allow
+symbolic offsets such as @samp{my_data + 4} to be used in place of
+integer constants. For example, the architectural instruction
+@code{lbu} allows only a signed 16-bit offset, whereas the macro
+@code{lbu} allows code such as @samp{lbu $4,array+32769($5)}.
+The implementation of these symbolic offsets depends on several factors,
+such as whether the assembler is generating SVR4-style PIC (selected by
+@option{-KPIC}, @pxref{MIPS Options,, Assembler options}), the size of symbols
+(@pxref{MIPS Symbol Sizes,, Directives to override the size of symbols}),
+and the small data limit (@pxref{MIPS Small Data,, Controlling the use
+of small data accesses}).
+
+@kindex @code{.set macro}
+@kindex @code{.set nomacro}
+Sometimes it is undesirable to have one assembly instruction expand
+to several machine instructions. The directive @code{.set nomacro}
+tells the assembler to warn when this happens. @code{.set macro}
+restores the default behavior.
+
+@cindex @code{at} register, MIPS
+@kindex @code{.set at=@var{reg}}
+Some macro instructions need a temporary register to store intermediate
+results. This register is usually @code{$1}, also known as @code{$at},
+but it can be changed to any core register @var{reg} using
+@code{.set at=@var{reg}}. Note that @code{$at} always refers
+to @code{$1} regardless of which register is being used as the
+temporary register.
+
+@kindex @code{.set at}
+@kindex @code{.set noat}
+Implicit uses of the temporary register in macros could interfere with
+explicit uses in the assembly code. The assembler therefore warns
+whenever it sees an explicit use of the temporary register. The directive
+@code{.set noat} silences this warning while @code{.set at} restores
+the default behavior. It is safe to use @code{.set noat} while
+@code{.set nomacro} is in effect since single-instruction macros
+never need a temporary register.
+
+Note that while the @sc{gnu} assembler provides these macros for compatibility,
+it does not make any attempt to optimize them with the surrounding code.
+
+@node MIPS Symbol Sizes