Subject: Re: Hardware Project
From: dempson@actrix.gen.nz (David Empson)
Date: Fri, Nov 13, 1998 21Ç8@
Message-id: <1dihsnr.1sn3m27fkxm5aN@dempson.actrix.gen.nz>

Terence J. Boldt <apple2@cgocable.net> wrote:

> What can you do to help?
> 
> I need to know how ProDOS accesses a block device for read and write.  I
> know about all the ID and info bytes required in ROM (thanks Dave Wilson),
> but what do I need to handle as far as calls from ProDOS to my card?

There are two levels of support you can consider implementing.

1. A ProDOS block driver.
2. A SmartPort driver.

The ProDOS block driver must support STATUS and READ calls, and may also
support WRITE and FORMAT calls (you should set up the flag byte at $CnFE
to indicate which calls are supported).

I've written a ProDOS block driver (for a network card), but haven't
gone to the trouble of writing a SmartPort driver (there wasn't enough
space left in the ROM anyway).

The main reasons for implementing a SmartPort driver are to add more
useful functionality.  The ProDOS driver has the following major limits:

- Maximum of two devices per slot (or four in limited circumstances).
- Block devices only (shouldn't be a problem here).
- Maximum of 32MB per volume (I can't picture you setting up a ROM disk
this big!).
- Block size is fixed at 512 bytes.
- No standard way to identify what the device actually is.
- No way to add custom calls.
- No support for selecting formatting options.

The SmartPort driver gets around all these problems.

You can always revisit this later.  I'd suggest starting with a ProDOS
driver and seeing whether it is sufficient for your requirements.

I'll take it as read that you know about the ID bytes ($Cn01/3/5), the
use of $CnFF to point to the driver entry point, the flags in $CnFE, and
the block count in $CnFC/D.  Note that $Cn07 must not be zero, or you
will look like a SmartPort device.

When ProDOS calls your driver, it sets up variables in zero page as
follows:

$42  Command code: 0 = STATUS, 1 = READ, 2 = WRITE, 3 = FORMAT.
$43  Unit number: bit 7 = drive, bits 4-6 = slot, bits 0-3 unused.
$44-$45  Buffer pointer (the buffer is 512 bytes)
$46-$47  Block number

On return from your driver, you must provide an error code in the
accumulator, with carry set if there was an error.  (If there is no
error, clear carry and set A to zero.)

The following error codes may be used:

$27  I/O error
$28  No device connected (e.g. no drive connected)
$2B  Write protected
$2F  Device offline (e.g. no disk in drive)

For dealing with the volume size, you have two options.

(a) If the volume size is fixed, put it in ROM at $CnFC/D.
(b) If the volume size may be variable, set these locations to zero, and
get your STATUS routine to return the size in registers: X=low, Y=high.

I'd be inclined to use the latter method even if you think the volume
size is going to be fixed.

The STATUS call must check that the device is ready for either a read or
write operation.  If, for example, your drive is write-protected, then
the STATUS call must return the write protected error code (along with
the size in X and Y).  Returning zero means you are able to accept a
subsequent read or write call.  The buffer pointer and block number are
not used for the STATUS call.

The READ and WRITE calls transfer a specified block between the device
and the specified buffer.  If the block number is out of range, you
should return I/O error.  If the device doesn't support writes (or is
protected), return a write protected error.

The FORMAT call doesn't use the buffer pointer or block number.  For a
floppy drive, it would rewrite all tracks, laying down the sector
structure.  You can do whatever operation is appropriate for your device
(which could be "nothing at all").  Your driver does NOT need to worry
about writing directory structures, boot blocks, etc. - this is the
responsibility of the formatting software.

Note that even if you don't support the WRITE and FORMAT calls, you
should be prepared to accept them (and return an appropriate error), to
allow for software which ignores the flag bytes in $CnFE.


If you have any further questions on this, feel free to ask (by E-Mail
if you prefer).

-- 
David Empson
dempson@actrix.gen.nz
Snail mail: P.O. Box 27-103, Wellington, New Zealand