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 @cindex @code{-z80} command-line option, Z80
  33 @item -z80
  34 Produce code for the Zilog Z80 processor. By default accepted undocumented
  35 operations with halves of index registers (@code{IXL}, @code{IXH}, @code{IYL},
  36 @code{IYH}) and instuction @code{IN F,(C)}. Other useful undocumented
  37 instructions produces warnings. Undocumented instructions may not work on some
  38 CPUs, use them on your own risk.
  39
  40 @cindex @code{-r800} command-line option, Z80
  41 @item -r800
  42 Produce code for the Ascii R800 processor.
  43
  44 @cindex @code{-z180} command-line option, Z80
  45 @item -z180
  46 Produce code for the Zilog Z180 processor.
  47
  48 @cindex @code{-ez80} command-line option, Z80
  49 @item -ez80
  50 Produce code for the eZ80 processor in Z80 memory mode by default.
  51
  52 @cindex @code{-ez80-adl} command-line option, Z80
  53 @item -ez80-adl
  54 Produce code for the eZ80 processor in ADL memory mode by default.
  55
  56 @cindex @code{-gbz80} command-line option, Z80
  57 @item -gbz80
  58 Produce code for the GameBoy Z80 processor.
  59
  60 @cindex @code{-z80n} command-line option, Z80
  61 @item -z80n
  62 Produce code for the Z80N processor.
  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 names 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
  86 @cindex @code{-strict} command-line option, Z80
  87 @item  -strict
  88 Accept documented instructions only.
  89
  90 @cindex @code{-full} command-line option, Z80
  91 @item  -full
  92 Accept all known Z80 instructions.
  93
  94 @item  -with-inst=@var{INST}[,...]
  95 @itemx -Wnins @var{INST}[,...]
  96 Enable specified undocumented instruction(s).
  97
  98 @item  -without-inst=@var{INST}[,...]
  99 @itemx -Fins @var{INST}[,...]
 100 Disable specified undocumented instruction(s).
 101
 102 @item  -ignore-undocumented-instructions
 103 @itemx -Wnud
 104 Silently assemble undocumented Z80-instructions that have been adopted
 105 as documented R800-instructions .
 106 @item  -ignore-unportable-instructions
 107 @itemx -Wnup
 108 Silently assemble all undocumented Z80-instructions.
 109 @item  -warn-undocumented-instructions
 110 @itemx -Wud
 111 Issue warnings for undocumented Z80-instructions that work on R800, do
 112 not assemble other undocumented instructions without warning.
 113 @item  -warn-unportable-instructions
 114 @itemx -Wup
 115 Issue warnings for other undocumented Z80-instructions, do not treat any
 116 undocumented instructions as errors.
 117 @item  -forbid-undocumented-instructions
 118 @itemx -Fud
 119 Treat all undocumented z80-instructions as errors.
 120 @item  -forbid-unportable-instructions
 121 @itemx -Fup
 122 Treat undocumented z80-instructions that do not work on R800 as errors.
 123 @end table
 124 @c man end
 125
 126 Floating point numbers formats.
 127 @table @option
 128 @item @code{ieee754}
 129 Single or double precision IEEE754 compatible format.
 130
 131 @item @code{half}
 132 Half precision IEEE754 compatible format (16 bits).
 133
 134 @item @code{single}
 135 Single precision IEEE754 compatible format (32 bits).
 136
 137 @item @code{double}
 138 Double precision IEEE754 compatible format (64 bits).
 139
 140 @item @code{zeda32}
 141 32 bit floating point format from z80float library by Zeda.
 142
 143 @item @code{math48}
 144 48 bit floating point format from Math48 package by Anders Hejlsberg.
 145 @end table
 146
 147 Known undocumented instructions.
 148 @table @option
 149 @cindex Known undocumented instructions
 150 @item  @code{idx-reg-halves}
 151 All operations with halves of index registers (@code{IXL}, @code{IXH}, @code{IYL}, @code{IYH}).
 152 @item  @code{sli}
 153 @code{SLI} or @code{SLL} instruction. Same as @code{SLA r; INC r}.
 154 @item  @code{op-ii-ld}
 155 Istructions like @code{<op> (<ii>+<d>),<r>}. For example: @code{RL (IX+5),C}
 156 @item @code{in-f-c}
 157 Instruction @code{IN F,(C)}.
 158 @item @code{out-c-0}
 159 Instruction @code{OUT (C),0}
 160 @end table
 161
 162 @cindex Z80 Syntax
 163 @node Z80 Syntax
 164 @section Syntax
 165 The assembler syntax closely follows the 'Z80 family CPU User Manual' by
 166 Zilog.
 167 In expressions a single @samp{=} may be used as ``is equal to''
 168 comparison operator.
 169
 170 Suffices can be used to indicate the radix of integer constants;
 171 @samp{H} or @samp{h} for hexadecimal, @samp{D} or @samp{d} for decimal,
 172 @samp{Q}, @samp{O}, @samp{q} or @samp{o} for octal, and @samp{B} for
 173 binary.
 174
 175 The suffix @samp{b} denotes a backreference to local label.
 176
 177 @menu
 178 * Z80-Chars::                Special Characters
 179 * Z80-Regs::                 Register Names
 180 * Z80-Case::                 Case Sensitivity
 181 * Z80-Labels::               Labels
 182 @end menu
 183
 184 @node Z80-Chars
 185 @subsection Special Characters
 186
 187 @cindex line comment character, Z80
 188 @cindex Z80 line comment character
 189 The semicolon @samp{;} is the line comment character;
 190
 191 If a @samp{#} appears as the first character of a line then the whole
 192 line is treated as a comment, but in this case the line could also be
 193 a logical line number directive (@pxref{Comments}) or a preprocessor
 194 control command (@pxref{Preprocessing}).
 195
 196 @cindex line separator, Z80
 197 @cindex statement separator, Z80
 198 @cindex Z80 line separator
 199 The Z80 assembler does not support a line separator character.
 200
 201 @cindex location counter, Z80
 202 @cindex hexadecimal prefix, Z80
 203 @cindex Z80 $
 204 The dollar sign @samp{$} can be used as a prefix for hexadecimal numbers
 205 and as a symbol denoting the current location counter.
 206
 207 @cindex character escapes, Z80
 208 @cindex Z80, \
 209 A backslash @samp{\} is an ordinary character for the Z80 assembler.
 210
 211 @cindex character constant, Z80
 212 @cindex single quote, Z80
 213 @cindex Z80 '
 214 The single quote @samp{'} must be followed by a closing quote. If there
 215 is one character in between, it is a character constant, otherwise it is
 216 a string constant.
 217
 218 @node Z80-Regs
 219 @subsection Register Names
 220 @cindex Z80 registers
 221 @cindex register names, Z80
 222
 223 The registers are referred to with the letters assigned to them by
 224 Zilog. In addition @command{@value{AS}} recognizes @samp{ixl} and
 225 @samp{ixh} as the least and most significant octet in @samp{ix}, and
 226 similarly @samp{iyl} and  @samp{iyh} as parts of @samp{iy}.
 227
 228 @c The @samp{'} in @samp{ex af,af'} may be omitted.
 229
 230 @node Z80-Case
 231 @subsection Case Sensitivity
 232 @cindex Z80, case sensitivity
 233 @cindex case sensitivity, Z80
 234
 235 Upper and lower case are equivalent in register names, opcodes,
 236 condition codes  and assembler directives.
 237 The case of letters is significant in labels and symbol names. The case
 238 is also important to distinguish the suffix @samp{b} for a backward reference
 239 to a local label from the suffix @samp{B} for a number in binary notation.
 240
 241 @node Z80-Labels
 242 @subsection Labels
 243
 244 @cindex labels, Z80
 245 @cindex Z80 labels
 246 Labels started by @code{.L} acts as local labels. You may specify custom local
 247 label prefix by @code{-local-prefix} command-line option.
 248 Dollar, forward and backward local labels are supported. By default, all labels
 249 are followed by colon.
 250 Legacy code with colonless labels can be built with @code{-colonless}
 251 command-line option specified. In this case all tokens at line begin are treated
 252 as labels.
 253
 254 @node Z80 Floating Point
 255 @section Floating Point
 256 @cindex floating point, Z80
 257 @cindex Z80 floating point
 258 Floating-point numbers of following types are supported:
 259
 260 @table @option
 261 @item @code{ieee754}
 262 Supported half, single and double precision IEEE754 compatible numbers.
 263
 264 @item @code{zeda32}
 265 32 bit floating point numbers from z80float library by Zeda.
 266
 267 @item @code{math48}
 268 48 bit floating point numbers from Math48 package by Anders Hejlsberg.
 269 @end table
 270
 271 @node Z80 Directives
 272 @section Z80 Assembler Directives
 273
 274 @command{@value{AS}} for the Z80 supports some additional directives for
 275 compatibility with other assemblers.
 276
 277 @cindex Z80-only directives
 278 These are the additional directives in @code{@value{AS}} for the Z80:
 279
 280 @table @code
 281 @item assume @var{ADL}@samp{=}@var{expression}
 282 Set ADL status for eZ80. Non-zero value enable compilation in ADL mode else
 283 used Z80 mode. ADL and Z80 mode produces incompatible object code. Mixing
 284 both of them within one binary may lead problems with disassembler.
 285
 286 @item db @var{expression}|@var{string}[,@var{expression}|@var{string}...]
 287 @itemx defb @var{expression}|@var{string}[,@var{expression}|@var{string}...]
 288 @itemx defm @var{string}...]
 289 For each @var{string} the characters are copied to the object file, for
 290 each other @var{expression} the value is stored in one byte.
 291 A warning is issued in case of an overflow.
 292 Backslash symbol in the strings is generic symbol, it cannot be used as
 293 escape character (for this purpose use @code{.ascii} or @code{.asciiz}
 294 directives).
 295
 296 @item dw @var{expression}[,@var{expression}...]
 297 @itemx defw @var{expression}[,@var{expression}...]
 298 For each @var{expression} the value is stored in two bytes, ignoring
 299 overflow.
 300
 301 @item d24 @var{expression}[,@var{expression}...]
 302 @itemx def24 @var{expression}[,@var{expression}...]
 303 For each @var{expression} the value is stored in three bytes, ignoring
 304 overflow.
 305
 306 @item d32 @var{expression}[,@var{expression}...]
 307 @itemx def32 @var{expression}[,@var{expression}...]
 308 For each @var{expression} the value is stored in four bytes, ignoring
 309 overflow.
 310
 311 @item ds @var{count}[, @var{value}]
 312 @itemx defs @var{count}[, @var{value}]
 313 @c Synonyms for @code{ds.b},
 314 @c which should have been described elsewhere
 315 Fill @var{count} bytes in the object file with @var{value}, if
 316 @var{value} is omitted it defaults to zero.
 317
 318 @item @var{symbol} equ @var{expression}
 319 @itemx @var{symbol} defl @var{expression}
 320 These directives set the value of @var{symbol} to @var{expression}. If
 321 @code{equ} is used, it is an error if @var{symbol} is already defined.
 322 Symbols defined with @code{equ} are not protected from redefinition.
 323
 324 @item psect @var{name}
 325 A synonym for @xref{Section}, no second argument should be given.
 326 @ignore
 327
 328 The following attributes will possibly be recognized in the future
 329 @table @code
 330 @item abs
 331 The section is to be absolute. @code{@value{AS}} will issue an error
 332 message because it can not produce an absolute section.
 333 @item global
 334 The section is to be concatenated with other sections of the same name
 335 by the linker, this is the default.
 336 @item local
 337 The section is not global. @code{@value{AS}} will issue a warning if
 338 object file format is not soff.
 339 @item ovrld
 340 The section is to be overlapped with other sections of the same name by
 341 the linker. @code{@value{AS}} will issue an error message
 342 because it can not mark a section as such.
 343 @item pure
 344 The section is marked as read only.
 345 @end table
 346 @end ignore
 347
 348 @end table
 349
 350 @node Z80 Opcodes
 351 @section Opcodes
 352 In line with common practice, Z80 mnemonics are used for the Z80,
 353 the Z180, eZ80 and the R800.
 354
 355 In many instructions it is possible to use one of the half index
 356 registers (@samp{ixl},@samp{ixh},@samp{iyl},@samp{iyh}) in stead of an
 357 8-bit general purpose register. This yields instructions that are
 358 documented on the eZ80 and the R800, undocumented on the Z80 and
 359 unsupported on the Z180.
 360 Similarly @code{in f,(c)} is documented on the R800, undocumented on
 361 the Z80 and unsupported on the Z180 and the eZ80.
 362
 363 The assembler also supports the following undocumented Z80-instructions,
 364 that have not been adopted in any other instruction set:
 365 @table @code
 366 @item out (c),0
 367 Sends zero to the port pointed to by register @code{C}.
 368
 369 @item sli @var{m}
 370 Equivalent to @code{@var{m} = (@var{m}<<1)+1}, the operand @var{m} can
 371 be any operand that is valid for @samp{sla}. One can use @samp{sll} as a
 372 synonym for @samp{sli}.
 373
 374 @item @var{op} (ix+@var{d}), @var{r}
 375 This is equivalent to
 376
 377 @example
 378 ld @var{r}, (ix+@var{d})
 379 @var{opc} @var{r}
 380 ld (ix+@var{d}), @var{r}
 381 @end example
 382
 383 The operation @samp{@var{opc}} may be any of @samp{res @var{b},},
 384 @samp{set @var{b},}, @samp{rl}, @samp{rlc}, @samp{rr}, @samp{rrc},
 385 @samp{sla}, @samp{sli}, @samp{sra} and @samp{srl}, and the register
 386 @samp{@var{r}} may be any of @samp{a}, @samp{b}, @samp{c}, @samp{d},
 387 @samp{e}, @samp{h} and @samp{l}.
 388
 389 @item @var{opc} (iy+@var{d}), @var{r}
 390 As above, but with @samp{iy} instead of @samp{ix}.
 391 @end table
 392
 393 The web site at @uref{http://www.z80.info} is a good starting place to
 394 find more information on programming the Z80.
 395
 396 You may enable or disable any of these instructions for any target CPU
 397 even this instruction is not supported by any real CPU of this type.
 398 Useful for custom CPU cores.