xex(5): started on.

2 files changed, 257 insertions, 0 deletions

diff --git a/xex.5 b/xex.5
new file mode 100644
index 0000000..ce9e449
--- /dev/null
+++ b/xex.5
@@ -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.
+.
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