From e2ba8458a5cfdfacfaf103e7ba97d610afa6c970 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Mon, 29 Aug 2022 16:11:13 -0400 Subject: initial commit --- xexsplit.rst | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 xexsplit.rst (limited to 'xexsplit.rst') diff --git a/xexsplit.rst b/xexsplit.rst new file mode 100644 index 0000000..3a304c3 --- /dev/null +++ b/xexsplit.rst @@ -0,0 +1,128 @@ +.. RST source for xexsplit(1) man page. Convert with: +.. rst2man.py xexsplit.rst > xexsplit.1 +.. rst2man.py comes from the SBo development/docutils package. + +.. TODO: add -n option (same as -v, but no output)? + +======== +xexsplit +======== + +-------------------------------------------------------------------------------------- +Split a multi-segment Atari 8-bit executable (XEX) into multiple single-segment files. +-------------------------------------------------------------------------------------- + +.. include:: manhdr.rst + +SYNOPSIS +======== + +*xexsplit* [*-hv*] *infile.xex* [*outfile-prefix*] + +DESCRIPTION +=========== + +xexsplit reads an Atari executable (XEX/BIN/COM/etc) from *infile* and +writes each segment to a separate file. To read from standard input, +infile may be omitted, or given as **-**. + +Output files are named **outfile-prefix.NNN.SSSS.EEEE**, where **NNN** is +the segment number (decimal, 3 digits, with leading zeroes), **SSSS** +is the start address of the segment (4 digits, hex), and **EEEE** is the +end address of the segment (4 digits, hex). If *outfile-prefix* is +omitted, the default prefix is **xexsplit.xex**. + +Each output file is a valid single-segment Atari executable, including +the required *$FFFF* header. They may be joined back together (possibly +after being modified) with xexcat or plain old **cat**\(1). + +OPTIONS +======= + +-h + Print a short help message and exit. + +-v + Verbose operation. Each segment's information is printed to + standard error, including start/end address and length. + +NOTES +===== + +The terms "Atari executable", "binary load file", and "XEX file" +all refer to the same thing. Also, there is no difference between +Atari executables named with "XEX", "COM", "BIN", "EXE", etc. The +Atari and its DOS don't care about the names, only the contents. + +It is not possible to use **-** to write to standard output. This makes +sense, because there's no way to write multiple, separate files to stdout. + +The output filenames were chosen so they will sort in the order they +were created, when used with the shell's globbing. This means that you +can join them back into a single valid XEX file with a command like:: + + cat prefix.* > joined.xex + +or use **xexcat**\(1) instead of **cat**:: + + xexcat -o joined.xex prefix.* + +The Atari binary load format requires the *$FFFF* header only for +the first segment in a file. The second and subsequent segments may +also have a *$FFFF* header, but it's optional. **xexsplit**'s output +files will always have the *$FFFF* header, regardless of whether +the segments in the original file had it or not (in fact, **xexsplit** +can handle an invalid XEX file which is missing the initial $FFFF +header for the first seg‐ ment). + +A segment starting at address **$02E2** contains an init address. +During loading, Atari DOSes JSR to the init address immediately +after its segment has loaded. Init addresses are optinal; there's no +rule that says that every file has to have one. It's also normal +and fairly common for there to be several init addresses in a +multi-segment file. An init ad‐ dress segment is normally located +right after the code segment it's in‐ tended to run, but this is not +a requirement. + +A segment starting at address **$02E0** contains a run address. +After all segments have been loaded, Atari DOSes JSR to the run +address to run the program just loaded. The run address is optional; +a file containing no run address segment will simply be loaded into +memory and not executed (user will be returned to the DOS menu). +It's legal for a multi-segment file to contain multiple run +address segments, but only the last run address will actually be +used. Normally, there is only one run address; if there are more than +one, only the last one is used. The run address is normally the last +segment in the file, but this is not a requirement. + +Attempting to run a single-segment file consisting of a run or init +address only, will generally crash the Atari. + +Some Atari executables contain raw blocks of data, which are meant +to be read into memory by the init routine. These blocks do not +have start/end address headers, so **xexsplit** is unable to handle +them. Raw data blocks usually occur in files created with "packer" +or "compressor" programs, or occasionally in other large programs +(Turbo BASIC is an example). Raw data blocks are generally found just +after an init address segment. If you have an executable that loads +just fine on a real Atari or emulator, but fails with **xexsplit**, +a raw data block is usually the reason why. + +.. other sections we might want, uncomment as needed. + +.. FILES +.. ===== + +.. ENVIRONMENT +.. =========== + +.. EXIT STATUS +.. =========== + +.. BUGS +.. ==== + +.. EXAMPLES +.. ======== + +.. include:: manftr.rst -- cgit v1.2.3