* doc/c-i386.texi (i386-Mnemonics): Fix typo.
[binutils.git] / gas / doc / c-m32r.texi
blob52a73c38700da60e68316aca38bece1eb2f55bf2
1 @c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000,
2 @c 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 M32R-Dependent
9 @chapter M32R Dependent Features
10 @end ifset
11 @ifclear GENERIC
12 @node Machine Dependencies
13 @chapter M32R Dependent Features
14 @end ifclear
16 @cindex M32R support
17 @menu
18 * M32R-Opts::                   M32R Options
19 * M32R-Directives::             M32R Directives
20 * M32R-Warnings::               M32R Warnings
21 @end menu
23 @node M32R-Opts
24 @section M32R Options
26 @cindex options, M32R
27 @cindex M32R options
29 The Renease M32R version of @code{@value{AS}} has a few machine
30 dependent options:
32 @table @code
34 @item -m32rx
35 @cindex @samp{-m32rx} option, M32RX
36 @cindex architecture options, M32RX
37 @cindex M32R architecture options
38 @code{@value{AS}} can assemble code for several different members of the
39 Renesas M32R family.  Normally the default is to assemble code for
40 the M32R microprocessor.  This option may be used to change the default
41 to the M32RX microprocessor, which adds some more instructions to the
42 basic M32R instruction set, and some additional parameters to some of
43 the original instructions.
45 @item -m32r2
46 @cindex @samp{-m32rx} option, M32R2
47 @cindex architecture options, M32R2
48 @cindex M32R architecture options
49 This option changes the target processor to the the M32R2
50 microprocessor.
52 @item -m32r
53 @cindex @samp{-m32r} option, M32R
54 @cindex architecture options, M32R
55 @cindex M32R architecture options
56 This option can be used to restore the assembler's default behaviour of
57 assembling for the M32R microprocessor.  This can be useful if the
58 default has been changed by a previous command line option.
60 @item -little
61 @cindex @code{-little} option, M32R
62 This option tells the assembler to produce little-endian code and
63 data.  The default is dependent upon how the toolchain was
64 configured.
66 @item -EL
67 @cindex @code{-EL} option, M32R
68 This is a synonum for @emph{-little}.
70 @item -big
71 @cindex @code{-big} option, M32R
72 This option tells the assembler to produce big-endian code and
73 data.
75 @item -EB
76 @cindex @code{-EB} option, M32R
77 This is a synonum for @emph{-big}.
79 @item -KPIC
80 @cindex @code{-KPIC} option, M32R
81 @cindex PIC code generation for M32R
82 This option specifies that the output of the assembler should be
83 marked as position-independent code (PIC).
85 @item -parallel
86 @cindex @code{-parallel} option, M32RX
87 This option tells the assembler to attempts to combine two sequential
88 instructions into a single, parallel instruction, where it is legal to
89 do so.
91 @item -no-parallel
92 @cindex @code{-no-parallel} option, M32RX
93 This option disables a previously enabled @emph{-parallel} option.
95 @item -no-bitinst
96 @cindex @samp{-no-bitinst}, M32R2
97 This option disables the support for the extended bit-field
98 instructions provided by the M32R2.  If this support needs to be
99 re-enabled the @emph{-bitinst} switch can be used to restore it.
101 @item -O
102 @cindex @code{-O} option, M32RX
103 This option tells the assembler to attempt to optimize the
104 instructions that it produces.  This includes filling delay slots and
105 converting sequential instructions into parallel ones.  This option
106 implies @emph{-parallel}.
108 @item -warn-explicit-parallel-conflicts
109 @cindex @samp{-warn-explicit-parallel-conflicts} option, M32RX
110 Instructs @code{@value{AS}} to produce warning messages when
111 questionable parallel instructions are encountered.  This option is
112 enabled by default, but @code{@value{GCC}} disables it when it invokes
113 @code{@value{AS}} directly.  Questionable instructions are those whoes
114 behaviour would be different if they were executed sequentially.  For
115 example the code fragment @samp{mv r1, r2 || mv r3, r1} produces a
116 different result from @samp{mv r1, r2 \n mv r3, r1} since the former
117 moves r1 into r3 and then r2 into r1, whereas the later moves r2 into r1
118 and r3.
120 @item -Wp
121 @cindex @samp{-Wp} option, M32RX
122 This is a shorter synonym for the @emph{-warn-explicit-parallel-conflicts}
123 option.
125 @item -no-warn-explicit-parallel-conflicts
126 @cindex @samp{-no-warn-explicit-parallel-conflicts} option, M32RX
127 Instructs @code{@value{AS}} not to produce warning messages when
128 questionable parallel instructions are encountered.
130 @item -Wnp
131 @cindex @samp{-Wnp} option, M32RX
132 This is a shorter synonym for the @emph{-no-warn-explicit-parallel-conflicts}
133 option.
135 @item -ignore-parallel-conflicts
136 @cindex @samp{-ignore-parallel-conflicts} option, M32RX
137 This option tells the assembler's to stop checking parallel
138 instructions for contraint violations.  This ability is provided for
139 hardware vendors testing chip designs and should not be used under
140 normal circumstances.
142 @item -no-ignore-parallel-conflicts
143 @cindex @samp{-no-ignore-parallel-conflicts} option, M32RX
144 This option restores the assembler's default behaviour of checking
145 parallel instructions to detect constraint violations.
147 @item -Ip
148 @cindex @samp{-Ip} option, M32RX
149 This is a shorter synonym for the @emph{-ignore-parallel-conflicts}
150 option.
152 @item -nIp
153 @cindex @samp{-nIp} option, M32RX
154 This is a shorter synonym for the @emph{-no-ignore-parallel-conflicts}
155 option.
157 @item -warn-unmatched-high
158 @cindex @samp{-warn-unmatched-high} option, M32R
159 This option tells the assembler to produce a warning message if a
160 @code{.high} pseudo op is encountered without a mathcing @code{.low}
161 pseudo op.  The presence of such an unmatches pseudo op usually
162 indicates a programming error.
164 @item -no-warn-unmatched-high
165 @cindex @samp{-no-warn-unmatched-high} option, M32R
166 Disables a previously enabled @emph{-warn-unmatched-high} option.
168 @item -Wuh
169 @cindex @samp{-Wuh} option, M32RX
170 This is a shorter synonym for the @emph{-warn-unmatched-high} option.
172 @item -Wnuh
173 @cindex @samp{-Wnuh} option, M32RX
174 This is a shorter synonym for the @emph{-no-warn-unmatched-high} option.
176 @end table
178 @node M32R-Directives
179 @section M32R Directives
180 @cindex directives, M32R
181 @cindex M32R directives
183 The Renease M32R version of @code{@value{AS}} has a few architecture
184 specific directives:
186 @table @code
188 @cindex @code{low} directive, M32R
189 @item low @var{expression}
190 The @code{low} directive computes the value of its expression and
191 places the lower 16-bits of the result into the immediate-field of the
192 instruction.  For example:
194 @smallexample
195    or3   r0, r0, #low(0x12345678) ; compute r0 = r0 | 0x5678 
196    add3, r0, r0, #low(fred)   ; compute r0 = r0 + low 16-bits of address of fred
197 @end smallexample
199 @item high @var{expression}
200 @cindex @code{high} directive, M32R
201 The @code{high} directive computes the value of its expression and
202 places the upper 16-bits of the result into the immediate-field of the
203 instruction.  For example:
205 @smallexample
206    seth  r0, #high(0x12345678) ; compute r0 = 0x12340000 
207    seth, r0, #high(fred)       ; compute r0 = upper 16-bits of address of fred
208 @end smallexample
210 @item shigh @var{expression}
211 @cindex @code{shigh} directive, M32R
212 The @code{shigh} directive is very similar to the @code{high}
213 directive.  It also computes the value of its expression and places
214 the upper 16-bits of the result into the immediate-field of the 
215 instruction.  The difference is that @code{shigh} also checks to see
216 if the lower 16-bits could be interpreted as a signed number, and if
217 so it assumes that a borrow will occur from the upper-16 bits.  To
218 compensate for this the @code{shigh} directive pre-biases the upper
219 16 bit value by adding one to it.  For example:
221 For example:
223 @smallexample
224    seth  r0, #shigh(0x12345678) ; compute r0 = 0x12340000
225    seth  r0, #shigh(0x00008000) ; compute r0 = 0x00010000
226 @end smallexample
228 In the second example the lower 16-bits are 0x8000.  If these are
229 treated as a signed value and sign extended to 32-bits then the value
230 becomes 0xffff8000.  If this value is then added to 0x00010000 then
231 the result is 0x00008000.
233 This behaviour is to allow for the different semantics of the
234 @code{or3} and @code{add3} instructions.  The @code{or3} instruction
235 treats its 16-bit immediate argument as unsigned whereas the
236 @code{add3} treats its 16-bit immediate as a signed value.  So for
237 example:
239 @smallexample
240    seth  r0, #shigh(0x00008000) 
241    add3  r0, r0, #low(0x00008000) 
242 @end smallexample
244 Produces the correct result in r0, whereas:
246 @smallexample
247    seth  r0, #shigh(0x00008000) 
248    or3   r0, r0, #low(0x00008000) 
249 @end smallexample
251 Stores 0xffff8000 into r0.
253 Note - the @code{shigh} directive does not know where in the assembly
254 source code the lower 16-bits of the value are going set, so it cannot
255 check to make sure that an @code{or3} instruction is being used rather
256 than an @code{add3} instruction.  It is up to the programmer to make
257 sure that correct directives are used.
259 @cindex @code{.m32r} directive, M32R
260 @item .m32r
261 The directive performs a similar thing as the @emph{-m32r} command
262 line option.  It tells the assembler to only accept M32R instructions
263 from now on.  An instructions from later M32R architectures are
264 refused.
266 @cindex @code{.m32rx} directive, M32RX
267 @item .m32rx
268 The directive performs a similar thing as the @emph{-m32rx} command
269 line option.  It tells the assembler to start accepting the extra
270 instructions in the M32RX ISA as well as the ordinary M32R ISA.
272 @cindex @code{.m32r2} directive, M32R2
273 @item .m32r2
274 The directive performs a similar thing as the @emph{-m32r2} command
275 line option.  It tells the assembler to start accepting the extra
276 instructions in the M32R2 ISA as well as the ordinary M32R ISA.
278 @cindex @code{.little} directive, M32RX
279 @item .little
280 The directive performs a similar thing as the @emph{-little} command
281 line option.  It tells the assembler to start producing little-endian
282 code and data.  This option should be used with care as producing
283 mixed-endian binary files is frought with danger.
285 @cindex @code{.big} directive, M32RX
286 @item .big
287 The directive performs a similar thing as the @emph{-big} command
288 line option.  It tells the assembler to start producing big-endian
289 code and data.  This option should be used with care as producing
290 mixed-endian binary files is frought with danger.
292 @end table
294 @node M32R-Warnings
295 @section M32R Warnings
297 @cindex warnings, M32R
298 @cindex M32R warnings
300 There are several warning and error messages that can be produced by
301 @code{@value{AS}} which are specific to the M32R:
303 @table @code
305 @item output of 1st instruction is the same as an input to 2nd instruction - is this intentional ?
306 This message is only produced if warnings for explicit parallel
307 conflicts have been enabled.  It indicates that the assembler has
308 encountered a parallel instruction in which the destination register of
309 the left hand instruction is used as an input register in the right hand
310 instruction.  For example in this code fragment
311 @samp{mv r1, r2 || neg r3, r1} register r1 is the destination of the
312 move instruction and the input to the neg instruction.
314 @item output of 2nd instruction is the same as an input to 1st instruction - is this intentional ?
315 This message is only produced if warnings for explicit parallel
316 conflicts have been enabled.  It indicates that the assembler has
317 encountered a parallel instruction in which the destination register of
318 the right hand instruction is used as an input register in the left hand
319 instruction.  For example in this code fragment
320 @samp{mv r1, r2 || neg r2, r3} register r2 is the destination of the
321 neg instruction and the input to the move instruction.
323 @item instruction @samp{...} is for the M32RX only
324 This message is produced when the assembler encounters an instruction
325 which is only supported by the M32Rx processor, and the @samp{-m32rx}
326 command line flag has not been specified to allow assembly of such
327 instructions. 
329 @item unknown instruction @samp{...}
330 This message is produced when the assembler encounters an instruction
331 which it does not recognise.
333 @item only the NOP instruction can be issued in parallel on the m32r
334 This message is produced when the assembler encounters a parallel
335 instruction which does not involve a NOP instruction and the
336 @samp{-m32rx} command line flag has not been specified.  Only the M32Rx
337 processor is able to execute two instructions in parallel.
339 @item instruction @samp{...} cannot be executed in parallel.
340 This message is produced when the assembler encounters a parallel
341 instruction which is made up of one or two instructions which cannot be
342 executed in parallel.
344 @item Instructions share the same execution pipeline
345 This message is produced when the assembler encounters a parallel
346 instruction whoes components both use the same execution pipeline.
348 @item Instructions write to the same destination register.
349 This message is produced when the assembler encounters a parallel
350 instruction where both components attempt to modify the same register.
351 For example these code fragments will produce this message:
352 @samp{mv r1, r2 || neg r1, r3}
353 @samp{jl r0 || mv r14, r1}
354 @samp{st r2, @@-r1 || mv r1, r3} 
355 @samp{mv r1, r2 || ld r0, @@r1+} 
356 @samp{cmp r1, r2 || addx r3, r4} (Both write to the condition bit)
358 @end table