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.1 | 195 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 xexsplit.1 (limited to 'xexsplit.1') diff --git a/xexsplit.1 b/xexsplit.1 new file mode 100644 index 0000000..c3a88e6 --- /dev/null +++ b/xexsplit.1 @@ -0,0 +1,195 @@ +.\" 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 "XEXSPLIT" 1 "2022-08-27" "0.2.0" "Urchlay's Atari 8-bit Tools" +.SH NAME +xexsplit \- Split a multi-segment Atari 8-bit executable (XEX) into multiple single-segment files. +.\" 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)? +. +.SH SYNOPSIS +.sp +\fIxexsplit\fP [\fI\-hv\fP] \fIinfile.xex\fP [\fIoutfile\-prefix\fP] +.SH DESCRIPTION +.sp +xexsplit reads an Atari executable (XEX/BIN/COM/etc) from \fIinfile\fP and +writes each segment to a separate file. To read from standard input, +infile may be omitted, or given as \fB\-\fP\&. +.sp +Output files are named \fBoutfile\-prefix.NNN.SSSS.EEEE\fP, where \fBNNN\fP is +the segment number (decimal, 3 digits, with leading zeroes), \fBSSSS\fP +is the start address of the segment (4 digits, hex), and \fBEEEE\fP is the +end address of the segment (4 digits, hex). If \fIoutfile\-prefix\fP is +omitted, the default prefix is \fBxexsplit.xex\fP\&. +.sp +Each output file is a valid single\-segment Atari executable, including +the required \fI$FFFF\fP header. They may be joined back together (possibly +after being modified) with xexcat or plain old \fBcat\fP(1). +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-h +Print a short help message and exit. +.TP +.B \-v +Verbose operation. Each segment\(aqs information is printed to +standard error, including start/end address and length. +.UNINDENT +.SH NOTES +.sp +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\(aqt care about the names, only the contents. +.sp +It is not possible to use \fB\-\fP to write to standard output. This makes +sense, because there\(aqs no way to write multiple, separate files to stdout. +.sp +The output filenames were chosen so they will sort in the order they +were created, when used with the shell\(aqs globbing. This means that you +can join them back into a single valid XEX file with a command like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +cat prefix.* > joined.xex +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +or use \fBxexcat\fP(1) instead of \fBcat\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +xexcat \-o joined.xex prefix.* +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The Atari binary load format requires the \fI$FFFF\fP header only for +the first segment in a file. The second and subsequent segments may +also have a \fI$FFFF\fP header, but it\(aqs optional. \fBxexsplit\fP\(aqs output +files will always have the \fI$FFFF\fP header, regardless of whether +the segments in the original file had it or not (in fact, \fBxexsplit\fP +can handle an invalid XEX file which is missing the initial $FFFF +header for the first seg‐ ment). +.sp +A segment starting at address \fB$02E2\fP contains an init address. +During loading, Atari DOSes JSR to the init address immediately +after its segment has loaded. Init addresses are optinal; there\(aqs no +rule that says that every file has to have one. It\(aqs 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\(aqs in‐ tended to run, but this is not +a requirement. +.sp +A segment starting at address \fB$02E0\fP 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\(aqs 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. +.sp +Attempting to run a single\-segment file consisting of a run or init +address only, will generally crash the Atari. +.sp +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 \fBxexsplit\fP 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 \fBxexsplit\fP, +a raw data block is usually the reason why. +.\" other sections we might want, uncomment as needed. +. +.\" FILES +. +.\" ===== +. +.\" ENVIRONMENT +. +.\" =========== +. +.\" EXIT STATUS +. +.\" =========== +. +.\" BUGS +. +.\" ==== +. +.\" EXAMPLES +. +.\" ======== +. +.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), +\fBcart2xex\fP(1), +\fBdasm2atasm\fP(1), +\fBfenders\fP(1), +\fBrom2cart\fP(1), +\fBunmac65\fP(1), +\fBxexcat\fP(1), +\fBxexsplit\fP(1), +\fBxfd2atr\fP(1). +.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. +. -- cgit v1.2.3