This chapter describes the O65 binary relocation format V1.3 for the 6502
family, as defined by Andre Fachat on 6502.org.
Option @option{-Fo65} outputs object files suitable for another linker pass,
while @option{-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.

@section Legal

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

@section Additional options for this module
@table @option
    @item -bss=<addr>
        Sets a start address for the @code{bss} section.
    @item -data=<addr>
        Sets a start address for the @code{data} section.
    @item -fopts
        Enable informational header options, generated by the assembler:
        file name, assembler name and version, creation date.
    @item -foauthor=<name>
        Write author's name to the header options.
    @item -foname=<name>
        Write file name to the header options. Overwrites the real file
        name, which would be set by @option{-fopts}.
    @item -paged
        Make the output file use paged alignment and simplified paged
        relocations.
    @item -secalign=<align>
        Set minimum alignment for all sections as number of least significant
        bits which have to be zero. @code{align} may be 0, 1, 2, 8.
        The default behaviour is to use the maximum alignment given by the
        input sections.
    @item -stack=<stacksize>
        Store required stack size in the header.
    @item -text=<addr>
        Sets a start address for the @code{text} section.
    @item -zero=<addr>
        Sets a start address for the @code{zero} (zero/direct page) section.
@end table

These options are valid for the @code{o65exe} module only:
@table @option
    @item -bsszero
        Set a flag in the header which requests automatic clearing of the
        @code{bss} section.
@end table


@section General

This output module outputs the @code{o65} object file and @code{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 @code{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:
@itemize @minus
@item text, sections which have executable code and/or are not
      writable (@code{acrx}).
@item data, sections which have initialized data and may be read and
      written (@code{adrw}).
@item bss, sections which have unitialized data and may be read and
      written (@code{aurw}).
@item zero, sections which have uninitialized data which may be read
      and written, and do not have the string @code{"bss"} anywhere in
      their name (@code{aurw}).
@end itemize

Up to two absolute sections (@code{ORG} directive) can be stored in
the @code{text} and @code{data} slots, in the order of occurence.


@section Restrictions

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

It supports all relocation types defined by o65, which are:
@itemize @minus
@item 0x20: absolute, 8-bit value or low-byte of 16-bit address
@item 0x40: absolute, 8-bit high-byte of 16-bit address
@item 0x80: absolute, 16-bit address
@item 0xa0: absolute, 8-bit segment-byte of 24-bit address
@item 0xc0: absolute, 24-bit address
@end itemize

Common or weak symbols are not supported.


@section Known Problems

    Some known problems of this module at the moment:

@itemize @minus
@item Needs a better way to set start addresses for the sections
      in the assembler.
@end itemize


@section Error Messages

This module has the following error messages:

@itemize @minus
@item 3004: section attributes <attr> not supported
@item 3008: output module doesn't allow multiple sections of the same type (%s)
@item 3011: weak symbol <%s> not supported by output format, treating as global
@item 3015: file option %d max size exceeded: %lu
@end itemize