gas/doc/c-s12z.texi

   1 @c Copyright (C) 2018-2023 Free Software Foundation, Inc.
   2 @c This is part of the GAS manual.
   3 @c For copying conditions, see the file as.texinfo.
   4 @ifset GENERIC
   5 @page
   6 @node S12Z-Dependent
   7 @chapter   S12Z Dependent Features
   8 @end ifset
   9 @ifclear GENERIC
  10 @node Machine Dependencies
  11 @chapter   S12Z Dependent Features
  12 @end ifclear
  13
  14 The Freescale S12Z version of @code{@value{AS}} has a few machine
  15 dependent features.
  16
  17 @cindex S12Z support
  18 @menu
  19 * S12Z Options::                S12Z Options
  20 * S12Z Syntax::                 Syntax
  21 @end menu
  22
  23 @node S12Z Options
  24 @section S12Z Options
  25
  26 @cindex options, S12Z
  27 @cindex S12Z options
  28
  29 The S12Z version of @code{@value{AS}} recognizes the following options:
  30
  31 @table @samp
  32
  33 @item -mreg-prefix=@var{prefix}
  34 @cindex @samp{-mreg-prefix=@var{prefix}} option, reg-prefix
  35 You can use the @samp{-mreg-prefix=@var{pfx}} option to indicate
  36 that the assembler should expect all register names to be prefixed with the
  37 string @var{pfx}.
  38
  39 For an explanation of what this means and why it might be needed,
  40 see @ref{S12Z Register Notation}.
  41
  42
  43 @item -mdollar-hex
  44 @cindex @samp{-mdollar-hex} option, dollar-hex
  45 @cindex hexadecimal prefix, S12Z
  46 The @samp{-mdollar-hex} option affects the way that literal hexadecimal constants
  47 are represented.  When this option is specified, the assembler will consider
  48 the @samp{$} character as the start of a hexadecimal integer constant.  Without
  49 this option, the standard value of @samp{0x} is expected.
  50
  51 If you use this option, then you cannot have symbol names starting with @samp{$}.
  52 @samp{-mdollar-hex} is implied if the @samp{--traditional-format}
  53 (@pxref{traditional-format}) is used.
  54 @end table
  55
  56 @node S12Z Syntax
  57 @section Syntax
  58
  59
  60 @menu
  61 * S12Z Syntax Overview::                  General description
  62 * S12Z Addressing Modes::                 Operands and their semantics
  63 * S12Z Register Notation::                How to refer to registers
  64 @end menu
  65
  66
  67 @cindex S12Z syntax
  68 @cindex syntax, S12Z
  69
  70 @node S12Z Syntax Overview
  71 @subsection Overview
  72
  73 In the S12Z syntax, the instruction name comes first and it may
  74 be followed by one, or by several operands.
  75 In most cases the maximum number of operands is three.
  76 Operands are separated by a comma (@samp{,}).
  77 A comma however does not act as a separator if it appears within parentheses
  78 (@samp{()}) or within square brackets (@samp{[]}).
  79 @code{@value{AS}} will complain if too many, too few or inappropriate operands
  80 are specified for a given instruction.
  81
  82 Some instructions accept and (in certain situations require) a suffix
  83 indicating the size of the operand.
  84 The suffix is separated from the instruction name by a period (@samp{.})
  85 and may be one of @samp{b}, @samp{w}, @samp{p} or @samp{l} indicating
  86 `byte' (a single byte), `word' (2 bytes), `pointer' (3 bytes) or `long' (4 bytes)
  87 respectively.
  88
  89 Example:
  90
  91 @smallexample
  92         bset.b  0xA98, #5
  93         mov.b   #6, 0x2409
  94         ld      d0, #4
  95         mov.l   (d0, x), 0x2409
  96         inc     d0
  97         cmp     d0, #12
  98         blt     *-4
  99         lea     x, 0x2409
 100         st      y,  (1, x)
 101 @end smallexample
 102
 103 @cindex line comment character, S12Z
 104 The presence of a @samp{;} character anywhere
 105 on a line indicates the start of a comment that extends to the end of
 106 that line.
 107
 108 A @samp{*} or a @samp{#} character at the start of a line also
 109 introduces a line comment, but these characters do not work elsewhere
 110 on the line.  If the first character of the line is a @samp{#} then as
 111 well as starting a comment, the line could also be logical line number
 112 directive (@pxref{Comments}) or a preprocessor control command
 113 (@pxref{Preprocessing}).
 114
 115 @cindex line separator, S12Z
 116 @cindex statement separator, S12Z
 117 @cindex S12Z line separator
 118 The S12Z assembler does not currently support a line separator
 119 character.
 120
 121
 122 @node S12Z Addressing Modes
 123 @subsection Addressing Modes
 124 @cindex S12Z addressing modes
 125 @cindex addressing modes, S12Z
 126
 127 The following addressing modes are understood for the S12Z.
 128 @table @dfn
 129 @item Immediate
 130 @samp{#@var{number}}
 131
 132 @item Immediate Bit Field
 133 @samp{#@var{width}:@var{offset}}
 134
 135 Bit field instructions in the immediate mode require the width and offset to
 136 be specified.
 137 The @var{width} parameter specifies the number of bits in the field.
 138 It should be a number in the range [1,32].
 139 @var{Offset} determines the position within the field where the operation
 140 should start.
 141 It should be a number in the range [0,31].
 142
 143 @item Relative
 144 @samp{*@var{symbol}}, or @samp{*[+-]@var{digits}}
 145
 146 Program counter relative addresses have a width of 15 bits.
 147 Thus, they must be within the range [-32768, 32767].
 148
 149 @item Register
 150 @samp{@var{reg}}
 151
 152 @cindex register names, S12Z
 153 Some instructions accept a register as an operand.
 154 In general, @var{reg} may be a
 155 data register (@samp{D0}, @samp{D1} @dots{} @samp{D7}),
 156 the @samp{X} register or the @samp{Y} register.
 157
 158 A few instructions accept as an argument the stack pointer
 159 register (@samp{S}), and/or the program counter (@samp{P}).
 160
 161 Some very special instructions accept arguments which refer to the
 162 condition code register.  For these arguments the  syntax is
 163 @samp{CCR}, @samp{CCH} or @samp{CCL} which refer to the complete
 164 condition code register, the condition code register high byte
 165 and the condition code register low byte respectively.
 166
 167
 168 @item Absolute Direct
 169 @samp{@var{symbol}}, or @samp{@var{digits}}
 170
 171 @item Absolute Indirect
 172 @samp{[@var{symbol}}, or @samp{@var{digits}]}
 173
 174
 175 @item Constant Offset Indexed
 176 @samp{(@var{number},@var{reg})}
 177
 178 @var{Reg} may be either @samp{X}, @samp{Y}, @samp{S} or
 179 @samp{P} or one of the data registers @samp{D0}, @samp{D1} @dots{}
 180 @samp{D7}.
 181 If any of the registers @samp{D2} @dots{} @samp{D5} are specified, then the
 182 register value is treated as a signed value.
 183 Otherwise it is treated as unsigned.
 184 @var{Number} may be any integer in the range [-8388608,8388607].
 185
 186 @item Offset Indexed Indirect
 187 @samp{[@var{number},@var{reg}]}
 188
 189 @var{Reg} may be either @samp{X}, @samp{Y}, @samp{S} or
 190 @samp{P}.
 191 @var{Number} may be any integer in the range [-8388608,8388607].
 192
 193 @item Auto Pre-Increment/Pre-Decrement/Post-Increment/Post-Decrement
 194 @samp{-@var{reg}},
 195 @samp{+@var{reg}},
 196 @samp{@var{reg}-} or
 197 @samp{@var{reg}+}
 198
 199 This addressing mode is typically used to access a value at an address,
 200 and simultaneously to increment/decrement the register pointing to that
 201 address.
 202 Thus @var{reg} may be any of the 24 bit registers @samp{X}, @samp{Y}, or
 203 @samp{S}.
 204 Pre-increment and post-decrement are not available for
 205 register @samp{S} (only post-increment and pre-decrement are available).
 206
 207 @item Register Offset Direct
 208 @samp{(@var{data-reg},@var{reg})}
 209
 210 @var{Reg} can be either @samp{X}, @samp{Y}, or @samp{S}.
 211 @var{Data-reg}
 212 must be one of the data registers @samp{D0}, @samp{D1} @dots{} @samp{D7}.
 213 If any of the registers @samp{D2} @dots{} @samp{D5} are specified, then
 214 the register value is treated as a signed value.
 215 Otherwise it is treated as unsigned.
 216
 217 @item Register Offset Indirect
 218 @samp{[@var{data-reg},@var{reg}]}
 219
 220 @var{Reg} can be either @samp{X} or @samp{Y}.
 221 @var{Data-reg}
 222 must be one of the data registers @samp{D0}, @samp{D1} @dots{} @samp{D7}.
 223 If any of the registers @samp{D2} @dots{} @samp{D5} are specified, then
 224 the register value is treated as a signed value.
 225 Otherwise it is treated as unsigned.
 226 @end table
 227
 228 For example:
 229
 230 @smallexample
 231         trap    #197        ;; Immediate mode
 232         bra     *+49        ;; Relative mode
 233         bra     .L0         ;;     ditto
 234         jmp     0xFE0034    ;; Absolute direct mode
 235         jmp     [0xFD0012]  ;; Absolute indirect mode
 236         inc.b   (4,x)       ;; Constant offset indexed mode
 237         jsr     (45, d0)    ;;     ditto
 238         dec.w   [4,y]       ;; Constant offset indexed indirect mode
 239         clr.p   (-s)        ;; Pre-decrement mode
 240         neg.l   (d0, s)     ;; Register offset direct mode
 241         com.b   [d1, x]     ;; Register offset indirect mode
 242         psh     cch         ;; Register mode
 243 @end smallexample
 244
 245 @node S12Z Register Notation
 246 @subsection Register Notation
 247
 248 @cindex register notation, S12Z
 249 Without a register prefix (@pxref{S12Z Options}), S12Z assembler code is expected in the traditional
 250 format like this:
 251 @smallexample
 252 lea s, (-2,s)
 253 st d2, (0,s)
 254 ld x,  symbol
 255 tfr d2, d6
 256 cmp d6, #1532
 257 @end smallexample
 258
 259 @noindent
 260 However, if @code{@value{AS}} is started with (for example) @samp{-mreg-prefix=%}
 261 then all register names must be prefixed with @samp{%} as follows:
 262 @smallexample
 263 lea %s, (-2,%s)
 264 st %d2, (0,%s)
 265 ld %x,  symbol
 266 tfr %d2, %d6
 267 cmp %d6, #1532
 268 @end smallexample
 269
 270 The register prefix feature is intended to be used by compilers
 271 to avoid ambiguity between symbols and register names.
 272 Consider the following assembler instruction:
 273 @smallexample
 274 st d0, d1
 275 @end smallexample
 276 @noindent
 277 The destination operand of this instruction could either refer to the register
 278 @samp{D1}, or it could refer to the symbol named ``d1''.
 279 If the latter is intended then @code{@value{AS}} must be invoked with
 280 @samp{-mreg-prefix=@var{pfx}} and the code written as
 281 @smallexample
 282 st @var{pfx}d0, d1
 283 @end smallexample
 284 @noindent
 285 where @var{pfx} is the chosen register prefix.
 286 For this reason, compiler back-ends should choose a register prefix which
 287 cannot be confused with a symbol name.