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.