Z80-ASM(5)

NAME
description of the z80-asm assembly language

DESCRIPTION
Source code compounds of lines. Each line contains max. one instruction. Line can be divided into three parts: label, instruction and arguments. These parts are separated by whitespace (whitespace is one or more tab, space or comma), arguments are separated by whitespace too. With the exception of strings whole line is case insensitive. And except inside strings, whitespace can never appear inside an argument.

INSTRUCTIONS
Assembler accepts all usual Z80 instructions:

adc, add, and, bit, call, ccf, cp, cpd, cpdr, cpi, cpir, cpl, daa, dec, di, djnz, ei, ex, exx, halt, im, in, inc, ind, ini, indr, inir, jp, jr, ld, ldd, ldi, lddr, ldir, neg, nop, or, otdr, otir, out, outd, outi, pop, push, res, ret, reti, retn, rl, rla, rlc, rlca, rld, rr, rra, rrc, rrca, rrd, rst, sbc, scf, set, sla, sll, sra, sub, xor

and pseudo (not Z80) instructions:

* org - org accepts one address argument; it tells
         the compiler to write following code to memory
         from mentioned address; if there's no org
         instruction at the start of the source,
         assembler stores code starting from address 0.
         The argument must be evaluable in pass 1. * defb - defb means 8-bit data; after defb instruction
         follow discretionary number of 8-bit numbers
         (or character constants); separate several by , * defw - defw is similar to defb; it means 16-bit data;
         this instruction takes 16-bit numbers as
         arguments; separate several by , (comma). * defm - defm is only instruction accepting string
         arguments; it accepts arbitrary number of
         strings; strings are stored in memory
         character after character as they are written
         in string. (abbreviation from define message) * defs - defs is used to reserve storage; it is followed
         by a nonnegative numerical argument, indicating
         the number of bytes the PC should be increased.
         The argument must be evaluable in pass 1. * align - align is used also to reserve memory; but it is
         followed by only one hexadecimal digit.
         If the current PC isn't divisible by 2^arg, it
         will be increased to the next value which
         satisfies this condition. So the new PC will have
         cleared its lowest arg-many bits. * equ - equ defines a name to be a value; thus an equ
         instruction must have a label which is taken
         as its name; this label gets the value of the
         following expression or number argument which
         is a 8- or 16-bit data (or character constant). * defl - defl defines a name to be a value; thus an defl
         instruction must have a label which is taken
         as its name; in contrast to the equ instruction
         this name may be redefined by following defl
         instructions. * end - end indicates the assembler that source ends
         here. * cond - cond indicates a block of statements follow for
         conditionel compilation. It needs one numerical
         argument which means in the case 0 that the
         following statements up to the corresponding
         endc with the exception of further cond and endc
         opcodes are ignored. The argument must be
         evaluable in pass 1 of the assembler. * endc - endc indicates the end of a block of statements
         of a condc statment. A remark for the arguments of the jr and the djnz instruction: only if its address is a constant number starting with a + or - sign this value is interpreted as a signed 8 bit relative jump distance. In all other cases it is considered as an unsigned 16 bit address which must lay in the signed 8 bit distance of the instruction.

ARGUMENTS
 Instruction argument can be one of the following:
    * register
    * flag
    * number or character constant
    * label
    * expression
    * indirect (number, label, expression or register)
    * string

REGISTERS
Standard Z80 register identifiers are allowed:
 8-bit register names: A, B, C, D, E, H, L, I, R
 16-bit register names: AF, AF', BC, DE, HL, IX, IY, SP

FLAGS
Assembler uses standard Z80 flag identifiers: C, NC, Z, NZ, P, M, PE, PO. Meaning is in sequence: carry, non carry, zero, non zero, plus, minus, parity even and parity odd.

NUMBERS
Assembler accepts integer numbers in binary, decimal, and hexadecimal scale.

Binary numbers must be prefaced with # (number sign) or postfixed by b or B , decimal numbers are without prefix and hexadecimal numbers are either prefaced with 0x or $ prefix or with h or H postfix.

Number can be also a character constant. Character constants are quoted in ' (apostrophes). Inside apostrophes there is exactly one character. Such character constants are considered as an unsigned eight-bit number.

If there is no hexadecimal prefix given, the first digit of a number must be one of 0 - 9. Numbers (except for character constants) can also be negative. Negative numbers are created by writing a - (minus) symbol in front of the number (binary, decimal or hexadecimal). Then their value is represented/interpreted as 2-complement. A leading + (plus) is ignored but valid if no minus follows.

Valid examples: -0x29a, -#10011011, 1234, +34H, $ffff

LABELS
Label is a string consisting of characters 0-9 (digits), a-z (lower case letters), A-Z (upper case letters) or the character _ (underscore). It may not start with a digit, must contain at least one alphanumerical character but at most 63 characters. Moreover it must be different from any number, register and flag identifiers. A label is declared by writing it at the beginning of a line, no character (nor whitespace) can precede. There's no colon needed behind a label declaration, but if there is one trailing colon in the declaration it is disgarded. Each label is separated from instruction by whitespace.

If you want to use a label as an instruction argument, you simply write its name. Labels can be used as (or inside) arguments before they are declared. The special label @ refers to the current value of the program counter.

Label example:
        djnz @
 test1: sub 10
        cp 42
        jr z,ok

EXPRESSIONS
For every argument where a label may appear an expression may appear. An expression is an algebraic expression consisting of labels and/or numbers (possibly prefixed by monadic operators) which are connected by binary operators. Also you may use parentheses to change the order of evaluation of an expression. Operators are ** for power, // for bitsize (equivalently log_2 strictly rounded up to the next integer), + for addition (and also as a monadic +), - for subtraction and also for the negation (2-complement) of an operand, * for multiplication, / for integer division (result will always round down if it is non integral), % for modulo (result will always non negative if modulus is non negative), ~ for 1-complement (binary representation is inverted bitwise), ! for boolean negation (only zero becomes true each other value becomes false), & for bitwise and, | for bitwise or, and ^ for bitwise exclusive or. The the monadic operators + - ~ ! // have highest priority, then follow the binary operator ** , the binary operators * / % which are left associative, next the left associative binary operators + - , the left associative binary shift operators >> and << then the binary left associative operator & and finally the binary left associative operators | ^ which have even lower priority. Moreover there are the six boolean comparision operators for signed values == != > < >= <= which are also left associative as well as the boolean operators && for logical and and || for logical or which have the lowest priority. The boolean value false is 0 and boolean true is represented as ~0. The evaluation of expressions is done in 32-bit signed arithmetic. Except the right operand of << >> ** and // which is always interpreted as unsigned, all other operands are considered signed. In the case an arithmetic overflow occurs the result will be undefined.
Lastly there is the monadic boolean operator ? which must be followed by a label. It evaluates to true if the label is defined else false.

INDIRECT
An argument which starts with a ( (opening parenthesis) and ends with a ) (closing parenthesis) describes an indirect memory addressing.

STRINGS
Strings are written in quotes. Inside quotes are allowed all character codes 32-255. A " (quote character) inside must be doubled. Strings are allowed only as argument of a defm instruction and may contain at most 255 characters.

String example: "hello world"

COMMENTS
A comment starts with a ; (semicolon) character and ends at the end of a line. Comments are ignored, they are only for programmer's use.

SEE ALSO
z80-asm(1), z80-mon(1), z80-file(5)