// UU  UU ZZZZZZ  8888   0000  // --------------------------------- //
// UU  UU     ZZ 88  88 00  00 // UZ80, a micro Z80 macro assembler //
// UU  UU    ZZ  88  88 00  00 // written by Cesar Nicolas-Gonzalez //
// UU  UU   ZZ    8888  00  00 // since 2018-02-23 17:05 till today //
// UU  UU  ZZ    88  88 00  00 // --------------------------------- //
// UU  UU ZZ     88  88 00  00 // http://cngsoft.no-ip.org/uz80.htm //
//  UUUU  ZZZZZZ  8888   0000  // --------------------------------- //

Foreword
--------

UZ80 is a freeware Z80 assembler that aims to be both small and fast
while still providing valuable services such as macro instructions and
conditional assembly. Internally, it departs from full two-pass methods
and relies instead on assembling as much code as possible during the
first pass and writing down the lines making references to still unseen
symbols; these lines will be assembled when all symbols are known.

How to use
----------

UZ80 relies on the standard C library, it doesn't need other libraries
to run. Its command line syntax is as follows:

	UZ80 [-q|-v] [-D[label[=value]]] source [-o]target

	-q : quiet mode, no messages other than fatal errors are shown;

	-v : verbose mode, all messages are shown; -vv shows even more
	information, such as label and macro dumps;

	-Dlabel=value : defines a symbol named "label" whose value is
	"value";

	-Dlabel : shortcut for "-Dlabel=1";

	-D : shortcut for "-DDEBUG=1";

	source : the source file; must be followed by a target file;

	target : the target file; must follow a source file.

The assembly syntax itself is as follows:

	[label] [instruction [parameter[,parameter ...]]]

Indenting is important: labels must begin on the first character of
each line and instructions start later in the line even when there are
no labels. Instructions are either those belonging to the Z80, or the
following pseudo instructions:

	org EXPRESSION : sets the assembly origin point at EXPRESSION;

	align EXPRESSION : aligns the current assembly point to the
	next address that is a multiplo of EXPRESSION;

	defb EXPRESSION... : defines a data block as a series of bytes
	separated with commas; strings within quotes can be used, too;

	defw EXPRESSION... : like "defb", but with 16-bit words and
	without strings;

	defd EXPRESSION... : like "defw", but with 32-bit double words;

	defs EXPRESSION : fills with zeroes the amount of bytes set by
	EXPRESSION;

	LABEL equ EXPRESSION / LABEL = EXPRESSION : creates a new label
	named LABEL whose value will be EXPRESSION;

	if EXPRESSION : assembles the next lines if EXPRESSION is
	nonzero (conditional assembly); "else" can follow, "endif"
	must follow;

	else : assembles the next lines if the current conditional
	assembly is false; must follow "if", "endif" must follow;

	endif : ends the current conditional assembly; can follow
	"else", must follow "if";

	include "FILENAME" : includes the contents of another source
	file named FILENAME within the current assembly;

	LABEL macro [PARAM1[,PARAM2 ...] : defines a macro instruction
	named LABEL featuring the optional parameters PARAM1, PARAM2...

	endm : ends the definition of the current macro;

	end : stops assembling the current source file.

Expressions are similar to those used in C and in other assemblers:
integers (either decimal, hexadecimal formatted as $1234, #1234, 1234h
or 0x1234, or binary formatted as %01010101 or 01010101b) and symbol
values (case-insensitive; "$" stands for the current address) can
endure addition ('+'), substraction ('-'), multiplication ('*'),
division ('/'), modulo ('%'), logical NOT ('!'), bitwise NOT ('~'),
bitwise AND ('&'), bitwise OR ('|'), bitwise XOR ('^'), left shift
('<<'), right shift ('>>') and several types of comparison ('<', '<=',
'='/'==', '<>'/'!=', '>=', '>'); by default, these operations follow
basic precedence rules such as additions and substractions happening
after multiplications and divisions, but before comparisons, unless
parentheses are used to prioritise some operations over others.

Notice that "equ" and "macro" must include labels and thus need to
begin on the first character of the line.

An example of a macro with parameters is as follows:

	memcpy macro target,source,length
	 ld hl,source
	 ld de,target
	 ld bc,length
	 ldir
	 endm

Using it with "memcpy buffer,string,10" generates the following code:

	 ld hl,string
	 ld de,buffer
	 ld bc,10
	 ldir

Originally undocumented instructions such as SLL (Shift Left Logical)
and OUT (C),0 and parameters such as the high and low halves of IX and
IY (XH, XL, YH and YL respectively) are supported, as well as synonyms:

	DEFM : DEFB
	DB : DEFB
	DW : DEFW
	DD : DEFD
	DS : DEFS
	IXH / HX : XH
	IXL / LX : XL
	IYH / HY : YH
	IYL / LY : YL
	OTD : OUTD
	OTI : OUTI
	SHL : SLA
	SHR : SRL
	PUSH REG1,REG2[,...] : PUSH REG1 + PUSH REG2 [+ ...]
	POP REG1,REG2[,...] : [... +] POP REG2 + POP REG1
	NOP NUMBER : NOP repeated NUMBER times

The pseudoinstructions "if" and "include" can be recursively nested;
however, too much nesting will cause a fatal error. Exit codes are
either 0 (success) or 1 (fatal error); errors will show a short message
stating the type of error and its location in the source.

History log
-----------

20180321-2040: first public release. Succesfully compiles FROGALOT,
HIREHARE, BASKETCS and the CHIPNSFX player demo.

20180322-1930: second public release. Added instructions OUTD and OUTI
(synonyms of OTD and OTI) and fixed inconsistencies when using a macro
with fewer parameters than defined.
