path: root/fenders.1

.\" 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 "2024-07-02" "0.2.1" "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\-hrcsiIv\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  \-b
Create \fBinfile\fP as a blank single\-density ATR image and update it
in\-place. This option requires \fBaxe\fP to be present on
\fIPATH\fP\&. May not be used when reading standard input.
.TP
.B  \-c
Rotate colors during load. May cause problems with some games.
.TP
.B  \-d
Delete \fIDOS.SYS\fP, \fIDUP.SYS\fP, and \fIAUTORUN.SYS\fP, if they
exist. This option requires \fBaxe\fP to be present on
\fIPATH\fP\&. May not be used when writing standard output.
.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, with backup. 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  \-I
In\-place update, without backup. Use with caution.
.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 has better compatibility with DOS 2.5 than the original
Atari version. Any files occupying sectors >=720 (the ones with <>
around the name) have their directory status bytes adjusted to make
them look like regular DOS 2.0 files. This allows them to display and
load correctly. The original Atari Fenders installer doesn\(aqt do this,
but the \fBfenders\fP author wrote a BASIC program to do the job, ages
ago.
.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). Other incompatible DOS formats such as
SpartaDOS or Atari DOS 1.0/3.0/4.0 are not supported.
.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
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
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
\fBa8cat\fP(1),
\fBa8eol\fP(1),
\fBa8xd\fP(1),
\fBatr2xfd\fP(1),
\fBatrsize\fP(1),
\fBaxe\fP(1),
\fBblob2c\fP(1),
\fBblob2xex\fP(1),
\fBcart2xex\fP(1),
\fBcxrefbas\fP(1),
\fBdasm2atasm\fP(1),
\fBdumpbas\fP(1),
\fBf2toxex\fP(1),
\fBfenders\fP(1),
\fBlistbas\fP(1),
\fBprotbas\fP(1),
\fBrenumbas\fP(1),
\fBrom2cart\fP(1),
\fBunmac65\fP(1),
\fBunprotbas\fP(1),
\fBvxrefbas\fP(1),
\fBxex1to2\fP(1),
\fBxexamine\fP(1),
\fBxexcat\fP(1),
\fBxexsplit\fP(1),
\fBxfd2atr\fP(1),
\fBxex\fP(5),
\fBatascii\fP(7).
.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.
.