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