Merge branch 'vendor/GCC50'
[dragonfly.git] / contrib / binutils-2.24 / gas / doc / c-z80.texi
CommitLineData
f40e693d
JM
1@c Copyright 2011 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
30The Zilog Z80 and Ascii R800 version of @code{@value{AS}} have a few machine
31dependent options.
32@table @option
33@cindex @code{-z80} command line option, Z80
34@item -z80
35Produce code for the Z80 processor. There are additional options to
36request warnings and error messages for undocumented instructions.
37@item -ignore-undocumented-instructions
38@itemx -Wnud
39Silently assemble undocumented Z80-instructions that have been adopted
40as documented R800-instructions.
41@item -ignore-unportable-instructions
42@itemx -Wnup
43Silently assemble all undocumented Z80-instructions.
44@item -warn-undocumented-instructions
45@itemx -Wud
46Issue warnings for undocumented Z80-instructions that work on R800, do
47not assemble other undocumented instructions without warning.
48@item -warn-unportable-instructions
49@itemx -Wup
50Issue warnings for other undocumented Z80-instructions, do not treat any
51undocumented instructions as errors.
52@item -forbid-undocumented-instructions
53@itemx -Fud
54Treat all undocumented z80-instructions as errors.
55@item -forbid-unportable-instructions
56@itemx -Fup
57Treat undocumented z80-instructions that do not work on R800 as errors.
58
59@cindex @code{-r800} command line option, Z80
60@item -r800
61Produce code for the R800 processor. The assembler does not support
62undocumented instructions for the R800.
63In line with common practice, @code{@value{AS}} uses Z80 instruction names
64for the R800 processor, as far as they exist.
65@end table
66
67@cindex Z80 Syntax
68@node Z80 Syntax
69@section Syntax
70The assembler syntax closely follows the 'Z80 family CPU User Manual' by
71Zilog.
72In expressions a single @samp{=} may be used as ``is equal to''
73comparison operator.
74
75Suffices can be used to indicate the radix of integer constants;
76@samp{H} or @samp{h} for hexadecimal, @samp{D} or @samp{d} for decimal,
77@samp{Q}, @samp{O}, @samp{q} or @samp{o} for octal, and @samp{B} for
78binary.
79
80The suffix @samp{b} denotes a backreference to local label.
81
82@menu
83* Z80-Chars:: Special Characters
84* Z80-Regs:: Register Names
85* Z80-Case:: Case Sensitivity
86@end menu
87
88@node Z80-Chars
89@subsection Special Characters
90
91@cindex line comment character, Z80
92@cindex Z80 line comment character
93The semicolon @samp{;} is the line comment character;
94
95If a @samp{#} appears as the first character of a line then the whole
96line is treated as a comment, but in this case the line could also be
97a logical line number directive (@pxref{Comments}) or a preprocessor
98control command (@pxref{Preprocessing}).
99
100@cindex line separator, Z80
101@cindex statement separator, Z80
102@cindex Z80 line separator
103The Z80 assembler does not support a line separator character.
104
105@cindex location counter, Z80
106@cindex hexadecimal prefix, Z80
107@cindex Z80 $
108The dollar sign @samp{$} can be used as a prefix for hexadecimal numbers
109and as a symbol denoting the current location counter.
110
111@cindex character escapes, Z80
112@cindex Z80, \
113A backslash @samp{\} is an ordinary character for the Z80 assembler.
114
115@cindex character constant, Z80
116@cindex single quote, Z80
117@cindex Z80 '
118The single quote @samp{'} must be followed by a closing quote. If there
119is one character in between, it is a character constant, otherwise it is
120a string constant.
121
122@node Z80-Regs
123@subsection Register Names
124@cindex Z80 registers
125@cindex register names, Z80
126
127The registers are referred to with the letters assigned to them by
128Zilog. In addition @command{@value{AS}} recognizes @samp{ixl} and
129@samp{ixh} as the least and most significant octet in @samp{ix}, and
130similarly @samp{iyl} and @samp{iyh} as parts of @samp{iy}.
131
132@c The @samp{'} in @samp{ex af,af'} may be omitted.
133
134@node Z80-Case
135@subsection Case Sensitivity
136@cindex Z80, case sensitivity
137@cindex case sensitivity, Z80
138
139Upper and lower case are equivalent in register names, opcodes,
140condition codes and assembler directives.
141The case of letters is significant in labels and symbol names. The case
142is also important to distinguish the suffix @samp{b} for a backward reference
143to a local label from the suffix @samp{B} for a number in binary notation.
144
145@node Z80 Floating Point
146@section Floating Point
147@cindex floating point, Z80
148@cindex Z80 floating point
149Floating-point numbers are not supported.
150
151@node Z80 Directives
152@section Z80 Assembler Directives
153
154@command{@value{AS}} for the Z80 supports some additional directives for
155compatibility with other assemblers.
156
157@cindex Z80-only directives
158These are the additional directives in @code{@value{AS}} for the Z80:
159
160@table @code
161@item db @var{expression}|@var{string}[,@var{expression}|@var{string}...]
162@itemx defb @var{expression}|@var{string}[,@var{expression}|@var{string}...]
163For each @var{string} the characters are copied to the object file, for
164each other @var{expression} the value is stored in one byte.
165A warning is issued in case of an overflow.
166
167@item dw @var{expression}[,@var{expression}...]
168@itemx defw @var{expression}[,@var{expression}...]
169For each @var{expression} the value is stored in two bytes, ignoring
170overflow.
171
172@item d24 @var{expression}[,@var{expression}...]
173@itemx def24 @var{expression}[,@var{expression}...]
174For each @var{expression} the value is stored in three bytes, ignoring
175overflow.
176
177@item d32 @var{expression}[,@var{expression}...]
178@itemx def32 @var{expression}[,@var{expression}...]
179For each @var{expression} the value is stored in four bytes, ignoring
180overflow.
181
182@item ds @var{count}[, @var{value}]
183@itemx defs @var{count}[, @var{value}]
184@c Synonyms for @code{ds.b},
185@c which should have been described elsewhere
186Fill @var{count} bytes in the object file with @var{value}, if
187@var{value} is omitted it defaults to zero.
188
189@item @var{symbol} equ @var{expression}
190@itemx @var{symbol} defl @var{expression}
191These directives set the value of @var{symbol} to @var{expression}. If
192@code{equ} is used, it is an error if @var{symbol} is already defined.
193Symbols defined with @code{equ} are not protected from redefinition.
194
195@item set
196This is a normal instruction on Z80, and not an assembler directive.
197
198@item psect @var{name}
199A synonym for @xref{Section}, no second argument should be given.
200@ignore
201
202The following attributes will possibly be recognized in the future
203@table @code
204@item abs
205The section is to be absolute. @code{@value{AS}} will issue an error
206message because it can not produce an absolute section.
207@item global
208The section is to be concatenated with other sections of the same name
209by the linker, this is the default.
210@item local
211The section is not global. @code{@value{AS}} will issue a warning if
212object file format is not soff.
213@item ovrld
214The section is to be overlapped with other sections of the same name by
215the linker. @code{@value{AS}} will issue an error message
216because it can not mark a section as such.
217@item pure
218The section is marked as read only.
219@end table
220@end ignore
221
222@end table
223
224@node Z80 Opcodes
225@section Opcodes
226In line with common practice, Z80 mnemonics are used for both the Z80 and
227the R800.
228
229In many instructions it is possible to use one of the half index
230registers (@samp{ixl},@samp{ixh},@samp{iyl},@samp{iyh}) in stead of an
2318-bit general purpose register. This yields instructions that are
232documented on the R800 and undocumented on the Z80.
233Similarly @code{in f,(c)} is documented on the R800 and undocumented on
234the Z80.
235
236The assembler also supports the following undocumented Z80-instructions,
237that have not been adopted in the R800 instruction set:
238@table @code
239@item out (c),0
240Sends zero to the port pointed to by register c.
241
242@item sli @var{m}
243Equivalent to @code{@var{m} = (@var{m}<<1)+1}, the operand @var{m} can
244be any operand that is valid for @samp{sla}. One can use @samp{sll} as a
245synonym for @samp{sli}.
246
247@item @var{op} (ix+@var{d}), @var{r}
248This is equivalent to
249
250@example
251ld @var{r}, (ix+@var{d})
252@var{opc} @var{r}
253ld (ix+@var{d}), @var{r}
254@end example
255
256The operation @samp{@var{opc}} may be any of @samp{res @var{b},},
257@samp{set @var{b},}, @samp{rl}, @samp{rlc}, @samp{rr}, @samp{rrc},
258@samp{sla}, @samp{sli}, @samp{sra} and @samp{srl}, and the register
259@samp{@var{r}} may be any of @samp{a}, @samp{b}, @samp{c}, @samp{d},
260@samp{e}, @samp{h} and @samp{l}.
261
262@item @var{opc} (iy+@var{d}), @var{r}
263As above, but with @samp{iy} instead of @samp{ix}.
264@end table
265
266The web site at @uref{http://www.z80.info} is a good starting place to
267find more information on programming the Z80.
268