2001-06-28 Elena Zannoni <ezannoni@redhat.com>
[deliverable/binutils-gdb.git] / gas / doc / c-mips.texi
CommitLineData
f7e42eb4
NC
1@c Copyright 1991, 1992, 1993, 1994, 1995, 1997, 1999, 2000
2@c Free Software Foundation, Inc.
252b5132
RH
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
84ea6cf2 17different @sc{mips} processors, and MIPS ISA levels I through V, MIPS32,
584da044
NC
18and MIPS64. For information about the @sc{mips} instruction set, see
19@cite{MIPS RISC Architecture}, by Kane and Heindrich (Prentice-Hall).
20For an overview of @sc{mips} assembly conventions, see ``Appendix D:
21Assembly Language Programming'' in the same work.
252b5132
RH
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@end menu
32
33@node MIPS Opts
34@section Assembler options
35
36The @sc{mips} configurations of @sc{gnu} @code{@value{AS}} support these
37special options:
38
39@table @code
40@cindex @code{-G} option (MIPS)
41@item -G @var{num}
42This option sets the largest size of an object that can be referenced
43implicitly with the @code{gp} register. It is only accepted for targets
44that use @sc{ecoff} format. The default value is 8.
45
46@cindex @code{-EB} option (MIPS)
47@cindex @code{-EL} option (MIPS)
48@cindex MIPS big-endian output
49@cindex MIPS little-endian output
50@cindex big-endian output, MIPS
51@cindex little-endian output, MIPS
52@item -EB
53@itemx -EL
54Any @sc{mips} configuration of @code{@value{AS}} can select big-endian or
55little-endian output at run time (unlike the other @sc{gnu} development
56tools, which must be configured for one or the other). Use @samp{-EB}
57to select big-endian output, and @samp{-EL} for little-endian.
58
59@cindex MIPS architecture options
60@item -mips1
61@itemx -mips2
62@itemx -mips3
63@itemx -mips4
84ea6cf2 64@itemx -mips5
e7af610e 65@itemx -mips32
84ea6cf2 66@itemx -mips64
252b5132
RH
67Generate code for a particular MIPS Instruction Set Architecture level.
68@samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors,
69@samp{-mips2} to the @sc{r6000} processor, @samp{-mips3} to the
84ea6cf2 70@sc{r4000} processor, and @samp{-mips4} to the @sc{r8000} and
584da044
NC
71@sc{r10000} processors. @samp{-mips5}, @samp{-mips32}, and
72@samp{-mips64} correspond to generic @sc{MIPS V}, @sc{MIPS32}, and
73@sc{MIPS64} ISA processors, respectively. You can also switch
74instruction sets during the assembly; see @ref{MIPS ISA, Directives to
75override the ISA level}.
252b5132 76
6349b5f4
AH
77@item -mgp32
78Assume that 32-bit general purpose registers are available. This
79affects synthetic instructions such as @code{move}, which will assemble
80to a 32-bit or a 64-bit instruction depending on this flag. On some
28d33191 81MIPS variants there is a 32-bit mode flag; when this flag is set,
6349b5f4
AH
8264-bit instructions generate a trap. Also, some 32-bit OSes only save
83the 32-bit registers on a context switch, so it is essential never to
84use the 64-bit registers.
85
86@item -mgp64
87Assume that 64-bit general purpose registers are available. This is
88provided in the interests of symmetry with -gp32.
89
252b5132
RH
90@item -mips16
91@itemx -no-mips16
92Generate code for the MIPS 16 processor. This is equivalent to putting
93@samp{.set mips16} at the start of the assembly file. @samp{-no-mips16}
94turns off this option.
95
6b76fefe
CM
96@item -mfix7000
97@itemx -no-mfix7000
98Cause nops to be inserted if the read of the destination register
99of an mfhi or mflo instruction occurs in the following two instructions.
100
252b5132
RH
101@item -m4010
102@itemx -no-m4010
103Generate code for the LSI @sc{r4010} chip. This tells the assembler to
104accept the @sc{r4010} specific instructions (@samp{addciu}, @samp{ffc},
105etc.), and to not schedule @samp{nop} instructions around accesses to
106the @samp{HI} and @samp{LO} registers. @samp{-no-m4010} turns off this
107option.
108
109@item -m4650
110@itemx -no-m4650
111Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept
112the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop}
113instructions around accesses to the @samp{HI} and @samp{LO} registers.
114@samp{-no-m4650} turns off this option.
115
116@itemx -m3900
117@itemx -no-m3900
118@itemx -m4100
119@itemx -no-m4100
120For each option @samp{-m@var{nnnn}}, generate code for the MIPS
121@sc{r@var{nnnn}} chip. This tells the assembler to accept instructions
122specific to that chip, and to schedule for that chip's hazards.
123
124@item -mcpu=@var{cpu}
125Generate code for a particular MIPS cpu. It is exactly equivalent to
126@samp{-m@var{cpu}}, except that there are more value of @var{cpu}
127understood. Valid @var{cpu} value are:
128
129@quotation
1302000,
1313000,
1323900,
1334000,
1344010,
1354100,
1364111,
1374300,
1384400,
1394600,
1404650,
1415000,
b946ec34
NC
142rm5200,
143rm5230,
144rm5231,
145rm5261,
146rm5721,
252b5132 1476000,
b946ec34 148rm7000,
252b5132 1498000,
e7af610e 15010000,
c6c98b38
NC
151mips32-4k,
152sb1
252b5132
RH
153@end quotation
154
155
156@cindex @code{-nocpp} ignored (MIPS)
157@item -nocpp
158This option is ignored. It is accepted for command-line compatibility with
159other assemblers, which use it to turn off C style preprocessing. With
160@sc{gnu} @code{@value{AS}}, there is no need for @samp{-nocpp}, because the
161@sc{gnu} assembler itself never runs the C preprocessor.
162
119d663a
NC
163@item --construct-floats
164@itemx --no-construct-floats
165@cindex --construct-floats
166@cindex --no-construct-floats
167The @code{--no-construct-floats} option disables the construction of
168double width floating point constants by loading the two halves of the
169value into the two single width floating point registers that make up
170the double width register. This feature is useful if the processor
171support the FR bit in its status register, and this bit is known (by
172the programmer) to be set. This bit prevents the aliasing of the double
173width register by the single width registers.
174
63bf5651 175By default @code{--construct-floats} is selected, allowing construction
119d663a
NC
176of these floating point constants.
177
252b5132
RH
178@item --trap
179@itemx --no-break
180@c FIXME! (1) reflect these options (next item too) in option summaries;
181@c (2) stop teasing, say _which_ instructions expanded _how_.
182@code{@value{AS}} automatically macro expands certain division and
183multiplication instructions to check for overflow and division by zero. This
184option causes @code{@value{AS}} to generate code to take a trap exception
185rather than a break exception when an error is detected. The trap instructions
186are only supported at Instruction Set Architecture level 2 and higher.
187
188@item --break
189@itemx --no-trap
190Generate code to take a break exception rather than a trap exception when an
191error is detected. This is the default.
63486801
L
192
193@item -n
194When this option is used, @code{@value{AS}} will issue a warning every
195time it generates a nop instruction from a macro.
252b5132
RH
196@end table
197
198@node MIPS Object
199@section MIPS ECOFF object code
200
201@cindex ECOFF sections
202@cindex MIPS ECOFF sections
203Assembling for a @sc{mips} @sc{ecoff} target supports some additional sections
204besides the usual @code{.text}, @code{.data} and @code{.bss}. The
205additional sections are @code{.rdata}, used for read-only data,
206@code{.sdata}, used for small data, and @code{.sbss}, used for small
207common objects.
208
209@cindex small objects, MIPS ECOFF
210@cindex @code{gp} register, MIPS
211When assembling for @sc{ecoff}, the assembler uses the @code{$gp} (@code{$28})
212register to form the address of a ``small object''. Any object in the
213@code{.sdata} or @code{.sbss} sections is considered ``small'' in this sense.
214For external objects, or for objects in the @code{.bss} section, you can use
215the @code{@value{GCC}} @samp{-G} option to control the size of objects addressed via
216@code{$gp}; the default value is 8, meaning that a reference to any object
217eight bytes or smaller uses @code{$gp}. Passing @samp{-G 0} to
218@code{@value{AS}} prevents it from using the @code{$gp} register on the basis
219of object size (but the assembler uses @code{$gp} for objects in @code{.sdata}
220or @code{sbss} in any case). The size of an object in the @code{.bss} section
221is set by the @code{.comm} or @code{.lcomm} directive that defines it. The
222size of an external object may be set with the @code{.extern} directive. For
223example, @samp{.extern sym,4} declares that the object at @code{sym} is 4 bytes
224in length, whie leaving @code{sym} otherwise undefined.
225
226Using small @sc{ecoff} objects requires linker support, and assumes that the
227@code{$gp} register is correctly initialized (normally done automatically by
228the startup code). @sc{mips} @sc{ecoff} assembly code must not modify the
229@code{$gp} register.
230
231@node MIPS Stabs
232@section Directives for debugging information
233
234@cindex MIPS debugging directives
235@sc{mips} @sc{ecoff} @code{@value{AS}} supports several directives used for
236generating debugging information which are not support by traditional @sc{mips}
237assemblers. These are @code{.def}, @code{.endef}, @code{.dim}, @code{.file},
238@code{.scl}, @code{.size}, @code{.tag}, @code{.type}, @code{.val},
239@code{.stabd}, @code{.stabn}, and @code{.stabs}. The debugging information
240generated by the three @code{.stab} directives can only be read by @sc{gdb},
241not by traditional @sc{mips} debuggers (this enhancement is required to fully
242support C++ debugging). These directives are primarily used by compilers, not
243assembly language programmers!
244
245@node MIPS ISA
246@section Directives to override the ISA level
247
248@cindex MIPS ISA override
249@kindex @code{.set mips@var{n}}
250@sc{gnu} @code{@value{AS}} supports an additional directive to change
251the @sc{mips} Instruction Set Architecture level on the fly: @code{.set
84ea6cf2
NC
252mips@var{n}}. @var{n} should be a number from 0 to 5, or 32 or 64.
253The values 1 to 5, 32, and 64 make the assembler accept instructions
584da044
NC
254for the corresponding @sc{isa} level, from that point on in the
255assembly. @code{.set mips@var{n}} affects not only which instructions
256are permitted, but also how certain macros are expanded. @code{.set
257mips0} restores the @sc{isa} level to its original level: either the
258level you selected with command line options, or the default for your
259configuration. You can use this feature to permit specific @sc{r4000}
260instructions while assembling in 32 bit mode. Use this directive with
261care!
252b5132
RH
262
263The directive @samp{.set mips16} puts the assembler into MIPS 16 mode,
264in which it will assemble instructions for the MIPS 16 processor. Use
265@samp{.set nomips16} to return to normal 32 bit mode.
266
267Traditional @sc{mips} assemblers do not support this directive.
268
269@node MIPS autoextend
270@section Directives for extending MIPS 16 bit instructions
271
272@kindex @code{.set autoextend}
273@kindex @code{.set noautoextend}
274By default, MIPS 16 instructions are automatically extended to 32 bits
275when necessary. The directive @samp{.set noautoextend} will turn this
276off. When @samp{.set noautoextend} is in effect, any 32 bit instruction
277must be explicitly extended with the @samp{.e} modifier (e.g.,
278@samp{li.e $4,1000}). The directive @samp{.set autoextend} may be used
279to once again automatically extend instructions when necessary.
280
281This directive is only meaningful when in MIPS 16 mode. Traditional
282@sc{mips} assemblers do not support this directive.
283
284@node MIPS insn
285@section Directive to mark data as an instruction
286
287@kindex @code{.insn}
288The @code{.insn} directive tells @code{@value{AS}} that the following
289data is actually instructions. This makes a difference in MIPS 16 mode:
290when loading the address of a label which precedes instructions,
291@code{@value{AS}} automatically adds 1 to the value, so that jumping to
292the loaded address will do the right thing.
293
294@node MIPS option stack
295@section Directives to save and restore options
296
297@cindex MIPS option stack
298@kindex @code{.set push}
299@kindex @code{.set pop}
300The directives @code{.set push} and @code{.set pop} may be used to save
301and restore the current settings for all the options which are
302controlled by @code{.set}. The @code{.set push} directive saves the
303current settings on a stack. The @code{.set pop} directive pops the
304stack and restores the settings.
305
306These directives can be useful inside an macro which must change an
307option such as the ISA level or instruction reordering but does not want
308to change the state of the code which invoked the macro.
309
310Traditional @sc{mips} assemblers do not support these directives.
This page took 0.089311 seconds and 4 git commands to generate.