diff options
| -rw-r--r-- | xex.5 | 154 | ||||
| -rw-r--r-- | xex.rst | 103 |
2 files changed, 257 insertions, 0 deletions
@@ -0,0 +1,154 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "XEX" 5 "2024-04-29" "0.2.1" "Urchlay's Atari 8-bit Tools" +.SH NAME +xex \- Atari 8-bit executable file format. +.\" RST source for xex(5) man page. Convert with: +. +.\" rst2man.py xex.rst > xex.5 +. +.SH DESCRIPTION +.sp +This manual describes the Atari 8\-bit binary load format, commonly known +as ".xex" or "binary load". +.sp +The file format consists of one or more segments, each having its own +load address. This is an absolute address in the Atari\(aqs memory map, +and there\(aqs no facility for relocating the code. +.sp +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. +.sp +The 6\-byte header consists of: +.INDENT 0.0 +.IP \(bu 2 +2 bytes set to \fB$FF\fP\&. +.IP \(bu 2 +The 2\-byte load address of the segment, in standard LSB\-first 6502 order. +.IP \(bu 2 +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. +.UNINDENT +.sp +The 4\-byte header is the same as the 6\-byte header, except it lacks the +initial \fB$FF\fP, \fB$FF\fP bytes. +.sp +The rest of each segment just consists of the data to be loaded, +exactly \fI(end_address \- load_address) + 1\fP bytes. +.sp +It\(aqs 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. +.sp +Init routines are normal segments. An init \fIaddress\fP is also a normal +segment: 2 bytes loaded at address \fB$02E2\fP, aka \fBINITAD\fP\&. As +soon as this segment is loaded, the DOS will jump (actually \fBJSR\fP) +to this address, which should exit back to DOS with an \fBRTS\fP +instruction. After the routine exits, DOS will continue loading the +file normally. +.sp +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\(aqs possible for the program to exit via the 6502 +\fBRTS\fP instruction, though many program (especially games) never +exit. +.sp +The run address segment is the one that loads the 2\-byte run address +into address \fB$02E0\fP, aka \fBRUNAD\fP\&. +.SH EXAMPLES +.SH HISTORY +.sp +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 \fB$84\fP, \fB$09\fP header (rather than the \fB$FF\fP, +\fB$FF\fP used by DOS 2.0S), and there was no such thing as an init +routine (DOS 1 didn\(aqt use or define \fBINITAD\fP). DOS 1.0 also used +\fBAUTO.SYS\fP rather than \fBAUTORUN.SYS\fP as the file to load at +startup. Very few (or probably \fIno\fP) files in this format still exist +today. +.sp +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 \fBAUTORUN.SYS\fP, which was automatically loaded and +run by the DOS at startup. +.sp +Some later third\-party DOSes do use the filename extension \fB\&.COM\fP +for their own external commands. Typing \fIFOO\fP at the SpartaDOS or DOS +XL command prompt will load and run a file called \fBFOO.COM\fP, if it +exists. The external command files that ship with SpartaDOS also don\(aqt +have run or init addresses (so they won\(aqt run, if loaded by another +DOS). SpartaDOS apparently uses the load address (or maybe a fixed +address) as the entry point to \fB\&.COM\fP files. +.sp +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\(aqs nothing XE\-specific about the +file format (it applies to the 400/800 and XL machines, too), and +technically a binary load file isn\(aqt necessarily an executable; it +could just be a block of data without run or init addresses. +.SH COPYRIGHT +.sp +WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details. +.SH AUTHOR +.INDENT 0.0 +.IP B. 3 +Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&. +.UNINDENT +.SH SEE ALSO +.sp +\fBa8eol\fP(1), +\fBa8utf8\fP(1), +\fBatr2xfd\fP(1), +\fBatrsize\fP(1), +\fBaxe\fP(1), +\fBblob2c\fP(1), +\fBblob2xex\fP(1), +\fBcart2xex\fP(1), +\fBdasm2atasm\fP(1), +\fBf2toxex\fP(1), +\fBfenders\fP(1), +\fBrom2cart\fP(1), +\fBunmac65\fP(1), +\fBxexamine\fP(1), +\fBxexcat\fP(1), +\fBxexsplit\fP(1), +\fBxfd2atr\fP(1), +\fBxex\fP(5). +.sp +Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC Reference +Manual\fP, the \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc. +.\" Generated by docutils manpage writer. +. @@ -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 |