| 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 @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 syntax (@xref{Set,,@code{.set}}). |
| 279 | It set the value of @var{symbol} to @var{expression}. Symbols defined |
| 280 | with @code{defl} are not protected from redefinition. |
| 281 | |
| 282 | @item @code{@var{symbol} equ @var{expression}} |
| 283 | @cindex @code{equ} directive, Z80 |
| 284 | The @code{equ} directive is like @code{.equiv} but with different syntax (@xref{Equiv,,@code{.equiv}}). |
| 285 | It set the value of @var{symbol} to @var{expression}. It is an error |
| 286 | if @var{symbol} is already defined. Symbols defined with @code{equ} |
| 287 | are not protected from redefinition. |
| 288 | |
| 289 | @item @code{psect @var{name}} |
| 290 | @cindex @code{psect} directive, Z80 |
| 291 | A synonym for @code{.section}, no second argument should be given (@xref{Section,,@code{.section}}). |
| 292 | |
| 293 | @item @code{xdef @var{symbol}} |
| 294 | @cindex @code{xdef} directive, Z80 |
| 295 | A synonym for @code{.global}, make @var{symbol} is visible to linker (@xref{Global,,@code{.global}}). |
| 296 | |
| 297 | @item @code{xref @var{name}} |
| 298 | @cindex @code{xref} directive, Z80 |
| 299 | A synonym for @code{.extern} (@ref{Extern,,@code{.extern}}). |
| 300 | @ignore |
| 301 | |
| 302 | The following attributes will possibly be recognized in the future |
| 303 | @table @code |
| 304 | @item abs |
| 305 | The section is to be absolute. @code{@value{AS}} will issue an error |
| 306 | message because it can not produce an absolute section. |
| 307 | @item global |
| 308 | The section is to be concatenated with other sections of the same name |
| 309 | by the linker, this is the default. |
| 310 | @item local |
| 311 | The section is not global. @code{@value{AS}} will issue a warning if |
| 312 | object file format is not soff. |
| 313 | @item ovrld |
| 314 | The section is to be overlapped with other sections of the same name by |
| 315 | the linker. @code{@value{AS}} will issue an error message |
| 316 | because it can not mark a section as such. |
| 317 | @item pure |
| 318 | The section is marked as read only. |
| 319 | @end table |
| 320 | @end ignore |
| 321 | |
| 322 | @end table |
| 323 | |
| 324 | @node Z80 Opcodes |
| 325 | @section Opcodes |
| 326 | In line with common practice, Z80 mnemonics are used for the Z80, |
| 327 | Z80N, Z180, eZ80, Ascii R800 and the GameBoy Z80. |
| 328 | |
| 329 | In many instructions it is possible to use one of the half index |
| 330 | registers (@samp{ixl},@samp{ixh},@samp{iyl},@samp{iyh}) in stead of an |
| 331 | 8-bit general purpose register. This yields instructions that are |
| 332 | documented on the eZ80 and the R800, undocumented on the Z80 and |
| 333 | unsupported on the Z180. |
| 334 | Similarly @code{in f,(c)} is documented on the R800, undocumented on |
| 335 | the Z80 and unsupported on the Z180 and the eZ80. |
| 336 | |
| 337 | The assembler also supports the following undocumented Z80-instructions, |
| 338 | that have not been adopted in any other instruction set: |
| 339 | @table @code |
| 340 | @item out (c),0 |
| 341 | Sends zero to the port pointed to by register @code{C}. |
| 342 | |
| 343 | @item sli @var{m} |
| 344 | Equivalent to @code{@var{m} = (@var{m}<<1)+1}, the operand @var{m} can |
| 345 | be any operand that is valid for @samp{sla}. One can use @samp{sll} as a |
| 346 | synonym for @samp{sli}. |
| 347 | |
| 348 | @item @var{op} (ix+@var{d}), @var{r} |
| 349 | This is equivalent to |
| 350 | |
| 351 | @example |
| 352 | ld @var{r}, (ix+@var{d}) |
| 353 | @var{op} @var{r} |
| 354 | ld (ix+@var{d}), @var{r} |
| 355 | @end example |
| 356 | |
| 357 | The operation @samp{@var{op}} may be any of @samp{res @var{b},}, |
| 358 | @samp{set @var{b},}, @samp{rl}, @samp{rlc}, @samp{rr}, @samp{rrc}, |
| 359 | @samp{sla}, @samp{sli}, @samp{sra} and @samp{srl}, and the register |
| 360 | @samp{@var{r}} may be any of @samp{a}, @samp{b}, @samp{c}, @samp{d}, |
| 361 | @samp{e}, @samp{h} and @samp{l}. |
| 362 | |
| 363 | @item @var{op} (iy+@var{d}), @var{r} |
| 364 | As above, but with @samp{iy} instead of @samp{ix}. |
| 365 | @end table |
| 366 | |
| 367 | The web site at @uref{http://www.z80.info} is a good starting place to |
| 368 | find more information on programming the Z80. |
| 369 | |
| 370 | You may enable or disable any of these instructions for any target CPU |
| 371 | even this instruction is not supported by any real CPU of this type. |
| 372 | Useful for custom CPU cores. |