z80asm File formats (v03)
=========================

This document describes the object and libary formats used by *z80asm*
versions *2.2.x*.

The version changed to *03* to include the address of the start of the
assembly instruction in the object file, so that expressions with ASMPC
are correctly computed at link time.

The object and library files are stored in binary form as a set of 
contiguous objects, i.e. each section follows the previous one without 
any end-markers. 

The files start with a signature that includes a version number and is 
verified by the assembler before trying to parse the file.

A set of file pointers at the start of the object file point to the 
start of each section existing the in the file, or contain *0xFFFFFFFF* 
(-1) if that section does not exist.

The following object types exist in the file:

* *char* :	one byte containing an ASCII character;

* *byte* :	one 8-bit value;

* *word* :	one 16-bit value, stored in low byte - high byte order 
	(Little endian format - Z80/Intel notation);

* *long* :	one 32-bit value, stored in low byte - high byte order, 
	containing the file position where the corresponding 
	section starts; the value is *0xFFFFFFFF* (-1) if the section 
	does not exist;

* *string*:	one byte containing the string length followed by the 
	characters of the string.


Object file format
------------------

The format of the object file is as follows:

|Addr | Type   | Object													|
|:---:|:------:|:-------------------------------------------------------|
|   0 | char[8]| 'Z80RMF03' (file signature and version)				|
|   8 | word   | *ORG Address*											|
|  10 | long   | File pointer to *Module Name*, always the last section	|
|  14 | long   | File pointer to *Expressions*, may be -1				|
|  18 | long   | File pointer to *Module Names*, may be -1				|
|  22 | long   | File pointer to *External Names*, may be -1			|
|  26 | long   | File pointer to *Machine Code*, may be -1				|
|  30 |        | *Expressions*											|
|     |  	   | ...													|
|     |  	   | *Module Names*											|
|     |  	   | ...													|
|     |  	   | *External Names*										|
|     |  	   | ...													|
|     |  	   | *Module Name*											|
|     |  	   | *Machine Code*											|


* *ORG Address* : contains the ORG address for the linked machine code 
	or *0xFFFF* for no ORG address defined. 


* *Expressions* : contains a set of expressions up to the 
	start of the next existing section. Each expression has the following
	format:

	* *type* (char) : defines the resulting evaluation type range:

		'U' : 8-bit integer (0 to 255)  
		'S' : 8-bit signed integer (-128 to 127)  
		'C' : 16-bit integer (-32768 to 65535)  
		'L' : 32-bit signed integer  

	* *ASMPC* (word) : defines the relative module code address of the 
	start of the assembly instruction to be used as *ASMPC* during
	expression evaluation.

	* *patchptr* (word) : defines the relative module code patch pointer to 
	store the result of evaluating the expression.

	* *expression* (string) : contains the expression text as parsed from the 
	source file, in the standard C-like expression syntax.

	* *0* (byte) : is a zero byte end marker, not part of the expression length.


* *Module Names* : contains a set of names defined in this module 
  up to the next existing section. Each name has the following format:
  
	* *scope* (char) : defines the scope of the name:
  
		'L' is local,  
		'G' is global,  

	* *type (char) : defines whether it is a: 

		'A' relocatable address,   
		'C' a constant.

	* *value* (long) : contains the absolute value for a constant, or the
	relative address to the start of the code block for a relocatable
	address.
	
	* *name* (string) : contains the name.


* *External Names* : contains a set of external names referred 
  by this module up to the next existing section. Each name has the 
  following format:
  
	* *name* (string) : contains the name.


* *Module Name* (string) : contains the module name.


* *Machine Code* : contains the binary code of the module with the 
  following format:


	* *length* (word) : defines the total code lenght, and contains 0 if the 
	  code is 65536 bytes long.
	
	* *code* (byte[length]) : contains the binary code.


Library file format
-------------------

The library file format is a sequense of object files with additional
structures.

|Addr | Type   | Object													|
|:---:|:------:|:-------------------------------------------------------|
|   0 | char[8]| 'Z80LMF01' (file signature and version)				|
|   8 | word   | *Object File Block*									|
|     |  	   | ...													|


* *Object File Block* : contains the following format: 

	* *next* (long) : contains the file pointer of the next object file 
	  in the library, or *-1* if this object file is the last in the library.
  
	* *length* (long) : contains the length of this object file, 
	  or *0* if this object files has been marked "deleted" and will not be used.
