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