1@c Copyright (C) 1991-2016 Free Software Foundation, Inc. 2@c This is part of the GAS manual. 3@c For copying conditions, see the file as.texinfo. 4@ifset GENERIC 5@page 6@node MIPS-Dependent 7@chapter MIPS Dependent Features 8@end ifset 9@ifclear GENERIC 10@node Machine Dependencies 11@chapter MIPS Dependent Features 12@end ifclear 13 14@cindex MIPS processor 15@sc{gnu} @code{@value{AS}} for MIPS architectures supports several 16different MIPS processors, and MIPS ISA levels I through V, MIPS32, 17and MIPS64. For information about the MIPS instruction set, see 18@cite{MIPS RISC Architecture}, by Kane and Heindrich (Prentice-Hall). 19For an overview of MIPS assembly conventions, see ``Appendix D: 20Assembly Language Programming'' in the same work. 21 22@menu 23* MIPS Options:: Assembler options 24* MIPS Macros:: High-level assembly macros 25* MIPS Symbol Sizes:: Directives to override the size of symbols 26* MIPS Small Data:: Controlling the use of small data accesses 27* MIPS ISA:: Directives to override the ISA level 28* MIPS assembly options:: Directives to control code generation 29* MIPS autoextend:: Directives for extending MIPS 16 bit instructions 30* MIPS insn:: Directive to mark data as an instruction 31* MIPS FP ABIs:: Marking which FP ABI is in use 32* MIPS NaN Encodings:: Directives to record which NaN encoding is being used 33* MIPS Option Stack:: Directives to save and restore options 34* MIPS ASE Instruction Generation Overrides:: Directives to control 35 generation of MIPS ASE instructions 36* MIPS Floating-Point:: Directives to override floating-point options 37* MIPS Syntax:: MIPS specific syntactical considerations 38@end menu 39 40@node MIPS Options 41@section Assembler options 42 43The MIPS configurations of @sc{gnu} @code{@value{AS}} support these 44special options: 45 46@table @code 47@cindex @code{-G} option (MIPS) 48@item -G @var{num} 49Set the ``small data'' limit to @var{n} bytes. The default limit is 8 bytes. 50@xref{MIPS Small Data,, Controlling the use of small data accesses}. 51 52@cindex @code{-EB} option (MIPS) 53@cindex @code{-EL} option (MIPS) 54@cindex MIPS big-endian output 55@cindex MIPS little-endian output 56@cindex big-endian output, MIPS 57@cindex little-endian output, MIPS 58@item -EB 59@itemx -EL 60Any MIPS configuration of @code{@value{AS}} can select big-endian or 61little-endian output at run time (unlike the other @sc{gnu} development 62tools, which must be configured for one or the other). Use @samp{-EB} 63to select big-endian output, and @samp{-EL} for little-endian. 64 65@item -KPIC 66@cindex PIC selection, MIPS 67@cindex @option{-KPIC} option, MIPS 68Generate SVR4-style PIC. This option tells the assembler to generate 69SVR4-style position-independent macro expansions. It also tells the 70assembler to mark the output file as PIC. 71 72@item -mvxworks-pic 73@cindex @option{-mvxworks-pic} option, MIPS 74Generate VxWorks PIC. This option tells the assembler to generate 75VxWorks-style position-independent macro expansions. 76 77@cindex MIPS architecture options 78@item -mips1 79@itemx -mips2 80@itemx -mips3 81@itemx -mips4 82@itemx -mips5 83@itemx -mips32 84@itemx -mips32r2 85@itemx -mips32r3 86@itemx -mips32r5 87@itemx -mips32r6 88@itemx -mips64 89@itemx -mips64r2 90@itemx -mips64r3 91@itemx -mips64r5 92@itemx -mips64r6 93Generate code for a particular MIPS Instruction Set Architecture level. 94@samp{-mips1} corresponds to the R2000 and R3000 processors, 95@samp{-mips2} to the R6000 processor, @samp{-mips3} to the 96R4000 processor, and @samp{-mips4} to the R8000 and R10000 processors. 97@samp{-mips5}, @samp{-mips32}, @samp{-mips32r2}, @samp{-mips32r3}, 98@samp{-mips32r5}, @samp{-mips32r6}, @samp{-mips64}, @samp{-mips64r2}, 99@samp{-mips64r3}, @samp{-mips64r5}, and @samp{-mips64r6} correspond to 100generic MIPS V, MIPS32, MIPS32 Release 2, MIPS32 Release 3, MIPS32 101Release 5, MIPS32 Release 6, MIPS64, and MIPS64 Release 2, MIPS64 102Release 3, MIPS64 Release 5, and MIPS64 Release 6 ISA processors, 103respectively. You can also switch instruction sets during the assembly; 104see @ref{MIPS ISA, Directives to override the ISA level}. 105 106@item -mgp32 107@itemx -mfp32 108Some macros have different expansions for 32-bit and 64-bit registers. 109The register sizes are normally inferred from the ISA and ABI, but these 110flags force a certain group of registers to be treated as 32 bits wide at 111all times. @samp{-mgp32} controls the size of general-purpose registers 112and @samp{-mfp32} controls the size of floating-point registers. 113 114The @code{.set gp=32} and @code{.set fp=32} directives allow the size 115of registers to be changed for parts of an object. The default value is 116restored by @code{.set gp=default} and @code{.set fp=default}. 117 118On some MIPS variants there is a 32-bit mode flag; when this flag is 119set, 64-bit instructions generate a trap. Also, some 32-bit OSes only 120save the 32-bit registers on a context switch, so it is essential never 121to use the 64-bit registers. 122 123@item -mgp64 124@itemx -mfp64 125Assume that 64-bit registers are available. This is provided in the 126interests of symmetry with @samp{-mgp32} and @samp{-mfp32}. 127 128The @code{.set gp=64} and @code{.set fp=64} directives allow the size 129of registers to be changed for parts of an object. The default value is 130restored by @code{.set gp=default} and @code{.set fp=default}. 131 132@item -mfpxx 133Make no assumptions about whether 32-bit or 64-bit floating-point 134registers are available. This is provided to support having modules 135compatible with either @samp{-mfp32} or @samp{-mfp64}. This option can 136only be used with MIPS II and above. 137 138The @code{.set fp=xx} directive allows a part of an object to be marked 139as not making assumptions about 32-bit or 64-bit FP registers. The 140default value is restored by @code{.set fp=default}. 141 142@item -modd-spreg 143@itemx -mno-odd-spreg 144Enable use of floating-point operations on odd-numbered single-precision 145registers when supported by the ISA. @samp{-mfpxx} implies 146@samp{-mno-odd-spreg}, otherwise the default is @samp{-modd-spreg} 147 148@item -mips16 149@itemx -no-mips16 150Generate code for the MIPS 16 processor. This is equivalent to putting 151@code{.set mips16} at the start of the assembly file. @samp{-no-mips16} 152turns off this option. 153 154@item -mmicromips 155@itemx -mno-micromips 156Generate code for the microMIPS processor. This is equivalent to putting 157@code{.set micromips} at the start of the assembly file. @samp{-mno-micromips} 158turns off this option. This is equivalent to putting @code{.set nomicromips} 159at the start of the assembly file. 160 161@item -msmartmips 162@itemx -mno-smartmips 163Enables the SmartMIPS extensions to the MIPS32 instruction set, which 164provides a number of new instructions which target smartcard and 165cryptographic applications. This is equivalent to putting 166@code{.set smartmips} at the start of the assembly file. 167@samp{-mno-smartmips} turns off this option. 168 169@item -mips3d 170@itemx -no-mips3d 171Generate code for the MIPS-3D Application Specific Extension. 172This tells the assembler to accept MIPS-3D instructions. 173@samp{-no-mips3d} turns off this option. 174 175@item -mdmx 176@itemx -no-mdmx 177Generate code for the MDMX Application Specific Extension. 178This tells the assembler to accept MDMX instructions. 179@samp{-no-mdmx} turns off this option. 180 181@item -mdsp 182@itemx -mno-dsp 183Generate code for the DSP Release 1 Application Specific Extension. 184This tells the assembler to accept DSP Release 1 instructions. 185@samp{-mno-dsp} turns off this option. 186 187@item -mdspr2 188@itemx -mno-dspr2 189Generate code for the DSP Release 2 Application Specific Extension. 190This option implies @samp{-mdsp}. 191This tells the assembler to accept DSP Release 2 instructions. 192@samp{-mno-dspr2} turns off this option. 193 194@item -mdspr3 195@itemx -mno-dspr3 196Generate code for the DSP Release 3 Application Specific Extension. 197This option implies @samp{-mdsp} and @samp{-mdspr2}. 198This tells the assembler to accept DSP Release 3 instructions. 199@samp{-mno-dspr3} turns off this option. 200 201@item -mmt 202@itemx -mno-mt 203Generate code for the MT Application Specific Extension. 204This tells the assembler to accept MT instructions. 205@samp{-mno-mt} turns off this option. 206 207@item -mmcu 208@itemx -mno-mcu 209Generate code for the MCU Application Specific Extension. 210This tells the assembler to accept MCU instructions. 211@samp{-mno-mcu} turns off this option. 212 213@item -mmsa 214@itemx -mno-msa 215Generate code for the MIPS SIMD Architecture Extension. 216This tells the assembler to accept MSA instructions. 217@samp{-mno-msa} turns off this option. 218 219@item -mxpa 220@itemx -mno-xpa 221Generate code for the MIPS eXtended Physical Address (XPA) Extension. 222This tells the assembler to accept XPA instructions. 223@samp{-mno-xpa} turns off this option. 224 225@item -mvirt 226@itemx -mno-virt 227Generate code for the Virtualization Application Specific Extension. 228This tells the assembler to accept Virtualization instructions. 229@samp{-mno-virt} turns off this option. 230 231@item -minsn32 232@itemx -mno-insn32 233Only use 32-bit instruction encodings when generating code for the 234microMIPS processor. This option inhibits the use of any 16-bit 235instructions. This is equivalent to putting @code{.set insn32} at 236the start of the assembly file. @samp{-mno-insn32} turns off this 237option. This is equivalent to putting @code{.set noinsn32} at the 238start of the assembly file. By default @samp{-mno-insn32} is 239selected, allowing all instructions to be used. 240 241@item -mfix7000 242@itemx -mno-fix7000 243Cause nops to be inserted if the read of the destination register 244of an mfhi or mflo instruction occurs in the following two instructions. 245 246@item -mfix-rm7000 247@itemx -mno-fix-rm7000 248Cause nops to be inserted if a dmult or dmultu instruction is 249followed by a load instruction. 250 251@item -mfix-loongson2f-jump 252@itemx -mno-fix-loongson2f-jump 253Eliminate instruction fetch from outside 256M region to work around the 254Loongson2F @samp{jump} instructions. Without it, under extreme cases, 255the kernel may crash. The issue has been solved in latest processor 256batches, but this fix has no side effect to them. 257 258@item -mfix-loongson2f-nop 259@itemx -mno-fix-loongson2f-nop 260Replace nops by @code{or at,at,zero} to work around the Loongson2F 261@samp{nop} errata. Without it, under extreme cases, the CPU might 262deadlock. The issue has been solved in later Loongson2F batches, but 263this fix has no side effect to them. 264 265@item -mfix-vr4120 266@itemx -mno-fix-vr4120 267Insert nops to work around certain VR4120 errata. This option is 268intended to be used on GCC-generated code: it is not designed to catch 269all problems in hand-written assembler code. 270 271@item -mfix-vr4130 272@itemx -mno-fix-vr4130 273Insert nops to work around the VR4130 @samp{mflo}/@samp{mfhi} errata. 274 275@item -mfix-24k 276@itemx -mno-fix-24k 277Insert nops to work around the 24K @samp{eret}/@samp{deret} errata. 278 279@item -mfix-cn63xxp1 280@itemx -mno-fix-cn63xxp1 281Replace @code{pref} hints 0 - 4 and 6 - 24 with hint 28 to work around 282certain CN63XXP1 errata. 283 284@item -m4010 285@itemx -no-m4010 286Generate code for the LSI R4010 chip. This tells the assembler to 287accept the R4010-specific instructions (@samp{addciu}, @samp{ffc}, 288etc.), and to not schedule @samp{nop} instructions around accesses to 289the @samp{HI} and @samp{LO} registers. @samp{-no-m4010} turns off this 290option. 291 292@item -m4650 293@itemx -no-m4650 294Generate code for the MIPS R4650 chip. This tells the assembler to accept 295the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop} 296instructions around accesses to the @samp{HI} and @samp{LO} registers. 297@samp{-no-m4650} turns off this option. 298 299@item -m3900 300@itemx -no-m3900 301@itemx -m4100 302@itemx -no-m4100 303For each option @samp{-m@var{nnnn}}, generate code for the MIPS 304R@var{nnnn} chip. This tells the assembler to accept instructions 305specific to that chip, and to schedule for that chip's hazards. 306 307@item -march=@var{cpu} 308Generate code for a particular MIPS CPU. It is exactly equivalent to 309@samp{-m@var{cpu}}, except that there are more value of @var{cpu} 310understood. Valid @var{cpu} value are: 311 312@quotation 3132000, 3143000, 3153900, 3164000, 3174010, 3184100, 3194111, 320vr4120, 321vr4130, 322vr4181, 3234300, 3244400, 3254600, 3264650, 3275000, 328rm5200, 329rm5230, 330rm5231, 331rm5261, 332rm5721, 333vr5400, 334vr5500, 3356000, 336rm7000, 3378000, 338rm9000, 33910000, 34012000, 34114000, 34216000, 3434kc, 3444km, 3454kp, 3464ksc, 3474kec, 3484kem, 3494kep, 3504ksd, 351m4k, 352m4kp, 353m14k, 354m14kc, 355m14ke, 356m14kec, 35724kc, 35824kf2_1, 35924kf, 36024kf1_1, 36124kec, 36224kef2_1, 36324kef, 36424kef1_1, 36534kc, 36634kf2_1, 36734kf, 36834kf1_1, 36934kn, 37074kc, 37174kf2_1, 37274kf, 37374kf1_1, 37474kf3_2, 3751004kc, 3761004kf2_1, 3771004kf, 3781004kf1_1, 379interaptiv, 380m5100, 381m5101, 382p5600, 3835kc, 3845kf, 38520kc, 38625kf, 387sb1, 388sb1a, 389i6400, 390p6600, 391loongson2e, 392loongson2f, 393loongson3a, 394octeon, 395octeon+, 396octeon2, 397octeon3, 398xlr, 399xlp 400@end quotation 401 402For compatibility reasons, @samp{@var{n}x} and @samp{@var{b}fx} are 403accepted as synonyms for @samp{@var{n}f1_1}. These values are 404deprecated. 405 406@item -mtune=@var{cpu} 407Schedule and tune for a particular MIPS CPU. Valid @var{cpu} values are 408identical to @samp{-march=@var{cpu}}. 409 410@item -mabi=@var{abi} 411Record which ABI the source code uses. The recognized arguments 412are: @samp{32}, @samp{n32}, @samp{o64}, @samp{64} and @samp{eabi}. 413 414@item -msym32 415@itemx -mno-sym32 416@cindex -msym32 417@cindex -mno-sym32 418Equivalent to adding @code{.set sym32} or @code{.set nosym32} to 419the beginning of the assembler input. @xref{MIPS Symbol Sizes}. 420 421@cindex @code{-nocpp} ignored (MIPS) 422@item -nocpp 423This option is ignored. It is accepted for command-line compatibility with 424other assemblers, which use it to turn off C style preprocessing. With 425@sc{gnu} @code{@value{AS}}, there is no need for @samp{-nocpp}, because the 426@sc{gnu} assembler itself never runs the C preprocessor. 427 428@item -msoft-float 429@itemx -mhard-float 430Disable or enable floating-point instructions. Note that by default 431floating-point instructions are always allowed even with CPU targets 432that don't have support for these instructions. 433 434@item -msingle-float 435@itemx -mdouble-float 436Disable or enable double-precision floating-point operations. Note 437that by default double-precision floating-point operations are always 438allowed even with CPU targets that don't have support for these 439operations. 440 441@item --construct-floats 442@itemx --no-construct-floats 443The @code{--no-construct-floats} option disables the construction of 444double width floating point constants by loading the two halves of the 445value into the two single width floating point registers that make up 446the double width register. This feature is useful if the processor 447support the FR bit in its status register, and this bit is known (by 448the programmer) to be set. This bit prevents the aliasing of the double 449width register by the single width registers. 450 451By default @code{--construct-floats} is selected, allowing construction 452of these floating point constants. 453 454@item --relax-branch 455@itemx --no-relax-branch 456The @samp{--relax-branch} option enables the relaxation of out-of-range 457branches. Any branches whose target cannot be reached directly are 458converted to a small instruction sequence including an inverse-condition 459branch to the physically next instruction, and a jump to the original 460target is inserted between the two instructions. In PIC code the jump 461will involve further instructions for address calculation. 462 463The @code{BC1ANY2F}, @code{BC1ANY2T}, @code{BC1ANY4F}, @code{BC1ANY4T}, 464@code{BPOSGE32} and @code{BPOSGE64} instructions are excluded from 465relaxation, because they have no complementing counterparts. They could 466be relaxed with the use of a longer sequence involving another branch, 467however this has not been implemented and if their target turns out of 468reach, they produce an error even if branch relaxation is enabled. 469 470Also no MIPS16 branches are ever relaxed. 471 472By default @samp{--no-relax-branch} is selected, causing any out-of-range 473branches to produce an error. 474 475@cindex @option{-mnan=} command line option, MIPS 476@item -mnan=@var{encoding} 477This option indicates whether the source code uses the IEEE 2008 478NaN encoding (@option{-mnan=2008}) or the original MIPS encoding 479(@option{-mnan=legacy}). It is equivalent to adding a @code{.nan} 480directive to the beginning of the source file. @xref{MIPS NaN Encodings}. 481 482@option{-mnan=legacy} is the default if no @option{-mnan} option or 483@code{.nan} directive is used. 484 485@item --trap 486@itemx --no-break 487@c FIXME! (1) reflect these options (next item too) in option summaries; 488@c (2) stop teasing, say _which_ instructions expanded _how_. 489@code{@value{AS}} automatically macro expands certain division and 490multiplication instructions to check for overflow and division by zero. This 491option causes @code{@value{AS}} to generate code to take a trap exception 492rather than a break exception when an error is detected. The trap instructions 493are only supported at Instruction Set Architecture level 2 and higher. 494 495@item --break 496@itemx --no-trap 497Generate code to take a break exception rather than a trap exception when an 498error is detected. This is the default. 499 500@item -mpdr 501@itemx -mno-pdr 502Control generation of @code{.pdr} sections. Off by default on IRIX, on 503elsewhere. 504 505@item -mshared 506@itemx -mno-shared 507When generating code using the Unix calling conventions (selected by 508@samp{-KPIC} or @samp{-mcall_shared}), gas will normally generate code 509which can go into a shared library. The @samp{-mno-shared} option 510tells gas to generate code which uses the calling convention, but can 511not go into a shared library. The resulting code is slightly more 512efficient. This option only affects the handling of the 513@samp{.cpload} and @samp{.cpsetup} pseudo-ops. 514@end table 515 516@node MIPS Macros 517@section High-level assembly macros 518 519MIPS assemblers have traditionally provided a wider range of 520instructions than the MIPS architecture itself. These extra 521instructions are usually referred to as ``macro'' instructions 522@footnote{The term ``macro'' is somewhat overloaded here, since 523these macros have no relation to those defined by @code{.macro}, 524@pxref{Macro,, @code{.macro}}.}. 525 526Some MIPS macro instructions extend an underlying architectural instruction 527while others are entirely new. An example of the former type is @code{and}, 528which allows the third operand to be either a register or an arbitrary 529immediate value. Examples of the latter type include @code{bgt}, which 530branches to the third operand when the first operand is greater than 531the second operand, and @code{ulh}, which implements an unaligned 5322-byte load. 533 534One of the most common extensions provided by macros is to expand 535memory offsets to the full address range (32 or 64 bits) and to allow 536symbolic offsets such as @samp{my_data + 4} to be used in place of 537integer constants. For example, the architectural instruction 538@code{lbu} allows only a signed 16-bit offset, whereas the macro 539@code{lbu} allows code such as @samp{lbu $4,array+32769($5)}. 540The implementation of these symbolic offsets depends on several factors, 541such as whether the assembler is generating SVR4-style PIC (selected by 542@option{-KPIC}, @pxref{MIPS Options,, Assembler options}), the size of symbols 543(@pxref{MIPS Symbol Sizes,, Directives to override the size of symbols}), 544and the small data limit (@pxref{MIPS Small Data,, Controlling the use 545of small data accesses}). 546 547@kindex @code{.set macro} 548@kindex @code{.set nomacro} 549Sometimes it is undesirable to have one assembly instruction expand 550to several machine instructions. The directive @code{.set nomacro} 551tells the assembler to warn when this happens. @code{.set macro} 552restores the default behavior. 553 554@cindex @code{at} register, MIPS 555@kindex @code{.set at=@var{reg}} 556Some macro instructions need a temporary register to store intermediate 557results. This register is usually @code{$1}, also known as @code{$at}, 558but it can be changed to any core register @var{reg} using 559@code{.set at=@var{reg}}. Note that @code{$at} always refers 560to @code{$1} regardless of which register is being used as the 561temporary register. 562 563@kindex @code{.set at} 564@kindex @code{.set noat} 565Implicit uses of the temporary register in macros could interfere with 566explicit uses in the assembly code. The assembler therefore warns 567whenever it sees an explicit use of the temporary register. The directive 568@code{.set noat} silences this warning while @code{.set at} restores 569the default behavior. It is safe to use @code{.set noat} while 570@code{.set nomacro} is in effect since single-instruction macros 571never need a temporary register. 572 573Note that while the @sc{gnu} assembler provides these macros for compatibility, 574it does not make any attempt to optimize them with the surrounding code. 575 576@node MIPS Symbol Sizes 577@section Directives to override the size of symbols 578 579@kindex @code{.set sym32} 580@kindex @code{.set nosym32} 581The n64 ABI allows symbols to have any 64-bit value. Although this 582provides a great deal of flexibility, it means that some macros have 583much longer expansions than their 32-bit counterparts. For example, 584the non-PIC expansion of @samp{dla $4,sym} is usually: 585 586@smallexample 587lui $4,%highest(sym) 588lui $1,%hi(sym) 589daddiu $4,$4,%higher(sym) 590daddiu $1,$1,%lo(sym) 591dsll32 $4,$4,0 592daddu $4,$4,$1 593@end smallexample 594 595whereas the 32-bit expansion is simply: 596 597@smallexample 598lui $4,%hi(sym) 599daddiu $4,$4,%lo(sym) 600@end smallexample 601 602n64 code is sometimes constructed in such a way that all symbolic 603constants are known to have 32-bit values, and in such cases, it's 604preferable to use the 32-bit expansion instead of the 64-bit 605expansion. 606 607You can use the @code{.set sym32} directive to tell the assembler 608that, from this point on, all expressions of the form 609@samp{@var{symbol}} or @samp{@var{symbol} + @var{offset}} 610have 32-bit values. For example: 611 612@smallexample 613.set sym32 614dla $4,sym 615lw $4,sym+16 616sw $4,sym+0x8000($4) 617@end smallexample 618 619will cause the assembler to treat @samp{sym}, @code{sym+16} and 620@code{sym+0x8000} as 32-bit values. The handling of non-symbolic 621addresses is not affected. 622 623The directive @code{.set nosym32} ends a @code{.set sym32} block and 624reverts to the normal behavior. It is also possible to change the 625symbol size using the command-line options @option{-msym32} and 626@option{-mno-sym32}. 627 628These options and directives are always accepted, but at present, 629they have no effect for anything other than n64. 630 631@node MIPS Small Data 632@section Controlling the use of small data accesses 633 634@c This section deliberately glosses over the possibility of using -G 635@c in SVR4-style PIC, as could be done on IRIX. We don't support that. 636@cindex small data, MIPS 637@cindex @code{gp} register, MIPS 638It often takes several instructions to load the address of a symbol. 639For example, when @samp{addr} is a 32-bit symbol, the non-PIC expansion 640of @samp{dla $4,addr} is usually: 641 642@smallexample 643lui $4,%hi(addr) 644daddiu $4,$4,%lo(addr) 645@end smallexample 646 647The sequence is much longer when @samp{addr} is a 64-bit symbol. 648@xref{MIPS Symbol Sizes,, Directives to override the size of symbols}. 649 650In order to cut down on this overhead, most embedded MIPS systems 651set aside a 64-kilobyte ``small data'' area and guarantee that all 652data of size @var{n} and smaller will be placed in that area. 653The limit @var{n} is passed to both the assembler and the linker 654using the command-line option @option{-G @var{n}}, @pxref{MIPS Options,, 655Assembler options}. Note that the same value of @var{n} must be used 656when linking and when assembling all input files to the link; any 657inconsistency could cause a relocation overflow error. 658 659The size of an object in the @code{.bss} section is set by the 660@code{.comm} or @code{.lcomm} directive that defines it. The size of 661an external object may be set with the @code{.extern} directive. For 662example, @samp{.extern sym,4} declares that the object at @code{sym} 663is 4 bytes in length, while leaving @code{sym} otherwise undefined. 664 665When no @option{-G} option is given, the default limit is 8 bytes. 666The option @option{-G 0} prevents any data from being automatically 667classified as small. 668 669It is also possible to mark specific objects as small by putting them 670in the special sections @code{.sdata} and @code{.sbss}, which are 671``small'' counterparts of @code{.data} and @code{.bss} respectively. 672The toolchain will treat such data as small regardless of the 673@option{-G} setting. 674 675On startup, systems that support a small data area are expected to 676initialize register @code{$28}, also known as @code{$gp}, in such a 677way that small data can be accessed using a 16-bit offset from that 678register. For example, when @samp{addr} is small data, 679the @samp{dla $4,addr} instruction above is equivalent to: 680 681@smallexample 682daddiu $4,$28,%gp_rel(addr) 683@end smallexample 684 685Small data is not supported for SVR4-style PIC. 686 687@node MIPS ISA 688@section Directives to override the ISA level 689 690@cindex MIPS ISA override 691@kindex @code{.set mips@var{n}} 692@sc{gnu} @code{@value{AS}} supports an additional directive to change 693the MIPS Instruction Set Architecture level on the fly: @code{.set 694mips@var{n}}. @var{n} should be a number from 0 to 5, or 32, 32r2, 32r3, 69532r5, 32r6, 64, 64r2, 64r3, 64r5 or 64r6. 696The values other than 0 make the assembler accept instructions 697for the corresponding ISA level, from that point on in the 698assembly. @code{.set mips@var{n}} affects not only which instructions 699are permitted, but also how certain macros are expanded. @code{.set 700mips0} restores the ISA level to its original level: either the 701level you selected with command line options, or the default for your 702configuration. You can use this feature to permit specific MIPS III 703instructions while assembling in 32 bit mode. Use this directive with 704care! 705 706@cindex MIPS CPU override 707@kindex @code{.set arch=@var{cpu}} 708The @code{.set arch=@var{cpu}} directive provides even finer control. 709It changes the effective CPU target and allows the assembler to use 710instructions specific to a particular CPU. All CPUs supported by the 711@samp{-march} command line option are also selectable by this directive. 712The original value is restored by @code{.set arch=default}. 713 714The directive @code{.set mips16} puts the assembler into MIPS 16 mode, 715in which it will assemble instructions for the MIPS 16 processor. Use 716@code{.set nomips16} to return to normal 32 bit mode. 717 718Traditional MIPS assemblers do not support this directive. 719 720The directive @code{.set micromips} puts the assembler into microMIPS mode, 721in which it will assemble instructions for the microMIPS processor. Use 722@code{.set nomicromips} to return to normal 32 bit mode. 723 724Traditional MIPS assemblers do not support this directive. 725 726@node MIPS assembly options 727@section Directives to control code generation 728 729@cindex MIPS directives to override command line options 730@kindex @code{.module} 731The @code{.module} directive allows command line options to be set directly 732from assembly. The format of the directive matches the @code{.set} 733directive but only those options which are relevant to a whole module are 734supported. The effect of a @code{.module} directive is the same as the 735corresponding command line option. Where @code{.set} directives support 736returning to a default then the @code{.module} directives do not as they 737define the defaults. 738 739These module-level directives must appear first in assembly. 740 741Traditional MIPS assemblers do not support this directive. 742 743@cindex MIPS 32-bit microMIPS instruction generation override 744@kindex @code{.set insn32} 745@kindex @code{.set noinsn32} 746The directive @code{.set insn32} makes the assembler only use 32-bit 747instruction encodings when generating code for the microMIPS processor. 748This directive inhibits the use of any 16-bit instructions from that 749point on in the assembly. The @code{.set noinsn32} directive allows 75016-bit instructions to be accepted. 751 752Traditional MIPS assemblers do not support this directive. 753 754@node MIPS autoextend 755@section Directives for extending MIPS 16 bit instructions 756 757@kindex @code{.set autoextend} 758@kindex @code{.set noautoextend} 759By default, MIPS 16 instructions are automatically extended to 32 bits 760when necessary. The directive @code{.set noautoextend} will turn this 761off. When @code{.set noautoextend} is in effect, any 32 bit instruction 762must be explicitly extended with the @code{.e} modifier (e.g., 763@code{li.e $4,1000}). The directive @code{.set autoextend} may be used 764to once again automatically extend instructions when necessary. 765 766This directive is only meaningful when in MIPS 16 mode. Traditional 767MIPS assemblers do not support this directive. 768 769@node MIPS insn 770@section Directive to mark data as an instruction 771 772@kindex @code{.insn} 773The @code{.insn} directive tells @code{@value{AS}} that the following 774data is actually instructions. This makes a difference in MIPS 16 and 775microMIPS modes: when loading the address of a label which precedes 776instructions, @code{@value{AS}} automatically adds 1 to the value, so 777that jumping to the loaded address will do the right thing. 778 779@kindex @code{.global} 780The @code{.global} and @code{.globl} directives supported by 781@code{@value{AS}} will by default mark the symbol as pointing to a 782region of data not code. This means that, for example, any 783instructions following such a symbol will not be disassembled by 784@code{objdump} as it will regard them as data. To change this 785behavior an optional section name can be placed after the symbol name 786in the @code{.global} directive. If this section exists and is known 787to be a code section, then the symbol will be marked as pointing at 788code not data. Ie the syntax for the directive is: 789 790 @code{.global @var{symbol}[ @var{section}][, @var{symbol}[ @var{section}]] ...}, 791 792Here is a short example: 793 794@example 795 .global foo .text, bar, baz .data 796foo: 797 nop 798bar: 799 .word 0x0 800baz: 801 .word 0x1 802 803@end example 804 805@node MIPS FP ABIs 806@section Directives to control the FP ABI 807@menu 808* MIPS FP ABI History:: History of FP ABIs 809* MIPS FP ABI Variants:: Supported FP ABIs 810* MIPS FP ABI Selection:: Automatic selection of FP ABI 811* MIPS FP ABI Compatibility:: Linking different FP ABI variants 812@end menu 813 814@node MIPS FP ABI History 815@subsection History of FP ABIs 816@cindex @code{.gnu_attribute 4, @var{n}} directive, MIPS 817@cindex @code{.gnu_attribute Tag_GNU_MIPS_ABI_FP, @var{n}} directive, MIPS 818The MIPS ABIs support a variety of different floating-point extensions 819where calling-convention and register sizes vary for floating-point data. 820The extensions exist to support a wide variety of optional architecture 821features. The resulting ABI variants are generally incompatible with each 822other and must be tracked carefully. 823 824Traditionally the use of an explicit @code{.gnu_attribute 4, @var{n}} 825directive is used to indicate which ABI is in use by a specific module. 826It was then left to the user to ensure that command line options and the 827selected ABI were compatible with some potential for inconsistencies. 828 829@node MIPS FP ABI Variants 830@subsection Supported FP ABIs 831The supported floating-point ABI variants are: 832 833@table @code 834@item 0 - No floating-point 835This variant is used to indicate that floating-point is not used within 836the module at all and therefore has no impact on the ABI. This is the 837default. 838 839@item 1 - Double-precision 840This variant indicates that double-precision support is used. For 64-bit 841ABIs this means that 64-bit wide floating-point registers are required. 842For 32-bit ABIs this means that 32-bit wide floating-point registers are 843required and double-precision operations use pairs of registers. 844 845@item 2 - Single-precision 846This variant indicates that single-precision support is used. Double 847precision operations will be supported via soft-float routines. 848 849@item 3 - Soft-float 850This variant indicates that although floating-point support is used all 851operations are emulated in software. This means the ABI is modified to 852pass all floating-point data in general-purpose registers. 853 854@item 4 - Deprecated 855This variant existed as an initial attempt at supporting 64-bit wide 856floating-point registers for O32 ABI on a MIPS32r2 CPU. This has been 857superseded by 5, 6 and 7. 858 859@item 5 - Double-precision 32-bit CPU, 32-bit or 64-bit FPU 860This variant is used by 32-bit ABIs to indicate that the floating-point 861code in the module has been designed to operate correctly with either 86232-bit wide or 64-bit wide floating-point registers. Double-precision 863support is used. Only O32 currently supports this variant and requires 864a minimum architecture of MIPS II. 865 866@item 6 - Double-precision 32-bit FPU, 64-bit FPU 867This variant is used by 32-bit ABIs to indicate that the floating-point 868code in the module requires 64-bit wide floating-point registers. 869Double-precision support is used. Only O32 currently supports this 870variant and requires a minimum architecture of MIPS32r2. 871 872@item 7 - Double-precision compat 32-bit FPU, 64-bit FPU 873This variant is used by 32-bit ABIs to indicate that the floating-point 874code in the module requires 64-bit wide floating-point registers. 875Double-precision support is used. This differs from the previous ABI 876as it restricts use of odd-numbered single-precision registers. Only 877O32 currently supports this variant and requires a minimum architecture 878of MIPS32r2. 879@end table 880 881@node MIPS FP ABI Selection 882@subsection Automatic selection of FP ABI 883@cindex @code{.module fp=@var{nn}} directive, MIPS 884In order to simplify and add safety to the process of selecting the 885correct floating-point ABI, the assembler will automatically infer the 886correct @code{.gnu_attribute 4, @var{n}} directive based on command line 887options and @code{.module} overrides. Where an explicit 888@code{.gnu_attribute 4, @var{n}} directive has been seen then a warning 889will be raised if it does not match an inferred setting. 890 891The floating-point ABI is inferred as follows. If @samp{-msoft-float} 892has been used the module will be marked as soft-float. If 893@samp{-msingle-float} has been used then the module will be marked as 894single-precision. The remaining ABIs are then selected based 895on the FP register width. Double-precision is selected if the width 896of GP and FP registers match and the special double-precision variants 897for 32-bit ABIs are then selected depending on @samp{-mfpxx}, 898@samp{-mfp64} and @samp{-mno-odd-spreg}. 899 900@node MIPS FP ABI Compatibility 901@subsection Linking different FP ABI variants 902Modules using the default FP ABI (no floating-point) can be linked with 903any other (singular) FP ABI variant. 904 905Special compatibility support exists for O32 with the four 906double-precision FP ABI variants. The @samp{-mfpxx} FP ABI is specifically 907designed to be compatible with the standard double-precision ABI and the 908@samp{-mfp64} FP ABIs. This makes it desirable for O32 modules to be 909built as @samp{-mfpxx} to ensure the maximum compatibility with other 910modules produced for more specific needs. The only FP ABIs which cannot 911be linked together are the standard double-precision ABI and the full 912@samp{-mfp64} ABI with @samp{-modd-spreg}. 913 914@node MIPS NaN Encodings 915@section Directives to record which NaN encoding is being used 916 917@cindex MIPS IEEE 754 NaN data encoding selection 918@cindex @code{.nan} directive, MIPS 919The IEEE 754 floating-point standard defines two types of not-a-number 920(NaN) data: ``signalling'' NaNs and ``quiet'' NaNs. The original version 921of the standard did not specify how these two types should be 922distinguished. Most implementations followed the i387 model, in which 923the first bit of the significand is set for quiet NaNs and clear for 924signalling NaNs. However, the original MIPS implementation assigned the 925opposite meaning to the bit, so that it was set for signalling NaNs and 926clear for quiet NaNs. 927 928The 2008 revision of the standard formally suggested the i387 choice 929and as from Sep 2012 the current release of the MIPS architecture 930therefore optionally supports that form. Code that uses one NaN encoding 931would usually be incompatible with code that uses the other NaN encoding, 932so MIPS ELF objects have a flag (@code{EF_MIPS_NAN2008}) to record which 933encoding is being used. 934 935Assembly files can use the @code{.nan} directive to select between the 936two encodings. @samp{.nan 2008} says that the assembly file uses the 937IEEE 754-2008 encoding while @samp{.nan legacy} says that the file uses 938the original MIPS encoding. If several @code{.nan} directives are given, 939the final setting is the one that is used. 940 941The command-line options @option{-mnan=legacy} and @option{-mnan=2008} 942can be used instead of @samp{.nan legacy} and @samp{.nan 2008} 943respectively. However, any @code{.nan} directive overrides the 944command-line setting. 945 946@samp{.nan legacy} is the default if no @code{.nan} directive or 947@option{-mnan} option is given. 948 949Note that @sc{gnu} @code{@value{AS}} does not produce NaNs itself and 950therefore these directives do not affect code generation. They simply 951control the setting of the @code{EF_MIPS_NAN2008} flag. 952 953Traditional MIPS assemblers do not support these directives. 954 955@node MIPS Option Stack 956@section Directives to save and restore options 957 958@cindex MIPS option stack 959@kindex @code{.set push} 960@kindex @code{.set pop} 961The directives @code{.set push} and @code{.set pop} may be used to save 962and restore the current settings for all the options which are 963controlled by @code{.set}. The @code{.set push} directive saves the 964current settings on a stack. The @code{.set pop} directive pops the 965stack and restores the settings. 966 967These directives can be useful inside an macro which must change an 968option such as the ISA level or instruction reordering but does not want 969to change the state of the code which invoked the macro. 970 971Traditional MIPS assemblers do not support these directives. 972 973@node MIPS ASE Instruction Generation Overrides 974@section Directives to control generation of MIPS ASE instructions 975 976@cindex MIPS MIPS-3D instruction generation override 977@kindex @code{.set mips3d} 978@kindex @code{.set nomips3d} 979The directive @code{.set mips3d} makes the assembler accept instructions 980from the MIPS-3D Application Specific Extension from that point on 981in the assembly. The @code{.set nomips3d} directive prevents MIPS-3D 982instructions from being accepted. 983 984@cindex SmartMIPS instruction generation override 985@kindex @code{.set smartmips} 986@kindex @code{.set nosmartmips} 987The directive @code{.set smartmips} makes the assembler accept 988instructions from the SmartMIPS Application Specific Extension to the 989MIPS32 ISA from that point on in the assembly. The 990@code{.set nosmartmips} directive prevents SmartMIPS instructions from 991being accepted. 992 993@cindex MIPS MDMX instruction generation override 994@kindex @code{.set mdmx} 995@kindex @code{.set nomdmx} 996The directive @code{.set mdmx} makes the assembler accept instructions 997from the MDMX Application Specific Extension from that point on 998in the assembly. The @code{.set nomdmx} directive prevents MDMX 999instructions from being accepted. 1000 1001@cindex MIPS DSP Release 1 instruction generation override 1002@kindex @code{.set dsp} 1003@kindex @code{.set nodsp} 1004The directive @code{.set dsp} makes the assembler accept instructions 1005from the DSP Release 1 Application Specific Extension from that point 1006on in the assembly. The @code{.set nodsp} directive prevents DSP 1007Release 1 instructions from being accepted. 1008 1009@cindex MIPS DSP Release 2 instruction generation override 1010@kindex @code{.set dspr2} 1011@kindex @code{.set nodspr2} 1012The directive @code{.set dspr2} makes the assembler accept instructions 1013from the DSP Release 2 Application Specific Extension from that point 1014on in the assembly. This directive implies @code{.set dsp}. The 1015@code{.set nodspr2} directive prevents DSP Release 2 instructions from 1016being accepted. 1017 1018@cindex MIPS DSP Release 3 instruction generation override 1019@kindex @code{.set dspr3} 1020@kindex @code{.set nodspr3} 1021The directive @code{.set dspr3} makes the assembler accept instructions 1022from the DSP Release 3 Application Specific Extension from that point 1023on in the assembly. This directive implies @code{.set dsp} and 1024@code{.set dspr2}. The @code{.set nodspr3} directive prevents DSP 1025Release 3 instructions from being accepted. 1026 1027@cindex MIPS MT instruction generation override 1028@kindex @code{.set mt} 1029@kindex @code{.set nomt} 1030The directive @code{.set mt} makes the assembler accept instructions 1031from the MT Application Specific Extension from that point on 1032in the assembly. The @code{.set nomt} directive prevents MT 1033instructions from being accepted. 1034 1035@cindex MIPS MCU instruction generation override 1036@kindex @code{.set mcu} 1037@kindex @code{.set nomcu} 1038The directive @code{.set mcu} makes the assembler accept instructions 1039from the MCU Application Specific Extension from that point on 1040in the assembly. The @code{.set nomcu} directive prevents MCU 1041instructions from being accepted. 1042 1043@cindex MIPS SIMD Architecture instruction generation override 1044@kindex @code{.set msa} 1045@kindex @code{.set nomsa} 1046The directive @code{.set msa} makes the assembler accept instructions 1047from the MIPS SIMD Architecture Extension from that point on 1048in the assembly. The @code{.set nomsa} directive prevents MSA 1049instructions from being accepted. 1050 1051@cindex Virtualization instruction generation override 1052@kindex @code{.set virt} 1053@kindex @code{.set novirt} 1054The directive @code{.set virt} makes the assembler accept instructions 1055from the Virtualization Application Specific Extension from that point 1056on in the assembly. The @code{.set novirt} directive prevents Virtualization 1057instructions from being accepted. 1058 1059@cindex MIPS eXtended Physical Address (XPA) instruction generation override 1060@kindex @code{.set xpa} 1061@kindex @code{.set noxpa} 1062The directive @code{.set xpa} makes the assembler accept instructions 1063from the XPA Extension from that point on in the assembly. The 1064@code{.set noxpa} directive prevents XPA instructions from being accepted. 1065 1066Traditional MIPS assemblers do not support these directives. 1067 1068@node MIPS Floating-Point 1069@section Directives to override floating-point options 1070 1071@cindex Disable floating-point instructions 1072@kindex @code{.set softfloat} 1073@kindex @code{.set hardfloat} 1074The directives @code{.set softfloat} and @code{.set hardfloat} provide 1075finer control of disabling and enabling float-point instructions. 1076These directives always override the default (that hard-float 1077instructions are accepted) or the command-line options 1078(@samp{-msoft-float} and @samp{-mhard-float}). 1079 1080@cindex Disable single-precision floating-point operations 1081@kindex @code{.set singlefloat} 1082@kindex @code{.set doublefloat} 1083The directives @code{.set singlefloat} and @code{.set doublefloat} 1084provide finer control of disabling and enabling double-precision 1085float-point operations. These directives always override the default 1086(that double-precision operations are accepted) or the command-line 1087options (@samp{-msingle-float} and @samp{-mdouble-float}). 1088 1089Traditional MIPS assemblers do not support these directives. 1090 1091@node MIPS Syntax 1092@section Syntactical considerations for the MIPS assembler 1093@menu 1094* MIPS-Chars:: Special Characters 1095@end menu 1096 1097@node MIPS-Chars 1098@subsection Special Characters 1099 1100@cindex line comment character, MIPS 1101@cindex MIPS line comment character 1102The presence of a @samp{#} on a line indicates the start of a comment 1103that extends to the end of the current line. 1104 1105If a @samp{#} appears as the first character of a line, the whole line 1106is treated as a comment, but in this case the line can also be a 1107logical line number directive (@pxref{Comments}) or a 1108preprocessor control command (@pxref{Preprocessing}). 1109 1110@cindex line separator, MIPS 1111@cindex statement separator, MIPS 1112@cindex MIPS line separator 1113The @samp{;} character can be used to separate statements on the same 1114line. 1115