1@c Copyright 1991, 1992, 1993, 1994, 1995, 1997, 1999, 2000, 2001, 2@c 2002, 2003, 2004 3@c Free Software Foundation, Inc. 4@c This is part of the GAS manual. 5@c For copying conditions, see the file as.texinfo. 6@ifset GENERIC 7@page 8@node MIPS-Dependent 9@chapter MIPS Dependent Features 10@end ifset 11@ifclear GENERIC 12@node Machine Dependencies 13@chapter MIPS Dependent Features 14@end ifclear 15 16@cindex MIPS processor 17@sc{gnu} @code{@value{AS}} for @sc{mips} architectures supports several 18different @sc{mips} processors, and MIPS ISA levels I through V, MIPS32, 19and MIPS64. For information about the @sc{mips} instruction set, see 20@cite{MIPS RISC Architecture}, by Kane and Heindrich (Prentice-Hall). 21For an overview of @sc{mips} assembly conventions, see ``Appendix D: 22Assembly Language Programming'' in the same work. 23 24@menu 25* MIPS Opts:: Assembler options 26* MIPS Object:: ECOFF object code 27* MIPS Stabs:: Directives for debugging information 28* MIPS ISA:: Directives to override the ISA level 29* MIPS symbol sizes:: Directives to override the size of symbols 30* MIPS autoextend:: Directives for extending MIPS 16 bit instructions 31* MIPS insn:: Directive to mark data as an instruction 32* MIPS option stack:: Directives to save and restore options 33* MIPS ASE instruction generation overrides:: Directives to control 34 generation of MIPS ASE instructions 35* MIPS floating-point:: Directives to override floating-point options 36@end menu 37 38@node MIPS Opts 39@section Assembler options 40 41The @sc{mips} configurations of @sc{gnu} @code{@value{AS}} support these 42special options: 43 44@table @code 45@cindex @code{-G} option (MIPS) 46@item -G @var{num} 47This option sets the largest size of an object that can be referenced 48implicitly with the @code{gp} register. It is only accepted for targets 49that use @sc{ecoff} format. The default value is 8. 50 51@cindex @code{-EB} option (MIPS) 52@cindex @code{-EL} option (MIPS) 53@cindex MIPS big-endian output 54@cindex MIPS little-endian output 55@cindex big-endian output, MIPS 56@cindex little-endian output, MIPS 57@item -EB 58@itemx -EL 59Any @sc{mips} configuration of @code{@value{AS}} can select big-endian or 60little-endian output at run time (unlike the other @sc{gnu} development 61tools, which must be configured for one or the other). Use @samp{-EB} 62to select big-endian output, and @samp{-EL} for little-endian. 63 64@item -KPIC 65@cindex PIC selection, MIPS 66@cindex @option{-KPIC} option, MIPS 67Generate SVR4-style PIC. This option tells the assembler to generate 68SVR4-style position-independent macro expansions. It also tells the 69assembler to mark the output file as PIC. 70 71@item -mvxworks-pic 72@cindex @option{-mvxworks-pic} option, MIPS 73Generate VxWorks PIC. This option tells the assembler to generate 74VxWorks-style position-independent macro expansions. 75 76@cindex MIPS architecture options 77@item -mips1 78@itemx -mips2 79@itemx -mips3 80@itemx -mips4 81@itemx -mips5 82@itemx -mips32 83@itemx -mips32r2 84@itemx -mips64 85@itemx -mips64r2 86Generate code for a particular MIPS Instruction Set Architecture level. 87@samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors, 88@samp{-mips2} to the @sc{r6000} processor, @samp{-mips3} to the 89@sc{r4000} processor, and @samp{-mips4} to the @sc{r8000} and 90@sc{r10000} processors. @samp{-mips5}, @samp{-mips32}, @samp{-mips32r2}, 91@samp{-mips64}, and @samp{-mips64r2} 92correspond to generic 93@sc{MIPS V}, @sc{MIPS32}, @sc{MIPS32 Release 2}, @sc{MIPS64}, 94and @sc{MIPS64 Release 2} 95ISA processors, respectively. You can also switch 96instruction sets during the assembly; see @ref{MIPS ISA, Directives to 97override the ISA level}. 98 99@item -mgp32 100@itemx -mfp32 101Some macros have different expansions for 32-bit and 64-bit registers. 102The register sizes are normally inferred from the ISA and ABI, but these 103flags force a certain group of registers to be treated as 32 bits wide at 104all times. @samp{-mgp32} controls the size of general-purpose registers 105and @samp{-mfp32} controls the size of floating-point registers. 106 107The @code{.set gp=32} and @code{.set fp=32} directives allow the size 108of registers to be changed for parts of an object. The default value is 109restored by @code{.set gp=default} and @code{.set fp=default}. 110 111On some MIPS variants there is a 32-bit mode flag; when this flag is 112set, 64-bit instructions generate a trap. Also, some 32-bit OSes only 113save the 32-bit registers on a context switch, so it is essential never 114to use the 64-bit registers. 115 116@item -mgp64 117@itemx -mfp64 118Assume that 64-bit registers are available. This is provided in the 119interests of symmetry with @samp{-mgp32} and @samp{-mfp32}. 120 121The @code{.set gp=64} and @code{.set fp=64} directives allow the size 122of registers to be changed for parts of an object. The default value is 123restored by @code{.set gp=default} and @code{.set fp=default}. 124 125@item -mips16 126@itemx -no-mips16 127Generate code for the MIPS 16 processor. This is equivalent to putting 128@code{.set mips16} at the start of the assembly file. @samp{-no-mips16} 129turns off this option. 130 131@item -msmartmips 132@itemx -mno-smartmips 133Enables the SmartMIPS extensions to the MIPS32 instruction set, which 134provides a number of new instructions which target smartcard and 135cryptographic applications. This is equivalent to putting 136@code{.set smartmips} at the start of the assembly file. 137@samp{-mno-smartmips} turns off this option. 138 139@item -mips3d 140@itemx -no-mips3d 141Generate code for the MIPS-3D Application Specific Extension. 142This tells the assembler to accept MIPS-3D instructions. 143@samp{-no-mips3d} turns off this option. 144 145@item -mdmx 146@itemx -no-mdmx 147Generate code for the MDMX Application Specific Extension. 148This tells the assembler to accept MDMX instructions. 149@samp{-no-mdmx} turns off this option. 150 151@item -mdsp 152@itemx -mno-dsp 153Generate code for the DSP Release 1 Application Specific Extension. 154This tells the assembler to accept DSP Release 1 instructions. 155@samp{-mno-dsp} turns off this option. 156 157@item -mdspr2 158@itemx -mno-dspr2 159Generate code for the DSP Release 2 Application Specific Extension. 160This option implies -mdsp. 161This tells the assembler to accept DSP Release 2 instructions. 162@samp{-mno-dspr2} turns off this option. 163 164@item -mmt 165@itemx -mno-mt 166Generate code for the MT Application Specific Extension. 167This tells the assembler to accept MT instructions. 168@samp{-mno-mt} turns off this option. 169 170@item -mfix7000 171@itemx -mno-fix7000 172Cause nops to be inserted if the read of the destination register 173of an mfhi or mflo instruction occurs in the following two instructions. 174 175@item -mfix-vr4120 176@itemx -no-mfix-vr4120 177Insert nops to work around certain VR4120 errata. This option is 178intended to be used on GCC-generated code: it is not designed to catch 179all problems in hand-written assembler code. 180 181@item -mfix-vr4130 182@itemx -no-mfix-vr4130 183Insert nops to work around the VR4130 @samp{mflo}/@samp{mfhi} errata. 184 185@item -m4010 186@itemx -no-m4010 187Generate code for the LSI @sc{r4010} chip. This tells the assembler to 188accept the @sc{r4010} specific instructions (@samp{addciu}, @samp{ffc}, 189etc.), and to not schedule @samp{nop} instructions around accesses to 190the @samp{HI} and @samp{LO} registers. @samp{-no-m4010} turns off this 191option. 192 193@item -m4650 194@itemx -no-m4650 195Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept 196the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop} 197instructions around accesses to the @samp{HI} and @samp{LO} registers. 198@samp{-no-m4650} turns off this option. 199 200@itemx -m3900 201@itemx -no-m3900 202@itemx -m4100 203@itemx -no-m4100 204For each option @samp{-m@var{nnnn}}, generate code for the MIPS 205@sc{r@var{nnnn}} chip. This tells the assembler to accept instructions 206specific to that chip, and to schedule for that chip's hazards. 207 208@item -march=@var{cpu} 209Generate code for a particular MIPS cpu. It is exactly equivalent to 210@samp{-m@var{cpu}}, except that there are more value of @var{cpu} 211understood. Valid @var{cpu} value are: 212 213@quotation 2142000, 2153000, 2163900, 2174000, 2184010, 2194100, 2204111, 221vr4120, 222vr4130, 223vr4181, 2244300, 2254400, 2264600, 2274650, 2285000, 229rm5200, 230rm5230, 231rm5231, 232rm5261, 233rm5721, 234vr5400, 235vr5500, 2366000, 237rm7000, 2388000, 239rm9000, 24010000, 24112000, 2424kc, 2434km, 2444kp, 2454ksc, 2464kec, 2474kem, 2484kep, 2494ksd, 250m4k, 251m4kp, 25224kc, 25324kf2_1, 25424kf, 25524kf1_1, 25624kec, 25724kef2_1, 25824kef, 25924kef1_1, 26034kc, 26134kf2_1, 26234kf, 26334kf1_1, 26474kc, 26574kf2_1, 26674kf, 26774kf1_1, 26874kf3_2, 2695kc, 2705kf, 27120kc, 27225kf, 273sb1, 274sb1a, 275loongson2e, 276loongson2f, 277octeon, 278xlr 279@end quotation 280 281For compatibility reasons, @samp{@var{n}x} and @samp{@var{b}fx} are 282accepted as synonyms for @samp{@var{n}f1_1}. These values are 283deprecated. 284 285@item -mtune=@var{cpu} 286Schedule and tune for a particular MIPS cpu. Valid @var{cpu} values are 287identical to @samp{-march=@var{cpu}}. 288 289@item -mabi=@var{abi} 290Record which ABI the source code uses. The recognized arguments 291are: @samp{32}, @samp{n32}, @samp{o64}, @samp{64} and @samp{eabi}. 292 293@item -msym32 294@itemx -mno-sym32 295@cindex -msym32 296@cindex -mno-sym32 297Equivalent to adding @code{.set sym32} or @code{.set nosym32} to 298the beginning of the assembler input. @xref{MIPS symbol sizes}. 299 300@cindex @code{-nocpp} ignored (MIPS) 301@item -nocpp 302This option is ignored. It is accepted for command-line compatibility with 303other assemblers, which use it to turn off C style preprocessing. With 304@sc{gnu} @code{@value{AS}}, there is no need for @samp{-nocpp}, because the 305@sc{gnu} assembler itself never runs the C preprocessor. 306 307@item -msoft-float 308@itemx -mhard-float 309Disable or enable floating-point instructions. Note that by default 310floating-point instructions are always allowed even with CPU targets 311that don't have support for these instructions. 312 313@item -msingle-float 314@itemx -mdouble-float 315Disable or enable double-precision floating-point operations. Note 316that by default double-precision floating-point operations are always 317allowed even with CPU targets that don't have support for these 318operations. 319 320@item --construct-floats 321@itemx --no-construct-floats 322The @code{--no-construct-floats} option disables the construction of 323double width floating point constants by loading the two halves of the 324value into the two single width floating point registers that make up 325the double width register. This feature is useful if the processor 326support the FR bit in its status register, and this bit is known (by 327the programmer) to be set. This bit prevents the aliasing of the double 328width register by the single width registers. 329 330By default @code{--construct-floats} is selected, allowing construction 331of these floating point constants. 332 333@item --trap 334@itemx --no-break 335@c FIXME! (1) reflect these options (next item too) in option summaries; 336@c (2) stop teasing, say _which_ instructions expanded _how_. 337@code{@value{AS}} automatically macro expands certain division and 338multiplication instructions to check for overflow and division by zero. This 339option causes @code{@value{AS}} to generate code to take a trap exception 340rather than a break exception when an error is detected. The trap instructions 341are only supported at Instruction Set Architecture level 2 and higher. 342 343@item --break 344@itemx --no-trap 345Generate code to take a break exception rather than a trap exception when an 346error is detected. This is the default. 347 348@item -mpdr 349@itemx -mno-pdr 350Control generation of @code{.pdr} sections. Off by default on IRIX, on 351elsewhere. 352 353@item -mshared 354@itemx -mno-shared 355When generating code using the Unix calling conventions (selected by 356@samp{-KPIC} or @samp{-mcall_shared}), gas will normally generate code 357which can go into a shared library. The @samp{-mno-shared} option 358tells gas to generate code which uses the calling convention, but can 359not go into a shared library. The resulting code is slightly more 360efficient. This option only affects the handling of the 361@samp{.cpload} and @samp{.cpsetup} pseudo-ops. 362@end table 363 364@node MIPS Object 365@section MIPS ECOFF object code 366 367@cindex ECOFF sections 368@cindex MIPS ECOFF sections 369Assembling for a @sc{mips} @sc{ecoff} target supports some additional sections 370besides the usual @code{.text}, @code{.data} and @code{.bss}. The 371additional sections are @code{.rdata}, used for read-only data, 372@code{.sdata}, used for small data, and @code{.sbss}, used for small 373common objects. 374 375@cindex small objects, MIPS ECOFF 376@cindex @code{gp} register, MIPS 377When assembling for @sc{ecoff}, the assembler uses the @code{$gp} (@code{$28}) 378register to form the address of a ``small object''. Any object in the 379@code{.sdata} or @code{.sbss} sections is considered ``small'' in this sense. 380For external objects, or for objects in the @code{.bss} section, you can use 381the @code{@value{GCC}} @samp{-G} option to control the size of objects addressed via 382@code{$gp}; the default value is 8, meaning that a reference to any object 383eight bytes or smaller uses @code{$gp}. Passing @samp{-G 0} to 384@code{@value{AS}} prevents it from using the @code{$gp} register on the basis 385of object size (but the assembler uses @code{$gp} for objects in @code{.sdata} 386or @code{sbss} in any case). The size of an object in the @code{.bss} section 387is set by the @code{.comm} or @code{.lcomm} directive that defines it. The 388size of an external object may be set with the @code{.extern} directive. For 389example, @samp{.extern sym,4} declares that the object at @code{sym} is 4 bytes 390in length, whie leaving @code{sym} otherwise undefined. 391 392Using small @sc{ecoff} objects requires linker support, and assumes that the 393@code{$gp} register is correctly initialized (normally done automatically by 394the startup code). @sc{mips} @sc{ecoff} assembly code must not modify the 395@code{$gp} register. 396 397@node MIPS Stabs 398@section Directives for debugging information 399 400@cindex MIPS debugging directives 401@sc{mips} @sc{ecoff} @code{@value{AS}} supports several directives used for 402generating debugging information which are not support by traditional @sc{mips} 403assemblers. These are @code{.def}, @code{.endef}, @code{.dim}, @code{.file}, 404@code{.scl}, @code{.size}, @code{.tag}, @code{.type}, @code{.val}, 405@code{.stabd}, @code{.stabn}, and @code{.stabs}. The debugging information 406generated by the three @code{.stab} directives can only be read by @sc{gdb}, 407not by traditional @sc{mips} debuggers (this enhancement is required to fully 408support C++ debugging). These directives are primarily used by compilers, not 409assembly language programmers! 410 411@node MIPS symbol sizes 412@section Directives to override the size of symbols 413 414@cindex @code{.set sym32} 415@cindex @code{.set nosym32} 416The n64 ABI allows symbols to have any 64-bit value. Although this 417provides a great deal of flexibility, it means that some macros have 418much longer expansions than their 32-bit counterparts. For example, 419the non-PIC expansion of @samp{dla $4,sym} is usually: 420 421@smallexample 422lui $4,%highest(sym) 423lui $1,%hi(sym) 424daddiu $4,$4,%higher(sym) 425daddiu $1,$1,%lo(sym) 426dsll32 $4,$4,0 427daddu $4,$4,$1 428@end smallexample 429 430whereas the 32-bit expansion is simply: 431 432@smallexample 433lui $4,%hi(sym) 434daddiu $4,$4,%lo(sym) 435@end smallexample 436 437n64 code is sometimes constructed in such a way that all symbolic 438constants are known to have 32-bit values, and in such cases, it's 439preferable to use the 32-bit expansion instead of the 64-bit 440expansion. 441 442You can use the @code{.set sym32} directive to tell the assembler 443that, from this point on, all expressions of the form 444@samp{@var{symbol}} or @samp{@var{symbol} + @var{offset}} 445have 32-bit values. For example: 446 447@smallexample 448.set sym32 449dla $4,sym 450lw $4,sym+16 451sw $4,sym+0x8000($4) 452@end smallexample 453 454will cause the assembler to treat @samp{sym}, @code{sym+16} and 455@code{sym+0x8000} as 32-bit values. The handling of non-symbolic 456addresses is not affected. 457 458The directive @code{.set nosym32} ends a @code{.set sym32} block and 459reverts to the normal behavior. It is also possible to change the 460symbol size using the command-line options @option{-msym32} and 461@option{-mno-sym32}. 462 463These options and directives are always accepted, but at present, 464they have no effect for anything other than n64. 465 466@node MIPS ISA 467@section Directives to override the ISA level 468 469@cindex MIPS ISA override 470@kindex @code{.set mips@var{n}} 471@sc{gnu} @code{@value{AS}} supports an additional directive to change 472the @sc{mips} Instruction Set Architecture level on the fly: @code{.set 473mips@var{n}}. @var{n} should be a number from 0 to 5, or 32, 32r2, 64 474or 64r2. 475The values other than 0 make the assembler accept instructions 476for the corresponding @sc{isa} level, from that point on in the 477assembly. @code{.set mips@var{n}} affects not only which instructions 478are permitted, but also how certain macros are expanded. @code{.set 479mips0} restores the @sc{isa} level to its original level: either the 480level you selected with command line options, or the default for your 481configuration. You can use this feature to permit specific @sc{mips3} 482instructions while assembling in 32 bit mode. Use this directive with 483care! 484 485@cindex MIPS CPU override 486@kindex @code{.set arch=@var{cpu}} 487The @code{.set arch=@var{cpu}} directive provides even finer control. 488It changes the effective CPU target and allows the assembler to use 489instructions specific to a particular CPU. All CPUs supported by the 490@samp{-march} command line option are also selectable by this directive. 491The original value is restored by @code{.set arch=default}. 492 493The directive @code{.set mips16} puts the assembler into MIPS 16 mode, 494in which it will assemble instructions for the MIPS 16 processor. Use 495@code{.set nomips16} to return to normal 32 bit mode. 496 497Traditional @sc{mips} assemblers do not support this directive. 498 499@node MIPS autoextend 500@section Directives for extending MIPS 16 bit instructions 501 502@kindex @code{.set autoextend} 503@kindex @code{.set noautoextend} 504By default, MIPS 16 instructions are automatically extended to 32 bits 505when necessary. The directive @code{.set noautoextend} will turn this 506off. When @code{.set noautoextend} is in effect, any 32 bit instruction 507must be explicitly extended with the @code{.e} modifier (e.g., 508@code{li.e $4,1000}). The directive @code{.set autoextend} may be used 509to once again automatically extend instructions when necessary. 510 511This directive is only meaningful when in MIPS 16 mode. Traditional 512@sc{mips} assemblers do not support this directive. 513 514@node MIPS insn 515@section Directive to mark data as an instruction 516 517@kindex @code{.insn} 518The @code{.insn} directive tells @code{@value{AS}} that the following 519data is actually instructions. This makes a difference in MIPS 16 mode: 520when loading the address of a label which precedes instructions, 521@code{@value{AS}} automatically adds 1 to the value, so that jumping to 522the loaded address will do the right thing. 523 524@node MIPS option stack 525@section Directives to save and restore options 526 527@cindex MIPS option stack 528@kindex @code{.set push} 529@kindex @code{.set pop} 530The directives @code{.set push} and @code{.set pop} may be used to save 531and restore the current settings for all the options which are 532controlled by @code{.set}. The @code{.set push} directive saves the 533current settings on a stack. The @code{.set pop} directive pops the 534stack and restores the settings. 535 536These directives can be useful inside an macro which must change an 537option such as the ISA level or instruction reordering but does not want 538to change the state of the code which invoked the macro. 539 540Traditional @sc{mips} assemblers do not support these directives. 541 542@node MIPS ASE instruction generation overrides 543@section Directives to control generation of MIPS ASE instructions 544 545@cindex MIPS MIPS-3D instruction generation override 546@kindex @code{.set mips3d} 547@kindex @code{.set nomips3d} 548The directive @code{.set mips3d} makes the assembler accept instructions 549from the MIPS-3D Application Specific Extension from that point on 550in the assembly. The @code{.set nomips3d} directive prevents MIPS-3D 551instructions from being accepted. 552 553@cindex SmartMIPS instruction generation override 554@kindex @code{.set smartmips} 555@kindex @code{.set nosmartmips} 556The directive @code{.set smartmips} makes the assembler accept 557instructions from the SmartMIPS Application Specific Extension to the 558MIPS32 @sc{isa} from that point on in the assembly. The 559@code{.set nosmartmips} directive prevents SmartMIPS instructions from 560being accepted. 561 562@cindex MIPS MDMX instruction generation override 563@kindex @code{.set mdmx} 564@kindex @code{.set nomdmx} 565The directive @code{.set mdmx} makes the assembler accept instructions 566from the MDMX Application Specific Extension from that point on 567in the assembly. The @code{.set nomdmx} directive prevents MDMX 568instructions from being accepted. 569 570@cindex MIPS DSP Release 1 instruction generation override 571@kindex @code{.set dsp} 572@kindex @code{.set nodsp} 573The directive @code{.set dsp} makes the assembler accept instructions 574from the DSP Release 1 Application Specific Extension from that point 575on in the assembly. The @code{.set nodsp} directive prevents DSP 576Release 1 instructions from being accepted. 577 578@cindex MIPS DSP Release 2 instruction generation override 579@kindex @code{.set dspr2} 580@kindex @code{.set nodspr2} 581The directive @code{.set dspr2} makes the assembler accept instructions 582from the DSP Release 2 Application Specific Extension from that point 583on in the assembly. This dirctive implies @code{.set dsp}. The 584@code{.set nodspr2} directive prevents DSP Release 2 instructions from 585being accepted. 586 587@cindex MIPS MT instruction generation override 588@kindex @code{.set mt} 589@kindex @code{.set nomt} 590The directive @code{.set mt} makes the assembler accept instructions 591from the MT Application Specific Extension from that point on 592in the assembly. The @code{.set nomt} directive prevents MT 593instructions from being accepted. 594 595Traditional @sc{mips} assemblers do not support these directives. 596 597@node MIPS floating-point 598@section Directives to override floating-point options 599 600@cindex Disable floating-point instructions 601@kindex @code{.set softfloat} 602@kindex @code{.set hardfloat} 603The directives @code{.set softfloat} and @code{.set hardfloat} provide 604finer control of disabling and enabling float-point instructions. 605These directives always override the default (that hard-float 606instructions are accepted) or the command-line options 607(@samp{-msoft-float} and @samp{-mhard-float}). 608 609@cindex Disable single-precision floating-point operations 610@kindex @code{.set singlefloat} 611@kindex @code{.set doublefloat} 612The directives @code{.set singlefloat} and @code{.set doublefloat} 613provide finer control of disabling and enabling double-precision 614float-point operations. These directives always override the default 615(that double-precision operations are accepted) or the command-line 616options (@samp{-msingle-float} and @samp{-mdouble-float}). 617 618Traditional @sc{mips} assemblers do not support these directives. 619