.XEX File Format

Atari 8-bit executable

Introduction

A .xex file is a program for the Atari 8-bit computers (the 400, 800, XL and XE, which have a 6502C processor, nicknamed SALLY, and the ANTIC, GTIA and POKEY chips). It is the binary load file format of Atari DOS: a list of segments, each saying which addresses of memory its bytes go to. A segment can also write the two vectors that tell DOS where to start the program, so the same file can load a program, patch the system and start it.

The extension is a convention: Atari DOS never looked at it. Programs have been called .xex, .com, .exe and .obx (the extension of the MADS assembler’s output), or had no extension at all; a file named AUTORUN.SYS is loaded and run by DOS 2 when the disk boots. Atari emulators run these files directly.

A file dropped on any page opens in the explorer. It lists every segment, marks the ones that set the run and init vectors, and disassembles each segment at its load address with the instruction decoder for the 6502, an instruction decoded at every byte and laid out in columns. Accesses to the hardware registers and the operating system’s entry points and variables are shown with their names (named addresses); undocumented and unstable opcodes are highlighted (see the instruction set).

The explorer takes a file as an Atari executable when its name ends in .xex or .obx, or when it has no extension and its segments exactly fill it. A .com or .exe file belongs to the DOS programs of the same names, so those are not claimed; an Atari program with such a name can be opened with “Read as” in the explorer.

Structure

  1. 0x0000Marker FF FF: required at the start of the file2 bytes
  2. 0x0002Start address of the first segment, little endian2 bytes
  3. 0x0004End address: the address of the segment’s last byte2 bytes
  4. 0x0006Data: end − start + 1 bytes, loaded at the start addressvariable
  5. …more segments, each an optional marker FF FF, a start, an end and datato the end of the file
An Atari binary load file; the file ends where the last segment’s data ends

The pages Segments and Loading and start-up describe each part. The explorer reads the segments in order and stops at the first thing that is not a segment, listing the rest as extra bytes.

An example

This 17-byte file loads a short program at $0600 and then sets the run address $02E0 to it:

  1. FF FFmarker2 bytes
  2. 00 06 04 06start $0600, end $0604: five data bytes4 bytes
  3. A9 00 8D 1A D0lda #$00, sta $d01a (the background colour COLBK)5 bytes
  4. E0 02 E1 02start $02E0, end $02E1: the run address vector, two bytes4 bytes
  5. 00 06RUNAD = $06002 bytes
The data of the first segment goes to $0600; when the file is loaded DOS jumps to $0600

The processor

The Atari 8-bit computers use a 6502C, an NMOS 6502 that has an extra line for ANTIC to halt it. A program does not say which processor it needs, so the explorer decodes it as an NMOS 6502, with the undocumented opcodes marked; the options bar can switch to the 65C02 for programs written for an upgrade board. See the 6502 instruction set for every instruction.

Not described

Known, not yet covered

  • Reference and viewer: the extended headers of other loaders. SpartaDOS X and some packers put other words than $FFFF in front of a segment (to load into banks or to relocate). The viewer stops there and lists the rest as extra bytes.
  • Viewer: which bytes are code and which are data. Every byte of a segment is decoded; code reached only through a table, or moved by the program, is not followed. A segment that sets a vector is disassembled too unless it covers only $02E0 to $02E3.
  • Viewer: programs that load other files, such as a game that runs a loader first and then streams data from the disk, show only the loader.
  • Reference: cartridge images (.CAR, .ROM), tokenised BASIC files and the boot disks’ own sector format. Boot sectors are in the ATR pages.

Unknown

  • Reference: no real Atari binary load file was available while these pages were written; the format was checked against built files, the loader of an emulator and published descriptions of DOS 2 only. How each DOS handles an INITAD that is set by a segment the loader has already run past, and what DOS 2 does when no RUNAD is set, rest on those descriptions.

Links

Software

  • Altirra – Atari 8-bit emulator with a debugger that runs XEX files (Windows)
  • Atari800 – Atari 8-bit emulator that runs XEX files (Windows, macOS, Linux)
  • MADS – 6502 cross-assembler that writes XEX files with segments and run and init vectors (Windows, macOS, Linux)
  • cc65 – C compiler, assembler and linker for 6502 systems, with an Atari target (Windows, macOS, Linux)

Reference

  • De Re Atari – the Atari programmers’ guide to the hardware and the operating system
  • Mapping the Atari – a memory map of the Atari 8-bit computers, with the names used in the explorer