# z80asm File formats (v06)

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

The version changed to 06 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.

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