path: root/xex.5

.\" 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.
.