XEXSPLIT(1)

NAME
xexsplit - Split a multi-segment Atari 8-bit executable (XEX) into multiple single-segment files.

SYNOPSIS

xexsplit [-hvr] 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.EXT, where NNN is the segment number (decimal, 3 digits, with leading zeroes), SSSS is the start address of the segment (4 digits, hex), EEEE is the end address of the segment (4 digits, hex), and EXT is .xex for .xex output or .bin for raw (-r) output. If outfile-prefix is omitted, the default prefix is the input filename.

By default, 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

-r  Raw output: the output files will just contain the data from each segment, without the $FFFF header, start, and end addresses. Useful for feeding the results to tools like disassemblers that don't understand the .xex format.

-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 segment).

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 address segment is normally located right after the code segment it's intended 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.

COPYRIGHT

WTFPL. See http://www.wtfpl.net/txt/copying/ for details.

AUTHOR

B.  Watson <urchlay@slackware.uk>; Urchlay on irc.libera.chat ##atari.

SEE ALSO

a8cat(1), a8eol(1), a8xd(1), atr2xfd(1), atrsize(1), axe(1), bas2aplus(1), blob2c(1), blob2xex(1), cart2xex(1), cxrefbas(1), dasm2atasm(1), diffbas(1), dumpbas(1), f2toxex(1), fenders(1), listbas(1), listamsb(1), protbas(1), renumbas(1), rom2cart(1), unmac65(1), unprotbas(1), vxrefbas(1), whichbas(1), xex1to2(1), xexamine(1), xexcat(1), xexsplit(1), xfd2atr(1), xex(5), atascii(7), fauxtari(7).

Any good Atari 8-bit book: De Re Atari, The Atari BASIC Reference Manual, the OS Users' Guide, Mapping the Atari, etc.