diff options
Diffstat (limited to 'binutils-2.25/gas/doc/c-mips.texi')
| -rw-r--r-- | binutils-2.25/gas/doc/c-mips.texi | 926 |
1 files changed, 926 insertions, 0 deletions
diff --git a/binutils-2.25/gas/doc/c-mips.texi b/binutils-2.25/gas/doc/c-mips.texi new file mode 100644 index 00000000..7927893c --- /dev/null +++ b/binutils-2.25/gas/doc/c-mips.texi @@ -0,0 +1,926 @@ +@c Copyright 1991, 1992, 1993, 1994, 1995, 1997, 1999, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2013 +@c Free Software Foundation, Inc. +@c This is part of the GAS manual. +@c For copying conditions, see the file as.texinfo. +@ifset GENERIC +@page +@node MIPS-Dependent +@chapter MIPS Dependent Features +@end ifset +@ifclear GENERIC +@node Machine Dependencies +@chapter MIPS Dependent Features +@end ifclear + +@cindex MIPS processor +@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 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 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 Options +@section Assembler options + +The MIPS configurations of @sc{gnu} @code{@value{AS}} support these +special options: + +@table @code +@cindex @code{-G} option (MIPS) +@item -G @var{num} +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 MIPS big-endian output +@cindex MIPS little-endian output +@cindex big-endian output, MIPS +@cindex little-endian output, MIPS +@item -EB +@itemx -EL +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 -mips64 +@itemx -mips64r2 +Generate code for a particular MIPS Instruction Set Architecture 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{-mips64}, and +@samp{-mips64r2} correspond to generic MIPS V, MIPS32, MIPS32 Release 2, +MIPS64, and MIPS64 Release 2 ISA processors, respectively. You can also +switch instruction sets during the assembly; see @ref{MIPS ISA, +Directives to override the ISA level}. + +@item -mgp32 +@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 +@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 -mips16 +@itemx -no-mips16 +Generate code for the MIPS 16 processor. This is equivalent to putting +@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 -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 -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-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 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 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. + +@item -m3900 +@itemx -no-m3900 +@itemx -m4100 +@itemx -no-m4100 +For each option @samp{-m@var{nnnn}}, generate code for the MIPS +R@var{nnnn} chip. This tells the assembler to accept instructions +specific to that chip, and to schedule for that chip's hazards. + +@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: + +@quotation +2000, +3000, +3900, +4000, +4010, +4100, +4111, +vr4120, +vr4130, +vr4181, +4300, +4400, +4600, +4650, +5000, +rm5200, +rm5230, +rm5231, +rm5261, +rm5721, +vr5400, +vr5500, +6000, +rm7000, +8000, +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, +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 +This option is ignored. It is accepted for command-line compatibility with +other assemblers, which use it to turn off C style preprocessing. With +@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; +@c (2) stop teasing, say _which_ instructions expanded _how_. +@code{@value{AS}} automatically macro expands certain division and +multiplication instructions to check for overflow and division by zero. This +option causes @code{@value{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. + +@item --break +@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 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: + +@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 + +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 +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 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, 64 +or 64r2. +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 +@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 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 @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 +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 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 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 +@kindex @code{.set push} +@kindex @code{.set pop} +The directives @code{.set push} and @code{.set pop} may be used to save +and restore the current settings for all the options which are +controlled by @code{.set}. The @code{.set push} directive saves the +current settings on a stack. The @code{.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. + +@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. + +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. |