aboutsummaryrefslogtreecommitdiff
path: root/gas/doc/c-z80.texi
blob: e768e38c7ae89e168624608e630e227f73222eee (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
@c Copyright (C) 2011-2020 Free Software Foundation, Inc.
@c This is part of the GAS manual.
@c For copying conditions, see the file as.texinfo.

@ifset GENERIC
@page
@node Z80-Dependent
@chapter Z80 Dependent Features
@end ifset


@ifclear GENERIC
@node Machine Dependencies
@chapter Z80 Dependent Features
@end ifclear

@cindex Z80 support
@menu
* Z80 Options::              Options
* Z80 Syntax::               Syntax
* Z80 Floating Point::       Floating Point
* Z80 Directives::           Z80 Machine Directives
* Z80 Opcodes::              Opcodes
@end menu

@node Z80 Options
@section Command-line Options
@cindex Z80 options
@cindex options for Z80
@c man begin OPTIONS
@table @gcctabopt
@cindex @code{-z80} command-line option, Z80
@item -z80
Produce code for the Zilog Z80 processor. By default accepted undocumented
operations with halves of index registers (@code{IXL}, @code{IXH}, @code{IYL},
@code{IYH}) and instuction @code{IN F,(C)}. Other useful undocumented
instructions produces warnings. Undocumented instructions may not work on some
CPUs, use them on your own risk.

@cindex @code{-r800} command-line option, Z80
@item -r800
Produce code for the Ascii R800 processor.

@cindex @code{-z180} command-line option, Z80
@item -z180
Produce code for the Zilog Z180 processor.

@cindex @code{-ez80} command-line option, Z80
@item -ez80
Produce code for the eZ80 processor in Z80 memory mode by default.

@cindex @code{-ez80-adl} command-line option, Z80
@item -ez80-adl
Produce code for the eZ80 processor in ADL memory mode by default.

@cindex @code{-gbz80} command-line option, Z80
@item -gbz80
Produce code for the GameBoy Z80 processor.

@cindex @code{-z80n} command-line option, Z80
@item -z80n
Produce code for the Z80N processor.

@cindex @code{-local-prefix} command-line option, Z80
@item  -local-prefix=@var{prefix}
Mark all labels with specified prefix as local. But such label can be
marked global explicitly in the code. This option do not change default
local label prefix @code{.L}, it is just adds new one.

@cindex @code{-colonless} command-line option, Z80
@item  -colonless
Accept colonless labels. All names at line begin are treated as labels.

@cindex @code{-sdcc} command-line option, Z80
@item  -sdcc
Accept assembler code produced by SDCC.

@cindex @code{-fp-s} command-line option, Z80
@item -fp-s=@var{FORMAT}
Single precision floating point numbers format. Default: ieee754 (32 bit).

@cindex @code{-fp-d} command-line option, Z80
@item -fp-d=@var{FORMAT}
Double precision floating point numbers format. Default: ieee754 (64 bit).

@cindex @code{-strict} command-line option, Z80
@item  -strict
Accept documented instructions only.

@cindex @code{-full} command-line option, Z80
@item  -full
Accept all known Z80 instructions.

@item  -with-inst=@var{INST}[,...]
@itemx -Wnins @var{INST}[,...]
Enable specified undocumented instruction(s).

@item  -without-inst=@var{INST}[,...]
@itemx -Fins @var{INST}[,...]
Disable specified undocumented instruction(s).

@item  -ignore-undocumented-instructions
@itemx -Wnud
Silently assemble undocumented Z80-instructions that have been adopted
as documented R800-instructions .
@item  -ignore-unportable-instructions
@itemx -Wnup
Silently assemble all undocumented Z80-instructions.
@item  -warn-undocumented-instructions
@itemx -Wud
Issue warnings for undocumented Z80-instructions that work on R800, do
not assemble other undocumented instructions without warning.
@item  -warn-unportable-instructions
@itemx -Wup
Issue warnings for other undocumented Z80-instructions, do not treat any
undocumented instructions as errors.
@item  -forbid-undocumented-instructions
@itemx -Fud
Treat all undocumented z80-instructions as errors.
@item  -forbid-unportable-instructions
@itemx -Fup
Treat undocumented z80-instructions that do not work on R800 as errors.
@end table
@c man end

Floating point numbers formats.
@table @option
@item @code{ieee754}
Single or double precision IEEE754 compatible format.

@item @code{half}
Half precision IEEE754 compatible format (16 bits).

@item @code{single}
Single precision IEEE754 compatible format (32 bits).

@item @code{double}
Double precision IEEE754 compatible format (64 bits).

@item @code{zeda32}
32 bit floating point format from z80float library by Zeda.

@item @code{math48}
48 bit floating point format from Math48 package by Anders Hejlsberg.
@end table

Known undocumented instructions.
@table @option
@cindex Known undocumented instructions
@item  @code{idx-reg-halves}
All operations with halves of index registers (@code{IXL}, @code{IXH}, @code{IYL}, @code{IYH}).
@item  @code{sli}
@code{SLI} or @code{SLL} instruction. Same as @code{SLA r; INC r}.
@item  @code{op-ii-ld}
Istructions like @code{<op> (<ii>+<d>),<r>}. For example: @code{RL (IX+5),C}
@item @code{in-f-c}
Instruction @code{IN F,(C)}.
@item @code{out-c-0}
Instruction @code{OUT (C),0}
@end table

@cindex Z80 Syntax
@node Z80 Syntax
@section Syntax
The assembler syntax closely follows the 'Z80 family CPU User Manual' by
Zilog.
In expressions a single @samp{=} may be used as ``is equal to''
comparison operator.

Suffices can be used to indicate the radix of integer constants;
@samp{H} or @samp{h} for hexadecimal, @samp{D} or @samp{d} for decimal,
@samp{Q}, @samp{O}, @samp{q} or @samp{o} for octal, and @samp{B} for
binary.

The suffix @samp{b} denotes a backreference to local label.

@menu
* Z80-Chars::                Special Characters
* Z80-Regs::                 Register Names
* Z80-Case::                 Case Sensitivity
* Z80-Labels::               Labels
@end menu

@node Z80-Chars
@subsection Special Characters

@cindex line comment character, Z80
@cindex Z80 line comment character
The semicolon @samp{;} is the line comment character;

If a @samp{#} appears as the first character of a line then the whole
line is treated as a comment, but in this case the line could also be
a logical line number directive (@pxref{Comments}) or a preprocessor
control command (@pxref{Preprocessing}).

@cindex line separator, Z80
@cindex statement separator, Z80
@cindex Z80 line separator
The Z80 assembler does not support a line separator character.

@cindex location counter, Z80
@cindex hexadecimal prefix, Z80
@cindex Z80 $
The dollar sign @samp{$} can be used as a prefix for hexadecimal numbers
and as a symbol denoting the current location counter.

@cindex character escapes, Z80
@cindex Z80, \
A backslash @samp{\} is an ordinary character for the Z80 assembler.

@cindex character constant, Z80
@cindex single quote, Z80
@cindex Z80 '
The single quote @samp{'} must be followed by a closing quote. If there
is one character in between, it is a character constant, otherwise it is
a string constant.

@node Z80-Regs
@subsection Register Names
@cindex Z80 registers
@cindex register names, Z80

The registers are referred to with the letters assigned to them by
Zilog. In addition @command{@value{AS}} recognizes @samp{ixl} and
@samp{ixh} as the least and most significant octet in @samp{ix}, and
similarly @samp{iyl} and  @samp{iyh} as parts of @samp{iy}.

@c The @samp{'} in @samp{ex af,af'} may be omitted.

@node Z80-Case
@subsection Case Sensitivity
@cindex Z80, case sensitivity
@cindex case sensitivity, Z80

Upper and lower case are equivalent in register names, opcodes,
condition codes  and assembler directives.
The case of letters is significant in labels and symbol names. The case
is also important to distinguish the suffix @samp{b} for a backward reference
to a local label from the suffix @samp{B} for a number in binary notation.

@node Z80-Labels
@subsection Labels

@cindex labels, Z80
@cindex Z80 labels
Labels started by @code{.L} acts as local labels. You may specify custom local
label prefix by @code{-local-prefix} command-line option.
Dollar, forward and backward local labels are supported. By default, all labels
are followed by colon.
Legacy code with colonless labels can be built with @code{-colonless}
command-line option specified. In this case all tokens at line begin are treated
as labels.

@node Z80 Floating Point
@section Floating Point
@cindex floating point, Z80
@cindex Z80 floating point
Floating-point numbers of following types are supported:

@table @option
@item @code{ieee754}
Supported half, single and double precision IEEE754 compatible numbers.

@item @code{zeda32}
32 bit floating point numbers from z80float library by Zeda.

@item @code{math48}
48 bit floating point numbers from Math48 package by Anders Hejlsberg.
@end table

@node Z80 Directives
@section Z80 Assembler Directives

@command{@value{AS}} for the Z80 supports some additional directives for
compatibility with other assemblers.

@cindex Z80-only directives
These are the additional directives in @code{@value{AS}} for the Z80:

@table @code
@item assume @var{ADL}@samp{=}@var{expression}
Set ADL status for eZ80. Non-zero value enable compilation in ADL mode else
used Z80 mode. ADL and Z80 mode produces incompatible object code. Mixing
both of them within one binary may lead problems with disassembler.

@item db @var{expression}|@var{string}[,@var{expression}|@var{string}...]
@itemx defb @var{expression}|@var{string}[,@var{expression}|@var{string}...]
@itemx defm @var{string}...]
For each @var{string} the characters are copied to the object file, for
each other @var{expression} the value is stored in one byte.
A warning is issued in case of an overflow.
Backslash symbol in the strings is generic symbol, it cannot be used as
escape character (for this purpose use @code{.ascii} or @code{.asciiz}
directives).

@item dw @var{expression}[,@var{expression}...]
@itemx defw @var{expression}[,@var{expression}...]
For each @var{expression} the value is stored in two bytes, ignoring
overflow.

@item d24 @var{expression}[,@var{expression}...]
@itemx def24 @var{expression}[,@var{expression}...]
For each @var{expression} the value is stored in three bytes, ignoring
overflow.

@item d32 @var{expression}[,@var{expression}...]
@itemx def32 @var{expression}[,@var{expression}...]
For each @var{expression} the value is stored in four bytes, ignoring
overflow.

@item ds @var{count}[, @var{value}]
@itemx defs @var{count}[, @var{value}]
@c Synonyms for @code{ds.b},
@c which should have been described elsewhere
Fill @var{count} bytes in the object file with @var{value}, if
@var{value} is omitted it defaults to zero.

@item @var{symbol} equ @var{expression}
@itemx @var{symbol} defl @var{expression}
These directives set the value of @var{symbol} to @var{expression}. If
@code{equ} is used, it is an error if @var{symbol} is already defined.
Symbols defined with @code{equ} are not protected from redefinition.

@item psect @var{name}
A synonym for @xref{Section}, no second argument should be given.
@ignore

The following attributes will possibly be recognized in the future
@table @code
@item abs
The section is to be absolute. @code{@value{AS}} will issue an error
message because it can not produce an absolute section.
@item global
The section is to be concatenated with other sections of the same name
by the linker, this is the default.
@item local
The section is not global. @code{@value{AS}} will issue a warning if
object file format is not soff.
@item ovrld
The section is to be overlapped with other sections of the same name by
the linker. @code{@value{AS}} will issue an error message
because it can not mark a section as such.
@item pure
The section is marked as read only.
@end table
@end ignore

@end table

@node Z80 Opcodes
@section Opcodes
In line with common practice, Z80 mnemonics are used for the Z80,
the Z180, eZ80 and the R800.

In many instructions it is possible to use one of the half index
registers (@samp{ixl},@samp{ixh},@samp{iyl},@samp{iyh}) in stead of an
8-bit general purpose register. This yields instructions that are
documented on the eZ80 and the R800, undocumented on the Z80 and
unsupported on the Z180.
Similarly @code{in f,(c)} is documented on the R800, undocumented on
the Z80 and unsupported on the Z180 and the eZ80.

The assembler also supports the following undocumented Z80-instructions,
that have not been adopted in any other instruction set:
@table @code
@item out (c),0
Sends zero to the port pointed to by register @code{C}.

@item sli @var{m}
Equivalent to @code{@var{m} = (@var{m}<<1)+1}, the operand @var{m} can
be any operand that is valid for @samp{sla}. One can use @samp{sll} as a
synonym for @samp{sli}.

@item @var{op} (ix+@var{d}), @var{r}
This is equivalent to

@example
ld @var{r}, (ix+@var{d})
@var{opc} @var{r}
ld (ix+@var{d}), @var{r}
@end example

The operation @samp{@var{opc}} may be any of @samp{res @var{b},},
@samp{set @var{b},}, @samp{rl}, @samp{rlc}, @samp{rr}, @samp{rrc},
@samp{sla}, @samp{sli}, @samp{sra} and @samp{srl}, and the register
@samp{@var{r}} may be any of @samp{a}, @samp{b}, @samp{c}, @samp{d},
@samp{e}, @samp{h} and @samp{l}.

@item @var{opc} (iy+@var{d}), @var{r}
As above, but with @samp{iy} instead of @samp{ix}.
@end table

The web site at @uref{http://www.z80.info} is a good starting place to
find more information on programming the Z80.

You may enable or disable any of these instructions for any target CPU
even this instruction is not supported by any real CPU of this type.
Useful for custom CPU cores.