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