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