hai -- Device Driver

Host adapter-independent SCSI driver

hai is a host  adapter-independent device driver that supports various SCSI
devices.  It  supports the Adaptec 154x host  adapter, and compatibles; and
all host  adapters built  around the  Future Domain TMC-950/9C50  chip set.
With a supported host adapter, hai  can support any mix of up to seven SCSI
hard  disks (either  fixed  or removable  media), CD-ROM  drives, and  tape
drives.

hai has major-device number 13.  It can access devices either in block mode
or character  mode.  The  minor number  specifies the device  and partition
number  for disk-type  devices; this  allows the  use of  up to  eight SCSI
identifiers (SCSI-ID's),  with up to  four logical unit  numbers (LUNs) per
SCSI-ID and up to four partitions  per LUN.  Tape and other special devices
decode the  minor number to perform special operations  such as ``rewind on
close'' or  ``no rewind on close''.   The first open() call  on a SCSI disk
device allocates memory for the partition table and reads it into memory.

hai is a modular driver that  you can configure to suit your system's suite
of SCSI hardware.   To build the driver, you must  link the main hai module
with the appropriate module for your system's SCSI host-adapter card, and a
module for each type of SCSI  device you have (hard disk, CD-ROM, or tape).
Each of  hai modules is  described below.  Usually, you  will configure hai
when you install COHERENT onto your  system, but you can reconfigure hai at
any  time should  you wish  to add  or modify your  system's suite  of SCSI
devices.  The  script /etc/conf/hai/mkdev  walks you through  this process.
Once you  have reconfigured hai,  run the program  /etc/conf/bin/idmkcoh to
build  a new  kernel; then  reboot your  system to  invoke the  newly built
kernel and you're back in business.

Extending hai

hai is  designed to  be extendable  to other host  adapters and  other SCSI
devices.   It is  easy to  extend  hai to  work with  new hardware.   It is
possible to extend hai either to  support a new host adapter, or to support
new peripheral device, or both.

To adapt hait to a new a host adapter, you must write a handful of routines
to initialize  and access the host adapter.  A  host-adapter module must be
able to do the following:

-> Initialize the host adapter and ready it for future requests.

-> Start a SCSI command and  call a notification function when that command
   completes or times out.

-> Abort a SCSI command in progress.

-> Reset a device on the SCSI bus.

-> Reset the SCSI bus.

It is  easier to write a  module for a peripheral device:  you only need to
send the appropriate SCSI commands to  access the device as required by the
COHERENT device-driver interface -- i.e., open(), close(), read(), write(),
and  ioctl(). To  do this,  use the routines  provided by  the host-adapter
module, when neccessary, to access the SCSI bus and the device.

The following  sections of this  article discuss each  of hai's constituent
modules.

hai154x -- Adaptec Host-Adapter Module

hai154x is the hai host-adapter  module for the Adaptec 154x and compatible
host  adapters.  This  module lets  you  run any  combination of  SCSI hard
disks,  tape drives,  or CD-ROM  drives through  any Adaptec  AHA-154x host
adapter.

The Adaptec AHA-154x is an intelligent ISA bus mastering SCSI host adapter.
Its on-board processor and DMA controllers handle the SCSI bus protocol and
the DMA transfer of SCSI data into the PC's main memory.  hai154x uses port
I/O, a DMA channel, and an interrupt line, which are configured through the
following tunable variables:

     HAI154X_BASE Base port
     HAI154X_INTR Interrupt level
     HAI154X_DMA  DMA channel

The following  tunable parameters let  you set the DMA  transfer speed, the
bus-on time, and the bus-off time on the SCSI bus:

     HAI154X_XFERSPEEDDMA transfer speed, from the table below
     HAI154X_BUSOFFTIMEHost-adapter bus-on time for DMA transfers
     HAI154X_BUSONTIMEHost-adapter bus-off time for DMA transfers

Variable HAI154X_XFERSPEED  must be set to  one of the values  given in the
following table.

  Setting Speed, megabytes/second
     0     5.0
     1     6.7
     2     8.0
     3    10.0
     4     5.7

The default setting is `4'.

You can  use these parameters to  tune the performance of  the SCSI bus for
your system.   For most installations, the default  settings should be work
well.

haiss -- Seagate Host-Adapter Module

haiss is the host-adapter module  for host adapters built around the Future
Domain  TMC-950  or  TMC-9C50  chip  sets.   It works  with  the  following
controllers:

    Seagate ST01 or ST02
    Future Domain TMC-845, 850, 860, 875, or 885
    Future Domain TMC-840, 841, 880, or 881

Through this host-adapter module, you  can run any combination of SCSI hard
disks,  tape  drives,  or CD-ROM  drives  through  any  of  the above  host
adapters.

These host  adapters map  the SCSI  bus data and  signal lines  onto memory
addresses on  the PC bus.  haiss then uses  standard memory-read and -write
operations to  access the  state of the  SCSI bus and  the data on  it.  By
default, this controller  uses the Intel block-move instruction to transfer
data between  the device's  buffer and  the SCSI data-address  range.  This
mode of  transfer may be too  fast for certain SCSI  devices, in which case
data can  be transferred  byte by  byte.  You can  set how  haiss transfers
data; this is described below.

haiss can be used through the following tunable kernel variables:

HAISS_TYPE
     The type of the card, as follows:

        Type   Controller
          0    Seagate ST01/02
          1    Future Domain TMC-845/850/860/875/885
          2    Future Domain TMC-840/841/880/881

HAISS_INTR
     The  interrupt  vector to  which  the card  is  set.  Although  MS-DOS
     permits  you to  use this card  without interrupts,  COHERENT requires
     that you use interrupts.

HAISS_BASE
     The real-mode  segment address for  the start of the  card's RAM area.
     On all Future Domain  and Seagate host adapters with an eight-kilobyte
     ROM, this is also the base address that is jumpered onto the card.  On
     Seagate host adapters with a 16-kilobyte ROM, this is the base address
     jumpered on the card plus 0x0200.

HAISS_SLOWDEV
     A bitmask of the target identifiers  of all SCSI devices whose rate of
     data transfer  is slower than the default transfer  mode that the host
     adapter supports.

These variables  are set  automatically by the  script /etc/conf/hai/mkdev,
when  you use  it to  configure hai  for your  system; or  you can  use the
command /etc/conf/bin/idtune to tune them individually.

haict -- Tape Device Module

haict is  the device  module that  controls SCSI tape  drives.  It  works a
number of popular quarter-inch and DAT SCSI tape drives

SCSI  tape-drive  configuration  is  controlled  by the  tunable  variables
HAI_TAPE_SPEC and HAICT_CACHE.

HAI_TAPE_SPEC is a bitmap of the SCSI identifiers that identify tape drives
on your system.  For example, if a system has only one SCSI tape drive, and
it is  assigned SCSI  identifier two, then  you would set  HAI_TAPE_SPEC to
0x04,  which  flips  on bit  two  of  that mask.   (If  you  are versed  in
converting   binary  values   into  bit   masks,   note  that   the  script
/etc/conf/hai/mkdev handles  that conversion for you -- all  you have to do
is tell it what SCSI identifiers  are set to which devices, and it does the
rest.)

Variable HAICT_CACHE  sets the  size of  block of memory  that hai  uses to
buffer data  that it writes to  or reads from the tape  drive.  You can set
this anywhere  from zero  to 256 kilobytes.   The default is  16 kilobytes,
which should works well with most  tape drives.  To tune this variable, use
either the command  /etc/conf/bin/idtune or the script /etc/conf/hai/mkdev.
Please  note  that larger  tape  caches may  not  necessarily improve  tape
performance.  For  example, the program cpio for  example uses a 5,120-byte
buffer that limits the effectiveness of any tape-buffering scheme.

haicd -- CD-ROM Device Module

haicd is  the device module  that controls SCSI CD-ROM  drives.  It permits
you to read data from both  audio CDs and CD-ROM that hold an ISO 9660 file
system.

Configuration of haicd  is controlled by the variable HAI_CDROM_SPEC, which
is a  bitmap of the  SCSI identifiers that  identify CD-ROM drives  on your
system.  For example, if a system has only one SCSI CD-ROM drive, and it is
assigned SCSI  identifier three, then you would  set HAI_TAPE_SPEC to 0x08,
which flips  on bit three of  that mask.  (If you  are versed in converting
binary  values into  bit masks,  note  that the  script /etc/conf/hai/mkdev
handles that conversion for you --  all you have to do is tell it what SCSI
identifiers are set to which devices, and it does the rest.)

As of this writing (September 1994), haicd has been tested with SCSI CD-ROM
drives from Toshiba and NEC.  The  CD-ROM functions work with both makes of
CD-ROM.  Please  note, however, that the audio functions  of the NEC CDR-74
and   CDR-84  CD-ROM   drives   deviate  from   the  SCSI-2   specification
considerably; therefore, the audio functions  of haicd do not work on these
drives.

haisd -- Hard Disk Device Module

haisd is the hai device module that controls SCSI disk drives.  Because hai
allows multiple, overlapping, simultaneous access to the system's SCSI host
adapter, the  disk drives that  hai controls operate  independently of each
other.   haisd  also  chains  ``like''  requests  for  multiple  contiguous
sectors, which  reduces the overhead of starting  SCSI commands and thereby
inproves performance.

haisd  is configured  through  the tunable  kernel variable  HAI_DISK_SPEC,
which is a bitmap of the SCSI identifiers that identify hard-disk drives on
your system.  For  example, if a system has two  SCSI disk drives, one with
SCSI identifier zero and  the other with SCSI identifier one, HAI_DISK_SPEC
to 0x03, which  flips on bits 0 and 1 of  that mask.  (If you are versed in
converting   binary  values   into  bit   masks,   note  that   the  script
/etc/conf/hai/mkdev handles  that conversion for you -- all  you have to do
is tell it what SCSI identifiers  are set to which devices, and it does the
rest.)

haisd determines partitioning information from the device's minor number as
follows:

     Bit:    7 6 5 4 3 2 1 0
             S I-I-I L-L P-P

The `S'  field is  the ``special'' bit:  it distinguishes SCSI  disk drives
from tape drives.  The `P' fields are a binary value of the partition-table
entry for this device, from 0 through 3.  If the special bit is set and the
partition fields  are not 0, then  haisd assumes that this  device is not a
disk drive  and will not allow  access to the device.   The `I' fields give
the binary value of the SCSI  identifier for this device, from zero through
seven.  This  convention is  used for all  SCSI devices.  Finally,  the `L'
fields set  the logical-unit number field,  from 0 through 3.   (If you are
not skilled at setting bit maps  by hand, do not despair: the configuration
script /etc/conf/hai/mkdev automatically  builds an appropriate device node
for each SCSI disk.)

Files

/dev/sd* -- Block-special SCSI-disk devices
/dev/Stp* -- Block-special SCSI-tape devices
/dev/Scdrom* -- Block-special SCSI CD-ROM devices
/dev/rsd* -- Character-special SCSI-disk devices
/dev/rStp* -- Character-special SCSI-tape devices
/dev/rScdrom* -- Character-special SCSI CD-ROM devices

See Also

CD-ROM,
device drivers,
hai154x,
haiss,
haicd,
haict,
haisd,
hard disk,
tape

Notes

For a list of the block-special  files via which you can access the devices
that hai supports, see the Lexicon entries for hard disk and tape.

If you  are using an  Adaptec AHA-1540, AHA-1542C, or  AHA-1542CF SCSI host
adapter with  a drive  larger than one  gigabyte and extended  BIOS support
turned on,  then you must override  the default number of  heads to 255 and
the number  of sectors per track  to 63. Note that when  you run the script
/etc/conf/hai/mkdev (or install COHERENT onto your system), ``255'' appears
as the default choice for the  number of heads; however, the default choice
for number  of sectors is 32.  Therefore,  when you run /etc/conf/hai/mkdev
or  install COHERENT  for a  system that  has one  of the  above-named SCSI
controllers, you  must select the default setting for  the number of heads,
but you must type ``63'' when asked for the number of sectors per track.

hai supercedes  the older  COHERENT device drivers  aha and ss,  which were
specific to the Adaptec and Future-Domain controllers, and which controlled
only SCSI disk drives.

hai was written by Chris Hilton (hilton@mwc.com).

© 2012 by Stephen A. Ness