diff options
Diffstat (limited to 'fenders.1')
| -rw-r--r-- | fenders.1 | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/fenders.1 b/fenders.1 new file mode 100644 index 0000000..aa6d5fc --- /dev/null +++ b/fenders.1 @@ -0,0 +1,282 @@ +.\" 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 "FENDERS" 1 "2022-08-27" "0.2.0" "Urchlay's Atari 8-bit Tools" +.SH NAME +fenders \- Install Fenders 3-sector loader in boot sectors of an ATR image +.\" RST source for fenders(1) man page. Convert with: +. +.\" rst2man.py fenders.rst > fenders.1 +. +.\" rst2man.py comes from the SBo development/docutils package. +. +.SH SYNOPSIS +.sp +\fIfenders\fP [\fI\-hrcsiv\fP] [\-t \fItitle\fP] \fIinfile.atr\fP [\fIoutfile.atr\fP] +.SH DESCRIPTION +.sp +\fBfenders\fP replaces the boot sectors of an ATR image with a menu\-driven +"game dos" binary loader. +.sp +When the disk is booted, a disk directory menu is displayed on the +screen. To load a binary (XEX/COM/BIN/etc) file, press the letter +shown for that file. Other file types may not be loaded (and will cause +the Atari to crash). +.sp +The installed bootloader overwrites sectors 1\-3 of the image +(and sector 720, for double\-density images). This is the same code +installed by the Atari\-based \fBFenders 3\-sector\fP loader installer +utility. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-h +Print this help message. +.TP +.B \-r +DON\(aqT reboot (coldstart) the Atari if Reset is pressed. The default is to coldstart. +.TP +.B \-c +Rotate colors during load. May cause problems with some games. +.TP +.B \-s +Screen off after load. May cause problems with some games, but +may fix graphics corruption for other games. YMMV. +.TP +.B \-i +In\-place update. The input file is renamed to end in \fB~\fP (tilde), +and the output is written to the original filename. May not be +used when reading from standard input. +.TP +.B \-v +Set inverse video bit in title. This causes the title text to +appear in red and/or blue on the Atari, instead of the default +orange and green colors. +.TP +.B \-t +Set the menu title. May up to 20 characters; default is \fIatari +arcade\fP\&. Will be truncated to 20 characters if a longer title is +given. See MENU TITLE, below. Note that you\(aqll have to quote the +title if it contains spaces or other characters that have meaning to your shell. +.UNINDENT +.INDENT 0.0 +.TP +.B infile +The ATR image to read from. It must be either single\-density +and at least 368 sectors long, or double\-density and at least +720 sectors long. You may use \fB\-\fP for \fIinfile\fP to read from +standard input (unless \fB\-i\fP is used). +.TP +.B outfile +The ATR image to create, which will contain all the files +from the input image, plus the Fenders boot loader. You may +omit \fIoutfile\fP or use \fB\-\fP to write to standard output. \fIoutfile\fP is +ignored when the \fB\-i\fP option is used. +.UNINDENT +.sp +If both \fIinfile\fP and \fIoutfile\fP are omitted, the default is to read from +standard input and write to standard output. +.SH NOTES +.sp +\fBfenders\fP will abort, if asked to write to standard output when standard +output is a terminal. This is to avoid spewing binary garbage to your +terminal. +.sp +The \fB\-r\fP, \fB\-c\fP, \fB\-s\fP, and \fB\-t\fP options actually modify the \fBfenders\fP 6502 object +code before writing it to the ATR image. +.sp +The Atari \fBfenders\fP installer\(aqs default is to not coldstart, which +tends to cause the Atari to lock up when Reset is pressed. The +author believes that rebooting the Atari is more useful than locking +it up, so \fBfenders\fP causes the coldstart by default. +.sp +The Atari \fBfenders\fP installer contains a bug: the meanings of the "Rotate +color" and "Screen off after load" options are reversed. \fBfenders\fP does +not duplicate this bug. +.sp +The disk density doesn\(aqt have to be specified, because \fBfenders\fP reads it +from the ATR header. The loader\(aqs 6502 object code is different, for +single\- and double\-density disks. +.sp +The double\-density version of the loader isn\(aqt actually a 3\-sector +loader. The first 384 bytes of its code are stored in the 3 boot sectors, and the last 256 bytes of code are actually read from sector 720. +When installing the boot loader on a double\-density disk, sector 720 is +\fBoverwritten\fP\&. Any data that may have been there is lost. On most disks, +sector 720 is either unusable by DOS, or not used unless the disk is +completely full, so this is less of a problem than you might think. +.sp +\fBfenders\fP and the \fBfenders\fP boot\-loader code will work with DOS +2.5 "enhanced density" formatted floppies, but only partially: files +that use sectors above 720 will not appear in the menu (these are the +same files that DOS 2.5 lists with <> around the filename). +.sp +\fBfenders\fP only works on Atari DOS 2.x and compatible (MyDOS, DOS XL, et +al) single\-sided disk images, either single\-density (720 sectors, 90K), +double\-density (720 sectors, 180K), or "1050 enhanced" density (1040 +sectors, 130K, although 1050 enhanced density images must be in DOS 2.5 +format, \fInot\fP MyDOS, and see \fBLIMITATIONS\fP below). Other non\-standard DOS +formats such as SpartaDOS or Atari DOS 3.0 and 4.0 are not supported. +Atari DOS 1.0 may or may not work (untested). +.sp +The \fBfenders\fP boot loader source code distributed with \fBfenders\fP +is not the original source code (which has never been +released). The author of \fBfenders\fP spent a couple of days with a +disassembly of the object code and reverse engineered (labelled, +commented) it so that humans can read it, provided they are humans who +speak 6502 assembly. The \fIfenders.dasm\fP and \fIfendersdbl.dasm\fP files +can be assembled with the DASM cross assembler. The resulting object +code is identical with the original \fBfenders\fP object code (which +the author read from a disk image in the first place). +.sp +Contrary to what you may have read, the Fenders boot loader code +doesn\(aqt have to be rewritten to a disk if you add/delete files. It +reads the disk directory, and can cope with changes just fine. Even a +heavily fragmented filesystem won\(aqt cause any problems. +.SH MENU TITLE +.sp +The menu title (set with \fB\-t\fP) is stored in sector 3 for a +single\-density disk or sector 720 of a double\-density disk, in Atari +internal screen codes (which are not the same as either ASCII or +ATASCII). fenders converts the title into internal codes, so the user +doesn\(aqt have to worry about this. +.sp +The menu title is displayed in "GRAPHICS 2" mode, which can only +display 64 different characters, including uppercase, numbers, and +(most) punctuation, but NOT including lowercase or inverse video. +.sp +However, lowercase letters are displayed as different\-colored +uppercase letters, and inverse characters are also displayed with +different colors. The boot loader uses the default Atari +colors, as set by the Atari OS. +.sp +The title is limited to 20 characters because that\(aqs the width of a +GRAPHICS 2 line of text on the Atari. +.sp +The character set used by GRAPHICS 2 consists of: +.INDENT 0.0 +.IP \(bu 2 +The space character. +.IP \(bu 2 +The letters \fBA\-Z\fP\&. +.IP \(bu 2 +The numbers \fB0\-9\fP\&. +.IP \(bu 2 +Punctuation: \fB!\fP \fB"\fP \fB#\fP \fB$\fP \fB%\fP \fB&\fP \fB\(aq\fP \fB(\fP \fB)\fP \fB*\fP \fB+\fP \fB,\fP \fB\-\fP \fB\&.\fP \fB/\fP \fB:\fP \fB;\fP \fB<\fP \fB=\fP \fB>\fP \fB?\fP \fB@\fP \fB[\fP \fB\e\fP \fB]\fP \fB^\fP \fB_\fP +.UNINDENT +.sp +Uppercase letters, numbers, and punctuation are displayed in orange (or +blue, if \fB\-v\fP is used). +.sp +Lowercase letters are displayed in green (or red, with \fB\-v\fP). +.sp +The characters \(ga { | } ~ are displayed as green (or red) versions of +@ [ ] ^, respectively. +.sp +Currently, it\(aqs not possible to mix normal (orange/green) characters +with inverse (blue/red) with fenders, unless your terminal provides a +way for you to enter ASCII characters with their high bits set. Some +versions of xterm(1x) allow this with the Alt or Meta key. +.SH LIMITATIONS +.sp +\fBfenders\fP should warn if the disk image contains more than 20 files, +since they won\(aqt all be displayed in the menu. +.sp +Double\-density images less than 720 sectors long are not handled, +although they could be with a little more work. +.sp +For double\-density disks, the VTOC and sector link bytes should +be checked to see if sector 720 is in use, rather than just blindly +overwriting it. On a single\-density DOS 2.0S disk, sector 720 is +marked "in use" in the VTOC when the disk is formatted, but will never +be used for file storage. +.sp +No checking for non\-standard formats (SpartaDOS, DOS 3, MyDOS with +subdirectories, dedicated bootdisks, etc) is done. +.sp +If an "enhanced" 1050 density disk image has the bootloader installed, +it won\(aqt display the files using sectors above 720 (the ones which +would appear as \fI<filename.ext>\fP in the DOS 2.5 directory). +.sp +Actually, the above limitations are a direct result of the fact that +\fBfenders\fP deals with the disk image at the "sector" level, and contains +no code that understands the files, directory, or VTOC on the image. +The original Atari\-based Fenders installer shares the same limitations, +so the author doesn\(aqt really consider them to be bugs, although they +may be addressed in a future version of \fBfenders\fP\&. +.sp +Note that the bootloader only displays up to 20 files on the screen. +This shouldn\(aqt be a real problem (how many games can you fit on a 180K +floppy?), but no warning or error is given if there are too many files. +.sp +The bootloader only supports standard SIO disk speed (19200bps). The +only way to make it support high\-speed SIO is to use the APE Warp OS +(or some other high\-speed patched OS) on the Atari. +.SH BUGS +.sp +There should be an option to delete DOS.SYS and DUP.SYS from the image, +but there isn\(aqt. The original Fenders installer has this option. +.sp +When used with an image whose size according to the ATR header +doesn\(aqt match the actual image file size, \fBfenders\fP may produce +a broken or zero\-length output file. If in doubt, use \fBatrcheck\fP to +validate the image before use. +.sp +There should be a way to install an arbitrary 3\-sector (384\-byte) +binary file in the boot sectors of an image. This can be done with +\fBdd\fP, of course, but its syntax is difficult to remember, and typos are +prone to wipe out the file you\(aqre working with. +.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. +. |