z80asm File formats (v07)
=========================

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

The version changed to *07* to include *DEFC* symbols that are defined as
an expression using other symbols and are computed at link time, after 
all addresses are allocated.

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  
		'=' : computed name at link time

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

	* *target_name* (string) : contains the name of the symbol that receives
	the result of evaluating the expression, only used for '=' type expressions,
	empty string for the other types.
	
	* *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,  
		'=' a symbol computed at link time, the corresponding 
		    expression is in the *Expressions* section.

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