This chapter describes the O65 binary relocation format V1.3 for the 6502 family, as defined by Andre Fachat on 6502.org. Option -Fo65 outputs object files suitable for another linker pass, while -Fo65exe outputs executable files for an O65 loader. The difference is just a flag which declares the file being an object, and vasm will make sure that the load-addresses of sections in an executable will be consecutive and do not overlay.

Legal
=====

This module is written in 2021 by Frank Wille and is covered by the vasm copyright without modifications.

Additional options for this module
==================================

-bss=<addr>
     Sets a start address for the bss section.

-data=<addr>
     Sets a start address for the data section.

-fopts
     Enable informational header options, generated by the assembler: file name, assembler name and version, creation date.

-foauthor=<name>
     Write author's name to the header options.

-foname=<name>
     Write file name to the header options. Overwrites the real file name, which would be set by -fopts.

-paged
     Make the output file use paged alignment and simplified paged relocations.

-secalign=<align>
     Set minimum alignment for all sections as number of least significant bits which have to be zero. align may be 0, 1, 2, 8. The default behaviour is to use the maximum alignment given by the input sections.

-stack=<stacksize>
     Store required stack size in the header.

-text=<addr>
     Sets a start address for the text section.

-zero=<addr>
     Sets a start address for the zero (zero/direct page) section.

These options are valid for the o65exe module only:

-bsszero
     Set a flag in the header which requests automatic clearing of the bss section.

General
=======

This output module outputs the o65 object file and o65exe executable file format for 6502-family processors and the 65816. The processor type is determined by the selected CPU of the active backend and stored in the header.

The o65exe module generates executable files for a o65-loader, which is present in some 6502 operating systems (e.g. Lunix, SMOS, OS/A65). Unresolved symbols are allowed in o65 object- and executable-files. In the latter case the o65-loader is responsible to resolve them. Common symbols, weak symbol and most relocation types, except absolute addresses, are not supported by o65.

The o65 format recognizes four different sections by their attributes or name:

  - text, sections which have executable code and/or are not writable (acrx).

  - data, sections which have initialized data and may be read and written (adrw).

  - bss, sections which have uninitialized data and may be read and written (aurw).

  - zero, sections which have uninitialized data, may be read and written, and do not have the string "bss" anywhere in their name (aurwz).

Up to two absolute sections (ORG directive) can be stored in the text and data slots, in the order of occurrence.

Restrictions
============

Currently the o65/o65exe output module is only intended to work with the 6502 cpu module and will abort when used otherwise.

It supports all relocation types defined by o65, which are:

  - 0x20: absolute, 8-bit value or low-byte of 16-bit address

  - 0x40: absolute, 8-bit high-byte of 16-bit address

  - 0x80: absolute, 16-bit address

  - 0xa0: absolute, 8-bit segment-byte of 24-bit address

  - 0xc0: absolute, 24-bit address

Common or weak symbols are not supported.

Known Problems
==============

Some known problems of this module at the moment:

  - Needs a better way to set start addresses for the sections in the assembler.

Error Messages
==============

This module has the following error messages:

  - 3004: section attributes <attr> not supported

  - 3008: output module doesn't allow multiple sections of the same type (%s)

  - 3011: weak symbol <%s> not supported by output format, treating as global

  - 3013: reloc type %d, mask %#lx to symbol %s + %#lx does not fit into %u bits

  - 3015: file option %d max size exceeded: %lu