gas/doc/c-z80.texi

   1 @c Copyright (C) 2011-2022 Free Software Foundation, Inc.
   2 @c This is part of the GAS manual.
   3 @c For copying conditions, see the file as.texinfo.
   4
   5 @ifset GENERIC
   6 @page
   7 @node Z80-Dependent
   8 @chapter Z80 Dependent Features
   9 @end ifset
  10
  11
  12 @ifclear GENERIC
  13 @node Machine Dependencies
  14 @chapter Z80 Dependent Features
  15 @end ifclear
  16
  17 @cindex Z80 support
  18 @menu
  19 * Z80 Options::              Options
  20 * Z80 Syntax::               Syntax
  21 * Z80 Floating Point::       Floating Point
  22 * Z80 Directives::           Z80 Machine Directives
  23 * Z80 Opcodes::              Opcodes
  24 @end menu
  25
  26 @node Z80 Options
  27 @section Command-line Options
  28 @cindex Z80 options
  29 @cindex options for Z80
  30 @c man begin OPTIONS
  31 @table @gcctabopt
  32
  33 @cindex @code{-march=} command-line option, Z80
  34 @item -march=@var{CPU}[-@var{EXT}@dots{}][+@var{EXT}@dots{}]
  35 This option specifies the target processor. The assembler will issue
  36 an error message if an attempt is made to assemble an instruction which
  37 will not execute on the target processor. The following processor names
  38 are recognized:
  39 @code{z80},
  40 @code{z180},
  41 @code{ez80},
  42 @code{gbz80},
  43 @code{z80n},
  44 @code{r800}.
  45 In addition to the basic instruction set, the assembler can be told to
  46 accept some extention mnemonics. For example,
  47 @code{-march=z180+sli+infc} extends @var{z180} with @var{SLI} instructions and
  48 @var{IN F,(C)}. The following extentions are currently supported:
  49 @code{full} (all known instructions),
  50 @code{adl} (ADL CPU mode by default, eZ80 only),
  51 @code{sli} (instruction known as @var{SLI}, @var{SLL} or @var{SL1}),
  52 @code{xyhl} (instructions with halves of index registers: @var{IXL}, @var{IXH},
  53 @var{IYL}, @var{IYH}),
  54 @code{xdcb} (instructions like @var{RotOp (II+d),R} and @var{BitOp n,(II+d),R}),
  55 @code{infc} (instruction @var{IN F,(C)} or @var{IN (C)}),
  56 @code{outc0} (instruction @var{OUT (C),0}).
  57 Note that rather than extending a basic instruction set, the extention
  58 mnemonics starting with @code{-} revoke the respective functionality:
  59 @code{-march=z80-full+xyhl} first removes all default extentions and adds
  60 support for index registers halves only.
  61
  62 If this option is not specified then @code{-march=z80+xyhl+infc} is assumed.
  63
  64 @cindex @code{-local-prefix} command-line option, Z80
  65 @item  -local-prefix=@var{prefix}
  66 Mark all labels with specified prefix as local. But such label can be
  67 marked global explicitly in the code. This option do not change default
  68 local label prefix @code{.L}, it is just adds new one.
  69
  70 @cindex @code{-colonless} command-line option, Z80
  71 @item  -colonless
  72 Accept colonless labels. All symbols at line begin are treated as labels.
  73
  74 @cindex @code{-sdcc} command-line option, Z80
  75 @item  -sdcc
  76 Accept assembler code produced by SDCC.
  77
  78 @cindex @code{-fp-s} command-line option, Z80
  79 @item -fp-s=@var{FORMAT}
  80 Single precision floating point numbers format. Default: ieee754 (32 bit).
  81
  82 @cindex @code{-fp-d} command-line option, Z80
  83 @item -fp-d=@var{FORMAT}
  84 Double precision floating point numbers format. Default: ieee754 (64 bit).
  85 @end table
  86 @c man end
  87
  88 Floating point numbers formats.
  89 @table @option
  90 @item @code{ieee754}
  91 Single or double precision IEEE754 compatible format.
  92
  93 @item @code{half}
  94 Half precision IEEE754 compatible format (16 bits).
  95
  96 @item @code{single}
  97 Single precision IEEE754 compatible format (32 bits).
  98
  99 @item @code{double}
 100 Double precision IEEE754 compatible format (64 bits).
 101
 102 @item @code{zeda32}
 103 32 bit floating point format from z80float library by Zeda.
 104
 105 @item @code{math48}
 106 48 bit floating point format from Math48 package by Anders Hejlsberg.
 107 @end table
 108
 109 @cindex Z80 Syntax
 110 @node Z80 Syntax
 111 @section Syntax
 112 The assembler syntax closely follows the 'Z80 family CPU User Manual' by
 113 Zilog.
 114 In expressions a single @samp{=} may be used as ``is equal to''
 115 comparison operator.
 116
 117 Suffices can be used to indicate the radix of integer constants;
 118 @samp{H} or @samp{h} for hexadecimal, @samp{D} or @samp{d} for decimal,
 119 @samp{Q}, @samp{O}, @samp{q} or @samp{o} for octal, and @samp{B} for
 120 binary.
 121
 122 The suffix @samp{b} denotes a backreference to local label.
 123
 124 @menu
 125 * Z80-Chars::                Special Characters
 126 * Z80-Regs::                 Register Names
 127 * Z80-Case::                 Case Sensitivity
 128 * Z80-Labels::               Labels
 129 @end menu
 130
 131 @node Z80-Chars
 132 @subsection Special Characters
 133
 134 @cindex line comment character, Z80
 135 @cindex Z80 line comment character
 136 The semicolon @samp{;} is the line comment character;
 137
 138 If a @samp{#} appears as the first character of a line then the whole
 139 line is treated as a comment, but in this case the line could also be
 140 a logical line number directive (@pxref{Comments}) or a preprocessor
 141 control command (@pxref{Preprocessing}).
 142
 143 @cindex line separator, Z80
 144 @cindex statement separator, Z80
 145 @cindex Z80 line separator
 146 The Z80 assembler does not support a line separator character.
 147
 148 @cindex location counter, Z80
 149 @cindex hexadecimal prefix, Z80
 150 @cindex Z80 $
 151 The dollar sign @samp{$} can be used as a prefix for hexadecimal numbers
 152 and as a symbol denoting the current location counter.
 153
 154 @cindex character escapes, Z80
 155 @cindex Z80, \
 156 A backslash @samp{\} is an ordinary character for the Z80 assembler.
 157
 158 @cindex character constant, Z80
 159 @cindex single quote, Z80
 160 @cindex Z80 '
 161 The single quote @samp{'} must be followed by a closing quote. If there
 162 is one character in between, it is a character constant, otherwise it is
 163 a string constant.
 164
 165 @node Z80-Regs
 166 @subsection Register Names
 167 @cindex Z80 registers
 168 @cindex register names, Z80
 169
 170 The registers are referred to with the letters assigned to them by
 171 Zilog. In addition @command{@value{AS}} recognizes @samp{ixl} and
 172 @samp{ixh} as the least and most significant octet in @samp{ix}, and
 173 similarly @samp{iyl} and  @samp{iyh} as parts of @samp{iy}.
 174
 175 @c The @samp{'} in @samp{ex af,af'} may be omitted.
 176
 177 @node Z80-Case
 178 @subsection Case Sensitivity
 179 @cindex Z80, case sensitivity
 180 @cindex case sensitivity, Z80
 181
 182 Upper and lower case are equivalent in register names, opcodes,
 183 condition codes  and assembler directives.
 184 The case of letters is significant in labels and symbol names. The case
 185 is also important to distinguish the suffix @samp{b} for a backward reference
 186 to a local label from the suffix @samp{B} for a number in binary notation.
 187
 188 @node Z80-Labels
 189 @subsection Labels
 190
 191 @cindex labels, Z80
 192 @cindex Z80 labels
 193 Labels started by @code{.L} acts as local labels. You may specify custom local
 194 label prefix by @code{-local-prefix} command-line option.
 195 Dollar, forward and backward local labels are supported. By default, all labels
 196 are followed by colon.
 197 Legacy code with colonless labels can be built with @code{-colonless}
 198 command-line option specified. In this case all tokens at line begin are treated
 199 as labels.
 200
 201 @node Z80 Floating Point
 202 @section Floating Point
 203 @cindex floating point, Z80
 204 @cindex Z80 floating point
 205 Floating-point numbers of following types are supported:
 206
 207 @table @option
 208 @item @code{ieee754}
 209 Supported half, single and double precision IEEE754 compatible numbers.
 210
 211 @item @code{zeda32}
 212 32 bit floating point numbers from z80float library by Zeda.
 213
 214 @item @code{math48}
 215 48 bit floating point numbers from Math48 package by Anders Hejlsberg.
 216 @end table
 217
 218 @node Z80 Directives
 219 @section Z80 Assembler Directives
 220 @cindex Z80-only directives
 221
 222 @command{@value{AS}} for the Z80 supports some additional directives for
 223 compatibility with other assemblers.
 224
 225 These are the additional directives in @code{@value{AS}} for the Z80:
 226
 227 @table @code
 228 @item @code{.assume ADL = @var{expression}}
 229 @cindex @code{.assume} directive, Z80
 230 Set ADL status for eZ80. Non-zero value enable compilation in ADL mode else
 231 used Z80 mode. ADL and Z80 mode produces incompatible object code. Mixing
 232 both of them within one binary may lead problems with disassembler.
 233
 234 @item @code{db @var{expression}|@var{string}[,@var{expression}|@var{string}...]}
 235 @cindex @code{db} directive, Z80
 236 @itemx @code{defb @var{expression}|@var{string}[,@var{expression}|@var{string}...]}
 237 @cindex @code{defb} directive, Z80
 238 @itemx @code{defm @var{string}[,@var{string}...]}
 239 @cindex @code{defm} directive, Z80
 240 For each @var{string} the characters are copied to the object file, for
 241 each other @var{expression} the value is stored in one byte.
 242 A warning is issued in case of an overflow.
 243 Backslash symbol in the strings is generic symbol, it cannot be used as
 244 escape character.  @xref{Ascii,,@code{.ascii}}.
 245
 246 @item @code{dw @var{expression}[,@var{expression}...]}
 247 @cindex @code{dw} directive, Z80
 248 @itemx @code{defw @var{expression}[,@var{expression}...]}
 249 @cindex @code{defw} directive, Z80
 250 For each @var{expression} the value is stored in two bytes, ignoring
 251 overflow.
 252
 253 @item @code{d24 @var{expression}[,@var{expression}...]}
 254 @cindex @code{d24} directive, Z80
 255 @itemx @code{def24 @var{expression}[,@var{expression}...]}
 256 @cindex @code{def24} directive, Z80
 257 For each @var{expression} the value is stored in three bytes, ignoring
 258 overflow.
 259
 260 @item @code{d32 @var{expression}[,@var{expression}...]}
 261 @cindex @code{d32} directive, Z80
 262 @itemx @code{def32 @var{expression}[,@var{expression}...]}
 263 @cindex @code{def32} directive, Z80
 264 For each @var{expression} the value is stored in four bytes, ignoring
 265 overflow.
 266
 267 @item @code{ds @var{count}[, @var{value}]}
 268 @cindex @code{ds} directive, Z80
 269 @itemx @code{defs @var{count}[, @var{value}]}
 270 @cindex @code{defs} directive, Z80
 271 @c Synonyms for @code{ds.b},
 272 @c which should have been described elsewhere
 273 Fill @var{count} bytes in the object file with @var{value}, if
 274 @var{value} is omitted it defaults to zero.
 275
 276 @item @code{@var{symbol} defl @var{expression}}
 277 @cindex @code{defl} directive, Z80
 278 The @code{defl} directive is like @code{.set} but with different
 279 syntax.  @xref{Set,,@code{.set}}.
 280 It set the value of @var{symbol} to @var{expression}. Symbols defined
 281 with @code{defl} are not protected from redefinition.
 282
 283 @item @code{@var{symbol} equ @var{expression}}
 284 @cindex @code{equ} directive, Z80
 285 The @code{equ} directive is like @code{.equiv} but with different
 286 syntax.  @xref{Equiv, ,@code{.equiv}}.
 287 It set the value of @var{symbol} to @var{expression}. It is an error
 288 if @var{symbol} is already defined. Symbols defined with @code{equ}
 289 are not protected from redefinition.
 290
 291 @item @code{psect @var{name}}
 292 @cindex @code{psect} directive, Z80
 293 A synonym for @code{.section}, no second argument should be given.
 294 @xref{Section,,@code{.section}}.
 295
 296 @item @code{xdef @var{symbol}}
 297 @cindex @code{xdef} directive, Z80
 298 A synonym for @code{.global}, make @var{symbol} is visible to linker.
 299 @xref{Global,,@code{.global}}.
 300
 301 @item @code{xref @var{name}}
 302 @cindex @code{xref} directive, Z80
 303 A synonym for @code{.extern} (@ref{Extern,,@code{.extern}}).
 304 @ignore
 305
 306 The following attributes will possibly be recognized in the future
 307 @table @code
 308 @item abs
 309 The section is to be absolute. @code{@value{AS}} will issue an error
 310 message because it can not produce an absolute section.
 311 @item global
 312 The section is to be concatenated with other sections of the same name
 313 by the linker, this is the default.
 314 @item local
 315 The section is not global. @code{@value{AS}} will issue a warning if
 316 object file format is not soff.
 317 @item ovrld
 318 The section is to be overlapped with other sections of the same name by
 319 the linker. @code{@value{AS}} will issue an error message
 320 because it can not mark a section as such.
 321 @item pure
 322 The section is marked as read only.
 323 @end table
 324 @end ignore
 325
 326 @end table
 327
 328 @node Z80 Opcodes
 329 @section Opcodes
 330 In line with common practice, Z80 mnemonics are used for the Z80,
 331 Z80N, Z180, eZ80, Ascii R800 and the GameBoy Z80.
 332
 333 In many instructions it is possible to use one of the half index
 334 registers (@samp{ixl},@samp{ixh},@samp{iyl},@samp{iyh}) in stead of an
 335 8-bit general purpose register. This yields instructions that are
 336 documented on the eZ80 and the R800, undocumented on the Z80 and
 337 unsupported on the Z180.
 338 Similarly @code{in f,(c)} is documented on the R800, undocumented on
 339 the Z80 and unsupported on the Z180 and the eZ80.
 340
 341 The assembler also supports the following undocumented Z80-instructions,
 342 that have not been adopted in any other instruction set:
 343 @table @code
 344 @item out (c),0
 345 Sends zero to the port pointed to by register @code{C}.
 346
 347 @item sli @var{m}
 348 Equivalent to @code{@var{m} = (@var{m}<<1)+1}, the operand @var{m} can
 349 be any operand that is valid for @samp{sla}. One can use @samp{sll} as a
 350 synonym for @samp{sli}.
 351
 352 @item @var{op} (ix+@var{d}), @var{r}
 353 This is equivalent to
 354
 355 @example
 356 ld @var{r}, (ix+@var{d})
 357 @var{op} @var{r}
 358 ld (ix+@var{d}), @var{r}
 359 @end example
 360
 361 The operation @samp{@var{op}} may be any of @samp{res @var{b},},
 362 @samp{set @var{b},}, @samp{rl}, @samp{rlc}, @samp{rr}, @samp{rrc},
 363 @samp{sla}, @samp{sli}, @samp{sra} and @samp{srl}, and the register
 364 @samp{@var{r}} may be any of @samp{a}, @samp{b}, @samp{c}, @samp{d},
 365 @samp{e}, @samp{h} and @samp{l}.
 366
 367 @item @var{op} (iy+@var{d}), @var{r}
 368 As above, but with @samp{iy} instead of @samp{ix}.
 369 @end table
 370
 371 The web site at @uref{http://www.z80.info} is a good starting place to
 372 find more information on programming the Z80.
 373
 374 You may enable or disable any of these instructions for any target CPU
 375 even this instruction is not supported by any real CPU of this type.
 376 Useful for custom CPU cores.