gas/doc/c-z80.texi

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