READ ME!

This file contains a wealth of useful information in addition to the printed
manual.  Please read through the printed docs carefully, then read through
this file carefully, before doing anything else.

First of all, if you don't have 'ded' (or something similar), I command you to
download it from somewhere, somehow.  It is so handy for patching modules that
you can't live without it.  Many of the changes below assume the use of 'ded'.


Descriptors
-----------

There's some new fields in the SCSI System descriptors.  Be sure to update
your old v1.0 descriptors with 'scsidesc' before creating a new boot disk with
the v2.2 driver.


Bootlist Order
--------------

The registered version uses an 8K block for the cache.  When accessing this
memory, it has to map the block into the system map.  I have chosen to use DAT
register $FFA6, which will map the cache into locations $C000-$DFFF in the
system space.  This area is occupied by system modules.  The farther down in
the bootlist that a module is, the higher in memory it will be in the system
map.  The SCSI System driver doesn't need to call any other modules while the
cache is mapped in, but the necessary drive tables are bound to be in lower
memory locations, hence the choice of the $C000-$DFFF region.  However, it is
important that the SCSI System driver itself not be in memory locations
$C000-$DFFF, or else it will swap itself out of existence, and a crash will
occur.  So make sure that the driver is at or near the top of your bootlist,
and it should end up occupying a space below $C000.  You can use Kevin
Darling's 'pmap' and 'dirm' (or mdir e) to verify its location.


F$Move Enhancements
-------------------

RBFMan uses the F$Move system call to copy data between the user's address
space and the sector buffer in the system space.  It also represents a serious
bottleneck to hard disk performance under OS/9 Level 2.  Normally, the central
copy loop is the following:

LOOP   ldd ,x++    8
       std ,u++    8
       leay -1,y   5
       bne LOOP    3

This is 24 clock cycles for 2 bytes, or 3072 clock cycles for a 256 byte
sector, excluding the overhead of the system call and setting up the loop. 
Fortunately, the 6309 has the block copy instruction to speed this up.  The
same 256 byte sector only takes 768 clock cycles to copy, not counting the
overhead.  Thus you wanna bet that both PowerBoost and NitrOS9 patch this call
for the 6309.

However, some people have installed the 6309 in their CoCo, but haven't gotten
around to getting PowerBoost or NitrOS9.  No problem!  I have whipped up an
F$Move patch of my own in the included 'fmove63' command.  Just execute it and
it will make the necessary changes to os9p1 for the 6309.  This patch will be
inherited by every boot disk you make with this patched os9p1, since cobbler
and os9gen always grab os9p1 out of memory.  To put os9p1 back to the way it
was for the 6809, use the 'fmove68' command.  Both of these are implemented as
commands and not modpatches because a modpatch would crash the system.

Also note that whenever you do a warm reboot by just hitting the reset button,
Boot, Rel and os9p1 that are in memory are re-used over the reboot.  Thus to
reboot with the updated os9p1 from the disk, you will have to turn your
computer off and on, or summon the 3 gurus.


Interrupts
----------

Whenever the SCSI System must do multipak switching and/or access the cache
memory and/or use 6309 block copies, interrupts are masked or blocked out
until the device driver is through with the multipak, cache or copy.  However,
through careful design, normal interrupt handling can remain unaffected if the
interrupts are not masked for too long.  I have attempted to ensure that the
SCSI System will work with 9600 baud (960 interrupts/sec) under normal
circumstances.  If the drive hangs or there is a serious hardware error,
characters might be lost.  But then you've got other problems to worry about.

If you must be able to receive 19,200 or even 31,250 baud, you will not be
able to use the accelerated handshake mode of the registered drivers.  You
will have to use the regular mode, which takes interrupt "breathers" more
often.  I suppose I could have made the turbo mode handle it, but the overhead
would penalize the majority of 9600 and below users for the minority of 19200
users.  Contact me if this is really a problem for you.

Besides the SCSI System driver, the aforementioned F$Move command also masks
interrupts briefly, because it must play with the DAT registers during the
copy.  Unmodified, it copies a maximum of 64 bytes at a time before taking an
interrupt breather.  On the 6809 this works out to enough time for 9600 baud
to occur, but 19200 or higher is too fast and interrupts tend to be lost.

Alternately, the overhead of the breather slows things down a bit.  If you are
only using 2400 baud, you could probably get away with copying 256 bytes at a
time.  This shaves a second or two off of a 6809 megaread.

To make these patches to the number of bytes F$Move copies at a time, the
modpatch files, m256.mp, m64.mp, and m32.mp are included to patch os9p1.  The
aforementioned warnings about boot disks inheriting os9p1 patches from memory
also applies.

These modpatch files will also work in conjuction with my fmove63 patches, so
you should use fmove63 and m256.mp for maximum 6309 performance, unless you
have troubles at high baud.  The modpatch files might not be compatible or
even necessary with NitrOS9 or PowerBoost, I don't know.


Ded-able Flags
--------------

There are a number of modifications that you can make to the driver with 'ded'
to customize it for your situation.  These consist of flags located at the end
of every driver module, just before the CRC bytes.  This approach was used to
avoid the need to assemble every possible permutation of driver features. 
Except for the Write Command option, you will have to reboot for these changes
to kick in.  Remember to verify the module CRC before quitting ded.

The flags are:
 ..  
 ..  
 -6  Write Command
 -5  Reset Flag
 -4  Cache Flag
 -3  Number of Drives
 -2  CRC byte 1
 -1  CRC byte 2
  0  CRC byte 3 (end of file)


Write Command
-------------

This byte contains the value of the SCSI Write command that the driver will
use.  Normally this is the ordinary extended write command ($2A).  However, if
you want added security, SCSI also defines a write-and-verify command ($2E)
that can be used in its place.  This way every write is reverified by the
drive itself, for added security.  I am unsure as to the SCSI error returned
when it fails, however.  I think it might be miscompare instead of write
fault.


Reset Disable
-------------

Normally the SCSI System resets the controller when the driver is first
initialized.  Since RBF only calls Init once per port address, and not once
per logical drive, the parms used by the reset will be based on the first
drive accessed.  The reset will reset all drives.  This reset should unjam
drives whose light was stuck on when something crashed or the reset button was
pressed.

However, this reset may foul up some drive controllers, and they may not work
when you first boot.  So you can disable the reset function by using 'ded' to
change the reset disable flag from $FF to $00.

Although it shouldn't be a problem, you may have to wait for the drive to spin
up before booting your CoCo.  The SCSI System tends to work fine even if it
has to wait for spin-up when you turn on the computer.  But I can't say that
with 100% certainty so you might have to delay your boot somehow if it is an
automatic EPROM boot.


Cache Disable
-------------

Setting the cache disable flag from $FF to $00 will prevent the driver from
allocating an 8K block for the cache, freeing up 8K for use by other programs.
Any caching flags in the descriptor will be ignored, and no caching will
occur.  This would be used mostly to create a special bootdisk for those times
when you just gotta have every last byte of RAM.

WARNING: When changing the cache disable flag in the descriptors, do not do
this to the in-memory descriptor!  Only change the disk descriptor and create
a new boot disk with OS9Gen.  Otherwise, the driver doesn't detect that the
cache disable flag has changed since the last time, and stale or corrupt data
may be in the buffer or cache, depending on which way the flag was changed.  I
may figure out a way to detect this in the future, but for now, follow this
advice.


Number of Drives
----------------

Each logical drive requires, besides a descriptor, 38 bytes of system space
for tables used by RBFman.  The maximum number of drive tables must be
specified when the driver is initialized, which in turn is most easily
determined by an assembly constant at compile time.  Thus there is no easy way
to change this parameter after the driver is assembled, because it affects the
U register offsets to the driver vars.  Thus it has to be set fairly high to
be able to handle whatever users may throw at it.  But this wastes system
space if you only have one or two logical drives.

One of the really nice things that I've thrown in to v2.2 at the last minute
is the ability to change the maximum number of drive tables that the driver
supports, without needing to reassemble it from scratch.  To the best of my
knowledge, the SCSI System v2.2 is the only CoCo disk driver that will let you
do this.

All you have to do is change the 'Number of Drives' byte to equal the number
of logical drives you need.  This way no extra system space need be wasted by
drives you don't have.  However, there is one other patch you must make.  You
must manually change the module data memory requirement bytes to match your
new configuration.  These are located in bytes $B and $C at the beginning of
all modules.  The driver comes compiled for 8 drives, so you must add or
subtract 38 bytes for each drive more or less than this that you need.  Say
for instance the bytes $B & $C are $028F (655 decimal).  To cut this down for
2 drives, subtract 38*6, or 228 bytes, to give 427 decimal, or $01AB in
hexadecimal.  So you would patch bytes $B-$C to $01AB.  That should be fairly
straightforward.


FAT Searching
-------------

A number of people have complained about the long search times when the file
allocation table is getting fragmented.  First, I want to reassure people that
RBF *does* pick up where it left off when doing a free space search.  UNLESS:
you have no more free block big enough for your segment allocation size.  When
that happens, RBF has to scan the entire FAT every time for the next-largest
free block of sectors.  The stock OS9 'free' command will reveal your largest
free block size, and if your drive is *that* full, you will have to wait for
RBFman.

I also hate the long FAT search, so if I get a chance I would like to patch
the F$SchBit algorithm with something faster.  But that is on a back burner
for now.  If you don't have Bruce Istead's Sacia driver, get it now.  At least
you can have up to a 3.75K buffer so you don't lose chars waiting for a FAT
search.


CRC Checking
------------

To get more speed out of your SCSI System, and to further eliminate the need
to use a ramdisk or keep modules in memory, you should patch os9p1 to disable
CRC checking.  That way there is no delay after modules are loaded.  Hard
drives are reliable enough that you rarely have to worry about corrupted
executables.  I have thrown the CRC modpatches in to the distribution as well,
in case you don't already have them.


RAM Problems?
-------------

I am uncertain as to the memory mapping used on 1 meg and 2 meg machines. 
Because the top DAT block would be 7F or FF, it may also be that the absolute
physical address of the device ports must be changed.  This is controlled by
byte offset $E in the device descriptor.  You may have to change the $7 that
is there (using 'ded') to $F (1 meg) or $1f (2 meg).  This is just a thought. 
I haven't had the time to check up on it.


Slowpokes
---------

I have assumed that all controllers, interfaces and multipaks that people are
using with their CoCo 3 work at the 2 MHz clock rate.  If you are certain that
your old clunker can't take it, and that your old SCSI driver uses the slow
speed, please drop a note to the author about it.


Pseudo RAMdisk
--------------

I use an /R0 descriptor that is really just a SCSI system descriptor.  I find
my compiles with the new CC command that utilize a RAM disk for tempfiles to
be almost as fast with the hard drive, so I don't keep a ramdisk around
anymore.


Overdrive
---------

Some drives might not be able to handle the I/O speed of the accelerated
handshake protocol.  You will simply have to use the regular handshake mode.


Manufacturer Info
-----------------

I've thrown in a list of manufacturer support phone numbers and BBS numbers
for you to contact about problems specific to your paticular hard drive, since
I certainly can't help with that.  I've also thrown in a condensed file of
Seagate Information.  Please read it if you are using Seagate.  It will also
tell you which Seagate drives need to be parked, and which don't.


256 Woes
--------

Most drives can't be formatted for 256 bytes per sector.  Even some older
Seagate 'N' SCSI drives can't do it.  You need Seagate ROM revision 104 or
greater to do it, so if your Seagate won't format at 256, that's why.  So use
it at 512.  After all, that's what the SCSI System is for.


ST157N
------

I have noticed that the SCSI ID jumpers on my 157N are reversed from what it
says on the installation sheet for Seagate drives.  My 1096N follows the
pattern, however.  So somebody messed up somewhere.


The Future
----------

For now, the SCSI System is aimed at hard drives.  In the future I might add
support for CD-ROMs, tape drives and flopticals.  But it can't happen without
more time and money.  For each system I need to acquire a set of relevant file
spec docs for each system, never mind the time needed to write and test the
necessary utils.  But please send me a message if you would like to see any of
this happen.  It won't unless I get enough support for it.


Verify Pass
-----------

Sometimes the verify pass will report an error when checking a whole wallop of
blocks, but then be unable to find it when narrowing down.  The error is a
flaky one, and thus you might want to do several verify passes to nail it
down.  One hint is to format at operating temperature, but do 2 verify passes,
one with an elevated temperature (use a hairdryer) and one with a chilled
temperature.  This will bring flaky errors out of the woodwork.  Do not use
too great a temperature extreme, however, or else the drive might (head) crash
and then you'll be in big trouble!


SS.SCSI Buffer
--------------

The SS.SCSI data buffer only supports 256 bytes of data at the present time. 
It borrows the sector buffer used by the non-cache 512-byte block algorithm. 
I will figure out a way to expand this in the future.


Error Mismatch
--------------

When using the cache, remember that if you get a read error it may not be for
the paticular sector you are reading, but for any of the sectors in the 2K
range.


The Zen of Interleave
---------------------

In the main manual, I tell you to use a 1:1 interleave.  Some last minute
experimentation has shed new insight on this.  Using a Seagate N SCSI drive, I
have determined the following wisdom.  It seems that even though the buffer
size is 1K or 2K, the drive will only process sectors as fast as you can clear
them out of the buffer.  Thus with a 6309 in turbo handshake mode, you can
leave the interleave a 1:1 for 512 bytes per block.  For 256 bytes per block,
use an interleave of 2:1, as the controller can't handle so many smaller
sectors in quick succession.  If using a 6809 in turbo handshake mode, use 4:1
for both 512 and 256 bytes per block.  For the robust mode, the interleave
will have to be greater than this.  Another factor is whether the 'N' drive is
MFM (5 MHz, 17 blocks/track) or RLL (7.5 MHz, 26 blocks/track).  I was using
an RLL SCSI drive.  For the MFM drives, you be able to use a smaller
interleave.  For the 296N (10 MHz, 34 blocks/track), you may need a longer
intereleave.  All megaread times are using Bruce Istead's original, unmodified
megaread, and all assume that the cache is being used:

ST157N    6309 (my patches)    6809 (m256.mp only)
------    -----------------    -------------------
@ 512     1:1   18 seconds     4:1   31 seconds
@ 256     2:1                  4:1   33 seconds

Note that the 6309 numbers will probably be better with Nitro or Boost because
they put the whole system into native mode, not just the F$Move data copy.


Cache Flash
-----------

Don't freak out if the drive light doesn't flash as often.  It's not your
program running slow, it's just the cache buffering the read data.


LUN
---

'Scsifmt' now asks for the drive's LUN.  This is normally zero unless you are
formatting the second drive on an Adaptec controller.


Contacting Me
-------------

If you have any questions or problems, feel free to email or mail me (unless
the problem is with the distribution disks, order or payment, in which case
please contact Northern Xposure).  My addresses are in the docs, you should be
able to reach me on Delphi, on the Internet, and (new) on Fido.  Also new is
that the SCSI System support hotline at 613-354-5734 is being deactivated, as
ordering is being looked after by Northern Xposure.  Some of you have managed
to get a hold of my mom's phone number somehow.  Please don't pester her about
the SCSI System, she can't help you very much!  If you do try to phone me,
don't phone in the morning :-)!
