1Z80ASM(1) General Commands Manual Z80ASM(1)
4
8 z80asm - assembler for the Z80 microprocessor
9
11 z80asm [options] [files...]
12
14 Z80asm is an assembler for Z80 assembly. If no input files are speci‐
15 fied, stdin is used. If no output file is specified, "a.bin" is used.
16 If "-" is specified as output file, stdout is used. This makes it pos‐
17 sible to use the assembler in a pipeline.
18 When multiple input files are specified, the assembler first uses all
20 files which were specified with -i or --input, in the order given.
21 After that, all files which were specified as non-option arguments are
22 assembled, also in the order given.
23
25 -h, --help
26 Show summary of options and exit.
27 -V, --version
29 Display version information and exit.
30 -v, --verbose
32 Be verbose. Specify multiple times to be more verbose. Mes‐
33 sages are sent to standard error.
34 -l, --list[=filename]
36 Write a list file. No filename or '-' means stderr.
37 -L, --label[=filename]
39 Write a label file. No filename or '-' means stderr.
40 -p, --label-prefix=prefix
42 prefix all labels with this prefix.
43 -i, --input=filename
45 Specify an input file (-i may be omitted). '-' means stdin.
46 -o, --output=filename
48 Specify the output file. '-' or completely omitting the option
49 means stdout.
50 -I, --includepath=dirname
52 Add a directory to the include path. The order in which the
53 directories are tried is from back to front: the last directory
54 specified has the highest priority. "/usr/share/z80asm" is
55 always in the include path (with lowest priority), you don't
56 have to specify it.
57 -f, --force
59 Produce output even in case of errors. Normally the output,
60 list and label files are removed when assembly is unsuccesful.
61
64 All mnemonics and registers are case insensitive. All other text (in
65 particular, labels and macros) are not. Undocumented opcodes are as
66 much as possible supported:
67 sll and sli are equal and can both be used.
69 ixh, ixl, iyh and iyl can be used.
71 Assembler directives are:
73 incbin 'filename'
75 Include a binary file into the resulting assembled file. This
76 can be used to include text files, or images, sound files, etc.
77 The filename is searched for in the current directory, and then
78 in the include path, just like for include. Also like for
79 include, the quotes can be any character (but must match) and no
80 substitution is performed (so ~ is not your home directory).
81 defb or db arg, arg, arg, ...
83 Define bytes.
84 defm or dm "String", 'String'
86 Define message. Each character in the string is stored as one
87 byte. Backslash escapes are allowed, as in characters in
88 expressions. Unlike the argument for include, the quotes must
89 really be quotes (but they can be single or double quotes. The
90 closing quote must match the opening quote.)
91 defb/db and defm/dm are really aliases; either can take both quoted
93 strings and numbers:
94 defb "This text should be in a buffer\r\n", 0
95 defs or ds count [, value]
97 Define space. count bytes are reserved. Each of them is ini‐
98 tialised to the specified value, or 0 if no value is specified.
99 defw or dw arg, arg, arg, ...
101 Define words. Each argument is stored as two bytes, the low
102 order byte first.
103 end End assembly of this source file. Any remaining lines are
105 copied into the list file (if present), but not assembled.
106 label: equ expression
108 Define label to have value expression.
109 if expression
111 code block 1
112 else
113 code block 2
114 else
115 code block 3
116 ...
117 code block n
118 endif
119 Conditionally assemble code. If expression is not 0, all odd
120 code blocks are assembled, if expression is 0, all even blocks
121 are assembled. Usually only one or two code blocks are present.
122 include 'file'
124 Include file into the source. The quotes around the file for
125 include are mandatory, but you can choose the quotes yourself.
126 eg, you may use % or even a letter as a quote. The filename
127 does not undergo any expansion, so \, ~, $, etc are passed as
128 written (which means ~ will not be your home directory.) The
129 filename is used as specified, and then prefixed with each
130 directory in the include path, until it can be opened.
131 label: macro arg1, arg2, ...
133 code block
134 endif
135 Define a macro. The macro can be used where an opcode is
136 expected. The code block is then substituted, with the given
137 values for the arguments. This is a textual substitution, so
138 the following example is valid:
139 makelabel name
140 label_name:
141 endm
142 This will generate a label with a constructed name (it's not a
143 very useful example, but it shows the possiblities).
144 org address
146 Set the "program counter" to address. This does not add any
147 bytes to the resulting binary, it only determines how the rest
148 of the code is interpreted (in particular, the value of labels
149 and $).
150 seek offset
152 Seek to position offset in the output file. This can be used
153 for overwiting previously assembled code, for example for patch‐
154 ing a binary which was included using incbin.
155
158 All expressions can use the following operators, in order of prece‐
159 dence: (a, b and c denote subexpressions)
160 a ? b : c
162 If a is not zero, return b, otherwise c
163 a | b bitwise or
165 a ^ b bitwise xor
167 a & b bitwise and
169 a == b, a = b, a != b
171 equality
172 a <= b, a >= b, a < b, a > b
174 inequality
175 a << b, a >> b
177 bit shift
178 a + b, a - b
180 addition and subtraction
181 a * b, a / b, a % b
183 multiplication, division and modulo
184 ~a, +a, -a
186 bitwise not, no effect and negation
187 ?label 1 if label exists, 0 if it does not. This does not generate an
189 error if label does not exist. Note that this is usually evalu‐
190 ated immediately (if the rest of the expression permits), and it
191 does not check if the label is defined later. This means it can
192 be used as the argument of if , to get the functionality of
193 #ifdef in C.
194 (a) parenthesis
196 Literals in expressions may be written as: (case does not matter)
198 @c11 arbitrary base number (specified by 'c' so c+1 == 10: here base
200 is 13)
201 14, 14d, @914
203 decimal number
204 016, 16o, 16q, &o16, @716
206 octal number
207 0Eh, 0xE, &hE, $E, @FE
209 hexadecimal number (for the first notations, the first character
210 must be 0-9)
211 %1110, 1110b, &b1110, @11110
213 binary number
214 's' ASCII code of 's'
216 '\n', '\r', '\a', '\t'
218 Newline, carriage return, alert, tab
219 '\nnn' Octal ASCII code
221 $ address of first byte of current command
223
226 In all expressions, labels may be used. However, there are some
227 expressions where the value must be computable at once, and therefore
228 only previously defined labels may be used. This is the case for:
229 - The argument of org
231 - The argument of seek
233 - The argument of equ (eg, a label definition)
235 - The first argument of ds
237 - The argument of if
239 In all other expressions, labels which are defined later may be used.
241 Labels must consist of letters, digits, underscores and periods, and
243 must not start with a digit. Labels are case sensitive.
244 Labels starting with a period (.) are local , which means their scope
246 is only the current include file or macro definition (and files
247 included/macros called from it). This is particularly useful for
248 macros, to prevent duplicate definitions when using a macro more than
249 once.
250
253 If assembly was successful, no output is produced (except the result,
254 and messages triggered by --verbose) and 0 is returned. At any error,
255 there is output on the standard error and 1 is returned.
256
259 Parts that are not assembled because of an if statement and macros
260 which are defined but never used are only checked to have a correct
261 command. The argument is not parsed. This means that if the file
262 passes through the assembler with no warnings or errors, it may still
263 not assemble correctly in a different setting (where the if's give dif‐
264 ferent results).
265
268 If you find a bug, or want to send comments, please use the web inter‐
269 face at http://savannah.nongnu.org/projects/z80asm/ or send an e-mail
270 to wijnen@debian.org.
271
274 Z80asm was written by Bas Wijnen <wijnen@debian.org>. Some patches
275 were provided by Jan Wilmans <jw@dds.nl>
276 May 10, 2005 Z80ASM(1)