# z80asm File formats (v01)

This document describes the object and libary formats used by z80asm up to version 1.2.10.

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] | 'Z80RMF01' (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

  - 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 original (legacy) 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,
    'X' global library

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