diff options
Diffstat (limited to 'fenders.rst')
| -rw-r--r-- | fenders.rst | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/fenders.rst b/fenders.rst new file mode 100644 index 0000000..9c4f1c7 --- /dev/null +++ b/fenders.rst @@ -0,0 +1,239 @@ +.. RST source for fenders(1) man page. Convert with: +.. rst2man.py fenders.rst > fenders.1 +.. rst2man.py comes from the SBo development/docutils package. + +======= +fenders +======= + +--------------------------------------------------------------- +Install Fenders 3-sector loader in boot sectors of an ATR image +--------------------------------------------------------------- + +.. include:: manhdr.rst + +SYNOPSIS +======== + +*fenders* [*-hrcsiv*] [-t *title*] *infile.atr* [*outfile.atr*] + +DESCRIPTION +=========== + +**fenders** replaces the boot sectors of an ATR image with a menu-driven +"game dos" binary loader. + +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). + +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 **Fenders 3-sector** loader installer +utility. + + +OPTIONS +======= + +-h + Print this help message. + +-r + DON'T reboot (coldstart) the Atari if Reset is pressed. The default is to coldstart. + +-c + Rotate colors during load. May cause problems with some games. + +-s + Screen off after load. May cause problems with some games, but + may fix graphics corruption for other games. YMMV. + +-i + In-place update. The input file is renamed to end in **~** (tilde), + and the output is written to the original filename. May not be + used when reading from standard input. + +-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. + +-t + Set the menu title. May up to 20 characters; default is *atari + arcade*. Will be truncated to 20 characters if a longer title is + given. See MENU TITLE, below. Note that you'll have to quote the + title if it contains spaces or other characters that have meaning to your shell. + +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 **-** for *infile* to read from + standard input (unless **-i** is used). + +outfile + The ATR image to create, which will contain all the files + from the input image, plus the Fenders boot loader. You may + omit *outfile* or use **-** to write to standard output. *outfile* is + ignored when the **-i** option is used. + +If both *infile* and *outfile* are omitted, the default is to read from +standard input and write to standard output. + +NOTES +===== + +**fenders** 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. + +The **-r**, **-c**, **-s**, and **-t** options actually modify the **fenders** 6502 object +code before writing it to the ATR image. + +The Atari **fenders** installer's 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 **fenders** causes the coldstart by default. + +The Atari **fenders** installer contains a bug: the meanings of the "Rotate +color" and "Screen off after load" options are reversed. **fenders** does +not duplicate this bug. + +The disk density doesn't have to be specified, because **fenders** reads it +from the ATR header. The loader's 6502 object code is different, for +single- and double-density disks. + +The double-density version of the loader isn't 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 +**overwritten**. 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. + +**fenders** and the **fenders** 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). + +**fenders** 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, *not* MyDOS, and see **LIMITATIONS** 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). + +The **fenders** boot loader source code distributed with **fenders** +is not the original source code (which has never been +released). The author of **fenders** 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 *fenders.dasm* and *fendersdbl.dasm* files +can be assembled with the DASM cross assembler. The resulting object +code is identical with the original **fenders** object code (which +the author read from a disk image in the first place). + +Contrary to what you may have read, the Fenders boot loader code +doesn't 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't cause any problems. + +MENU TITLE +========== + +The menu title (set with **-t**) 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't have to worry about this. + +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. + +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. + +The title is limited to 20 characters because that's the width of a +GRAPHICS 2 line of text on the Atari. + +The character set used by GRAPHICS 2 consists of: + +- The space character. + +- The letters **A-Z**. + +- The numbers **0-9**. + +- Punctuation: **!** **"** **#** **$** **%** **&** **'** **(** **)** **\*** **+** **,** **-** **.** **/** **:** **;** **<** **=** **>** **?** **@** **[** **\\** **]** **^** **_** + +Uppercase letters, numbers, and punctuation are displayed in orange (or +blue, if **-v** is used). + +Lowercase letters are displayed in green (or red, with **-v**). + +The characters ` { | } ~ are displayed as green (or red) versions of +@ [ \ ] ^, respectively. + +Currently, it's 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. + +LIMITATIONS +=========== + +**fenders** should warn if the disk image contains more than 20 files, +since they won't all be displayed in the menu. + +Double-density images less than 720 sectors long are not handled, +although they could be with a little more work. + +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. + +No checking for non-standard formats (SpartaDOS, DOS 3, MyDOS with +subdirectories, dedicated bootdisks, etc) is done. + +If an "enhanced" 1050 density disk image has the bootloader installed, +it won't display the files using sectors above 720 (the ones which +would appear as *<filename.ext>* in the DOS 2.5 directory). + +Actually, the above limitations are a direct result of the fact that +**fenders** 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't really consider them to be bugs, although they +may be addressed in a future version of **fenders**. + +Note that the bootloader only displays up to 20 files on the screen. +This shouldn't 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. + +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. + +BUGS +==== + +There should be an option to delete DOS.SYS and DUP.SYS from the image, +but there isn't. The original Fenders installer has this option. + +When used with an image whose size according to the ATR header +doesn't match the actual image file size, **fenders** may produce +a broken or zero-length output file. If in doubt, use **atrcheck** to +validate the image before use. + +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 +**dd**, of course, but its syntax is difficult to remember, and typos are +prone to wipe out the file you're working with. + +.. include:: manftr.rst |