Merge branch 'vendor/GCC44'
[dragonfly.git] / contrib / binutils-2.22 / gas / doc / c-m68hc11.texi
1 @c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 2000, 2003,
2 @c 2006, 2011
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 M68HC11-Dependent
9 @chapter M68HC11 and M68HC12 Dependent Features
10 @end ifset
11 @ifclear GENERIC
12 @node Machine Dependencies
13 @chapter M68HC11 and M68HC12 Dependent Features
14 @end ifclear
15
16 @cindex M68HC11 and M68HC12 support
17 @menu
18 * M68HC11-Opts::                   M68HC11 and M68HC12 Options
19 * M68HC11-Syntax::                 Syntax
20 * M68HC11-Modifiers::              Symbolic Operand Modifiers
21 * M68HC11-Directives::             Assembler Directives
22 * M68HC11-Float::                  Floating Point
23 * M68HC11-opcodes::                Opcodes
24 @end menu
25
26 @node M68HC11-Opts
27 @section M68HC11 and M68HC12 Options
28
29 @cindex options, M68HC11
30 @cindex M68HC11 options
31 The Motorola 68HC11 and 68HC12 version of @code{@value{AS}} have a few machine
32 dependent options.
33
34 @table @code
35
36 @cindex @samp{-m68hc11}
37 @item -m68hc11
38 This option switches the assembler in the M68HC11 mode. In this mode,
39 the assembler only accepts 68HC11 operands and mnemonics. It produces
40 code for the 68HC11.
41
42 @cindex @samp{-m68hc12}
43 @item -m68hc12
44 This option switches the assembler in the M68HC12 mode. In this mode,
45 the assembler also accepts 68HC12 operands and mnemonics. It produces
46 code for the 68HC12. A few 68HC11 instructions are replaced by
47 some 68HC12 instructions as recommended by Motorola specifications.
48
49 @cindex @samp{-m68hcs12}
50 @item -m68hcs12
51 This option switches the assembler in the M68HCS12 mode.  This mode is
52 similar to @samp{-m68hc12} but specifies to assemble for the 68HCS12
53 series.  The only difference is on the assembling of the @samp{movb}
54 and @samp{movw} instruction when a PC-relative operand is used.
55
56 @cindex @samp{-mshort}
57 @item -mshort
58 This option controls the ABI and indicates to use a 16-bit integer ABI.
59 It has no effect on the assembled instructions.
60 This is the default.
61
62 @cindex @samp{-mlong}
63 @item -mlong
64 This option controls the ABI and indicates to use a 32-bit integer ABI.
65
66 @cindex @samp{-mshort-double}
67 @item -mshort-double
68 This option controls the ABI and indicates to use a 32-bit float ABI.
69 This is the default.
70
71 @cindex @samp{-mlong-double}
72 @item -mlong-double
73 This option controls the ABI and indicates to use a 64-bit float ABI.
74
75 @cindex @samp{--strict-direct-mode}
76 @item --strict-direct-mode
77 You can use the @samp{--strict-direct-mode} option to disable
78 the automatic translation of direct page mode addressing into
79 extended mode when the instruction does not support direct mode.
80 For example, the @samp{clr} instruction does not support direct page
81 mode addressing. When it is used with the direct page mode,
82 @code{@value{AS}} will ignore it and generate an absolute addressing.
83 This option prevents @code{@value{AS}} from doing this, and the wrong
84 usage of the direct page mode will raise an error.
85
86 @cindex @samp{--short-branches}
87 @item --short-branches
88 The @samp{--short-branches} option turns off the translation of
89 relative branches into absolute branches when the branch offset is
90 out of range. By default @code{@value{AS}} transforms the relative
91 branch (@samp{bsr}, @samp{bgt}, @samp{bge}, @samp{beq}, @samp{bne},
92 @samp{ble}, @samp{blt}, @samp{bhi}, @samp{bcc}, @samp{bls},
93 @samp{bcs}, @samp{bmi}, @samp{bvs}, @samp{bvs}, @samp{bra}) into
94 an absolute branch when the offset is out of the -128 .. 127 range.
95 In that case, the @samp{bsr} instruction is translated into a
96 @samp{jsr}, the @samp{bra} instruction is translated into a
97 @samp{jmp} and the conditional branches instructions are inverted and
98 followed by a @samp{jmp}. This option disables these translations
99 and @code{@value{AS}} will generate an error if a relative branch
100 is out of range. This option does not affect the optimization
101 associated to the @samp{jbra}, @samp{jbsr} and @samp{jbXX} pseudo opcodes.
102
103 @cindex @samp{--force-long-branches}
104 @item --force-long-branches
105 The @samp{--force-long-branches} option forces the translation of
106 relative branches into absolute branches. This option does not affect
107 the optimization associated to the @samp{jbra}, @samp{jbsr} and
108 @samp{jbXX} pseudo opcodes. 
109
110 @cindex @samp{--print-insn-syntax}
111 @item --print-insn-syntax
112 You can use the @samp{--print-insn-syntax} option to obtain the
113 syntax description of the instruction when an error is detected.
114
115 @cindex @samp{--print-opcodes}
116 @item --print-opcodes
117 The @samp{--print-opcodes} option prints the list of all the
118 instructions with their syntax. The first item of each line
119 represents the instruction name and the rest of the line indicates
120 the possible operands for that instruction. The list is printed
121 in alphabetical order. Once the list is printed @code{@value{AS}}
122 exits.
123
124 @cindex @samp{--generate-example}
125 @item --generate-example
126 The @samp{--generate-example} option is similar to @samp{--print-opcodes}
127 but it generates an example for each instruction instead.
128 @end table
129
130 @node M68HC11-Syntax
131 @section Syntax
132
133 @cindex M68HC11 syntax
134 @cindex syntax, M68HC11
135
136 In the M68HC11 syntax, the instruction name comes first and it may
137 be followed by one or several operands (up to three). Operands are
138 separated by comma (@samp{,}). In the normal mode,
139 @code{@value{AS}} will complain if too many operands are specified for
140 a given instruction. In the MRI mode (turned on with @samp{-M} option),
141 it will treat them as comments. Example:
142
143 @smallexample
144 inx
145 lda  #23
146 bset 2,x #4
147 brclr *bot #8 foo
148 @end smallexample
149
150 @cindex line comment character, M68HC11
151 @cindex M68HC11 line comment character
152 The presence of a @samp{;} character or a @samp{!} character anywhere
153 on a line indicates the start of a comment that extends to the end of
154 that line.
155
156 A @samp{*} or a @samp{#} character at the start of a line also
157 introduces a line comment, but these characters do not work elsewhere
158 on the line.  If the first character of the line is a @samp{#} then as
159 well as starting a comment, the line could also be logical line number
160 directive (@pxref{Comments}) or a preprocessor control command
161 (@pxref{Preprocessing}).
162
163 @cindex line separator, M68HC11
164 @cindex statement separator, M68HC11
165 @cindex M68HC11 line separator
166 The M68HC11 assembler does not currently support a line separator
167 character.
168
169 @cindex M68HC11 addressing modes
170 @cindex addressing modes, M68HC11
171 The following addressing modes are understood for 68HC11 and 68HC12:
172 @table @dfn
173 @item Immediate
174 @samp{#@var{number}}
175
176 @item Address Register
177 @samp{@var{number},X}, @samp{@var{number},Y}
178
179 The @var{number} may be omitted in which case 0 is assumed.
180
181 @item Direct Addressing mode
182 @samp{*@var{symbol}}, or @samp{*@var{digits}}
183
184 @item Absolute
185 @samp{@var{symbol}}, or @samp{@var{digits}}
186 @end table
187
188 The M68HC12 has other more complex addressing modes. All of them
189 are supported and they are represented below:
190
191 @table @dfn
192 @item Constant Offset Indexed Addressing Mode
193 @samp{@var{number},@var{reg}}
194
195 The @var{number} may be omitted in which case 0 is assumed.
196 The register can be either @samp{X}, @samp{Y}, @samp{SP} or
197 @samp{PC}.  The assembler will use the smaller post-byte definition
198 according to the constant value (5-bit constant offset, 9-bit constant
199 offset or 16-bit constant offset).  If the constant is not known by
200 the assembler it will use the 16-bit constant offset post-byte and the value
201 will be resolved at link time.
202
203 @item Offset Indexed Indirect
204 @samp{[@var{number},@var{reg}]}
205
206 The register can be either @samp{X}, @samp{Y}, @samp{SP} or @samp{PC}.
207
208 @item Auto Pre-Increment/Pre-Decrement/Post-Increment/Post-Decrement
209 @samp{@var{number},-@var{reg}}
210 @samp{@var{number},+@var{reg}}
211 @samp{@var{number},@var{reg}-}
212 @samp{@var{number},@var{reg}+}
213
214 The number must be in the range @samp{-8}..@samp{+8} and must not be 0.
215 The register can be either @samp{X}, @samp{Y}, @samp{SP} or @samp{PC}.
216
217 @item Accumulator Offset
218 @samp{@var{acc},@var{reg}}
219
220 The accumulator register can be either @samp{A}, @samp{B} or @samp{D}.
221 The register can be either @samp{X}, @samp{Y}, @samp{SP} or @samp{PC}.
222
223 @item Accumulator D offset indexed-indirect
224 @samp{[D,@var{reg}]}
225
226 The register can be either @samp{X}, @samp{Y}, @samp{SP} or @samp{PC}.
227
228 @end table
229
230 For example:
231
232 @smallexample
233 ldab 1024,sp
234 ldd [10,x]
235 orab 3,+x
236 stab -2,y-
237 ldx a,pc
238 sty [d,sp]
239 @end smallexample
240
241
242 @node M68HC11-Modifiers
243 @section Symbolic Operand Modifiers
244
245 @cindex M68HC11 modifiers
246 @cindex syntax, M68HC11
247
248 The assembler supports several modifiers when using symbol addresses
249 in 68HC11 and 68HC12 instruction operands.  The general syntax is
250 the following:
251
252 @smallexample
253 %modifier(symbol)
254 @end smallexample
255
256 @table @code
257 @cindex symbol modifiers
258 @item %addr
259 This modifier indicates to the assembler and linker to use
260 the 16-bit physical address corresponding to the symbol.  This is intended
261 to be used on memory window systems to map a symbol in the memory bank window.
262 If the symbol is in a memory expansion part, the physical address
263 corresponds to the symbol address within the memory bank window.
264 If the symbol is not in a memory expansion part, this is the symbol address
265 (using or not using the %addr modifier has no effect in that case).
266
267 @item %page
268 This modifier indicates to use the memory page number corresponding
269 to the symbol.  If the symbol is in a memory expansion part, its page
270 number is computed by the linker as a number used to map the page containing
271 the symbol in the memory bank window.  If the symbol is not in a memory
272 expansion part, the page number is 0.
273
274 @item %hi
275 This modifier indicates to use the 8-bit high part of the physical
276 address of the symbol.
277
278 @item %lo
279 This modifier indicates to use the 8-bit low part of the physical
280 address of the symbol.
281
282 @end table
283
284 For example a 68HC12 call to a function @samp{foo_example} stored in memory
285 expansion part could be written as follows:
286
287 @smallexample
288 call %addr(foo_example),%page(foo_example)
289 @end smallexample
290
291 and this is equivalent to
292
293 @smallexample
294 call foo_example
295 @end smallexample
296
297 And for 68HC11 it could be written as follows:
298
299 @smallexample
300 ldab #%page(foo_example)
301 stab _page_switch
302 jsr  %addr(foo_example)
303 @end smallexample
304
305 @node M68HC11-Directives
306 @section Assembler Directives
307
308 @cindex assembler directives, M68HC11
309 @cindex assembler directives, M68HC12
310 @cindex M68HC11 assembler directives
311 @cindex M68HC12 assembler directives
312
313 The 68HC11 and 68HC12 version of @code{@value{AS}} have the following
314 specific assembler directives:
315
316 @table @code
317 @item .relax
318 @cindex assembler directive .relax, M68HC11
319 @cindex M68HC11 assembler directive .relax
320 The relax directive is used by the @samp{GNU Compiler} to emit a specific
321 relocation to mark a group of instructions for linker relaxation.
322 The sequence of instructions within the group must be known to the linker
323 so that relaxation can be performed.
324
325 @item .mode [mshort|mlong|mshort-double|mlong-double]
326 @cindex assembler directive .mode, M68HC11
327 @cindex M68HC11 assembler directive .mode
328 This directive specifies the ABI.  It overrides the @samp{-mshort},
329 @samp{-mlong}, @samp{-mshort-double} and @samp{-mlong-double} options.
330
331 @item .far @var{symbol}
332 @cindex assembler directive .far, M68HC11
333 @cindex M68HC11 assembler directive .far
334 This directive marks the symbol as a @samp{far} symbol meaning that it
335 uses a @samp{call/rtc} calling convention as opposed to @samp{jsr/rts}.
336 During a final link, the linker will identify references to the @samp{far}
337 symbol and will verify the proper calling convention.
338
339 @item .interrupt @var{symbol}
340 @cindex assembler directive .interrupt, M68HC11
341 @cindex M68HC11 assembler directive .interrupt
342 This directive marks the symbol as an interrupt entry point.
343 This information is then used by the debugger to correctly unwind the
344 frame across interrupts.
345
346 @item .xrefb @var{symbol}
347 @cindex assembler directive .xrefb, M68HC11
348 @cindex M68HC11 assembler directive .xrefb
349 This directive is defined for compatibility with the
350 @samp{Specification for Motorola 8 and 16-Bit Assembly Language Input
351 Standard} and is ignored.
352
353 @end table
354
355 @node M68HC11-Float
356 @section Floating Point
357
358 @cindex floating point, M68HC11
359 @cindex M68HC11 floating point
360 Packed decimal (P) format floating literals are not supported.
361 Feel free to add the code!
362
363 The floating point formats generated by directives are these.
364
365 @table @code
366 @cindex @code{float} directive, M68HC11
367 @item .float
368 @code{Single} precision floating point constants.
369
370 @cindex @code{double} directive, M68HC11
371 @item .double
372 @code{Double} precision floating point constants.
373
374 @cindex @code{extend} directive M68HC11
375 @cindex @code{ldouble} directive M68HC11
376 @item .extend
377 @itemx .ldouble
378 @code{Extended} precision (@code{long double}) floating point constants.
379 @end table
380
381 @need 2000
382 @node M68HC11-opcodes
383 @section Opcodes
384
385 @cindex M68HC11 opcodes
386 @cindex opcodes, M68HC11
387 @cindex instruction set, M68HC11
388
389 @menu
390 * M68HC11-Branch::                 Branch Improvement
391 @end menu
392
393 @node M68HC11-Branch
394 @subsection Branch Improvement
395
396 @cindex pseudo-opcodes, M68HC11
397 @cindex M68HC11 pseudo-opcodes
398 @cindex branch improvement, M68HC11
399 @cindex M68HC11 branch improvement
400
401 Certain pseudo opcodes are permitted for branch instructions.
402 They expand to the shortest branch instruction that reach the
403 target. Generally these mnemonics are made by prepending @samp{j} to
404 the start of Motorola mnemonic. These pseudo opcodes are not affected
405 by the @samp{--short-branches} or @samp{--force-long-branches} options.
406
407 The following table summarizes the pseudo-operations.
408
409 @smallexample
410                         Displacement Width
411      +-------------------------------------------------------------+
412      |                     Options                                 |
413      |    --short-branches           --force-long-branches         |
414      +--------------------------+----------------------------------+
415   Op |BYTE             WORD     | BYTE          WORD               |
416      +--------------------------+----------------------------------+
417  bsr | bsr <pc-rel>    <error>  |               jsr <abs>          |
418  bra | bra <pc-rel>    <error>  |               jmp <abs>          |
419 jbsr | bsr <pc-rel>   jsr <abs> | bsr <pc-rel>  jsr <abs>          |
420 jbra | bra <pc-rel>   jmp <abs> | bra <pc-rel>  jmp <abs>          |
421  bXX | bXX <pc-rel>    <error>  |               bNX +3; jmp <abs>  | 
422 jbXX | bXX <pc-rel>   bNX +3;   | bXX <pc-rel>  bNX +3; jmp <abs>  |
423      |                jmp <abs> |                                  |
424      +--------------------------+----------------------------------+
425 XX: condition
426 NX: negative of condition XX
427
428 @end smallexample
429
430 @table @code
431 @item jbsr
432 @itemx jbra
433 These are the simplest jump pseudo-operations; they always map to one
434 particular machine instruction, depending on the displacement to the
435 branch target.
436
437 @item jb@var{XX}
438 Here, @samp{jb@var{XX}} stands for an entire family of pseudo-operations,
439 where @var{XX} is a conditional branch or condition-code test.  The full
440 list of pseudo-ops in this family is:
441 @smallexample
442  jbcc   jbeq   jbge   jbgt   jbhi   jbvs   jbpl  jblo
443  jbcs   jbne   jblt   jble   jbls   jbvc   jbmi
444 @end smallexample
445
446 For the cases of non-PC relative displacements and long displacements,
447 @code{@value{AS}} issues a longer code fragment in terms of
448 @var{NX}, the opposite condition to @var{XX}.  For example, for the
449 non-PC relative case:
450 @smallexample
451     jb@var{XX} foo
452 @end smallexample
453 gives
454 @smallexample
455      b@var{NX}s oof
456      jmp foo
457  oof:
458 @end smallexample
459
460 @end table
461
462