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