z80asm File formats (v05)
=========================

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

The version changed to *05* to include source code sections.

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.

* *lstring*: one word 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]| 'Z80RMF04' (file signature and version)				|
|   8 | long   | *ORG Address*											|
|  12 | long   | File pointer to *Module Name*, always the last section	|
|  16 | long   | File pointer to *Expressions*, may be -1				|
|  20 | long   | File pointer to *Module Names*, may be -1				|
|  24 | long   | File pointer to *External Names*, may be -1			|
|  28 | long   | File pointer to *Machine Code*, may be -1				|
|  32 |        | *Expressions*											|
|     |  	   | ...													|
|     |  	   | *Module Names*											|
|     |  	   | ...													|
|     |  	   | *External Names*										|
|     |  	   | ...													|
|     |  	   | *Module Name*											|
|     |  	   | *Machine Code*											|


* *ORG Address* : contains the ORG address for the linked machine code 
	or -1 for no ORG address defined. 


* *Expressions* : contains a set of expressions up to 
    an end marker (*type* = 0). 
    Each expression has the following format:

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

		0   : end marker  
		'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  

	* *sourcefile* (lstring) : source file name where expression was defined,
	to be used in error messages. May be an empty string, signalling that
	the previous *sourcefile* of the previous expression should be used.

	* *line_number* (long) : line number in source file where 
	expression was defined, to be used in error messages.

	* *section* (string) : source file section name where expression 
	was defined. 

	* *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* (lstring) : contains the expression text as parsed from the 
	source file, in the standard C-like expression syntax.


* *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:
  
		0   : end marker  
		'L' is local,  
		'G' is global,  

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

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

	* *section* (string) : source file section name where name 
	was defined. 

	* *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* (long) : defines the total code lenght, contains -1
	  to signal the end.
	
	* *section* (string) : source file section name. 

	* *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.
