-@c Copyright (C) 1991, 92, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c Copyright (C) 1991-2014 Free Software Foundation, Inc.
@c This is part of the GAS manual.
@c For copying conditions, see the file as.texinfo.
@ifset GENERIC
@end ifclear
@cindex MIPS processor
-@sc{gnu} @code{@value{AS}} for @sc{mips} architectures supports several
-different @sc{mips} processors, and MIPS ISA levels I through IV. For
-information about the @sc{mips} instruction set, see @cite{MIPS RISC
-Architecture}, by Kane and Heindrich (Prentice-Hall). For an overview
-of @sc{mips} assembly conventions, see ``Appendix D: Assembly Language
-Programming'' in the same work.
+@sc{gnu} @code{@value{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
+@cite{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.
@menu
-* MIPS Opts:: Assembler options
-* MIPS Object:: ECOFF object code
-* MIPS Stabs:: Directives for debugging information
+* MIPS Options:: Assembler options
+* MIPS Macros:: High-level assembly macros
+* MIPS Symbol Sizes:: Directives to override the size of symbols
+* MIPS Small Data:: Controlling the use of small data accesses
* MIPS ISA:: Directives to override the ISA level
+* MIPS assembly options:: Directives to control code generation
* MIPS autoextend:: Directives for extending MIPS 16 bit instructions
* MIPS insn:: Directive to mark data as an instruction
-* MIPS option stack:: Directives to save and restore options
+* MIPS FP ABIs:: Marking which FP ABI is in use
+* MIPS NaN Encodings:: Directives to record which NaN encoding is being used
+* MIPS Option Stack:: Directives to save and restore options
+* MIPS ASE Instruction Generation Overrides:: Directives to control
+ generation of MIPS ASE instructions
+* MIPS Floating-Point:: Directives to override floating-point options
+* MIPS Syntax:: MIPS specific syntactical considerations
@end menu
-@node MIPS Opts
+@node MIPS Options
@section Assembler options
-The @sc{mips} configurations of @sc{gnu} @code{@value{AS}} support these
+The MIPS configurations of @sc{gnu} @code{@value{AS}} support these
special options:
@table @code
@cindex @code{-G} option (MIPS)
@item -G @var{num}
-This option sets the largest size of an object that can be referenced
-implicitly with the @code{gp} register. It is only accepted for targets
-that use @sc{ecoff} format. The default value is 8.
+Set the ``small data'' limit to @var{n} bytes. The default limit is 8 bytes.
+@xref{MIPS Small Data,, Controlling the use of small data accesses}.
@cindex @code{-EB} option (MIPS)
@cindex @code{-EL} option (MIPS)
@cindex little-endian output, MIPS
@item -EB
@itemx -EL
-Any @sc{mips} configuration of @code{@value{AS}} can select big-endian or
+Any MIPS configuration of @code{@value{AS}} can select big-endian or
little-endian output at run time (unlike the other @sc{gnu} development
tools, which must be configured for one or the other). Use @samp{-EB}
to select big-endian output, and @samp{-EL} for little-endian.
+@item -KPIC
+@cindex PIC selection, MIPS
+@cindex @option{-KPIC} option, MIPS
+Generate SVR4-style PIC. This option tells the assembler to generate
+SVR4-style position-independent macro expansions. It also tells the
+assembler to mark the output file as PIC.
+
+@item -mvxworks-pic
+@cindex @option{-mvxworks-pic} option, MIPS
+Generate VxWorks PIC. This option tells the assembler to generate
+VxWorks-style position-independent macro expansions.
+
@cindex MIPS architecture options
@item -mips1
@itemx -mips2
@itemx -mips3
@itemx -mips4
+@itemx -mips5
+@itemx -mips32
+@itemx -mips32r2
+@itemx -mips32r3
+@itemx -mips32r5
+@itemx -mips32r6
+@itemx -mips64
+@itemx -mips64r2
+@itemx -mips64r3
+@itemx -mips64r5
+@itemx -mips64r6
Generate code for a particular MIPS Instruction Set Architecture level.
-@samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
-@samp{-mips2} to the @sc{r6000} processor, @samp{-mips3} to the
-@sc{r4000} processor, and @samp{-mips4} to the @sc{r8000} and
-@sc{r10000} processors. You can also switch instruction sets during the
-assembly; see @ref{MIPS ISA,, Directives to override the ISA level}.
+@samp{-mips1} corresponds to the R2000 and R3000 processors,
+@samp{-mips2} to the R6000 processor, @samp{-mips3} to the
+R4000 processor, and @samp{-mips4} to the R8000 and R10000 processors.
+@samp{-mips5}, @samp{-mips32}, @samp{-mips32r2}, @samp{-mips32r3},
+@samp{-mips32r5}, @samp{-mips32r6}, @samp{-mips64}, @samp{-mips64r2},
+@samp{-mips64r3}, @samp{-mips64r5}, and @samp{-mips64r6} correspond to
+generic MIPS V, MIPS32, MIPS32 Release 2, MIPS32 Release 3, MIPS32
+Release 5, MIPS32 Release 6, MIPS64, and MIPS64 Release 2, MIPS64
+Release 3, MIPS64 Release 5, and MIPS64 Release 6 ISA processors,
+respectively. You can also switch instruction sets during the assembly;
+see @ref{MIPS ISA, Directives to override the ISA level}.
@item -mgp32
-Assume that 32-bit general purpose registers are available. This
-affects synthetic instructions such as @code{move}, which will assemble
-to a 32-bit or a 64-bit instruction depending on this flag. 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.
+@itemx -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. @samp{-mgp32} controls the size of general-purpose registers
+and @samp{-mfp32} controls the size of floating-point registers.
+
+The @code{.set gp=32} and @code{.set fp=32} directives allow the size
+of registers to be changed for parts of an object. The default value is
+restored by @code{.set gp=default} and @code{.set fp=default}.
+
+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.
@item -mgp64
-Assume that 64-bit general purpose registers are available. This is
-provided in the interests of symmetry with -gp32.
+@itemx -mfp64
+Assume that 64-bit registers are available. This is provided in the
+interests of symmetry with @samp{-mgp32} and @samp{-mfp32}.
+
+The @code{.set gp=64} and @code{.set fp=64} directives allow the size
+of registers to be changed for parts of an object. The default value is
+restored by @code{.set gp=default} and @code{.set fp=default}.
+
+@item -mfpxx
+Make no assumptions about whether 32-bit or 64-bit floating-point
+registers are available. This is provided to support having modules
+compatible with either @samp{-mfp32} or @samp{-mfp64}. This option can
+only be used with MIPS II and above.
+
+The @code{.set fp=xx} directive allows a part of an object to be marked
+as not making assumptions about 32-bit or 64-bit FP registers. The
+default value is restored by @code{.set fp=default}.
+
+@item -modd-spreg
+@itemx -mno-odd-spreg
+Enable use of floating-point operations on odd-numbered single-precision
+registers when supported by the ISA. @samp{-mfpxx} implies
+@samp{-mno-odd-spreg}, otherwise the default is @samp{-modd-spreg}
@item -mips16
@itemx -no-mips16
Generate code for the MIPS 16 processor. This is equivalent to putting
-@samp{.set mips16} at the start of the assembly file. @samp{-no-mips16}
+@code{.set mips16} at the start of the assembly file. @samp{-no-mips16}
turns off this option.
+@item -mmicromips
+@itemx -mno-micromips
+Generate code for the microMIPS processor. This is equivalent to putting
+@code{.set micromips} at the start of the assembly file. @samp{-mno-micromips}
+turns off this option. This is equivalent to putting @code{.set nomicromips}
+at the start of the assembly file.
+
+@item -msmartmips
+@itemx -mno-smartmips
+Enables the SmartMIPS extensions to the MIPS32 instruction set, which
+provides a number of new instructions which target smartcard and
+cryptographic applications. This is equivalent to putting
+@code{.set smartmips} at the start of the assembly file.
+@samp{-mno-smartmips} turns off this option.
+
+@item -mips3d
+@itemx -no-mips3d
+Generate code for the MIPS-3D Application Specific Extension.
+This tells the assembler to accept MIPS-3D instructions.
+@samp{-no-mips3d} turns off this option.
+
+@item -mdmx
+@itemx -no-mdmx
+Generate code for the MDMX Application Specific Extension.
+This tells the assembler to accept MDMX instructions.
+@samp{-no-mdmx} turns off this option.
+
+@item -mdsp
+@itemx -mno-dsp
+Generate code for the DSP Release 1 Application Specific Extension.
+This tells the assembler to accept DSP Release 1 instructions.
+@samp{-mno-dsp} turns off this option.
+
+@item -mdspr2
+@itemx -mno-dspr2
+Generate code for the DSP Release 2 Application Specific Extension.
+This option implies -mdsp.
+This tells the assembler to accept DSP Release 2 instructions.
+@samp{-mno-dspr2} turns off this option.
+
+@item -mmt
+@itemx -mno-mt
+Generate code for the MT Application Specific Extension.
+This tells the assembler to accept MT instructions.
+@samp{-mno-mt} turns off this option.
+
+@item -mmcu
+@itemx -mno-mcu
+Generate code for the MCU Application Specific Extension.
+This tells the assembler to accept MCU instructions.
+@samp{-mno-mcu} turns off this option.
+
+@item -mmsa
+@itemx -mno-msa
+Generate code for the MIPS SIMD Architecture Extension.
+This tells the assembler to accept MSA instructions.
+@samp{-mno-msa} turns off this option.
+
+@item -mxpa
+@itemx -mno-xpa
+Generate code for the MIPS eXtended Physical Address (XPA) Extension.
+This tells the assembler to accept XPA instructions.
+@samp{-mno-xpa} turns off this option.
+
+@item -mvirt
+@itemx -mno-virt
+Generate code for the Virtualization Application Specific Extension.
+This tells the assembler to accept Virtualization instructions.
+@samp{-mno-virt} turns off this option.
+
+@item -minsn32
+@itemx -mno-insn32
+Only use 32-bit instruction encodings when generating code for the
+microMIPS processor. This option inhibits the use of any 16-bit
+instructions. This is equivalent to putting @code{.set insn32} at
+the start of the assembly file. @samp{-mno-insn32} turns off this
+option. This is equivalent to putting @code{.set noinsn32} at the
+start of the assembly file. By default @samp{-mno-insn32} is
+selected, allowing all instructions to be used.
+
@item -mfix7000
-@itemx -no-mfix7000
+@itemx -mno-fix7000
Cause nops to be inserted if the read of the destination register
of an mfhi or mflo instruction occurs in the following two instructions.
+@item -mfix-rm7000
+@itemx -mno-fix-rm7000
+Cause nops to be inserted if a dmult or dmultu instruction is
+followed by a load instruction.
+
+@item -mfix-loongson2f-jump
+@itemx -mno-fix-loongson2f-jump
+Eliminate instruction fetch from outside 256M region to work around the
+Loongson2F @samp{jump} instructions. Without it, under extreme cases,
+the kernel may crash. The issue has been solved in latest processor
+batches, but this fix has no side effect to them.
+
+@item -mfix-loongson2f-nop
+@itemx -mno-fix-loongson2f-nop
+Replace nops by @code{or at,at,zero} to work around the Loongson2F
+@samp{nop} errata. Without it, under extreme cases, the CPU might
+deadlock. The issue has been solved in later Loongson2F batches, but
+this fix has no side effect to them.
+
+@item -mfix-vr4120
+@itemx -mno-fix-vr4120
+Insert nops to work around certain VR4120 errata. This option is
+intended to be used on GCC-generated code: it is not designed to catch
+all problems in hand-written assembler code.
+
+@item -mfix-vr4130
+@itemx -mno-fix-vr4130
+Insert nops to work around the VR4130 @samp{mflo}/@samp{mfhi} errata.
+
+@item -mfix-24k
+@itemx -mno-fix-24k
+Insert nops to work around the 24K @samp{eret}/@samp{deret} errata.
+
+@item -mfix-cn63xxp1
+@itemx -mno-fix-cn63xxp1
+Replace @code{pref} hints 0 - 4 and 6 - 24 with hint 28 to work around
+certain CN63XXP1 errata.
+
@item -m4010
@itemx -no-m4010
-Generate code for the LSI @sc{r4010} chip. This tells the assembler to
-accept the @sc{r4010} specific instructions (@samp{addciu}, @samp{ffc},
+Generate code for the LSI R4010 chip. This tells the assembler to
+accept the R4010-specific instructions (@samp{addciu}, @samp{ffc},
etc.), and to not schedule @samp{nop} instructions around accesses to
the @samp{HI} and @samp{LO} registers. @samp{-no-m4010} turns off this
option.
@item -m4650
@itemx -no-m4650
-Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept
+Generate code for the MIPS R4650 chip. This tells the assembler to accept
the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
instructions around accesses to the @samp{HI} and @samp{LO} registers.
@samp{-no-m4650} turns off this option.
-@itemx -m3900
+@item -m3900
@itemx -no-m3900
@itemx -m4100
@itemx -no-m4100
For each option @samp{-m@var{nnnn}}, generate code for the MIPS
-@sc{r@var{nnnn}} chip. This tells the assembler to accept instructions
+R@var{nnnn} chip. This tells the assembler to accept instructions
specific to that chip, and to schedule for that chip's hazards.
-@item -mcpu=@var{cpu}
-Generate code for a particular MIPS cpu. It is exactly equivalent to
+@item -march=@var{cpu}
+Generate code for a particular MIPS CPU. It is exactly equivalent to
@samp{-m@var{cpu}}, except that there are more value of @var{cpu}
understood. Valid @var{cpu} value are:
4010,
4100,
4111,
+vr4120,
+vr4130,
+vr4181,
4300,
4400,
4600,
4650,
5000,
+rm5200,
+rm5230,
+rm5231,
+rm5261,
+rm5721,
+vr5400,
+vr5500,
6000,
+rm7000,
8000,
-10000
+rm9000,
+10000,
+12000,
+14000,
+16000,
+4kc,
+4km,
+4kp,
+4ksc,
+4kec,
+4kem,
+4kep,
+4ksd,
+m4k,
+m4kp,
+m14k,
+m14kc,
+m14ke,
+m14kec,
+24kc,
+24kf2_1,
+24kf,
+24kf1_1,
+24kec,
+24kef2_1,
+24kef,
+24kef1_1,
+34kc,
+34kf2_1,
+34kf,
+34kf1_1,
+34kn,
+74kc,
+74kf2_1,
+74kf,
+74kf1_1,
+74kf3_2,
+1004kc,
+1004kf2_1,
+1004kf,
+1004kf1_1,
+p5600,
+5kc,
+5kf,
+20kc,
+25kf,
+sb1,
+sb1a,
+loongson2e,
+loongson2f,
+loongson3a,
+octeon,
+octeon+,
+octeon2,
+xlr,
+xlp
@end quotation
+For compatibility reasons, @samp{@var{n}x} and @samp{@var{b}fx} are
+accepted as synonyms for @samp{@var{n}f1_1}. These values are
+deprecated.
+
+@item -mtune=@var{cpu}
+Schedule and tune for a particular MIPS CPU. Valid @var{cpu} values are
+identical to @samp{-march=@var{cpu}}.
+
+@item -mabi=@var{abi}
+Record which ABI the source code uses. The recognized arguments
+are: @samp{32}, @samp{n32}, @samp{o64}, @samp{64} and @samp{eabi}.
+
+@item -msym32
+@itemx -mno-sym32
+@cindex -msym32
+@cindex -mno-sym32
+Equivalent to adding @code{.set sym32} or @code{.set nosym32} to
+the beginning of the assembler input. @xref{MIPS Symbol Sizes}.
@cindex @code{-nocpp} ignored (MIPS)
@item -nocpp
@sc{gnu} @code{@value{AS}}, there is no need for @samp{-nocpp}, because the
@sc{gnu} assembler itself never runs the C preprocessor.
+@item -msoft-float
+@itemx -mhard-float
+Disable or enable floating-point instructions. Note that by default
+floating-point instructions are always allowed even with CPU targets
+that don't have support for these instructions.
+
+@item -msingle-float
+@itemx -mdouble-float
+Disable or enable double-precision floating-point operations. Note
+that by default double-precision floating-point operations are always
+allowed even with CPU targets that don't have support for these
+operations.
+
+@item --construct-floats
+@itemx --no-construct-floats
+The @code{--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 @code{--construct-floats} is selected, allowing construction
+of these floating point constants.
+
+@item --relax-branch
+@itemx --no-relax-branch
+The @samp{--relax-branch} option enables the relaxation of out-of-range
+branches. Any branches whose target cannot be reached directly are
+converted to a small instruction sequence including an inverse-condition
+branch to the physically next instruction, and a jump to the original
+target is inserted between the two instructions. In PIC code the jump
+will involve further instructions for address calculation.
+
+The @code{BC1ANY2F}, @code{BC1ANY2T}, @code{BC1ANY4F}, @code{BC1ANY4T},
+@code{BPOSGE32} and @code{BPOSGE64} instructions are excluded from
+relaxation, because they have no complementing counterparts. They could
+be relaxed with the use of a longer sequence involving another branch,
+however this has not been implemented and if their target turns out of
+reach, they produce an error even if branch relaxation is enabled.
+
+Also no MIPS16 branches are ever relaxed.
+
+By default @samp{--no-relax-branch} is selected, causing any out-of-range
+branches to produce an error.
+
+@cindex @option{-mnan=} command line option, MIPS
+@item -mnan=@var{encoding}
+This option indicates whether the source code uses the IEEE 2008
+NaN encoding (@option{-mnan=2008}) or the original MIPS encoding
+(@option{-mnan=legacy}). It is equivalent to adding a @code{.nan}
+directive to the beginning of the source file. @xref{MIPS NaN Encodings}.
+
+@option{-mnan=legacy} is the default if no @option{-mnan} option or
+@code{.nan} directive is used.
+
@item --trap
@itemx --no-break
@c FIXME! (1) reflect these options (next item too) in option summaries;
@itemx --no-trap
Generate code to take a break exception rather than a trap exception when an
error is detected. This is the default.
+
+@item -mpdr
+@itemx -mno-pdr
+Control generation of @code{.pdr} sections. Off by default on IRIX, on
+elsewhere.
+
+@item -mshared
+@itemx -mno-shared
+When generating code using the Unix calling conventions (selected by
+@samp{-KPIC} or @samp{-mcall_shared}), gas will normally generate code
+which can go into a shared library. The @samp{-mno-shared} option
+tells gas to generate code which uses the calling convention, but can
+not go into a shared library. The resulting code is slightly more
+efficient. This option only affects the handling of the
+@samp{.cpload} and @samp{.cpsetup} pseudo-ops.
@end table
-@node MIPS Object
-@section MIPS ECOFF object code
+@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
+@section Directives to override the size of symbols
+
+@kindex @code{.set sym32}
+@kindex @code{.set nosym32}
+The n64 ABI allows symbols to have any 64-bit value. Although this
+provides a great deal of flexibility, it means that some macros have
+much longer expansions than their 32-bit counterparts. For example,
+the non-PIC expansion of @samp{dla $4,sym} is usually:
-@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.
+@smallexample
+lui $4,%highest(sym)
+lui $1,%hi(sym)
+daddiu $4,$4,%higher(sym)
+daddiu $1,$1,%lo(sym)
+dsll32 $4,$4,0
+daddu $4,$4,$1
+@end smallexample
-@cindex small objects, MIPS ECOFF
+whereas the 32-bit expansion is simply:
+
+@smallexample
+lui $4,%hi(sym)
+daddiu $4,$4,%lo(sym)
+@end smallexample
+
+n64 code is sometimes constructed in such a way that all symbolic
+constants are known to have 32-bit values, and in such cases, it's
+preferable to use the 32-bit expansion instead of the 64-bit
+expansion.
+
+You can use the @code{.set sym32} directive to tell the assembler
+that, from this point on, all expressions of the form
+@samp{@var{symbol}} or @samp{@var{symbol} + @var{offset}}
+have 32-bit values. For example:
+
+@smallexample
+.set sym32
+dla $4,sym
+lw $4,sym+16
+sw $4,sym+0x8000($4)
+@end smallexample
+
+will cause the assembler to treat @samp{sym}, @code{sym+16} and
+@code{sym+0x8000} as 32-bit values. The handling of non-symbolic
+addresses is not affected.
+
+The directive @code{.set nosym32} ends a @code{.set sym32} block and
+reverts to the normal behavior. It is also possible to change the
+symbol size using the command-line options @option{-msym32} and
+@option{-mno-sym32}.
+
+These options and directives are always accepted, but at present,
+they have no effect for anything other than n64.
+
+@node MIPS Small Data
+@section Controlling the use of small data accesses
+
+@c This section deliberately glosses over the possibility of using -G
+@c in SVR4-style PIC, as could be done on IRIX. We don't support that.
+@cindex small data, MIPS
@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!
+It often takes several instructions to load the address of a symbol.
+For example, when @samp{addr} is a 32-bit symbol, the non-PIC expansion
+of @samp{dla $4,addr} is usually:
+
+@smallexample
+lui $4,%hi(addr)
+daddiu $4,$4,%lo(addr)
+@end smallexample
+
+The sequence is much longer when @samp{addr} is a 64-bit symbol.
+@xref{MIPS Symbol Sizes,, Directives to override the size of symbols}.
+
+In order to cut down on this overhead, most embedded MIPS systems
+set aside a 64-kilobyte ``small data'' area and guarantee that all
+data of size @var{n} and smaller will be placed in that area.
+The limit @var{n} is passed to both the assembler and the linker
+using the command-line option @option{-G @var{n}}, @pxref{MIPS Options,,
+Assembler options}. Note that the same value of @var{n} must be used
+when linking and when assembling all input files to the link; any
+inconsistency could cause a relocation overflow error.
+
+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, while leaving @code{sym} otherwise undefined.
+
+When no @option{-G} option is given, the default limit is 8 bytes.
+The option @option{-G 0} prevents any data from being automatically
+classified as small.
+
+It is also possible to mark specific objects as small by putting them
+in the special sections @code{.sdata} and @code{.sbss}, which are
+``small'' counterparts of @code{.data} and @code{.bss} respectively.
+The toolchain will treat such data as small regardless of the
+@option{-G} setting.
+
+On startup, systems that support a small data area are expected to
+initialize register @code{$28}, also known as @code{$gp}, in such a
+way that small data can be accessed using a 16-bit offset from that
+register. For example, when @samp{addr} is small data,
+the @samp{dla $4,addr} instruction above is equivalent to:
+
+@smallexample
+daddiu $4,$28,%gp_rel(addr)
+@end smallexample
+
+Small data is not supported for SVR4-style PIC.
@node MIPS ISA
@section Directives to override the ISA level
@cindex MIPS ISA override
@kindex @code{.set mips@var{n}}
@sc{gnu} @code{@value{AS}} supports an additional directive to change
-the @sc{mips} Instruction Set Architecture level on the fly: @code{.set
-mips@var{n}}. @var{n} should be a number from 0 to 4. A value from 1
-to 4 makes the assembler accept instructions for the corresponding
-@sc{isa} level, from that point on in the assembly. @code{.set
-mips@var{n}} affects not only which instructions are permitted, but also
-how certain macros are expanded. @code{.set mips0} restores the
-@sc{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 @sc{r4000} instructions while
-assembling in 32 bit mode. Use this directive with care!
-
-The directive @samp{.set mips16} puts the assembler into MIPS 16 mode,
+the MIPS Instruction Set Architecture level on the fly: @code{.set
+mips@var{n}}. @var{n} should be a number from 0 to 5, or 32, 32r2, 32r3,
+32r5, 32r6, 64, 64r2, 64r3, 64r5 or 64r6.
+The values other than 0 make the assembler accept instructions
+for the corresponding ISA level, from that point on in the
+assembly. @code{.set mips@var{n}} affects not only which instructions
+are permitted, but also how certain macros are expanded. @code{.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 MIPS III
+instructions while assembling in 32 bit mode. Use this directive with
+care!
+
+@cindex MIPS CPU override
+@kindex @code{.set arch=@var{cpu}}
+The @code{.set arch=@var{cpu}} directive provides even finer control.
+It changes the effective CPU target and allows the assembler to use
+instructions specific to a particular CPU. All CPUs supported by the
+@samp{-march} command line option are also selectable by this directive.
+The original value is restored by @code{.set arch=default}.
+
+The directive @code{.set mips16} puts the assembler into MIPS 16 mode,
in which it will assemble instructions for the MIPS 16 processor. Use
-@samp{.set nomips16} to return to normal 32 bit mode.
+@code{.set nomips16} to return to normal 32 bit mode.
+
+Traditional MIPS assemblers do not support this directive.
+
+The directive @code{.set micromips} puts the assembler into microMIPS mode,
+in which it will assemble instructions for the microMIPS processor. Use
+@code{.set nomicromips} to return to normal 32 bit mode.
+
+Traditional MIPS assemblers do not support this directive.
+
+@node MIPS assembly options
+@section Directives to control code generation
+
+@cindex MIPS directives to override command line options
+@kindex @code{.module}
+The @code{.module} directive allows command line options to be set directly
+from assembly. The format of the directive matches the @code{.set}
+directive but only those options which are relevant to a whole module are
+supported. The effect of a @code{.module} directive is the same as the
+corresponding command line option. Where @code{.set} directives support
+returning to a default then the @code{.module} directives do not as they
+define the defaults.
+
+These module-level directives must appear first in assembly.
-Traditional @sc{mips} assemblers do not support this directive.
+Traditional MIPS assemblers do not support this directive.
+
+@cindex MIPS 32-bit microMIPS instruction generation override
+@kindex @code{.set insn32}
+@kindex @code{.set noinsn32}
+The directive @code{.set insn32} makes the assembler only use 32-bit
+instruction encodings when generating code for the microMIPS processor.
+This directive inhibits the use of any 16-bit instructions from that
+point on in the assembly. The @code{.set noinsn32} directive allows
+16-bit instructions to be accepted.
+
+Traditional MIPS assemblers do not support this directive.
@node MIPS autoextend
@section Directives for extending MIPS 16 bit instructions
@kindex @code{.set autoextend}
@kindex @code{.set noautoextend}
By default, MIPS 16 instructions are automatically extended to 32 bits
-when necessary. The directive @samp{.set noautoextend} will turn this
-off. When @samp{.set noautoextend} is in effect, any 32 bit instruction
-must be explicitly extended with the @samp{.e} modifier (e.g.,
-@samp{li.e $4,1000}). The directive @samp{.set autoextend} may be used
+when necessary. The directive @code{.set noautoextend} will turn this
+off. When @code{.set noautoextend} is in effect, any 32 bit instruction
+must be explicitly extended with the @code{.e} modifier (e.g.,
+@code{li.e $4,1000}). The directive @code{.set autoextend} may be used
to once again automatically extend instructions when necessary.
This directive is only meaningful when in MIPS 16 mode. Traditional
-@sc{mips} assemblers do not support this directive.
+MIPS assemblers do not support this directive.
@node MIPS insn
@section Directive to mark data as an instruction
@kindex @code{.insn}
The @code{.insn} directive tells @code{@value{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,
-@code{@value{AS}} automatically adds 1 to the value, so that jumping to
-the loaded address will do the right thing.
+data is actually instructions. This makes a difference in MIPS 16 and
+microMIPS modes: when loading the address of a label which precedes
+instructions, @code{@value{AS}} automatically adds 1 to the value, so
+that jumping to the loaded address will do the right thing.
+
+@kindex @code{.global}
+The @code{.global} and @code{.globl} directives supported by
+@code{@value{AS}} will by default mark the symbol as pointing to a
+region of data not code. This means that, for example, any
+instructions following such a symbol will not be disassembled by
+@code{objdump} as it will regard them as data. To change this
+behaviour an optional section name can be placed after the symbol name
+in the @code{.global} directive. If this section exists and is known
+to be a code section, then the symbol will be marked as poiting at
+code not data. Ie the syntax for the directive is:
+
+ @code{.global @var{symbol}[ @var{section}][, @var{symbol}[ @var{section}]] ...},
+
+Here is a short example:
+
+@example
+ .global foo .text, bar, baz .data
+foo:
+ nop
+bar:
+ .word 0x0
+baz:
+ .word 0x1
+
+@end example
+
+@node MIPS FP ABIs
+@section Directives to control the FP ABI
+@menu
+* MIPS FP ABI History:: History of FP ABIs
+* MIPS FP ABI Variants:: Supported FP ABIs
+* MIPS FP ABI Selection:: Automatic selection of FP ABI
+* MIPS FP ABI Compatibility:: Linking different FP ABI variants
+@end menu
+
+@node MIPS FP ABI History
+@subsection History of FP ABIs
+@cindex @code{.gnu_attribute 4, @var{n}} directive, MIPS
+@cindex @code{.gnu_attribute Tag_GNU_MIPS_ABI_FP, @var{n}} directive, MIPS
+The MIPS ABIs support a variety of different floating-point extensions
+where calling-convention and register sizes vary for floating-point data.
+The extensions exist to support a wide variety of optional architecture
+features. The resulting ABI variants are generally incompatible with each
+other and must be tracked carefully.
+
+Traditionally the use of an explicit @code{.gnu_attribute 4, @var{n}}
+directive is used to indicate which ABI is in use by a specific module.
+It was then left to the user to ensure that command line options and the
+selected ABI were compatible with some potential for inconsistencies.
+
+@node MIPS FP ABI Variants
+@subsection Supported FP ABIs
+The supported floating-point ABI variants are:
+
+@table @code
+@item 0 - No floating-point
+This variant is used to indicate that floating-point is not used within
+the module at all and therefore has no impact on the ABI. This is the
+default.
+
+@item 1 - Double-precision
+This variant indicates that double-precision support is used. For 64-bit
+ABIs this means that 64-bit wide floating-point registers are required.
+For 32-bit ABIs this means that 32-bit wide floating-point registers are
+required and double-precision operations use pairs of registers.
+
+@item 2 - Single-precision
+This variant indicates that single-precision support is used. Double
+precision operations will be supported via soft-float routines.
+
+@item 3 - Soft-float
+This variant indicates that although floating-point support is used all
+operations are emulated in software. This means the ABI is modified to
+pass all floating-point data in general-purpose registers.
+
+@item 4 - Deprecated
+This variant existed as an initial attempt at supporting 64-bit wide
+floating-point registers for O32 ABI on a MIPS32r2 cpu. This has been
+superceded by @value{5}, @value{6} and @value{7}.
+
+@item 5 - Double-precision 32-bit CPU, 32-bit or 64-bit FPU
+This variant is used by 32-bit ABIs to indicate that the floating-point
+code in the module has been designed to operate correctly with either
+32-bit wide or 64-bit wide floating-point registers. Double-precision
+support is used. Only O32 currently supports this variant and requires
+a minimum architecture of MIPS II.
+
+@item 6 - Double-precision 32-bit FPU, 64-bit FPU
+This variant is used by 32-bit ABIs to indicate that the floating-point
+code in the module requires 64-bit wide floating-point registers.
+Double-precision support is used. Only O32 currently supports this
+variant and requires a minimum architecture of MIPS32r2.
+
+@item 7 - Double-precision compat 32-bit FPU, 64-bit FPU
+This variant is used by 32-bit ABIs to indicate that the floating-point
+code in the module requires 64-bit wide floating-point registers.
+Double-precision support is used. This differs from the previous ABI
+as it restricts use of odd-numbered single-precision registers. Only
+O32 currently supports this variant and requires a minimum architecture
+of MIPS32r2.
+@end table
+
+@node MIPS FP ABI Selection
+@subsection Automatic selection of FP ABI
+@cindex @code{.module fp=@var{nn}} directive, MIPS
+In order to simplify and add safety to the process of selecting the
+correct floating-point ABI, the assembler will automatically infer the
+correct @code{.gnu_attribute 4, @var{n}} directive based on command line
+options and @code{.module} overrides. Where an explicit
+@code{.gnu_attribute 4, @var{n}} directive has been seen then a warning
+will be raised if it does not match an inferred setting.
+
+The floating-point ABI is inferred as follows. If @samp{-msoft-float}
+has been used the module will be marked as soft-float. If
+@samp{-msingle-float} has been used then the module will be marked as
+single-precision. The remaining ABIs are then selected based
+on the FP register width. Double-precision is selected if the width
+of GP and FP registers match and the special double-precision variants
+for 32-bit ABIs are then selected depending on @samp{-mfpxx},
+@samp{-mfp64} and @samp{-mno-odd-spreg}.
-@node MIPS option stack
+@node MIPS FP ABI Compatibility
+@subsection Linking different FP ABI variants
+Modules using the default FP ABI (no floating-point) can be linked with
+any other (singular) FP ABI variant.
+
+Special compatibility support exists for O32 with the four
+double-precision FP ABI variants. The @samp{-mfpxx} FP ABI is specifically
+designed to be compatible with the standard double-precision ABI and the
+@samp{-mfp64} FP ABIs. This makes it desirable for O32 modules to be
+built as @samp{-mfpxx} to ensure the maximum compatibility with other
+modules produced for more specific needs. The only FP ABIs which cannot
+be linked together are the standard double-precision ABI and the full
+@samp{-mfp64} ABI with @samp{-modd-spreg}.
+
+@node MIPS NaN Encodings
+@section Directives to record which NaN encoding is being used
+
+@cindex MIPS IEEE 754 NaN data encoding selection
+@cindex @code{.nan} directive, MIPS
+The IEEE 754 floating-point standard defines two types of not-a-number
+(NaN) data: ``signalling'' NaNs and ``quiet'' NaNs. The original version
+of the standard did not specify how these two types should be
+distinguished. Most implementations followed the i387 model, in which
+the first bit of the significand is set for quiet NaNs and clear for
+signalling NaNs. However, the original MIPS implementation assigned the
+opposite meaning to the bit, so that it was set for signalling NaNs and
+clear for quiet NaNs.
+
+The 2008 revision of the standard formally suggested the i387 choice
+and as from Sep 2012 the current release of the MIPS architecture
+therefore optionally supports that form. Code that uses one NaN encoding
+would usually be incompatible with code that uses the other NaN encoding,
+so MIPS ELF objects have a flag (@code{EF_MIPS_NAN2008}) to record which
+encoding is being used.
+
+Assembly files can use the @code{.nan} directive to select between the
+two encodings. @samp{.nan 2008} says that the assembly file uses the
+IEEE 754-2008 encoding while @samp{.nan legacy} says that the file uses
+the original MIPS encoding. If several @code{.nan} directives are given,
+the final setting is the one that is used.
+
+The command-line options @option{-mnan=legacy} and @option{-mnan=2008}
+can be used instead of @samp{.nan legacy} and @samp{.nan 2008}
+respectively. However, any @code{.nan} directive overrides the
+command-line setting.
+
+@samp{.nan legacy} is the default if no @code{.nan} directive or
+@option{-mnan} option is given.
+
+Note that @sc{gnu} @code{@value{AS}} does not produce NaNs itself and
+therefore these directives do not affect code generation. They simply
+control the setting of the @code{EF_MIPS_NAN2008} flag.
+
+Traditional MIPS assemblers do not support these directives.
+
+@node MIPS Option Stack
@section Directives to save and restore options
@cindex MIPS option stack
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 @sc{mips} assemblers do not support these directives.
+Traditional MIPS assemblers do not support these directives.
+
+@node MIPS ASE Instruction Generation Overrides
+@section Directives to control generation of MIPS ASE instructions
+
+@cindex MIPS MIPS-3D instruction generation override
+@kindex @code{.set mips3d}
+@kindex @code{.set nomips3d}
+The directive @code{.set mips3d} makes the assembler accept instructions
+from the MIPS-3D Application Specific Extension from that point on
+in the assembly. The @code{.set nomips3d} directive prevents MIPS-3D
+instructions from being accepted.
+
+@cindex SmartMIPS instruction generation override
+@kindex @code{.set smartmips}
+@kindex @code{.set nosmartmips}
+The directive @code{.set smartmips} makes the assembler accept
+instructions from the SmartMIPS Application Specific Extension to the
+MIPS32 ISA from that point on in the assembly. The
+@code{.set nosmartmips} directive prevents SmartMIPS instructions from
+being accepted.
+
+@cindex MIPS MDMX instruction generation override
+@kindex @code{.set mdmx}
+@kindex @code{.set nomdmx}
+The directive @code{.set mdmx} makes the assembler accept instructions
+from the MDMX Application Specific Extension from that point on
+in the assembly. The @code{.set nomdmx} directive prevents MDMX
+instructions from being accepted.
+
+@cindex MIPS DSP Release 1 instruction generation override
+@kindex @code{.set dsp}
+@kindex @code{.set nodsp}
+The directive @code{.set dsp} makes the assembler accept instructions
+from the DSP Release 1 Application Specific Extension from that point
+on in the assembly. The @code{.set nodsp} directive prevents DSP
+Release 1 instructions from being accepted.
+
+@cindex MIPS DSP Release 2 instruction generation override
+@kindex @code{.set dspr2}
+@kindex @code{.set nodspr2}
+The directive @code{.set dspr2} makes the assembler accept instructions
+from the DSP Release 2 Application Specific Extension from that point
+on in the assembly. This dirctive implies @code{.set dsp}. The
+@code{.set nodspr2} directive prevents DSP Release 2 instructions from
+being accepted.
+
+@cindex MIPS MT instruction generation override
+@kindex @code{.set mt}
+@kindex @code{.set nomt}
+The directive @code{.set mt} makes the assembler accept instructions
+from the MT Application Specific Extension from that point on
+in the assembly. The @code{.set nomt} directive prevents MT
+instructions from being accepted.
+
+@cindex MIPS MCU instruction generation override
+@kindex @code{.set mcu}
+@kindex @code{.set nomcu}
+The directive @code{.set mcu} makes the assembler accept instructions
+from the MCU Application Specific Extension from that point on
+in the assembly. The @code{.set nomcu} directive prevents MCU
+instructions from being accepted.
+
+@cindex MIPS SIMD Architecture instruction generation override
+@kindex @code{.set msa}
+@kindex @code{.set nomsa}
+The directive @code{.set msa} makes the assembler accept instructions
+from the MIPS SIMD Architecture Extension from that point on
+in the assembly. The @code{.set nomsa} directive prevents MSA
+instructions from being accepted.
+
+@cindex Virtualization instruction generation override
+@kindex @code{.set virt}
+@kindex @code{.set novirt}
+The directive @code{.set virt} makes the assembler accept instructions
+from the Virtualization Application Specific Extension from that point
+on in the assembly. The @code{.set novirt} directive prevents Virtualization
+instructions from being accepted.
+
+@cindex MIPS eXtended Physical Address (XPA) instruction generation override
+@kindex @code{.set xpa}
+@kindex @code{.set noxpa}
+The directive @code{.set xpa} makes the assembler accept instructions
+from the XPA Extension from that point on in the assembly. The
+@code{.set noxpa} directive prevents XPA instructions from being accepted.
+
+Traditional MIPS assemblers do not support these directives.
+
+@node MIPS Floating-Point
+@section Directives to override floating-point options
+
+@cindex Disable floating-point instructions
+@kindex @code{.set softfloat}
+@kindex @code{.set hardfloat}
+The directives @code{.set softfloat} and @code{.set hardfloat} provide
+finer control of disabling and enabling float-point instructions.
+These directives always override the default (that hard-float
+instructions are accepted) or the command-line options
+(@samp{-msoft-float} and @samp{-mhard-float}).
+
+@cindex Disable single-precision floating-point operations
+@kindex @code{.set singlefloat}
+@kindex @code{.set doublefloat}
+The directives @code{.set singlefloat} and @code{.set doublefloat}
+provide finer control of disabling and enabling double-precision
+float-point operations. These directives always override the default
+(that double-precision operations are accepted) or the command-line
+options (@samp{-msingle-float} and @samp{-mdouble-float}).
+
+Traditional MIPS assemblers do not support these directives.
+
+@node MIPS Syntax
+@section Syntactical considerations for the MIPS assembler
+@menu
+* MIPS-Chars:: Special Characters
+@end menu
+
+@node MIPS-Chars
+@subsection Special Characters
+
+@cindex line comment character, MIPS
+@cindex MIPS line comment character
+The presence of a @samp{#} on a line indicates the start of a comment
+that extends to the end of the current line.
+
+If a @samp{#} appears as the first character of a line, the whole line
+is treated as a comment, but in this case the line can also be a
+logical line number directive (@pxref{Comments}) or a
+preprocessor control command (@pxref{Preprocessing}).
+
+@cindex line separator, MIPS
+@cindex statement separator, MIPS
+@cindex MIPS line separator
+The @samp{;} character can be used to separate statements on the same
+line.
projects / deliverable / binutils-gdb.git / blobdiff