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:

+o: Initialize the host adapter and ready it for future requests.
+o: Start a SCSI command and call a notification function when that command completes or times out.
+o: Abort a SCSI command in progress.
+o: Reset a device on the SCSI bus.
+o: 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:

     HHAAII115544XX__BBAASSEEBase port
     HHAAII115544XX__IINNTTRRInterrupt level
     HHAAII115544XX__DDMMAA 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:

     HHAAII115544XX__XXFFEERRSSPPEEEEDDDMA transfer speed, from the table below
     HHAAII115544XX__BBUUSSOOFFFFTTIIMMEEHost-adapter bus-on time for DMA transfers
     HHAAII115544XX__BBUUSSOONNTTIIMMEEHost-adapter bus-off time for DMA transfers

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

  _S_e_t_t_i_n_g _S_p_e_e_d_, _m_e_g_a_b_y_t_e_s_/_s_e_c_o_n_d
     00     5.0
     11     6.7
     22     8.0
     33    10.0
     44     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:

HHAAIISSSS__TTYYPPEE

The type of the card, as follows:

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

HHAAIISSSS__IINNTTRR

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.

HHAAIISSSS__BBAASSEE

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.

HHAAIISSSS__SSLLOOWWDDEEVV

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:

     _B_i_t_:   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

//ddeevv//ssdd** -- Block-special SCSI-disk devices //ddeevv//SSttpp** -- Block-special SCSI-tape devices //ddeevv//SSccddrroomm** -- Block-special SCSI CD-ROM devices //ddeevv//rrssdd** -- Character-special SCSI-disk devices //ddeevv//rrSSttpp** -- Character-special SCSI-tape devices //ddeevv//rrSSccddrroomm** -- Character-special SCSI CD-ROM devices

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.

A 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.

A 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.

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