* config/tc-mips.c (append_insn): Correctly handle mips16 case
[binutils.git] / gas / doc / c-mips.texi
blob97469fe2449a199a0adee1caedb8433ef2bfc5b8
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
16 @cindex MIPS processor
17 @sc{gnu} @code{@value{AS}} for @sc{mips} architectures supports several
18 different @sc{mips} processors, and MIPS ISA levels I through V, MIPS32,
19 and MIPS64.  For information about the @sc{mips} instruction set, see
20 @cite{MIPS RISC Architecture}, by Kane and Heindrich (Prentice-Hall).
21 For an overview of @sc{mips} assembly conventions, see ``Appendix D:
22 Assembly Language Programming'' in the same work.
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 @end menu
37 @node MIPS Opts
38 @section Assembler options
40 The @sc{mips} configurations of @sc{gnu} @code{@value{AS}} support these
41 special options:
43 @table @code
44 @cindex @code{-G} option (MIPS)
45 @item -G @var{num}
46 This option sets the largest size of an object that can be referenced
47 implicitly with the @code{gp} register.  It is only accepted for targets
48 that use @sc{ecoff} format.  The default value is 8.
50 @cindex @code{-EB} option (MIPS)
51 @cindex @code{-EL} option (MIPS)
52 @cindex MIPS big-endian output
53 @cindex MIPS little-endian output
54 @cindex big-endian output, MIPS
55 @cindex little-endian output, MIPS
56 @item -EB
57 @itemx -EL
58 Any @sc{mips} configuration of @code{@value{AS}} can select big-endian or
59 little-endian output at run time (unlike the other @sc{gnu} development
60 tools, which must be configured for one or the other).  Use @samp{-EB}
61 to select big-endian output, and @samp{-EL} for little-endian.
63 @cindex MIPS architecture options
64 @item -mips1
65 @itemx -mips2
66 @itemx -mips3
67 @itemx -mips4
68 @itemx -mips5
69 @itemx -mips32
70 @itemx -mips32r2
71 @itemx -mips64
72 @itemx -mips64r2
73 Generate code for a particular MIPS Instruction Set Architecture level.
74 @samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
75 @samp{-mips2} to the @sc{r6000} processor, @samp{-mips3} to the
76 @sc{r4000} processor, and @samp{-mips4} to the @sc{r8000} and
77 @sc{r10000} processors.  @samp{-mips5}, @samp{-mips32}, @samp{-mips32r2},
78 @samp{-mips64}, and @samp{-mips64r2}
79 correspond to generic
80 @sc{MIPS V}, @sc{MIPS32}, @sc{MIPS32 Release 2}, @sc{MIPS64},
81 and @sc{MIPS64 Release 2}
82 ISA processors, respectively.  You can also switch
83 instruction sets during the assembly; see @ref{MIPS ISA, Directives to
84 override the ISA level}.
86 @item -mgp32
87 @itemx -mfp32
88 Some macros have different expansions for 32-bit and 64-bit registers.
89 The register sizes are normally inferred from the ISA and ABI, but these
90 flags force a certain group of registers to be treated as 32 bits wide at
91 all times.  @samp{-mgp32} controls the size of general-purpose registers
92 and @samp{-mfp32} controls the size of floating-point registers.
94 On some MIPS variants there is a 32-bit mode flag; when this flag is
95 set, 64-bit instructions generate a trap.  Also, some 32-bit OSes only
96 save the 32-bit registers on a context switch, so it is essential never
97 to use the 64-bit registers.
99 @item -mgp64
100 Assume that 64-bit general purpose registers are available.  This is
101 provided in the interests of symmetry with -gp32.
103 @item -mips16
104 @itemx -no-mips16
105 Generate code for the MIPS 16 processor.  This is equivalent to putting
106 @samp{.set mips16} at the start of the assembly file.  @samp{-no-mips16}
107 turns off this option.
109 @item -mips3d
110 @itemx -no-mips3d
111 Generate code for the MIPS-3D Application Specific Extension.
112 This tells the assembler to accept MIPS-3D instructions.
113 @samp{-no-mips3d} turns off this option.
115 @item -mdmx
116 @itemx -no-mdmx
117 Generate code for the MDMX Application Specific Extension.
118 This tells the assembler to accept MDMX instructions.
119 @samp{-no-mdmx} turns off this option.
121 @item -mfix7000
122 @itemx -mno-fix7000
123 Cause nops to be inserted if the read of the destination register
124 of an mfhi or mflo instruction occurs in the following two instructions.
126 @item -mfix-vr4120
127 @itemx -no-mfix-vr4120
128 Insert nops to work around certain VR4120 errata.  This option is
129 intended to be used on GCC-generated code: it is not designed to catch
130 all problems in hand-written assembler code.
132 @item -mfix-vr4130
133 @itemx -no-mfix-vr4130
134 Insert nops to work around the VR4130 @samp{mflo}/@samp{mfhi} errata.
136 @item -m4010
137 @itemx -no-m4010
138 Generate code for the LSI @sc{r4010} chip.  This tells the assembler to
139 accept the @sc{r4010} specific instructions (@samp{addciu}, @samp{ffc},
140 etc.), and to not schedule @samp{nop} instructions around accesses to
141 the @samp{HI} and @samp{LO} registers.  @samp{-no-m4010} turns off this
142 option.
144 @item -m4650
145 @itemx -no-m4650
146 Generate code for the MIPS @sc{r4650} chip.  This tells the assembler to accept
147 the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
148 instructions around accesses to the @samp{HI} and @samp{LO} registers.
149 @samp{-no-m4650} turns off this option.
151 @itemx -m3900
152 @itemx -no-m3900
153 @itemx -m4100
154 @itemx -no-m4100
155 For each option @samp{-m@var{nnnn}}, generate code for the MIPS
156 @sc{r@var{nnnn}} chip.  This tells the assembler to accept instructions
157 specific to that chip, and to schedule for that chip's hazards.
159 @item -march=@var{cpu}
160 Generate code for a particular MIPS cpu.  It is exactly equivalent to
161 @samp{-m@var{cpu}}, except that there are more value of @var{cpu}
162 understood.  Valid @var{cpu} value are:
164 @quotation
165 2000,
166 3000,
167 3900,
168 4000,
169 4010,
170 4100,
171 4111,
172 vr4120,
173 vr4130,
174 vr4181,
175 4300,
176 4400,
177 4600,
178 4650,
179 5000,
180 rm5200,
181 rm5230,
182 rm5231,
183 rm5261,
184 rm5721,
185 vr5400,
186 vr5500,
187 6000,
188 rm7000,
189 8000,
190 rm9000,
191 10000,
192 12000,
193 mips32-4k,
195 @end quotation
197 @item -mtune=@var{cpu}
198 Schedule and tune for a particular MIPS cpu.  Valid @var{cpu} values are
199 identical to @samp{-march=@var{cpu}}.
201 @item -mabi=@var{abi}
202 Record which ABI the source code uses.  The recognized arguments
203 are: @samp{32}, @samp{n32}, @samp{o64}, @samp{64} and @samp{eabi}.
205 @item -msym32
206 @itemx -mno-sym32
207 @cindex -msym32
208 @cindex -mno-sym32
209 Equivalent to adding @code{.set sym32} or @code{.set nosym32} to
210 the beginning of the assembler input.  @xref{MIPS symbol sizes}.
212 @cindex @code{-nocpp} ignored (MIPS)
213 @item -nocpp
214 This option is ignored.  It is accepted for command-line compatibility with
215 other assemblers, which use it to turn off C style preprocessing.  With
216 @sc{gnu} @code{@value{AS}}, there is no need for @samp{-nocpp}, because the
217 @sc{gnu} assembler itself never runs the C preprocessor.
219 @item --construct-floats
220 @itemx --no-construct-floats
221 @cindex --construct-floats
222 @cindex --no-construct-floats
223 The @code{--no-construct-floats} option disables the construction of
224 double width floating point constants by loading the two halves of the
225 value into the two single width floating point registers that make up
226 the double width register.  This feature is useful if the processor
227 support the FR bit in its status  register, and this bit is known (by
228 the programmer) to be set.  This bit prevents the aliasing of the double
229 width register by the single width registers.
231 By default @code{--construct-floats} is selected, allowing construction
232 of these floating point constants.
234 @item --trap
235 @itemx --no-break
236 @c FIXME!  (1) reflect these options (next item too) in option summaries;
237 @c         (2) stop teasing, say _which_ instructions expanded _how_.
238 @code{@value{AS}} automatically macro expands certain division and
239 multiplication instructions to check for overflow and division by zero.  This
240 option causes @code{@value{AS}} to generate code to take a trap exception
241 rather than a break exception when an error is detected.  The trap instructions
242 are only supported at Instruction Set Architecture level 2 and higher.
244 @item --break
245 @itemx --no-trap
246 Generate code to take a break exception rather than a trap exception when an
247 error is detected.  This is the default.
249 @item -mpdr
250 @itemx -mno-pdr
251 Control generation of @code{.pdr} sections.  Off by default on IRIX, on
252 elsewhere.
254 @item -mshared
255 @itemx -mno-shared
256 When generating code using the Unix calling conventions (selected by
257 @samp{-KPIC} or @samp{-mcall_shared}), gas will normally generate code
258 which can go into a shared library.  The @samp{-mno-shared} option
259 tells gas to generate code which uses the calling convention, but can
260 not go into a shared library.  The resulting code is slightly more
261 efficient.  This option only affects the handling of the
262 @samp{.cpload} and @samp{.cpsetup} pseudo-ops.
263 @end table
265 @node MIPS Object
266 @section MIPS ECOFF object code
268 @cindex ECOFF sections
269 @cindex MIPS ECOFF sections
270 Assembling for a @sc{mips} @sc{ecoff} target supports some additional sections
271 besides the usual @code{.text}, @code{.data} and @code{.bss}.  The
272 additional sections are @code{.rdata}, used for read-only data,
273 @code{.sdata}, used for small data, and @code{.sbss}, used for small
274 common objects.
276 @cindex small objects, MIPS ECOFF
277 @cindex @code{gp} register, MIPS
278 When assembling for @sc{ecoff}, the assembler uses the @code{$gp} (@code{$28})
279 register to form the address of a ``small object''.  Any object in the
280 @code{.sdata} or @code{.sbss} sections is considered ``small'' in this sense.
281 For external objects, or for objects in the @code{.bss} section, you can use
282 the @code{@value{GCC}} @samp{-G} option to control the size of objects addressed via
283 @code{$gp}; the default value is 8, meaning that a reference to any object
284 eight bytes or smaller uses @code{$gp}.  Passing @samp{-G 0} to
285 @code{@value{AS}} prevents it from using the @code{$gp} register on the basis
286 of object size (but the assembler uses @code{$gp} for objects in @code{.sdata}
287 or @code{sbss} in any case).  The size of an object in the @code{.bss} section
288 is set by the @code{.comm} or @code{.lcomm} directive that defines it.  The
289 size of an external object may be set with the @code{.extern} directive.  For
290 example, @samp{.extern sym,4} declares that the object at @code{sym} is 4 bytes
291 in length, whie leaving @code{sym} otherwise undefined.
293 Using small @sc{ecoff} objects requires linker support, and assumes that the
294 @code{$gp} register is correctly initialized (normally done automatically by
295 the startup code).  @sc{mips} @sc{ecoff} assembly code must not modify the
296 @code{$gp} register.
298 @node MIPS Stabs
299 @section Directives for debugging information
301 @cindex MIPS debugging directives
302 @sc{mips} @sc{ecoff} @code{@value{AS}} supports several directives used for
303 generating debugging information which are not support by traditional @sc{mips}
304 assemblers.  These are @code{.def}, @code{.endef}, @code{.dim}, @code{.file},
305 @code{.scl}, @code{.size}, @code{.tag}, @code{.type}, @code{.val},
306 @code{.stabd}, @code{.stabn}, and @code{.stabs}.  The debugging information
307 generated by the three @code{.stab} directives can only be read by @sc{gdb},
308 not by traditional @sc{mips} debuggers (this enhancement is required to fully
309 support C++ debugging).  These directives are primarily used by compilers, not
310 assembly language programmers!
312 @node MIPS symbol sizes
313 @section Directives to override the size of symbols
315 @cindex @code{.set sym32}
316 @cindex @code{.set nosym32}
317 The n64 ABI allows symbols to have any 64-bit value.  Although this
318 provides a great deal of flexibility, it means that some macros have
319 much longer expansions than their 32-bit counterparts.  For example,
320 the non-PIC expansion of @samp{dla $4,sym} is usually:
322 @smallexample
323 lui     $4,%highest(sym)
324 lui     $1,%hi(sym)
325 daddiu  $4,$4,%higher(sym)
326 daddiu  $1,$1,%lo(sym)
327 dsll32  $4,$4,0
328 daddu   $4,$4,$1
329 @end smallexample
331 whereas the 32-bit expansion is simply:
333 @smallexample
334 lui     $4,%hi(sym)
335 daddiu  $4,$4,%lo(sym)
336 @end smallexample
338 n64 code is sometimes constructed in such a way that all symbolic
339 constants are known to have 32-bit values, and in such cases, it's
340 preferable to use the 32-bit expansion instead of the 64-bit
341 expansion.
343 You can use the @code{.set sym32} directive to tell the assembler
344 that, from this point on, all expressions of the form
345 @samp{@var{symbol}} or @samp{@var{symbol} + @var{offset}}
346 have 32-bit values.  For example:
348 @smallexample
349 .set sym32
350 dla     $4,sym
351 lw      $4,sym+16
352 sw      $4,sym+0x8000($4)
353 @end smallexample
355 will cause the assembler to treat @samp{sym}, @code{sym+16} and
356 @code{sym+0x8000} as 32-bit values.  The handling of non-symbolic
357 addresses is not affected.
359 The directive @code{.set nosym32} ends a @code{.set sym32} block and
360 reverts to the normal behavior.  It is also possible to change the
361 symbol size using the command-line options @option{-msym32} and
362 @option{-mno-sym32}.
364 These options and directives are always accepted, but at present,
365 they have no effect for anything other than n64.
367 @node MIPS ISA
368 @section Directives to override the ISA level
370 @cindex MIPS ISA override
371 @kindex @code{.set mips@var{n}}
372 @sc{gnu} @code{@value{AS}} supports an additional directive to change
373 the @sc{mips} Instruction Set Architecture level on the fly: @code{.set
374 mips@var{n}}.  @var{n} should be a number from 0 to 5, or 32, 32r2, 64
375 or 64r2.
376 The values other than 0 make the assembler accept instructions
377 for the corresponding @sc{isa} level, from that point on in the
378 assembly.  @code{.set mips@var{n}} affects not only which instructions
379 are permitted, but also how certain macros are expanded.  @code{.set
380 mips0} restores the @sc{isa} level to its original level: either the
381 level you selected with command line options, or the default for your
382 configuration.  You can use this feature to permit specific @sc{r4000}
383 instructions while assembling in 32 bit mode.  Use this directive with
384 care!
386 The directive @samp{.set mips16} puts the assembler into MIPS 16 mode,
387 in which it will assemble instructions for the MIPS 16 processor.  Use
388 @samp{.set nomips16} to return to normal 32 bit mode.
390 Traditional @sc{mips} assemblers do not support this directive.
392 @node MIPS autoextend
393 @section Directives for extending MIPS 16 bit instructions
395 @kindex @code{.set autoextend}
396 @kindex @code{.set noautoextend}
397 By default, MIPS 16 instructions are automatically extended to 32 bits
398 when necessary.  The directive @samp{.set noautoextend} will turn this
399 off.  When @samp{.set noautoextend} is in effect, any 32 bit instruction
400 must be explicitly extended with the @samp{.e} modifier (e.g.,
401 @samp{li.e $4,1000}).  The directive @samp{.set autoextend} may be used
402 to once again automatically extend instructions when necessary.
404 This directive is only meaningful when in MIPS 16 mode.  Traditional
405 @sc{mips} assemblers do not support this directive.
407 @node MIPS insn
408 @section Directive to mark data as an instruction
410 @kindex @code{.insn}
411 The @code{.insn} directive tells @code{@value{AS}} that the following
412 data is actually instructions.  This makes a difference in MIPS 16 mode:
413 when loading the address of a label which precedes instructions,
414 @code{@value{AS}} automatically adds 1 to the value, so that jumping to
415 the loaded address will do the right thing.
417 @node MIPS option stack
418 @section Directives to save and restore options
420 @cindex MIPS option stack
421 @kindex @code{.set push}
422 @kindex @code{.set pop}
423 The directives @code{.set push} and @code{.set pop} may be used to save
424 and restore the current settings for all the options which are
425 controlled by @code{.set}.  The @code{.set push} directive saves the
426 current settings on a stack.  The @code{.set pop} directive pops the
427 stack and restores the settings.
429 These directives can be useful inside an macro which must change an
430 option such as the ISA level or instruction reordering but does not want
431 to change the state of the code which invoked the macro.
433 Traditional @sc{mips} assemblers do not support these directives.
435 @node MIPS ASE instruction generation overrides
436 @section Directives to control generation of MIPS ASE instructions
438 @cindex MIPS MIPS-3D instruction generation override
439 @kindex @code{.set mips3d}
440 @kindex @code{.set nomips3d}
441 The directive @code{.set mips3d} makes the assembler accept instructions
442 from the MIPS-3D Application Specific Extension from that point on
443 in the assembly.  The @code{.set nomips3d} directive prevents MIPS-3D
444 instructions from being accepted.
446 @cindex MIPS MDMX instruction generation override
447 @kindex @code{.set mdmx}
448 @kindex @code{.set nomdmx}
449 The directive @code{.set mdmx} makes the assembler accept instructions
450 from the MDMX Application Specific Extension from that point on
451 in the assembly.  The @code{.set nomdmx} directive prevents MDMX
452 instructions from being accepted.
454 Traditional @sc{mips} assemblers do not support these directives.