Inside the XEX: The Atari DOS Binary-Load File Format
Almost every Atari 8-bit program you download today is a .xex. The name is modern. .XEX (like .OBX for non-autorun object files) was adopted so that PCs wouldn't mistake Atari .EXE and .OBJ files for MS-DOS ones. The format itself goes back to Atari DOS 2.0S and the Assembler Editor cartridge. De Re Atari calls it the object-file ("binary") format used by DOS menu options K. Binary Save and L. Binary Load. Once you know how it is laid out you can debug loaders, split and join files, write multi-stage loaders with title screens, and see why some files fail under particular DOSes.
What you'll learn: the exact byte layout, how RUNAD and INITAD drive execution, common multi-segment patterns, the SpartaDOS X extensions, and a small tool to list a file's segments.
1. The layout
A binary-load file is just a series of segments (cc65's documentation calls them "load chunks"):
FF FF header: marks a binary file
SS SS EE EE data... segment: start address, END address (inclusive), bytes
SS SS EE EE data... next segment (an FF FF before it is optional)
...
- All addresses are little-endian (low byte first).
- The second word is the last address loaded, not a length. The segment holds
end - start + 1bytes. This trips up almost everyone who writes their first XEX tool. - The
$FFFFmarker is required at the start of the file. Before later segments it may appear or not. Tools differ. MADS, for example, writes it only once at the start of the file. Loaders accept it either way. - Segments may come in any order and go to any RAM address, including page zero, page two and the hardware registers (with care).
2. Making it run: RUNAD and INITAD
There's no "entry point" field. The loader watches two OS locations, and a segment that writes to them controls execution:
| Name | Address | When it's used |
|---|---|---|
| RUNAD | 736–737 ($2E0–$2E1) |
After the whole file has loaded, the loader jumps to this address. |
| INITAD | 738–739 ($2E2–$2E3) |
As soon as a segment that sets it has loaded, the loader calls (JSRs) this address. When the routine returns with RTS, loading continues. |
In short: INITAD code runs as soon as that location is loaded, RUNAD code only after the entire load has finished, and you return to DOS by ending with RTS. A file can contain any number of INIT segments. Only the last RUNAD written takes effect.
Careful: De Re Atari's DOS chapter gives the two addresses the wrong way round (INIT as
$02E0, RUN as$02E2). The correct values, used by the cc65 runtime (which writes its run vector to$02E0) and every modern assembler, are RUNAD =$2E0, INITAD =$2E2.
3. A complete file, byte by byte
Here's a 23-byte program that sets the border colour and waits for a key:
*= $2000
START LDA #$34
STA $02C8 ; COLOR4
LDA #$FF
STA $02FC ; CH: clear last key
WAIT LDA $02FC
CMP #$FF
BEQ WAIT
LDA #$FF
STA $02FC
RTS
*= $02E0
.WORD START
The resulting file is 35 bytes:
0000: FF FF 00 20 16 20 A9 34 8D C8 02 A9 FF 8D FC 02
0010: AD FC 02 C9 FF F0 F9 A9 FF 8D FC 02 60 E0 02 E1
0020: 02 00 20
Read it as: header FF FF, then a segment from $2000 to $2016 holding 23 bytes of code, then a segment from $02E0 to $02E1 holding 00 20. That second segment puts $2000 into RUNAD. (This is byte-for-byte what MADS produces from the equivalent source. ATasm writes the same two segments in the opposite order, $02E0 first. That makes no difference, because RUNAD is only used once the whole file has loaded.)
4. Patterns you'll meet
Loading screens and music during the load. The first segments hold a picture or player routine plus an INIT segment that switches it on and returns. The main game segments load while the picture is showing.
Loading "impossible" areas. You can't load straight into RAM under the OS ROM, because the ROM is mapped in while DOS runs. The common trick is to load the data into ordinary RAM, follow it with an INIT segment whose routine switches the ROM out, copies the data, switches the ROM back in and returns, and then load the next part.
Checks before the main program. cc65 programs start with a "system check" chunk, always at $2E00. It is followed by INIT code that aborts the load if there isn't enough memory or if the program would load below MEMLO. The atarixl target adds a third chunk that moves the screen and copies the character set into RAM under the ROM.
Lots of tiny segments. Some old assemblers split their output. MAC/65, for instance, is remembered for writing object files in chunks of 252 bytes, each with its own address header. This works, but it wastes space and slows the load. Tools that join adjacent segments are common.
Producing segments with your assembler:
; MADS
org $2000
...
ini setup ; INITAD segment
run main ; RUNAD segment
; MAC/65, Assembler Editor, ATasm
*= $02E2
.WORD SETUP
*= $02E0
.WORD MAIN
cc65's atari-xex.cfg / atari-asm-xex.cfg use ld65's native XEX writer. Each MEMORY area becomes a segment, and you can give each one an INITAD.
5. SpartaDOS X extensions
SpartaDOS X added relocatable programs and named system symbols using extra header values. They are:
| Header | Block type |
|---|---|
$FFFF |
Ordinary Atari DOS segment |
$FFFA |
SpartaDOS X segment at a fixed address |
$FFFE |
Relocatable block (main or extended memory), loaded at MEMLO |
$FFFD |
Address-fixup block for relocatable code |
$FFFB |
Symbol-fixup block (resolves names such as PRINTF) |
$FFFC |
Defines a new symbol |
These files are not loadable by Atari DOS. DOS II+ stops reading when it reaches a $FFFA block, while SpartaDOS 4.22 treats $FFFA and $FFFF the same. If a .COM file "loads but does nothing" under DOS 2.5, check whether it is really an SDX program.
6. A segment lister in Python
#!/usr/bin/env python3
"""xexdump.py - list the segments of an Atari DOS binary-load (XEX) file."""
import sys
data = open(sys.argv[1], 'rb').read()
i = 0
if data[:2] != b'\xff\xff':
sys.exit('not an Atari binary file: missing $FFFF header')
while i + 4 <= len(data):
start = data[i] | data[i + 1] << 8
if start == 0xFFFF: # optional extra header before any segment
i += 2
continue
end = data[i + 2] | data[i + 3] << 8
i += 4
size = end - start + 1
if size <= 0 or i + size > len(data):
sys.exit(f'bad or truncated segment ${start:04X}-${end:04X}')
seg = data[i:i + size]
i += size
note = ''
for vec, name in ((0x2E0, 'RUNAD'), (0x2E2, 'INITAD')):
if start <= vec and vec + 1 <= end:
addr = seg[vec - start] | seg[vec - start + 1] << 8
note += f' {name} -> ${addr:04X}'
print(f'${start:04X}-${end:04X} {size:5d} bytes{note}')
if i != len(data):
print(f'warning: {len(data) - i} trailing byte(s) ignored')
Run on the file from section 3 it prints:
$2000-$2016 23 bytes
$02E0-$02E1 2 bytes RUNAD -> $2000
7. Loading and inspecting XEX files in Altirra
- File > Boot Image loads an XEX directly. Start Altirra with
/debugbrkrun(or turn on the matching debugger option) to stop in the debugger at the run address. .onexeloadand.onexerunqueue debugger commands to run just before the first segment loads or just before the run vector is used. These hooks work only with Altirra's own loader, not when a DOS on the emulated machine loads the file..loadobj file.xexloads a file's segments into memory without running its INIT or RUN vectors. Handy for loading helper code while you're debugging.
Troubleshooting
- DOS refuses the file or loads garbage. The first two bytes aren't
$FF $FF, often because a raw binary was saved with the wrong option, or the file was mangled in a text-mode transfer (CR/LF conversion). - The program crashes as soon as it loads under one DOS but not another. A segment overlaps that DOS's memory. Compare the lowest segment address with MEMLO (
$2E7/$2E8) under that DOS. - Loading hangs part way. An INIT routine never returned, or returned with the stack unbalanced. INIT code must end with
RTSand leave the IOCB that DOS is reading from untouched. - It loads but doesn't start. No RUNAD segment. Run it from DOS with M. Run at Address, or add the segment.
- Works from DOS, fails on a "game loader" or flash cart. Some quick loaders don't support INIT segments, or don't allow segments in page two or three. Try another loader, or merge the segments.
Further reading
- Mapping the Atari (Ian Chadwick, COMPUTE! Books, 1983), entries 736–744 and the DOS section.
- Inside Atari DOS, Bill Wilkinson (COMPUTE!/Small System Services, 1982), with the full FMS source for DOS 2.0S.
- De Re Atari, chapter 9, for the DOS menu and AUTORUN.SYS. Remember the swapped addresses.
Credits
- Mapping the Atari — RUNAD (736) and INITAD (738), MEMLO/MEMTOP — AtariArchives.org
- De Re Atari, chapter 9 — The Disk Operating System (Binary Save/Load, AUTORUN.SYS) — AtariArchives.org
- cc65 documentation — Atari binary format and load chunks — cc65.github.io
- Fast Assembler 1.8 manual — SpartaDOS X block types — GitHub project authors
- MADS example file_header.asm ($FFFA blocks under DOS II+ vs SpartaDOS) — JAC; mads.atari8.info
- AtariAge — Format of .XEX files? — AtariAge forum members
- AtariAge — Building a XEX with MAC/65 — AtariAge forum members
- comp.sys.atari.8bit FAQ — file name extensions (.COM, .EXE, .OBJ, .OBX, .XEX) — Michael Current (comp.sys.atari.8bit FAQ)
- Altirra debugger help (.loadobj, /debugbrkrun, .onexerun) — Screenshot from Avery Lee's Altirra page, virtualdub.org
