Add -lpwl to ppllibs, and -lisl to clooglibs.
[binutils.git] / gas / doc / c-m68k.texi
blob9d92aa0cdbdfac217b95457fecea83bf11670095
1 @c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 2000, 2003,
2 @c 2004, 2006, 2007, 2011 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 M68K-Dependent
8 @chapter M680x0 Dependent Features
9 @end ifset
10 @ifclear GENERIC
11 @node Machine Dependencies
12 @chapter M680x0 Dependent Features
13 @end ifclear
15 @cindex M680x0 support
16 @menu
17 * M68K-Opts::                   M680x0 Options
18 * M68K-Syntax::                 Syntax
19 * M68K-Moto-Syntax::            Motorola Syntax
20 * M68K-Float::                  Floating Point
21 * M68K-Directives::             680x0 Machine Directives
22 * M68K-opcodes::                Opcodes
23 @end menu
25 @node M68K-Opts
26 @section M680x0 Options
28 @cindex options, M680x0
29 @cindex M680x0 options
30 The Motorola 680x0 version of @code{@value{AS}} has a few machine
31 dependent options:
33 @table @samp
35 @cindex @samp{-march=} command line option, M680x0
36 @item -march=@var{architecture}
37 This option specifies a target architecture.  The following
38 architectures are recognized:
39 @code{68000},
40 @code{68010},
41 @code{68020},
42 @code{68030},
43 @code{68040},
44 @code{68060},
45 @code{cpu32},
46 @code{isaa},
47 @code{isaaplus},
48 @code{isab},
49 @code{isac} and
50 @code{cfv4e}.
53 @cindex @samp{-mcpu=} command line option, M680x0
54 @item -mcpu=@var{cpu}
55 This option specifies a target cpu.  When used in conjunction with the
56 @option{-march} option, the cpu must be within the specified
57 architecture.  Also, the generic features of the architecture are used
58 for instruction generation, rather than those of the specific chip.
60 @cindex @samp{-m[no-]68851} command line option, M680x0
61 @cindex @samp{-m[no-]68881} command line option, M680x0
62 @cindex @samp{-m[no-]div} command line option, M680x0
63 @cindex @samp{-m[no-]usp} command line option, M680x0
64 @cindex @samp{-m[no-]float} command line option, M680x0
65 @cindex @samp{-m[no-]mac} command line option, M680x0
66 @cindex @samp{-m[no-]emac} command line option, M680x0
67 @item -m[no-]68851
68 @itemx -m[no-]68881
69 @itemx -m[no-]div
70 @itemx -m[no-]usp
71 @itemx -m[no-]float
72 @itemx -m[no-]mac
73 @itemx -m[no-]emac
75 Enable or disable various architecture specific features.  If a chip
76 or architecture by default supports an option (for instance
77 @option{-march=isaaplus} includes the @option{-mdiv} option),
78 explicitly disabling the option will override the default.
80 @cindex @samp{-l} option, M680x0
81 @item -l
82 You can use the @samp{-l} option to shorten the size of references to undefined
83 symbols.  If you do not use the @samp{-l} option, references to undefined
84 symbols are wide enough for a full @code{long} (32 bits).  (Since
85 @code{@value{AS}} cannot know where these symbols end up, @code{@value{AS}} can
86 only allocate space for the linker to fill in later.  Since @code{@value{AS}}
87 does not know how far away these symbols are, it allocates as much space as it
88 can.)  If you use this option, the references are only one word wide (16 bits).
89 This may be useful if you want the object file to be as small as possible, and
90 you know that the relevant symbols are always less than 17 bits away.
92 @cindex @samp{--register-prefix-optional} option, M680x0
93 @item --register-prefix-optional
94 For some configurations, especially those where the compiler normally
95 does not prepend an underscore to the names of user variables, the
96 assembler requires a @samp{%} before any use of a register name.  This
97 is intended to let the assembler distinguish between C variables and
98 functions named @samp{a0} through @samp{a7}, and so on.  The @samp{%} is
99 always accepted, but is not required for certain configurations, notably
100 @samp{sun3}.  The @samp{--register-prefix-optional} option may be used
101 to permit omitting the @samp{%} even for configurations for which it is
102 normally required.  If this is done, it will generally be impossible to
103 refer to C variables and functions with the same names as register
104 names.
106 @cindex @samp{--bitwise-or} option, M680x0
107 @item --bitwise-or
108 Normally the character @samp{|} is treated as a comment character, which
109 means that it can not be used in expressions.  The @samp{--bitwise-or}
110 option turns @samp{|} into a normal character.  In this mode, you must
111 either use C style comments, or start comments with a @samp{#} character
112 at the beginning of a line.
114 @cindex @samp{--base-size-default-16}
115 @cindex @samp{--base-size-default-32}
116 @item --base-size-default-16  --base-size-default-32 
117 If you use an addressing mode with a base register without specifying
118 the size, @code{@value{AS}} will normally use the full 32 bit value.
119 For example, the addressing mode @samp{%a0@@(%d0)} is equivalent to
120 @samp{%a0@@(%d0:l)}.  You may use the @samp{--base-size-default-16}
121 option to tell @code{@value{AS}} to default to using the 16 bit value.
122 In this case, @samp{%a0@@(%d0)} is equivalent to @samp{%a0@@(%d0:w)}.
123 You may use the @samp{--base-size-default-32} option to restore the
124 default behaviour.
126 @cindex @samp{--disp-size-default-16}
127 @cindex @samp{--disp-size-default-32}
128 @item --disp-size-default-16  --disp-size-default-32
129 If you use an addressing mode with a displacement, and the value of the
130 displacement is not known, @code{@value{AS}} will normally assume that
131 the value is 32 bits.  For example, if the symbol @samp{disp} has not
132 been defined, @code{@value{AS}} will assemble the addressing mode
133 @samp{%a0@@(disp,%d0)} as though @samp{disp} is a 32 bit value.  You may
134 use the @samp{--disp-size-default-16} option to tell @code{@value{AS}}
135 to instead assume that the displacement is 16 bits.  In this case,
136 @code{@value{AS}} will assemble @samp{%a0@@(disp,%d0)} as though
137 @samp{disp} is a 16 bit value.  You may use the
138 @samp{--disp-size-default-32} option to restore the default behaviour.
140 @cindex @samp{--pcrel}
141 @item --pcrel
142 Always keep branches PC-relative.  In the M680x0 architecture all branches
143 are defined as PC-relative.  However, on some processors they are limited
144 to word displacements maximum.  When @code{@value{AS}} needs a long branch
145 that is not available, it normally emits an absolute jump instead.  This
146 option disables this substitution.  When this option is given and no long
147 branches are available, only word branches will be emitted.  An error
148 message will be generated if a word branch cannot reach its target.  This
149 option has no effect on 68020 and other processors that have long branches.
150 @pxref{M68K-Branch,,Branch Improvement}.
152 @cindex @samp{-m68000} and related options
153 @cindex architecture options, M680x0
154 @cindex M680x0 architecture options
155 @item -m68000
156 @code{@value{AS}} can assemble code for several different members of the
157 Motorola 680x0 family.  The default depends upon how @code{@value{AS}}
158 was configured when it was built; normally, the default is to assemble
159 code for the 68020 microprocessor.  The following options may be used to
160 change the default.  These options control which instructions and
161 addressing modes are permitted.  The members of the 680x0 family are
162 very similar.  For detailed information about the differences, see the
163 Motorola manuals.
165 @table @samp
166 @item -m68000
167 @itemx -m68ec000
168 @itemx -m68hc000
169 @itemx -m68hc001
170 @itemx -m68008
171 @itemx -m68302
172 @itemx -m68306
173 @itemx -m68307
174 @itemx -m68322
175 @itemx -m68356
176 Assemble for the 68000. @samp{-m68008}, @samp{-m68302}, and so on are synonyms
177 for @samp{-m68000}, since the chips are the same from the point of view
178 of the assembler.
180 @item -m68010
181 Assemble for the 68010.
183 @item -m68020
184 @itemx -m68ec020
185 Assemble for the 68020.  This is normally the default.
187 @item -m68030
188 @itemx -m68ec030
189 Assemble for the 68030.
191 @item -m68040
192 @itemx -m68ec040
193 Assemble for the 68040.
195 @item -m68060
196 @itemx -m68ec060
197 Assemble for the 68060.
199 @item -mcpu32
200 @itemx -m68330
201 @itemx -m68331
202 @itemx -m68332
203 @itemx -m68333
204 @itemx -m68334
205 @itemx -m68336
206 @itemx -m68340
207 @itemx -m68341
208 @itemx -m68349
209 @itemx -m68360
210 Assemble for the CPU32 family of chips.
212 @item -m5200
213 @itemx -m5202
214 @itemx -m5204
215 @itemx -m5206
216 @itemx -m5206e
217 @itemx -m521x
218 @itemx -m5249
219 @itemx -m528x
220 @itemx -m5307
221 @itemx -m5407
222 @itemx -m547x
223 @itemx -m548x
224 @itemx -mcfv4
225 @itemx -mcfv4e
226 Assemble for the ColdFire family of chips.
228 @item -m68881
229 @itemx -m68882
230 Assemble 68881 floating point instructions.  This is the default for the
231 68020, 68030, and the CPU32.  The 68040 and 68060 always support
232 floating point instructions.
234 @item -mno-68881
235 Do not assemble 68881 floating point instructions.  This is the default
236 for 68000 and the 68010.  The 68040 and 68060 always support floating
237 point instructions, even if this option is used.
239 @item -m68851
240 Assemble 68851 MMU instructions.  This is the default for the 68020,
241 68030, and 68060.  The 68040 accepts a somewhat different set of MMU
242 instructions; @samp{-m68851} and @samp{-m68040} should not be used
243 together.
245 @item -mno-68851
246 Do not assemble 68851 MMU instructions.  This is the default for the
247 68000, 68010, and the CPU32.  The 68040 accepts a somewhat different set
248 of MMU instructions.
249 @end table
250 @end table
252 @node M68K-Syntax
253 @section Syntax
255 @cindex @sc{mit}
256 This syntax for the Motorola 680x0 was developed at @sc{mit}.
258 @cindex M680x0 syntax
259 @cindex syntax, M680x0
260 @cindex M680x0 size modifiers
261 @cindex size modifiers, M680x0
262 The 680x0 version of @code{@value{AS}} uses instructions names and
263 syntax compatible with the Sun assembler.  Intervening periods are
264 ignored; for example, @samp{movl} is equivalent to @samp{mov.l}.
266 In the following table @var{apc} stands for any of the address registers
267 (@samp{%a0} through @samp{%a7}), the program counter (@samp{%pc}), the
268 zero-address relative to the program counter (@samp{%zpc}), a suppressed
269 address register (@samp{%za0} through @samp{%za7}), or it may be omitted
270 entirely.  The use of @var{size} means one of @samp{w} or @samp{l}, and
271 it may be omitted, along with the leading colon, unless a scale is also
272 specified.  The use of @var{scale} means one of @samp{1}, @samp{2},
273 @samp{4}, or @samp{8}, and it may always be omitted along with the
274 leading colon.
276 @cindex M680x0 addressing modes
277 @cindex addressing modes, M680x0
278 The following addressing modes are understood:
279 @table @dfn
280 @item Immediate
281 @samp{#@var{number}}
283 @item Data Register
284 @samp{%d0} through @samp{%d7}
286 @item Address Register
287 @samp{%a0} through @samp{%a7}@*
288 @samp{%a7} is also known as @samp{%sp}, i.e., the Stack Pointer.  @code{%a6}
289 is also known as @samp{%fp}, the Frame Pointer.
291 @item Address Register Indirect
292 @samp{%a0@@} through @samp{%a7@@}
294 @item Address Register Postincrement
295 @samp{%a0@@+} through @samp{%a7@@+}
297 @item Address Register Predecrement
298 @samp{%a0@@-} through @samp{%a7@@-}
300 @item Indirect Plus Offset
301 @samp{@var{apc}@@(@var{number})}
303 @item Index
304 @samp{@var{apc}@@(@var{number},@var{register}:@var{size}:@var{scale})}
306 The @var{number} may be omitted.
308 @item Postindex
309 @samp{@var{apc}@@(@var{number})@@(@var{onumber},@var{register}:@var{size}:@var{scale})}
311 The @var{onumber} or the @var{register}, but not both, may be omitted.
313 @item Preindex
314 @samp{@var{apc}@@(@var{number},@var{register}:@var{size}:@var{scale})@@(@var{onumber})}
316 The @var{number} may be omitted.  Omitting the @var{register} produces
317 the Postindex addressing mode.
319 @item Absolute
320 @samp{@var{symbol}}, or @samp{@var{digits}}, optionally followed by
321 @samp{:b}, @samp{:w}, or @samp{:l}.
322 @end table
324 @node M68K-Moto-Syntax
325 @section Motorola Syntax
327 @cindex Motorola syntax for the 680x0
328 @cindex alternate syntax for the 680x0
330 The standard Motorola syntax for this chip differs from the syntax
331 already discussed (@pxref{M68K-Syntax,,Syntax}).  @code{@value{AS}} can
332 accept Motorola syntax for operands, even if @sc{mit} syntax is used for
333 other operands in the same instruction.  The two kinds of syntax are
334 fully compatible.
336 In the following table @var{apc} stands for any of the address registers
337 (@samp{%a0} through @samp{%a7}), the program counter (@samp{%pc}), the
338 zero-address relative to the program counter (@samp{%zpc}), or a
339 suppressed address register (@samp{%za0} through @samp{%za7}).  The use
340 of @var{size} means one of @samp{w} or @samp{l}, and it may always be
341 omitted along with the leading dot.  The use of @var{scale} means one of
342 @samp{1}, @samp{2}, @samp{4}, or @samp{8}, and it may always be omitted
343 along with the leading asterisk.
345 The following additional addressing modes are understood:
347 @table @dfn
348 @item Address Register Indirect
349 @samp{(%a0)} through @samp{(%a7)}@* 
350 @samp{%a7} is also known as @samp{%sp}, i.e., the Stack Pointer.  @code{%a6}
351 is also known as @samp{%fp}, the Frame Pointer.
353 @item Address Register Postincrement
354 @samp{(%a0)+} through @samp{(%a7)+}
356 @item Address Register Predecrement
357 @samp{-(%a0)} through @samp{-(%a7)}
359 @item Indirect Plus Offset
360 @samp{@var{number}(@var{%a0})} through @samp{@var{number}(@var{%a7})},
361 or @samp{@var{number}(@var{%pc})}.
363 The @var{number} may also appear within the parentheses, as in
364 @samp{(@var{number},@var{%a0})}.  When used with the @var{pc}, the
365 @var{number} may be omitted (with an address register, omitting the
366 @var{number} produces Address Register Indirect mode).
368 @item Index
369 @samp{@var{number}(@var{apc},@var{register}.@var{size}*@var{scale})}
371 The @var{number} may be omitted, or it may appear within the
372 parentheses.  The @var{apc} may be omitted.  The @var{register} and the
373 @var{apc} may appear in either order.  If both @var{apc} and
374 @var{register} are address registers, and the @var{size} and @var{scale}
375 are omitted, then the first register is taken as the base register, and
376 the second as the index register.
378 @item Postindex
379 @samp{([@var{number},@var{apc}],@var{register}.@var{size}*@var{scale},@var{onumber})}
381 The @var{onumber}, or the @var{register}, or both, may be omitted.
382 Either the @var{number} or the @var{apc} may be omitted, but not both.
384 @item Preindex
385 @samp{([@var{number},@var{apc},@var{register}.@var{size}*@var{scale}],@var{onumber})}
387 The @var{number}, or the @var{apc}, or the @var{register}, or any two of
388 them, may be omitted.  The @var{onumber} may be omitted.  The
389 @var{register} and the @var{apc} may appear in either order.  If both
390 @var{apc} and @var{register} are address registers, and the @var{size}
391 and @var{scale} are omitted, then the first register is taken as the
392 base register, and the second as the index register.
393 @end table
395 @node M68K-Float
396 @section Floating Point
398 @cindex floating point, M680x0
399 @cindex M680x0 floating point
400 Packed decimal (P) format floating literals are not supported.
401 Feel free to add the code!
403 The floating point formats generated by directives are these.
405 @table @code
406 @cindex @code{float} directive, M680x0
407 @item .float
408 @code{Single} precision floating point constants.
410 @cindex @code{double} directive, M680x0
411 @item .double
412 @code{Double} precision floating point constants.
414 @cindex @code{extend} directive M680x0
415 @cindex @code{ldouble} directive M680x0
416 @item .extend
417 @itemx .ldouble
418 @code{Extended} precision (@code{long double}) floating point constants.
419 @end table
421 @node M68K-Directives
422 @section 680x0 Machine Directives
424 @cindex M680x0 directives
425 @cindex directives, M680x0
426 In order to be compatible with the Sun assembler the 680x0 assembler
427 understands the following directives.
429 @table @code
430 @cindex @code{data1} directive, M680x0
431 @item .data1
432 This directive is identical to a @code{.data 1} directive.
434 @cindex @code{data2} directive, M680x0
435 @item .data2
436 This directive is identical to a @code{.data 2} directive.
438 @cindex @code{even} directive, M680x0
439 @item .even
440 This directive is a special case of the @code{.align} directive; it
441 aligns the output to an even byte boundary.
443 @cindex @code{skip} directive, M680x0
444 @item .skip
445 This directive is identical to a @code{.space} directive.
447 @cindex @code{arch} directive, M680x0
448 @item .arch @var{name}
449 Select the target architecture and extension features.  Valid values
450 for @var{name} are the same as for the @option{-march} command line
451 option.  This directive cannot be specified after
452 any instructions have been assembled.  If it is given multiple times,
453 or in conjunction with the @option{-march} option, all uses must be for
454 the same architecture and extension set.
456 @cindex @code{cpu} directive, M680x0
457 @item .cpu @var{name}
458 Select the target cpu.  Valid valuse
459 for @var{name} are the same as for the @option{-mcpu} command line
460 option.  This directive cannot be specified after
461 any instructions have been assembled.  If it is given multiple times,
462 or in conjunction with the @option{-mopt} option, all uses must be for
463 the same cpu.
465 @end table
467 @need 2000
468 @node M68K-opcodes
469 @section Opcodes
471 @cindex M680x0 opcodes
472 @cindex opcodes, M680x0
473 @cindex instruction set, M680x0
474 @c doc@cygnus.com: I don't see any point in the following
475 @c                   paragraph.  Bugs are bugs; how does saying this
476 @c                   help anyone?
477 @ignore
478 Danger:  Several bugs have been found in the opcode table (and
479 fixed).  More bugs may exist.  Be careful when using obscure
480 instructions.
481 @end ignore
483 @menu
484 * M68K-Branch::                 Branch Improvement
485 * M68K-Chars::                  Special Characters
486 @end menu
488 @node M68K-Branch
489 @subsection Branch Improvement
491 @cindex pseudo-opcodes, M680x0
492 @cindex M680x0 pseudo-opcodes
493 @cindex branch improvement, M680x0
494 @cindex M680x0 branch improvement
495 Certain pseudo opcodes are permitted for branch instructions.
496 They expand to the shortest branch instruction that reach the
497 target.  Generally these mnemonics are made by substituting @samp{j} for
498 @samp{b} at the start of a Motorola mnemonic.
500 The following table summarizes the pseudo-operations.  A @code{*} flags
501 cases that are more fully described after the table:
503 @smallexample
504           Displacement
505           +------------------------------------------------------------
506           |                68020           68000/10, not PC-relative OK
507 Pseudo-Op |BYTE    WORD    LONG            ABSOLUTE LONG JUMP    **
508           +------------------------------------------------------------
509      jbsr |bsrs    bsrw    bsrl            jsr
510       jra |bras    braw    bral            jmp
511 *     jXX |bXXs    bXXw    bXXl            bNXs;jmp
512 *    dbXX | N/A    dbXXw   dbXX;bras;bral  dbXX;bras;jmp
513      fjXX | N/A    fbXXw   fbXXl            N/A
515 XX: condition
516 NX: negative of condition XX
518 @end smallexample
519 @center @code{*}---see full description below
520 @center @code{**}---this expansion mode is disallowed by @samp{--pcrel}
522 @table @code
523 @item jbsr
524 @itemx jra
525 These are the simplest jump pseudo-operations; they always map to one
526 particular machine instruction, depending on the displacement to the
527 branch target.  This instruction will be a byte or word branch is that
528 is sufficient.  Otherwise, a long branch will be emitted if available.
529 If no long branches are available and the @samp{--pcrel} option is not
530 given, an absolute long jump will be emitted instead.  If no long
531 branches are available, the @samp{--pcrel} option is given, and a word
532 branch cannot reach the target, an error message is generated.
534 In addition to standard branch operands, @code{@value{AS}} allows these
535 pseudo-operations to have all operands that are allowed for jsr and jmp,
536 substituting these instructions if the operand given is not valid for a
537 branch instruction.
539 @item j@var{XX}
540 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
541 where @var{XX} is a conditional branch or condition-code test.  The full
542 list of pseudo-ops in this family is:
543 @smallexample
544  jhi   jls   jcc   jcs   jne   jeq   jvc
545  jvs   jpl   jmi   jge   jlt   jgt   jle
546 @end smallexample
548 Usually, each of these pseudo-operations expands to a single branch
549 instruction.  However, if a word branch is not sufficient, no long branches
550 are available, and the @samp{--pcrel} option is not given, @code{@value{AS}}
551 issues a longer code fragment in terms of @var{NX}, the opposite condition
552 to @var{XX}.  For example, under these conditions:
553 @smallexample
554     j@var{XX} foo
555 @end smallexample
556 gives
557 @smallexample
558      b@var{NX}s oof
559      jmp foo
560  oof:
561 @end smallexample
563 @item db@var{XX}
564 The full family of pseudo-operations covered here is
565 @smallexample
566  dbhi   dbls   dbcc   dbcs   dbne   dbeq   dbvc
567  dbvs   dbpl   dbmi   dbge   dblt   dbgt   dble
568  dbf    dbra   dbt
569 @end smallexample
571 Motorola @samp{db@var{XX}} instructions allow word displacements only.  When
572 a word displacement is sufficient, each of these pseudo-operations expands
573 to the corresponding Motorola instruction.  When a word displacement is not
574 sufficient and long branches are available, when the source reads
575 @samp{db@var{XX} foo}, @code{@value{AS}} emits
576 @smallexample
577      db@var{XX} oo1
578      bras oo2
579  oo1:bral foo
580  oo2:
581 @end smallexample
583 If, however, long branches are not available and the @samp{--pcrel} option is
584 not given, @code{@value{AS}} emits
585 @smallexample
586      db@var{XX} oo1
587      bras oo2
588  oo1:jmp foo
589  oo2:
590 @end smallexample
592 @item fj@var{XX}
593 This family includes
594 @smallexample
595  fjne   fjeq   fjge   fjlt   fjgt   fjle   fjf
596  fjt    fjgl   fjgle  fjnge  fjngl  fjngle fjngt
597  fjnle  fjnlt  fjoge  fjogl  fjogt  fjole  fjolt
598  fjor   fjseq  fjsf   fjsne  fjst   fjueq  fjuge
599  fjugt  fjule  fjult  fjun
600 @end smallexample
602 Each of these pseudo-operations always expands to a single Motorola
603 coprocessor branch instruction, word or long.  All Motorola coprocessor
604 branch instructions allow both word and long displacements.
606 @end table
608 @node M68K-Chars
609 @subsection Special Characters
611 @cindex special characters, M680x0
613 @cindex M680x0 line comment character
614 @cindex line comment character, M680x0
615 @cindex comments, M680x0
616 Line comments are introduced by the @samp{|} character appearing
617 anywhere on a line, unless the @option{--bitwise-or} command line option
618 has been specified. 
620 An asterisk (@samp{*}) as the first character on a line marks the
621 start of a line comment as well.
623 @cindex M680x0 immediate character
624 @cindex immediate character, M680x0
626 A hash character (@samp{#}) as the first character on a line also
627 marks the start of a line comment, but in this case it could also be a
628 logical line number directive (@pxref{Comments}) or a preprocessor
629 control command (@pxref{Preprocessing}).  If the hash character
630 appears elsewhere on a line it is used to introduce an immediate
631 value.  (This is for compatibility with Sun's assembler).
633 @cindex M680x0 line separator
634 @cindex line separator, M680x0
636 Multiple statements on the same line can appear if they are separated
637 by the @samp{;} character.