-@c Copyright (C) 1991-2014 Free Software Foundation, Inc.
+@c Copyright (C) 1991-2018 Free Software Foundation, Inc.
@c This is part of the GAS manual.
@c For copying conditions, see the file as.texinfo.
@ifset GENERIC
* 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 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
@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 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{-mips64}, @samp{-mips64r2}, @samp{-mips64r3}, and
-@samp{-mips64r5} correspond to generic MIPS V, MIPS32, MIPS32 Release 2,
-MIPS32 Release 3, MIPS32 Release 5, MIPS64, and MIPS64 Release 2,
-MIPS64 Release 3, and MIPS64 Release 5 ISA processors, respectively. You
-can also switch instruction sets during the assembly; see @ref{MIPS ISA,
-Directives to override the ISA level}.
+@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
@itemx -mfp32
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
-@code{.set mips16} at the start of the assembly file. @samp{-no-mips16}
+@code{.module mips16} at the start of the assembly file. @samp{-no-mips16}
turns off this option.
+@item -mmips16e2
+@itemx -mno-mips16e2
+Enable the use of MIPS16e2 instructions in MIPS16 mode. This is equivalent
+to putting @code{.module mips16e2} at the start of the assembly file.
+@samp{-mno-mips16e2} 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.
+@code{.module micromips} at the start of the assembly file.
+@samp{-mno-micromips} turns off this option. This is equivalent to putting
+@code{.module 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.
+@code{.module smartmips} at the start of the assembly file.
@samp{-mno-smartmips} turns off this option.
@item -mips3d
@item -mdspr2
@itemx -mno-dspr2
Generate code for the DSP Release 2 Application Specific Extension.
-This option implies -mdsp.
+This option implies @samp{-mdsp}.
This tells the assembler to accept DSP Release 2 instructions.
@samp{-mno-dspr2} turns off this option.
+@item -mdspr3
+@itemx -mno-dspr3
+Generate code for the DSP Release 3 Application Specific Extension.
+This option implies @samp{-mdsp} and @samp{-mdspr2}.
+This tells the assembler to accept DSP Release 3 instructions.
+@samp{-mno-dspr3} turns off this option.
+
@item -mmt
@itemx -mno-mt
Generate code for the MT Application Specific Extension.
This tells the assembler to accept Virtualization instructions.
@samp{-mno-virt} turns off this option.
+@item -mcrc
+@itemx -mno-crc
+Generate code for the cyclic redundancy check (CRC) Application Specific
+Extension. This tells the assembler to accept CRC instructions.
+@samp{-mno-crc} turns off this option.
+
+@item -mginv
+@itemx -mno-ginv
+Generate code for the Global INValidate (GINV) Application Specific
+Extension. This tells the assembler to accept GINV instructions.
+@samp{-mno-ginv} turns off this option.
+
+@item -mloongson-mmi
+@itemx -mno-loongson-mmi
+Generate code for the Loongson MultiMedia extensions Instructions (MMI)
+Application Specific Extension. This tells the assembler to accept MMI
+instructions.
+@samp{-mno-loongson-mmi} turns off this option.
+
+@item -mloongson-cam
+@itemx -mno-loongson-cam
+Generate code for the Loongson Content Address Memory (CAM)
+Application Specific Extension. This tells the assembler to accept CAM
+instructions.
+@samp{-mno-loongson-cam} turns off this option.
+
+@item -mloongson-ext
+@itemx -mno-loongson-ext
+Generate code for the Loongson EXTensions (EXT) instructions
+Application Specific Extension. This tells the assembler to accept EXT
+instructions.
+@samp{-mno-loongson-ext} turns off this option.
+
+@item -mloongson-ext2
+@itemx -mno-loongson-ext2
+Generate code for the Loongson EXTensions R2 (EXT2) instructions
+Application Specific Extension. This tells the assembler to accept EXT2
+instructions.
+@samp{-mno-loongson-ext2} turns off this option.
+
@item -minsn32
@itemx -mno-insn32
Only use 32-bit instruction encodings when generating code for the
1004kf2_1,
1004kf,
1004kf1_1,
+interaptiv,
+interaptiv-mr2,
+m5100,
+m5101,
p5600,
5kc,
5kf,
25kf,
sb1,
sb1a,
+i6400,
+p6600,
loongson2e,
loongson2f,
-loongson3a,
+gs464,
+gs464e,
+gs264e,
octeon,
octeon+,
octeon2,
+octeon3,
xlr,
xlp
@end quotation
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 -mignore-branch-isa
+@itemx -mno-ignore-branch-isa
+Ignore branch checks for invalid transitions between ISA modes.
+
+The semantics of branches does not provide for an ISA mode switch, so in
+most cases the ISA mode a branch has been encoded for has to be the same
+as the ISA mode of the branch's target label. If the ISA modes do not
+match, then such a branch, if taken, will cause the ISA mode to remain
+unchanged and instructions that follow will be executed in the wrong ISA
+mode causing the program to misbehave or crash.
+
+In the case of the @code{BAL} instruction it may be possible to relax
+it to an equivalent @code{JALX} instruction so that the ISA mode is
+switched at the run time as required. For other branches no relaxation
+is possible and therefore GAS has checks implemented that verify in
+branch assembly that the two ISA modes match, and report an error
+otherwise so that the problem with code can be diagnosed at the assembly
+time rather than at the run time.
+
+However some assembly code, including generated code produced by some
+versions of GCC, may incorrectly include branches to data labels, which
+appear to require a mode switch but are either dead or immediately
+followed by valid instructions encoded for the same ISA the branch has
+been encoded for. While not strictly correct at the source level such
+code will execute as intended, so to help with these cases
+@samp{-mignore-branch-isa} is supported which disables ISA mode checks
+for branches.
+
+By default @samp{-mno-ignore-branch-isa} is selected, causing any invalid
+branch requiring a transition between ISA modes 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
@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, 32r3,
-32r5, 64, 64r2, 64r3 or 64r5.
+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
+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!
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.
+@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,
@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 MIPS assemblers do not support this directive.
+
@cindex MIPS 32-bit microMIPS instruction generation override
@kindex @code{.set insn32}
@kindex @code{.set noinsn32}
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
+behavior 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
+to be a code section, then the symbol will be marked as pointing at
code not data. Ie the syntax for the directive is:
@code{.global @var{symbol}[ @var{section}][, @var{symbol}[ @var{section}]] ...},
@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
+superseded by 5, 6 and 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 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
@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
+on in the assembly. This directive implies @code{.set dsp}. The
@code{.set nodspr2} directive prevents DSP Release 2 instructions from
being accepted.
+@cindex MIPS DSP Release 3 instruction generation override
+@kindex @code{.set dspr3}
+@kindex @code{.set nodspr3}
+The directive @code{.set dspr3} makes the assembler accept instructions
+from the DSP Release 3 Application Specific Extension from that point
+on in the assembly. This directive implies @code{.set dsp} and
+@code{.set dspr2}. The @code{.set nodspr3} directive prevents DSP
+Release 3 instructions from being accepted.
+
@cindex MIPS MT instruction generation override
@kindex @code{.set mt}
@kindex @code{.set nomt}
from the XPA Extension from that point on in the assembly. The
@code{.set noxpa} directive prevents XPA instructions from being accepted.
+@cindex MIPS16e2 instruction generation override
+@kindex @code{.set mips16e2}
+@kindex @code{.set nomips16e2}
+The directive @code{.set mips16e2} makes the assembler accept instructions
+from the MIPS16e2 Application Specific Extension from that point on in the
+assembly, whenever in MIPS16 mode. The @code{.set nomips16e2} directive
+prevents MIPS16e2 instructions from being accepted, in MIPS16 mode. Neither
+directive affects the state of MIPS16 mode being active itself which has
+separate controls.
+
+@cindex MIPS cyclic redundancy check (CRC) instruction generation override
+@kindex @code{.set crc}
+@kindex @code{.set nocrc}
+The directive @code{.set crc} makes the assembler accept instructions
+from the CRC Extension from that point on in the assembly. The
+@code{.set nocrc} directive prevents CRC instructions from being accepted.
+
+@cindex MIPS Global INValidate (GINV) instruction generation override
+@kindex @code{.set ginv}
+@kindex @code{.set noginv}
+The directive @code{.set ginv} makes the assembler accept instructions
+from the GINV Extension from that point on in the assembly. The
+@code{.set noginv} directive prevents GINV instructions from being accepted.
+
+@cindex Loongson MultiMedia extensions Instructions (MMI) generation override
+@kindex @code{.set loongson-mmi}
+@kindex @code{.set noloongson-mmi}
+The directive @code{.set loongson-mmi} makes the assembler accept
+instructions from the MMI Extension from that point on in the assembly.
+The @code{.set noloongson-mmi} directive prevents MMI instructions from
+being accepted.
+
+@cindex Loongson Content Address Memory (CAM) generation override
+@kindex @code{.set loongson-cam}
+@kindex @code{.set noloongson-cam}
+The directive @code{.set loongson-cam} makes the assembler accept
+instructions from the Loongson CAM from that point on in the assembly.
+The @code{.set noloongson-cam} directive prevents Loongson CAM instructions
+from being accepted.
+
+@cindex Loongson EXTensions (EXT) instructions generation override
+@kindex @code{.set loongson-ext}
+@kindex @code{.set noloongson-ext}
+The directive @code{.set loongson-ext} makes the assembler accept
+instructions from the Loongson EXT from that point on in the assembly.
+The @code{.set noloongson-ext} directive prevents Loongson EXT instructions
+from being accepted.
+
+@cindex Loongson EXTensions R2 (EXT2) instructions generation override
+@kindex @code{.set loongson-ext2}
+@kindex @code{.set noloongson-ext2}
+The directive @code{.set loongson-ext2} makes the assembler accept
+instructions from the Loongson EXT2 from that point on in the assembly.
+This directive implies @code{.set loognson-ext}.
+The @code{.set noloongson-ext2} directive prevents Loongson EXT2 instructions
+from being accepted.
+
Traditional MIPS assemblers do not support these directives.
@node MIPS Floating-Point