path: root/xex.rst

.. RST source for xex(5) man page. Convert with:
..   rst2man.py xex.rst > xex.5

===
xex
===

-----------------------------------
Atari 8-bit executable file format.
-----------------------------------

.. include:: manhdr5.rst

DESCRIPTION
===========

This manual describes the Atari 8-bit binary load format, commonly known
as ".xex" or "binary load".

The file format consists of one or more segments, each having its own
load address. This is an absolute address in the Atari's memory map,
and there's no facility for relocating the code.

File Structure
--------------

In pseudo-EBNF, the file structure looks like:

- ffff_header = "$FF", "$FF"
- initial_segment = ffff_header, segment
- segment = start_address, end_address, data
- file = initial_segment, [ (initial_segment | segment) ... ]

In English:

Each segment has a 4- or 6-byte header. The first segment in the file
must use the 6-byte header. Further segments can use either the 4-byte
or 6-byte header.

The 6-byte header consists of:

- 2 bytes set to **$FF**.

- The 2-byte load address of the segment, in standard LSB-first 6502 order.

- The 2-byte end address of the segment, in standard LSB-first 6502 order.
  This address must be greater than or equal to the load address.

The 4-byte header is the same as the 6-byte header, except it lacks the
initial **$FF**, **$FF** bytes.

The rest of each segment just consists of the data to be loaded,
exactly *(end_address - load_address) + 1* bytes.

Initialization
--------------

It's possible to run code in the middle of loading the file. Such code
is usually referred to as an an "init routine". A XEX file can have
multiple init routines, or none at all.

Init routines are normal segments. An init *address* is also a normal
segment: 2 bytes loaded at address **$02E2**, aka **INITAD**. As
soon as this segment is loaded, the DOS will jump (actually **JSR**)
to this address, which should exit back to DOS with an **RTS**
instruction. After the routine exits, DOS will continue loading the
file normally.

Run Address
-----------

A .xex file can (and usually does) also have a run address. Unlike
init addresses, there can be only one run address. If the file
contains more than one run address, only the last one loaded has any
effect. The program loader jumps to the run address after the file
is done loading. It's possible for the program to exit via the 6502
**RTS** instruction, though many program (especially games) never
exit.

The run address segment is the one that loads the 2-byte run address
into address **$02E0**, aka **RUNAD**.

Raw Data Blocks
---------------

When init code runs, the file is still being loaded. It's open on IOCB
#1, and the init code can read some or all of the rest of the file
itself, before returning to DOS. The part of the file read by an init
segment doesn't have to conform to the regular XEX file structure, so
they're referred to here as raw data blocks.

Raw data blocks usually occur in files created with "packer" or
"compressor" programs, or occasionally in other large programs (Turbo
BASIC is an example). Raw data blocks are generally found just after
an init address segment. If you have an executable that loads just
fine on a real Atari or emulator, but fails with **xexcat** and
**xexamine**, a raw data block is usually the reason why.

Files with raw data blocks also can't be loaded by simple bootloaders
such as Fenders 3-sector loader.

EXAMPLES
========

Assembly
---------

Here is a simple assembly language program that changes the background
of the GRAPHICS 0 text screen to black, and the text to high-intensity white::

  1000     *=  $0600
  1010 START
  1020     LDA #0
  1030     STA 710
  1040     LDA #$0F
  1050     STA 709
  1060     RTS 
  2000     *=  $02E0   ; AKA RUNAD
  2010     .WORD START

To assemble this with either Atari's Assembler/Editor or OSS Mac/65,
the command is::

  ASM ,,#D:COLORS.XEX

This will create a binary file that looks like this::

  offset  0: FF FF 00 06 0A 06 A9 00
  offset  8: 8D C6 02 A9 0F 8D C5 02
  offset 16: 60 E0 02 E1 02 00 06

This is a complete (though short) XEX file, and it can be loaded from
the DOS menu (or D1: prompt, if you use a command-line-based DOS).

The first 2 bytes (**$FF**, **$FF**) are the signature for the initial
segment header.

The next 2 bytes (**$00**, **$06**) are the load address of the first segment
(**$0600**, in 6502-style LSB-first notation).

The next 2 bytes (**$0A**, **$06**) are the end address (**$060A**).

Since the header says to load data from **$0600** to **$060A**, there are 11
data bytes in the segment, beginning with **$A9**, **$00** (the 6502 object
code for the *LDA #0* instruction), and extending to the **$60** (*RTS*
opcode) at offset 16.

The data from the first segment is immediately followed by the header
of the next segment, at offset 17. A **$FF**, **$FF** signature would be allowed
here, but in the example, the 2nd segment uses the 4-byte header.

At offset 17, the **$E0**, **$02** (aka **$02E0**) is the load address. **$E1**, **$02**
(**$02E1**) is the end address. **$02E0**, **$02E1** is known as *RUNAD* in the
Atari world, and it's the address where DOS will find the entry point
to the program when it's done being loaded.

The next (and last) 2 bytes are **$00**, **$06** (aka **$0600**), which is the run
address itself (to be deposited at *RUNAD*).

There are no more segments, since we've reached end of file.

Data Only
---------

Since a XEX file can load arbitrary data at arbitrary addresses, there's
simpler way to accomplish the color changes. Instead of writing code to
do the job, we just create a XEX file that loads the colors we want
directly into the color shadow registers.

In BASIC, you'd say::

  POKE 709,15
  POKE 710,0

...but BASIC doesn't have an easy way to create a XEX file.
An assembler is a more convenient tool. The code is::

  1000  *= $02C5
  1010  .BYTE $0F,$00

The binary looks like this::

  ff ff C5 02 C6 02 0F 00

The file begins with **$FF**, **$FF** header, then the 2-byte load address
(**$C5**, **$02** for address **$02C5**), then the 2-byte end address (**$C6**, **$02**,
aka **$02C6**), then the 2 bytes of data to be stored there (**$0F**, **$00**).

When loaded, this will store **$0F** at address **$02C5** (aka *COLOR0*,
the text luminance in *GRAPHICS 0*) and **$00** at **$02C6** (*COLOR1*, the
*GRAPHICS 0* background color).

Notice that there's no run or init address. That's because no code is
executed; it's just 2 bytes of raw data.

HISTORY
=======

The first Atari 8-bit binary load format was defined by Atari DOS 1.0,
in 1979. This was a multi-segmented format, but not compatible with
the DOS 2.0S binary load format (aka the XEX format). Specifically,
files began with a **$84**, **$09** header (rather than the **$FF**,
**$FF** used by DOS 2.0S), and there was no such thing as an init
routine (DOS 1 didn't use or define **INITAD**). DOS 1.0 also used
**AUTO.SYS** rather than **AUTORUN.SYS** as the file to load at
startup. Very few (or probably *no*) files in this format still exist
today.

The format used by all other Atari and third-party DOSes was
first defined by Atari DOS 2.0S. There was no standard filename
extension. Files were usually named .OBJ, .BIN, or .COM... except the
special filename **AUTORUN.SYS**, which was automatically loaded and
run by the DOS at startup.

Some later third-party DOSes do use the filename extension **.COM**
for their own external commands. Typing *FOO* at the SpartaDOS or DOS
XL command prompt will load and run a file called **FOO.COM**, if it
exists. The external command files that ship with SpartaDOS also don't
have run or init addresses (so they won't run, if loaded by another
DOS). SpartaDOS apparently uses the load address (or maybe a fixed
address) as the entry point to **.COM** files.

The name "xex" and the filename extension ".xex" came into use on the
early Internet in the 1990s, to distinguish Atari executables from
e.g. MS-DOS executables. XEX stands for "XE eXecutable", although
this is a double misnomer: there's nothing XE-specific about the
file format (it applies to the 400/800 and XL machines, too), and
technically a binary load file isn't necessarily an executable; it
could just be a block of data without run or init addresses.

.. include:: manftr.rst