* ld-elf/header.d: Allow arbitrary lines between "Program Header"
[binutils.git] / gas / doc / c-m68k.texi
blob0f8bb7853ef0f2d67620070eac06dd4eca1daee5
1 @c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 2000, 2003,
2 @c 2004 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} and
49 @code{cfv4e}.
52 @cindex @samp{-mcpu=} command line option, M680x0
53 @item -mcpu=@var{cpu}
54 This option specifies a target cpu.  When used in conjunction with the
55 @option{-march} option, the cpu must be within the specified
56 architecture.  Also, the generic features of the architecture are used
57 for instruction generation, rather than those of the specific chip.
59 @cindex @samp{-m[no-]68851} command line option, M680x0
60 @cindex @samp{-m[no-]68881} command line option, M680x0
61 @cindex @samp{-m[no-]div} command line option, M680x0
62 @cindex @samp{-m[no-]usp} command line option, M680x0
63 @cindex @samp{-m[no-]float} command line option, M680x0
64 @cindex @samp{-m[no-]mac} command line option, M680x0
65 @cindex @samp{-m[no-]emac} command line option, M680x0
66 @item -m[no-]68851
67 @item -m[no-]68881
68 @item -m[no-]div
69 @item -m[no-]usp
70 @item -m[no-]float
71 @item -m[no-]mac
72 @item -m[no-]emac
74 Enable or disable various architecture specific features.  If a chip
75 or architecture by default supports an option (for instance
76 @option{-march=isaaplus} includes the @option{-mdiv} option),
77 explicitly disabling the option will override the default.
79 @cindex @samp{-l} option, M680x0
80 @item -l
81 You can use the @samp{-l} option to shorten the size of references to undefined
82 symbols.  If you do not use the @samp{-l} option, references to undefined
83 symbols are wide enough for a full @code{long} (32 bits).  (Since
84 @code{@value{AS}} cannot know where these symbols end up, @code{@value{AS}} can
85 only allocate space for the linker to fill in later.  Since @code{@value{AS}}
86 does not know how far away these symbols are, it allocates as much space as it
87 can.)  If you use this option, the references are only one word wide (16 bits).
88 This may be useful if you want the object file to be as small as possible, and
89 you know that the relevant symbols are always less than 17 bits away.
91 @cindex @samp{--register-prefix-optional} option, M680x0
92 @item --register-prefix-optional
93 For some configurations, especially those where the compiler normally
94 does not prepend an underscore to the names of user variables, the
95 assembler requires a @samp{%} before any use of a register name.  This
96 is intended to let the assembler distinguish between C variables and
97 functions named @samp{a0} through @samp{a7}, and so on.  The @samp{%} is
98 always accepted, but is not required for certain configurations, notably
99 @samp{sun3}.  The @samp{--register-prefix-optional} option may be used
100 to permit omitting the @samp{%} even for configurations for which it is
101 normally required.  If this is done, it will generally be impossible to
102 refer to C variables and functions with the same names as register
103 names.
105 @cindex @samp{--bitwise-or} option, M680x0
106 @item --bitwise-or
107 Normally the character @samp{|} is treated as a comment character, which
108 means that it can not be used in expressions.  The @samp{--bitwise-or}
109 option turns @samp{|} into a normal character.  In this mode, you must
110 either use C style comments, or start comments with a @samp{#} character
111 at the beginning of a line.
113 @cindex @samp{--base-size-default-16}
114 @cindex @samp{--base-size-default-32}
115 @item --base-size-default-16  --base-size-default-32 
116 If you use an addressing mode with a base register without specifying
117 the size, @code{@value{AS}} will normally use the full 32 bit value.
118 For example, the addressing mode @samp{%a0@@(%d0)} is equivalent to
119 @samp{%a0@@(%d0:l)}.  You may use the @samp{--base-size-default-16}
120 option to tell @code{@value{AS}} to default to using the 16 bit value.
121 In this case, @samp{%a0@@(%d0)} is equivalent to @samp{%a0@@(%d0:w)}.
122 You may use the @samp{--base-size-default-32} option to restore the
123 default behaviour.
125 @cindex @samp{--disp-size-default-16}
126 @cindex @samp{--disp-size-default-32}
127 @item --disp-size-default-16  --disp-size-default-32
128 If you use an addressing mode with a displacement, and the value of the
129 displacement is not known, @code{@value{AS}} will normally assume that
130 the value is 32 bits.  For example, if the symbol @samp{disp} has not
131 been defined, @code{@value{AS}} will assemble the addressing mode
132 @samp{%a0@@(disp,%d0)} as though @samp{disp} is a 32 bit value.  You may
133 use the @samp{--disp-size-default-16} option to tell @code{@value{AS}}
134 to instead assume that the displacement is 16 bits.  In this case,
135 @code{@value{AS}} will assemble @samp{%a0@@(disp,%d0)} as though
136 @samp{disp} is a 16 bit value.  You may use the
137 @samp{--disp-size-default-32} option to restore the default behaviour.
139 @cindex @samp{--pcrel}
140 @item --pcrel
141 Always keep branches PC-relative.  In the M680x0 architecture all branches
142 are defined as PC-relative.  However, on some processors they are limited
143 to word displacements maximum.  When @code{@value{AS}} needs a long branch
144 that is not available, it normally emits an absolute jump instead.  This
145 option disables this substitution.  When this option is given and no long
146 branches are available, only word branches will be emitted.  An error
147 message will be generated if a word branch cannot reach its target.  This
148 option has no effect on 68020 and other processors that have long branches.
149 @pxref{M68K-Branch,,Branch Improvement}.
151 @cindex @samp{-m68000} and related options
152 @cindex architecture options, M680x0
153 @cindex M680x0 architecture options
154 @item -m68000
155 @code{@value{AS}} can assemble code for several different members of the
156 Motorola 680x0 family.  The default depends upon how @code{@value{AS}}
157 was configured when it was built; normally, the default is to assemble
158 code for the 68020 microprocessor.  The following options may be used to
159 change the default.  These options control which instructions and
160 addressing modes are permitted.  The members of the 680x0 family are
161 very similar.  For detailed information about the differences, see the
162 Motorola manuals.
164 @table @samp
165 @item -m68000
166 @itemx -m68ec000
167 @itemx -m68hc000
168 @itemx -m68hc001
169 @itemx -m68008
170 @itemx -m68302
171 @itemx -m68306
172 @itemx -m68307
173 @itemx -m68322
174 @itemx -m68356
175 Assemble for the 68000. @samp{-m68008}, @samp{-m68302}, and so on are synonyms
176 for @samp{-m68000}, since the chips are the same from the point of view
177 of the assembler.
179 @item -m68010
180 Assemble for the 68010.
182 @item -m68020
183 @itemx -m68ec020
184 Assemble for the 68020.  This is normally the default.
186 @item -m68030
187 @itemx -m68ec030
188 Assemble for the 68030.
190 @item -m68040
191 @itemx -m68ec040
192 Assemble for the 68040.
194 @item -m68060
195 @itemx -m68ec060
196 Assemble for the 68060.
198 @item -mcpu32
199 @itemx -m68330
200 @itemx -m68331
201 @itemx -m68332
202 @itemx -m68333
203 @itemx -m68334
204 @itemx -m68336
205 @itemx -m68340
206 @itemx -m68341
207 @itemx -m68349
208 @itemx -m68360
209 Assemble for the CPU32 family of chips.
211 @item -m5200
212 @item -m5202
213 @item -m5204
214 @item -m5206
215 @item -m5206e
216 @item -m521x
217 @item -m5249
218 @item -m528x
219 @item -m5307
220 @item -m5407
221 @item -m547x
222 @item -m548x
223 @item -mcfv4
224 @item -mcfv4e
225 Assemble for the ColdFire family of chips.
227 @item -m68881
228 @itemx -m68882
229 Assemble 68881 floating point instructions.  This is the default for the
230 68020, 68030, and the CPU32.  The 68040 and 68060 always support
231 floating point instructions.
233 @item -mno-68881
234 Do not assemble 68881 floating point instructions.  This is the default
235 for 68000 and the 68010.  The 68040 and 68060 always support floating
236 point instructions, even if this option is used.
238 @item -m68851
239 Assemble 68851 MMU instructions.  This is the default for the 68020,
240 68030, and 68060.  The 68040 accepts a somewhat different set of MMU
241 instructions; @samp{-m68851} and @samp{-m68040} should not be used
242 together.
244 @item -mno-68851
245 Do not assemble 68851 MMU instructions.  This is the default for the
246 68000, 68010, and the CPU32.  The 68040 accepts a somewhat different set
247 of MMU instructions.
248 @end table
249 @end table
251 @node M68K-Syntax
252 @section Syntax
254 @cindex @sc{mit}
255 This syntax for the Motorola 680x0 was developed at @sc{mit}.
257 @cindex M680x0 syntax
258 @cindex syntax, M680x0
259 @cindex M680x0 size modifiers
260 @cindex size modifiers, M680x0
261 The 680x0 version of @code{@value{AS}} uses instructions names and
262 syntax compatible with the Sun assembler.  Intervening periods are
263 ignored; for example, @samp{movl} is equivalent to @samp{mov.l}.
265 In the following table @var{apc} stands for any of the address registers
266 (@samp{%a0} through @samp{%a7}), the program counter (@samp{%pc}), the
267 zero-address relative to the program counter (@samp{%zpc}), a suppressed
268 address register (@samp{%za0} through @samp{%za7}), or it may be omitted
269 entirely.  The use of @var{size} means one of @samp{w} or @samp{l}, and
270 it may be omitted, along with the leading colon, unless a scale is also
271 specified.  The use of @var{scale} means one of @samp{1}, @samp{2},
272 @samp{4}, or @samp{8}, and it may always be omitted along with the
273 leading colon.
275 @cindex M680x0 addressing modes
276 @cindex addressing modes, M680x0
277 The following addressing modes are understood:
278 @table @dfn
279 @item Immediate
280 @samp{#@var{number}}
282 @item Data Register
283 @samp{%d0} through @samp{%d7}
285 @item Address Register
286 @samp{%a0} through @samp{%a7}@*
287 @samp{%a7} is also known as @samp{%sp}, i.e., the Stack Pointer.  @code{%a6}
288 is also known as @samp{%fp}, the Frame Pointer.
290 @item Address Register Indirect
291 @samp{%a0@@} through @samp{%a7@@}
293 @item Address Register Postincrement
294 @samp{%a0@@+} through @samp{%a7@@+}
296 @item Address Register Predecrement
297 @samp{%a0@@-} through @samp{%a7@@-}
299 @item Indirect Plus Offset
300 @samp{@var{apc}@@(@var{number})}
302 @item Index
303 @samp{@var{apc}@@(@var{number},@var{register}:@var{size}:@var{scale})}
305 The @var{number} may be omitted.
307 @item Postindex
308 @samp{@var{apc}@@(@var{number})@@(@var{onumber},@var{register}:@var{size}:@var{scale})}
310 The @var{onumber} or the @var{register}, but not both, may be omitted.
312 @item Preindex
313 @samp{@var{apc}@@(@var{number},@var{register}:@var{size}:@var{scale})@@(@var{onumber})}
315 The @var{number} may be omitted.  Omitting the @var{register} produces
316 the Postindex addressing mode.
318 @item Absolute
319 @samp{@var{symbol}}, or @samp{@var{digits}}, optionally followed by
320 @samp{:b}, @samp{:w}, or @samp{:l}.
321 @end table
323 @node M68K-Moto-Syntax
324 @section Motorola Syntax
326 @cindex Motorola syntax for the 680x0
327 @cindex alternate syntax for the 680x0
329 The standard Motorola syntax for this chip differs from the syntax
330 already discussed (@pxref{M68K-Syntax,,Syntax}).  @code{@value{AS}} can
331 accept Motorola syntax for operands, even if @sc{mit} syntax is used for
332 other operands in the same instruction.  The two kinds of syntax are
333 fully compatible.
335 In the following table @var{apc} stands for any of the address registers
336 (@samp{%a0} through @samp{%a7}), the program counter (@samp{%pc}), the
337 zero-address relative to the program counter (@samp{%zpc}), or a
338 suppressed address register (@samp{%za0} through @samp{%za7}).  The use
339 of @var{size} means one of @samp{w} or @samp{l}, and it may always be
340 omitted along with the leading dot.  The use of @var{scale} means one of
341 @samp{1}, @samp{2}, @samp{4}, or @samp{8}, and it may always be omitted
342 along with the leading asterisk.
344 The following additional addressing modes are understood:
346 @table @dfn
347 @item Address Register Indirect
348 @samp{(%a0)} through @samp{(%a7)}@* 
349 @samp{%a7} is also known as @samp{%sp}, i.e., the Stack Pointer.  @code{%a6}
350 is also known as @samp{%fp}, the Frame Pointer.
352 @item Address Register Postincrement
353 @samp{(%a0)+} through @samp{(%a7)+}
355 @item Address Register Predecrement
356 @samp{-(%a0)} through @samp{-(%a7)}
358 @item Indirect Plus Offset
359 @samp{@var{number}(@var{%a0})} through @samp{@var{number}(@var{%a7})},
360 or @samp{@var{number}(@var{%pc})}.
362 The @var{number} may also appear within the parentheses, as in
363 @samp{(@var{number},@var{%a0})}.  When used with the @var{pc}, the
364 @var{number} may be omitted (with an address register, omitting the
365 @var{number} produces Address Register Indirect mode).
367 @item Index
368 @samp{@var{number}(@var{apc},@var{register}.@var{size}*@var{scale})}
370 The @var{number} may be omitted, or it may appear within the
371 parentheses.  The @var{apc} may be omitted.  The @var{register} and the
372 @var{apc} may appear in either order.  If both @var{apc} and
373 @var{register} are address registers, and the @var{size} and @var{scale}
374 are omitted, then the first register is taken as the base register, and
375 the second as the index register.
377 @item Postindex
378 @samp{([@var{number},@var{apc}],@var{register}.@var{size}*@var{scale},@var{onumber})}
380 The @var{onumber}, or the @var{register}, or both, may be omitted.
381 Either the @var{number} or the @var{apc} may be omitted, but not both.
383 @item Preindex
384 @samp{([@var{number},@var{apc},@var{register}.@var{size}*@var{scale}],@var{onumber})}
386 The @var{number}, or the @var{apc}, or the @var{register}, or any two of
387 them, may be omitted.  The @var{onumber} may be omitted.  The
388 @var{register} and the @var{apc} may appear in either order.  If both
389 @var{apc} and @var{register} are address registers, and the @var{size}
390 and @var{scale} are omitted, then the first register is taken as the
391 base register, and the second as the index register.
392 @end table
394 @node M68K-Float
395 @section Floating Point
397 @cindex floating point, M680x0
398 @cindex M680x0 floating point
399 Packed decimal (P) format floating literals are not supported.
400 Feel free to add the code!
402 The floating point formats generated by directives are these.
404 @table @code
405 @cindex @code{float} directive, M680x0
406 @item .float
407 @code{Single} precision floating point constants.
409 @cindex @code{double} directive, M680x0
410 @item .double
411 @code{Double} precision floating point constants.
413 @cindex @code{extend} directive M680x0
414 @cindex @code{ldouble} directive M680x0
415 @item .extend
416 @itemx .ldouble
417 @code{Extended} precision (@code{long double}) floating point constants.
418 @end table
420 @node M68K-Directives
421 @section 680x0 Machine Directives
423 @cindex M680x0 directives
424 @cindex directives, M680x0
425 In order to be compatible with the Sun assembler the 680x0 assembler
426 understands the following directives.
428 @table @code
429 @cindex @code{data1} directive, M680x0
430 @item .data1
431 This directive is identical to a @code{.data 1} directive.
433 @cindex @code{data2} directive, M680x0
434 @item .data2
435 This directive is identical to a @code{.data 2} directive.
437 @cindex @code{even} directive, M680x0
438 @item .even
439 This directive is a special case of the @code{.align} directive; it
440 aligns the output to an even byte boundary.
442 @cindex @code{skip} directive, M680x0
443 @item .skip
444 This directive is identical to a @code{.space} directive.
446 @cindex @code{arch} directive, M680x0
447 @item .arch @var{name}
448 Select the target architecture and extension features.  Valid values
449 for @var{name} are the same as for the @option{-march} command line
450 option.  This directive cannot be specified after
451 any instructions have been assembled.  If it is given multiple times,
452 or in conjunction with the @option{-march} option, all uses must be for
453 the same architecture and extension set.
455 @cindex @code{cpu} directive, M680x0
456 @item .cpu @var{name}
457 Select the target cpu.  Valid valuse
458 for @var{name} are the same as for the @option{-mcpu} command line
459 option.  This directive cannot be specified after
460 any instructions have been assembled.  If it is given multiple times,
461 or in conjunction with the @option{-mopt} option, all uses must be for
462 the same cpu.
464 @end table
466 @need 2000
467 @node M68K-opcodes
468 @section Opcodes
470 @cindex M680x0 opcodes
471 @cindex opcodes, M680x0
472 @cindex instruction set, M680x0
473 @c doc@cygnus.com: I don't see any point in the following
474 @c                   paragraph.  Bugs are bugs; how does saying this
475 @c                   help anyone?
476 @ignore
477 Danger:  Several bugs have been found in the opcode table (and
478 fixed).  More bugs may exist.  Be careful when using obscure
479 instructions.
480 @end ignore
482 @menu
483 * M68K-Branch::                 Branch Improvement
484 * M68K-Chars::                  Special Characters
485 @end menu
487 @node M68K-Branch
488 @subsection Branch Improvement
490 @cindex pseudo-opcodes, M680x0
491 @cindex M680x0 pseudo-opcodes
492 @cindex branch improvement, M680x0
493 @cindex M680x0 branch improvement
494 Certain pseudo opcodes are permitted for branch instructions.
495 They expand to the shortest branch instruction that reach the
496 target.  Generally these mnemonics are made by substituting @samp{j} for
497 @samp{b} at the start of a Motorola mnemonic.
499 The following table summarizes the pseudo-operations.  A @code{*} flags
500 cases that are more fully described after the table:
502 @smallexample
503           Displacement
504           +------------------------------------------------------------
505           |                68020           68000/10, not PC-relative OK
506 Pseudo-Op |BYTE    WORD    LONG            ABSOLUTE LONG JUMP    **
507           +------------------------------------------------------------
508      jbsr |bsrs    bsrw    bsrl            jsr
509       jra |bras    braw    bral            jmp
510 *     jXX |bXXs    bXXw    bXXl            bNXs;jmp
511 *    dbXX | N/A    dbXXw   dbXX;bras;bral  dbXX;bras;jmp
512      fjXX | N/A    fbXXw   fbXXl            N/A
514 XX: condition
515 NX: negative of condition XX
517 @end smallexample
518 @center @code{*}---see full description below
519 @center @code{**}---this expansion mode is disallowed by @samp{--pcrel}
521 @table @code
522 @item jbsr
523 @itemx jra
524 These are the simplest jump pseudo-operations; they always map to one
525 particular machine instruction, depending on the displacement to the
526 branch target.  This instruction will be a byte or word branch is that
527 is sufficient.  Otherwise, a long branch will be emitted if available.
528 If no long branches are available and the @samp{--pcrel} option is not
529 given, an absolute long jump will be emitted instead.  If no long
530 branches are available, the @samp{--pcrel} option is given, and a word
531 branch cannot reach the target, an error message is generated.
533 In addition to standard branch operands, @code{@value{AS}} allows these
534 pseudo-operations to have all operands that are allowed for jsr and jmp,
535 substituting these instructions if the operand given is not valid for a
536 branch instruction.
538 @item j@var{XX}
539 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
540 where @var{XX} is a conditional branch or condition-code test.  The full
541 list of pseudo-ops in this family is:
542 @smallexample
543  jhi   jls   jcc   jcs   jne   jeq   jvc
544  jvs   jpl   jmi   jge   jlt   jgt   jle
545 @end smallexample
547 Usually, each of these pseudo-operations expands to a single branch
548 instruction.  However, if a word branch is not sufficient, no long branches
549 are available, and the @samp{--pcrel} option is not given, @code{@value{AS}}
550 issues a longer code fragment in terms of @var{NX}, the opposite condition
551 to @var{XX}.  For example, under these conditions:
552 @smallexample
553     j@var{XX} foo
554 @end smallexample
555 gives
556 @smallexample
557      b@var{NX}s oof
558      jmp foo
559  oof:
560 @end smallexample
562 @item db@var{XX}
563 The full family of pseudo-operations covered here is
564 @smallexample
565  dbhi   dbls   dbcc   dbcs   dbne   dbeq   dbvc
566  dbvs   dbpl   dbmi   dbge   dblt   dbgt   dble
567  dbf    dbra   dbt
568 @end smallexample
570 Motorola @samp{db@var{XX}} instructions allow word displacements only.  When
571 a word displacement is sufficient, each of these pseudo-operations expands
572 to the corresponding Motorola instruction.  When a word displacement is not
573 sufficient and long branches are available, when the source reads
574 @samp{db@var{XX} foo}, @code{@value{AS}} emits
575 @smallexample
576      db@var{XX} oo1
577      bras oo2
578  oo1:bral foo
579  oo2:
580 @end smallexample
582 If, however, long branches are not available and the @samp{--pcrel} option is
583 not given, @code{@value{AS}} emits
584 @smallexample
585      db@var{XX} oo1
586      bras oo2
587  oo1:jmp foo
588  oo2:
589 @end smallexample
591 @item fj@var{XX}
592 This family includes
593 @smallexample
594  fjne   fjeq   fjge   fjlt   fjgt   fjle   fjf
595  fjt    fjgl   fjgle  fjnge  fjngl  fjngle fjngt
596  fjnle  fjnlt  fjoge  fjogl  fjogt  fjole  fjolt
597  fjor   fjseq  fjsf   fjsne  fjst   fjueq  fjuge
598  fjugt  fjule  fjult  fjun
599 @end smallexample
601 Each of these pseudo-operations always expands to a single Motorola
602 coprocessor branch instruction, word or long.  All Motorola coprocessor
603 branch instructions allow both word and long displacements.
605 @end table
607 @node M68K-Chars
608 @subsection Special Characters
610 @cindex special characters, M680x0
611 @cindex M680x0 immediate character
612 @cindex immediate character, M680x0
613 @cindex M680x0 line comment character
614 @cindex line comment character, M680x0
615 @cindex comments, M680x0
616 The immediate character is @samp{#} for Sun compatibility.  The
617 line-comment character is @samp{|} (unless the @samp{--bitwise-or}
618 option is used).  If a @samp{#} appears at the beginning of a line, it
619 is treated as a comment unless it looks like @samp{# line file}, in
620 which case it is treated normally.