[Coco] RFC: dwload - a minimal DriveWire client for BASIC

[Tormod Volden]

Hi,
I am posting this for review and comments, especially among the
DriveWire people. My current implementation works wonderfully, but if
something is worth changing it would be nice to sort it out before we
start burning too many ROMs :)

<tl;dr>
dwload is a DOS-less BASIC client for DriveWire, loading DECB binaries
instead of disk sectors. Like DLOADM or CLOADM over DriveWire!

The background is that I have worked on DLOAD on Dragon
(http://archive.worldofdragon.org/phpBB3/viewtopic.php?f=5&t=4272),
but wanted server compatibility with (and the speed of) DriveWire. So
I extended DWDOS to load arbitrary files using a header format
inspired by DECB. Thanks to KenH for lots of testing and many useful
discussions! We found that simply using the straight DECB format would
be a good solution, and I decided to ditch DWDOS compatibility and
included a full DECB parser instead.

*** dwload ***

dwload is a simple DriveWire client for use in BASIC. It allows the
user to load M/L programs and other binary files from the DriveWire
server without running HDBDOS or NitrOS-9 on the Dragon (or CoCo).

The present implementation is small enough to fit in unused parts of
the Dragon 32 BASIC ROM, replacing the dysfunctional DLOAD command. It
is actually all in the upper 8KB, which is socketed on most Dragon
32's! It does not need any dedicated RAM, but uses the normal low-RAM
cassette and command line buffer area while it is running.

dwload mounts a "named object" at the DriveWire server and transfers
the object as a binary file starting at "sector" 0. dwload does not
treat the object as a disk image (as HDBDOS and NitrOS-9 do), but as
one file to be transferred in its entirety.

The file format is compatible with the DECB binary format, that is,
the transferred file has a 5-byte header containing:
- a zero byte to identify the file (or segment) header
- length of file payload (segment) in bytes
- load address, where the file (segment) should be loaded in memory
Multiple segments (each with its own header) can follow.

The file is terminated by a 5-byte trailer containing:
- a $FF byte to identify the file trailer
- stack pointer address
- execution address

The stack pointer address is an extension to the DECB format and
replaces the two reserved zero bytes. After loading of the file, the
stack pointer is set to this value before jumping to the execution
address. This can be used to load a binary into any memory location
without risk of overwriting parts of the binary by the system stack
upon finished loading. Note that it only sets the stack pointer and
doesn't relocate BASIC memory pointers. So in many cases, CLEAR x,y
would still be needed to reserve the target memory location and avoid
conflicts with BASIC, similar to when using for instance CLOADM.
However, it allows simplified loading and execution of many existing
DECB binaries with only a minimal modification of the DECB trailer. In
other cases, a small stub can be included in the binary to perform the
CLEAR x,y action as soon as the file is executed.

Internally dwload uses its own stack area in lower parts of RAM.

For data files, the execution address can be set to the BASIC ROM "FC
ERROR" or to $FFxx, which dwload recognizes as an invalid execution
address.

***

The beauty of this is that it does not occupy any RAM (for instance
HDBDOS would OTOH reserve several kilobytes of RAM for buffers and
housekeeping), and everything fits inside the Dragon 32 ROM without
touching anything else than the unusable DLOAD code. So 100%
compatibility with everything people use. Only that the broken DLOAD
command now has DriveWire superpower :)

I have also included a silent attempt at download on power-on, so that
the machine can boot straight into anything at the wish of the user.
The autoload can be disabled by holding the shift key.

My code also includes a vector table for the DriveWire low-level
routines (exposed via the return address on the stack), so that a
chainloaded "app" can reuse these. One working example is the DOSN
app, which implements DWDOS, for instance DLOAD"DOSN"3 to boot from
drive 3. Another useful app, waiting to be implemented, is the SAVE
app... Or an app to load BASIC programs.

dwload would be very useful on a CoCo as well, but fitting it into the
CoCo BASIC ROM will probably require some sacrifice and compromise.

Cheers,
Tormod