[ bfd/ChangeLog ]
[external/binutils.git] / gas / doc / c-mips.texi
1 @c Copyright 1991, 1992, 1993, 1994, 1995, 1997, 1999, 2000
2 @c Free Software Foundation, Inc.
3 @c This is part of the GAS manual.
4 @c For copying conditions, see the file as.texinfo.
5 @ifset GENERIC
6 @page
7 @node MIPS-Dependent
8 @chapter MIPS Dependent Features
9 @end ifset
10 @ifclear GENERIC
11 @node Machine Dependencies
12 @chapter MIPS Dependent Features
13 @end ifclear
14
15 @cindex MIPS processor
16 @sc{gnu} @code{@value{AS}} for @sc{mips} architectures supports several
17 different @sc{mips} processors, and MIPS ISA levels I through V, MIPS32,
18 and MIPS64.  For information about the @sc{mips} instruction set, see
19 @cite{MIPS RISC Architecture}, by Kane and Heindrich (Prentice-Hall).
20 For an overview of @sc{mips} assembly conventions, see ``Appendix D:
21 Assembly Language Programming'' in the same work.
22
23 @menu
24 * MIPS Opts::           Assembler options
25 * MIPS Object::         ECOFF object code
26 * MIPS Stabs::          Directives for debugging information
27 * MIPS ISA::            Directives to override the ISA level
28 * MIPS autoextend::     Directives for extending MIPS 16 bit instructions
29 * MIPS insn::           Directive to mark data as an instruction
30 * MIPS option stack::   Directives to save and restore options
31 * MIPS ASE instruction generation overrides:: Directives to control
32                         generation of MIPS ASE instructions
33 @end menu
34
35 @node MIPS Opts
36 @section Assembler options
37
38 The @sc{mips} configurations of @sc{gnu} @code{@value{AS}} support these
39 special options:
40
41 @table @code
42 @cindex @code{-G} option (MIPS)
43 @item -G @var{num}
44 This option sets the largest size of an object that can be referenced
45 implicitly with the @code{gp} register.  It is only accepted for targets
46 that use @sc{ecoff} format.  The default value is 8.
47
48 @cindex @code{-EB} option (MIPS)
49 @cindex @code{-EL} option (MIPS)
50 @cindex MIPS big-endian output
51 @cindex MIPS little-endian output
52 @cindex big-endian output, MIPS
53 @cindex little-endian output, MIPS
54 @item -EB
55 @itemx -EL
56 Any @sc{mips} configuration of @code{@value{AS}} can select big-endian or
57 little-endian output at run time (unlike the other @sc{gnu} development
58 tools, which must be configured for one or the other).  Use @samp{-EB}
59 to select big-endian output, and @samp{-EL} for little-endian.
60
61 @cindex MIPS architecture options
62 @item -mips1
63 @itemx -mips2
64 @itemx -mips3
65 @itemx -mips4
66 @itemx -mips5
67 @itemx -mips32
68 @itemx -mips32r2
69 @itemx -mips64
70 Generate code for a particular MIPS Instruction Set Architecture level.
71 @samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
72 @samp{-mips2} to the @sc{r6000} processor, @samp{-mips3} to the
73 @sc{r4000} processor, and @samp{-mips4} to the @sc{r8000} and
74 @sc{r10000} processors.  @samp{-mips5}, @samp{-mips32}, @samp{-mips32r2}, and
75 @samp{-mips64} correspond to generic @sc{MIPS V}, @sc{MIPS32},
76 @sc{MIPS32 Release 2}, and
77 @sc{MIPS64} ISA processors, respectively.  You can also switch
78 instruction sets during the assembly; see @ref{MIPS ISA, Directives to
79 override the ISA level}.
80
81 @item -mgp32
82 @itemx -mfp32
83 Some macros have different expansions for 32-bit and 64-bit registers.
84 The register sizes are normally inferred from the ISA and ABI, but these
85 flags force a certain group of registers to be treated as 32 bits wide at
86 all times.  @samp{-mgp32} controls the size of general-purpose registers
87 and @samp{-mfp32} controls the size of floating-point registers.
88
89 On some MIPS variants there is a 32-bit mode flag; when this flag is
90 set, 64-bit instructions generate a trap.  Also, some 32-bit OSes only
91 save the 32-bit registers on a context switch, so it is essential never
92 to use the 64-bit registers.
93
94 @item -mgp64
95 Assume that 64-bit general purpose registers are available.  This is
96 provided in the interests of symmetry with -gp32.
97
98 @item -mips16
99 @itemx -no-mips16
100 Generate code for the MIPS 16 processor.  This is equivalent to putting
101 @samp{.set mips16} at the start of the assembly file.  @samp{-no-mips16}
102 turns off this option.
103
104 @item -mips3d
105 @itemx -no-mips3d
106 Generate code for the MIPS-3D Application Specific Extension.
107 This tells the assembler to accept MIPS-3D instructions.
108 @samp{-no-mips3d} turns off this option.
109
110 @item -mdmx
111 @itemx -no-mdmx
112 Generate code for the MDMX Application Specific Extension.
113 This tells the assembler to accept MDMX instructions.
114 @samp{-no-mdmx} turns off this option.
115
116 @item -mfix7000
117 @itemx -mno-fix7000
118 Cause nops to be inserted if the read of the destination register
119 of an mfhi or mflo instruction occurs in the following two instructions.
120
121 @item -mfix-vr4122-bugs
122 @itemx -no-mfix-vr4122-bugs
123 Insert @samp{nop} instructions to avoid errors in certain versions of
124 the vr4122 core.  This option is intended to be used on GCC-generated
125 code: it is not designed to catch errors in hand-written assembler code.
126
127 @item -m4010
128 @itemx -no-m4010
129 Generate code for the LSI @sc{r4010} chip.  This tells the assembler to
130 accept the @sc{r4010} specific instructions (@samp{addciu}, @samp{ffc},
131 etc.), and to not schedule @samp{nop} instructions around accesses to
132 the @samp{HI} and @samp{LO} registers.  @samp{-no-m4010} turns off this
133 option.
134
135 @item -m4650
136 @itemx -no-m4650
137 Generate code for the MIPS @sc{r4650} chip.  This tells the assembler to accept
138 the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
139 instructions around accesses to the @samp{HI} and @samp{LO} registers.
140 @samp{-no-m4650} turns off this option.
141
142 @itemx -m3900
143 @itemx -no-m3900
144 @itemx -m4100
145 @itemx -no-m4100
146 For each option @samp{-m@var{nnnn}}, generate code for the MIPS
147 @sc{r@var{nnnn}} chip.  This tells the assembler to accept instructions
148 specific to that chip, and to schedule for that chip's hazards.
149
150 @item -march=@var{cpu}
151 Generate code for a particular MIPS cpu.  It is exactly equivalent to
152 @samp{-m@var{cpu}}, except that there are more value of @var{cpu}
153 understood.  Valid @var{cpu} value are:
154
155 @quotation
156 2000,
157 3000,
158 3900,
159 4000,
160 4010,
161 4100,
162 4111,
163 vr4120,
164 vr4130,
165 vr4181,
166 4300,
167 4400,
168 4600,
169 4650,
170 5000,
171 rm5200,
172 rm5230,
173 rm5231,
174 rm5261,
175 rm5721,
176 vr5400,
177 vr5500,
178 6000,
179 rm7000,
180 8000,
181 10000,
182 12000,
183 mips32-4k,
184 sb1
185 @end quotation
186
187 @item -mtune=@var{cpu}
188 Schedule and tune for a particular MIPS cpu.  Valid @var{cpu} values are
189 identical to @samp{-march=@var{cpu}}.
190
191 @item -mabi=@var{abi}
192 Record which ABI the source code uses.  The recognized arguments
193 are: @samp{32}, @samp{n32}, @samp{o64}, @samp{64} and @samp{eabi}.
194
195 @cindex @code{-nocpp} ignored (MIPS)
196 @item -nocpp
197 This option is ignored.  It is accepted for command-line compatibility with
198 other assemblers, which use it to turn off C style preprocessing.  With
199 @sc{gnu} @code{@value{AS}}, there is no need for @samp{-nocpp}, because the
200 @sc{gnu} assembler itself never runs the C preprocessor.
201
202 @item --construct-floats
203 @itemx --no-construct-floats
204 @cindex --construct-floats
205 @cindex --no-construct-floats
206 The @code{--no-construct-floats} option disables the construction of
207 double width floating point constants by loading the two halves of the
208 value into the two single width floating point registers that make up
209 the double width register.  This feature is useful if the processor
210 support the FR bit in its status  register, and this bit is known (by
211 the programmer) to be set.  This bit prevents the aliasing of the double
212 width register by the single width registers.
213
214 By default @code{--construct-floats} is selected, allowing construction
215 of these floating point constants.
216
217 @item --trap
218 @itemx --no-break
219 @c FIXME!  (1) reflect these options (next item too) in option summaries;
220 @c         (2) stop teasing, say _which_ instructions expanded _how_.
221 @code{@value{AS}} automatically macro expands certain division and
222 multiplication instructions to check for overflow and division by zero.  This
223 option causes @code{@value{AS}} to generate code to take a trap exception
224 rather than a break exception when an error is detected.  The trap instructions
225 are only supported at Instruction Set Architecture level 2 and higher.
226
227 @item --break
228 @itemx --no-trap
229 Generate code to take a break exception rather than a trap exception when an
230 error is detected.  This is the default.
231
232 @item -n
233 When this option is used, @code{@value{AS}} will issue a warning every
234 time it generates a nop instruction from a macro.
235 @end table
236
237 @node MIPS Object
238 @section MIPS ECOFF object code
239
240 @cindex ECOFF sections
241 @cindex MIPS ECOFF sections
242 Assembling for a @sc{mips} @sc{ecoff} target supports some additional sections
243 besides the usual @code{.text}, @code{.data} and @code{.bss}.  The
244 additional sections are @code{.rdata}, used for read-only data,
245 @code{.sdata}, used for small data, and @code{.sbss}, used for small
246 common objects.
247
248 @cindex small objects, MIPS ECOFF
249 @cindex @code{gp} register, MIPS
250 When assembling for @sc{ecoff}, the assembler uses the @code{$gp} (@code{$28})
251 register to form the address of a ``small object''.  Any object in the
252 @code{.sdata} or @code{.sbss} sections is considered ``small'' in this sense.
253 For external objects, or for objects in the @code{.bss} section, you can use
254 the @code{@value{GCC}} @samp{-G} option to control the size of objects addressed via
255 @code{$gp}; the default value is 8, meaning that a reference to any object
256 eight bytes or smaller uses @code{$gp}.  Passing @samp{-G 0} to
257 @code{@value{AS}} prevents it from using the @code{$gp} register on the basis
258 of object size (but the assembler uses @code{$gp} for objects in @code{.sdata}
259 or @code{sbss} in any case).  The size of an object in the @code{.bss} section
260 is set by the @code{.comm} or @code{.lcomm} directive that defines it.  The
261 size of an external object may be set with the @code{.extern} directive.  For
262 example, @samp{.extern sym,4} declares that the object at @code{sym} is 4 bytes
263 in length, whie leaving @code{sym} otherwise undefined.
264
265 Using small @sc{ecoff} objects requires linker support, and assumes that the
266 @code{$gp} register is correctly initialized (normally done automatically by
267 the startup code).  @sc{mips} @sc{ecoff} assembly code must not modify the
268 @code{$gp} register.
269
270 @node MIPS Stabs
271 @section Directives for debugging information
272
273 @cindex MIPS debugging directives
274 @sc{mips} @sc{ecoff} @code{@value{AS}} supports several directives used for
275 generating debugging information which are not support by traditional @sc{mips}
276 assemblers.  These are @code{.def}, @code{.endef}, @code{.dim}, @code{.file},
277 @code{.scl}, @code{.size}, @code{.tag}, @code{.type}, @code{.val},
278 @code{.stabd}, @code{.stabn}, and @code{.stabs}.  The debugging information
279 generated by the three @code{.stab} directives can only be read by @sc{gdb},
280 not by traditional @sc{mips} debuggers (this enhancement is required to fully
281 support C++ debugging).  These directives are primarily used by compilers, not
282 assembly language programmers!
283
284 @node MIPS ISA
285 @section Directives to override the ISA level
286
287 @cindex MIPS ISA override
288 @kindex @code{.set mips@var{n}}
289 @sc{gnu} @code{@value{AS}} supports an additional directive to change
290 the @sc{mips} Instruction Set Architecture level on the fly: @code{.set
291 mips@var{n}}.  @var{n} should be a number from 0 to 5, or 32 or 64.
292 The values 1 to 5, 32, and 64 make the assembler accept instructions
293 for the corresponding @sc{isa} level, from that point on in the
294 assembly.  @code{.set mips@var{n}} affects not only which instructions
295 are permitted, but also how certain macros are expanded.  @code{.set
296 mips0} restores the @sc{isa} level to its original level: either the
297 level you selected with command line options, or the default for your
298 configuration.  You can use this feature to permit specific @sc{r4000}
299 instructions while assembling in 32 bit mode.  Use this directive with
300 care!
301
302 The directive @samp{.set mips16} puts the assembler into MIPS 16 mode,
303 in which it will assemble instructions for the MIPS 16 processor.  Use
304 @samp{.set nomips16} to return to normal 32 bit mode.
305
306 Traditional @sc{mips} assemblers do not support this directive.
307
308 @node MIPS autoextend
309 @section Directives for extending MIPS 16 bit instructions
310
311 @kindex @code{.set autoextend}
312 @kindex @code{.set noautoextend}
313 By default, MIPS 16 instructions are automatically extended to 32 bits
314 when necessary.  The directive @samp{.set noautoextend} will turn this
315 off.  When @samp{.set noautoextend} is in effect, any 32 bit instruction
316 must be explicitly extended with the @samp{.e} modifier (e.g.,
317 @samp{li.e $4,1000}).  The directive @samp{.set autoextend} may be used
318 to once again automatically extend instructions when necessary.
319
320 This directive is only meaningful when in MIPS 16 mode.  Traditional
321 @sc{mips} assemblers do not support this directive.
322
323 @node MIPS insn
324 @section Directive to mark data as an instruction
325
326 @kindex @code{.insn}
327 The @code{.insn} directive tells @code{@value{AS}} that the following
328 data is actually instructions.  This makes a difference in MIPS 16 mode:
329 when loading the address of a label which precedes instructions,
330 @code{@value{AS}} automatically adds 1 to the value, so that jumping to
331 the loaded address will do the right thing.
332
333 @node MIPS option stack
334 @section Directives to save and restore options
335
336 @cindex MIPS option stack
337 @kindex @code{.set push}
338 @kindex @code{.set pop}
339 The directives @code{.set push} and @code{.set pop} may be used to save
340 and restore the current settings for all the options which are
341 controlled by @code{.set}.  The @code{.set push} directive saves the
342 current settings on a stack.  The @code{.set pop} directive pops the
343 stack and restores the settings.
344
345 These directives can be useful inside an macro which must change an
346 option such as the ISA level or instruction reordering but does not want
347 to change the state of the code which invoked the macro.
348
349 Traditional @sc{mips} assemblers do not support these directives.
350
351 @node MIPS ASE instruction generation overrides
352 @section Directives to control generation of MIPS ASE instructions
353
354 @cindex MIPS MIPS-3D instruction generation override
355 @kindex @code{.set mips3d}
356 @kindex @code{.set nomips3d}
357 The directive @code{.set mips3d} makes the assembler accept instructions
358 from the MIPS-3D Application Specific Extension from that point on
359 in the assembly.  The @code{.set nomips3d} directive prevents MIPS-3D
360 instructions from being accepted.
361
362 @cindex MIPS MDMX instruction generation override
363 @kindex @code{.set mdmx}
364 @kindex @code{.set nomdmx}
365 The directive @code{.set mdmx} makes the assembler accept instructions
366 from the MDMX Application Specific Extension from that point on
367 in the assembly.  The @code{.set nomdmx} directive prevents MDMX
368 instructions from being accepted.
369
370 Traditional @sc{mips} assemblers do not support these directives.