Z80ASM(1)

💖 Z80ASM(1) 💖

okay so bestie, you found yourself a Z80 assembler and you want the tea? this is the General Commands Manual page for z80asm, and I'm gonna walk you through it like we're texting at 2am. no cap, every flag is here, I promise. 🫶

---

✨ NAME ✨

z80asm — an assembler for the Z80 microprocessor. she assembles. she's iconic. that's the whole job. 👑

---

🌸 SYNOPSIS 🌸

z80asm [options] [files...]

---

🦋 DESCRIPTION 🦋

Z80asm is an assembler for Z80 assembly, periodt. Here's the vibe of how it handles your files:

• No input files? She reads from stdin. Casual.
• No output file? She writes to a.bin.
• - as the output file? That means stdout, bestie.
• All of that together means you can absolutely drop her into a pipeline and she'll slay. 🌈

Now, when you give her multiple input files, here's the exact order she does things, and this matters so don't skip it:

1. First, she uses all the files you specified with -i or --input, in the order you gave them.
2. Then, she assembles all the files you passed as non-option arguments, also in the order given.

so -i files go first, always, then the loose files. iykyk. 💅

---

💅 OPTIONS 💅

• -h, --help — show a lil summary of the options and dip out. bye! 👋
• -V, --version — print the version info and exit. flex a little. ✨
• -v, --verbose — be verbose. stack it up multiple times to get even more verbose. all these messages go to standard error.
• -l, --list[=filename] — write a list file. no filename, or -, means stderr.
• -L, --label[=filename] — write a label file. no filename, or -, means stderr.
• -p, --label-prefix=prefix — prefix all the labels with this prefix.
• -i, --input=filename — specify an input file (and yes, -i may be omitted). - means stdin.
• -o, --output=filename — specify the output file. -, or just leaving the option out entirely, means stdout.
• -I, --includepath=dirname — add a directory to the include path. the order the directories get tried is back to front: the last directory you specified has the highest priority. and "/usr/share/z80asm" is always in the include path (with the lowest priority) so you never have to specify that one yourself. 💖
• -f, --force — produce output even when there are errors. normally the output, list and label files get yeeted when assembly is unsuccessful, but with this? she stays. 🙈

---

🎀 ASSEMBLER DIRECTIVES 🎀

quick rules before we get into the list, bestie:

• All mnemonics and registers are case insensitive. ✨
• All other text — especially labels and macros — is not. case matters, she's picky.
• Undocumented opcodes are, as much as possible, supported:
  • sll and sli are equal and you can use either one.
  • ixh, ixl, iyh and iyl can all be used. 💜

now, the assembler directives are:

🍓 incbin 'filename'

Include a binary file into the resulting assembled file. you can use this to pull in text files, or images, or sound files, etc. — whatever your heart desires. 🌈

The filename gets searched for in the current directory first, and then in the include path, just like for include. And also just like for include: the quotes can be any character (but they must match), and no substitution is performed — so ~ is not your home directory. sorry babe. 😭

🍓 defb or db arg, arg, arg, ...

Define bytes. one byte per arg, straightforward queen.

🍓 defm or dm "String", 'String'

Define message. Each character in the string is stored as one byte. Backslash escapes are allowed, as in characters in expressions. And unlike the argument for include, the quotes here must really be quotes — though they can be single or double quotes. The closing quote must match the opening quote. no mismatched energy allowed. 💅

🍓 defb/db and defm/dm are really aliases

either one can take both quoted strings and numbers:

defb "This text should be in a buffer\r\n", 0

🍓 defs or ds count [, value]

Define space. count bytes get reserved, and each one is initialised to the specified value — or 0 if you didn't specify a value. defaults, she has them. ✨

🍓 defw or dw arg, arg, arg, ...

Define words. Each argument is stored as two bytes, with the low order byte first.

🍓 end

End assembly of this source file. Any remaining lines get copied into the list file (if there is one), but they are not assembled.

🍓 label: equ expression

Define label to have the value expression.

🍓 if expression

if expression
code block 1
else
code block 2
else
code block 3
...
code block n
endif

Conditionally assemble code. If expression is not 0, all odd code blocks get assembled. If expression is 0, all even blocks get assembled. Usually you'll only have one or two code blocks hanging around.

🍓 include 'file'

Include file into the source. The quotes around the file for include are mandatory, but you get to choose the quotes yourself — eg, you may use % or even a letter as a quote. 😱

The filename does not undergo any expansion, so \, ~, $, etc are passed as written — which means ~ will not be your home directory. The filename is used as specified, and then prefixed with each directory in the include path, until it can be opened. 🔥

🍓 label: macro arg1, arg2, ...

label: macro arg1, arg2, ...
code block
endif

Define a macro. The macro can be used wherever an opcode is expected. The code block then gets substituted in, with the given values for the arguments. This is a textual substitution, so the following example is valid:

makelabel name
label_name:
endm

This will generate a label with a constructed name. (it's not a very useful example, but it shows the possibilities.) 💫

🍓 org address

Set the "program counter" to address. This does not add any bytes to the resulting binary — it only determines how the rest of the code is interpreted (in particular, the value of labels and $). no extra bytes, just vibes. 🦋

🍓 seek offset

Seek to position offset in the output file. You can use this for overwriting previously assembled code — for example, for patching a binary which was included using incbin. sneaky. I love it. 🙈

---

⭐ EXPRESSIONS ⭐

All expressions can use the following operators, listed in order of precedence. (a, b and c denote subexpressions.)

• a ? b : c — if a is not zero, return b, otherwise c
• a | b — bitwise or
• a ^ b — bitwise xor
• a & b — bitwise and
• a == b, a = b, a != b — equality
• a <= b, a >= b, a < b, a > b — inequality
• a << b, a >> b — bit shift
• a + b, a - b — addition and subtraction
• a * b, a / b, a % b — multiplication, division and modulo
• ~a, +a, -a — bitwise not, no effect and negation
• ?label — 1 if the label exists, 0 if it does not. This does not generate an error if the label doesn't exist. Note that this is usually evaluated immediately (if the rest of the expression permits), and it does not check whether the label is defined later. That means you can use it as the argument of if, to get the functionality of #ifdef in C. 💅
• (a) — parenthesis

🧚 Literals in expressions 🧚

Literals in expressions may be written as follows — and case does not matter:

• @c11 — arbitrary base number (specified by 'c' so c+1 == 10: here the base is 13)
• 14, 14d, @914 — decimal number
• 016, 16o, 16q, &o16, @716 — octal number
• 0Eh, 0xE, &hE, $E, @FE — hexadecimal number (for the first notations, the first character must be 0-9)
• %1110, 1110b, &b1110, @11110 — binary number
• 's' — ASCII code of 's'
• '\n', '\r', '\a', '\t' — Newline, carriage return, alert, tab
• '\nnn' — Octal ASCII code
• $ — address of the first byte of the current command

---

👑 LABELS 👑

In all expressions, labels may be used. However, there are some expressions where the value must be computable at once, and therefore only previously defined labels may be used. This is the case for:

• The argument of org
• The argument of seek
• The argument of equ (eg, a label definition)
• The first argument of ds
• The argument of if

In all other expressions, labels which are defined later may be used. so like, patience is allowed everywhere else. 🫶

Labels must consist of letters, digits, underscores and periods, and must not start with a digit. Labels are case sensitive. (yes, again. she means it.)

Labels starting with a period (.) are local, which means their scope is only the current include file or macro definition (and files included/macros called from it). This is particularly useful for macros, to prevent duplicate definitions when you use a macro more than once. chef's kiss. 💋

---

🌈 EXIT STATUS 🌈

If assembly was successful, no output is produced (except the result, and messages triggered by --verbose) and 0 is returned. clean. ✨

At any error, there is output on the standard error and 1 is returned. 💀

---

🔥 NOTES 🔥

Parts that are not assembled because of an if statement — and macros which are defined but never used — are only checked to have a correct command. The argument is not parsed.

Which means: even if the file passes through the assembler with no warnings or errors, it may still not assemble correctly in a different setting (where the if's give different results). so like... she checked the fit but not the whole outfit. be aware, bestie. 😭

---

💀 BUGS 💀

If you find a bug, or want to send comments, please use the web interface at http://savannah.nongnu.org/projects/z80asm/ or send an e-mail to wijnen@debian.org.

---

💜 AUTHOR 💜

Z80asm was written by Bas Wijnen <wijnen@debian.org>. Some patches were provided by Jan Wilmans <jw@dds.nl>.

---

and that's the whole page bestie — this one's from May 10, 2005, Z80ASM(1), General Commands Manual. go assemble something iconic. mwah. 💋✨