contrib/binutils-2.24/gas/doc/c-m68hc11.texi

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