From b7c94a9fee83f132708cf2bc9febef24f3e55274 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Mon, 29 Apr 2024 04:49:38 -0400 Subject: xex(5): started on. --- xex.rst | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 xex.rst (limited to 'xex.rst') diff --git a/xex.rst b/xex.rst new file mode 100644 index 0000000..41ecb0e --- /dev/null +++ b/xex.rst @@ -0,0 +1,103 @@ +.. 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. + +Segments have 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. + +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. + +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**. + +EXAMPLES +======== + +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 -- cgit v1.2.3