The Silicon Graphics computer systems supported by IRIX 6.2 can attach multiple SCSI adapters, as follows:

In all systems, DMA mapping hardware allows a SCSI adapter to treat discontiguous memory locations as if they were a contiguous buffer, providing scatter/gather support.

The IRIX kernel contains two levels of SCSI support. An inner SCSI driver, the host adapter driver, manages all communication with SCSI hardware adapters. The kernel-level SCSI device drivers for particular devices prepare SCSI commands and call on the host adapter driver to execute them. This design centralizes the management of SCSI adapters. Centralization is necessary because the use of the SCSI bus is multiplexed across many devices, while recovery and error-handling need central handling. In addition, use of the host adapter driver makes it simpler to write a SCSI device driver.

Host Adapter Drivers

Different host adapter drivers are loaded, depending on the hardware in the system. Some examples of host adapter drivers are wd93, wd95, and jag.

The host adapter drivers support all levels of the SCSI standard: SCSI-1, the Common Command Set (CCS, superceded by SCSI-2), and SCSI-2. Not all optional features of the standard are supported. Different systems support different feature combinations (such as synchronous, fast, and wide SCSI), depending on the available hardware.

The host adapter drivers handle the low-level communication over the SCSI interface, such as programming the SCSI interface chip or board, negotiating synchronous or wide mode, and handling disconnect/reconnect.

A host adapter driver is not, strictly speaking, a proper device driver because it does not support all the entry points documented in Chapter 8, “Structure of a Kernel-Level Driver.” You can think of it as a specialized library module for SCSI-bus management or as a device driver, whichever you prefer. The software interface to the host adapter driver is documented under “Host Adapter Facilities”.

---

Caution: Connect/disconnect strategy is enabled on any SCSI bus by default (the option is controlled by a constant defined in the host adapter driver descriptive file in /var/sysgen/master.d). When disconnect is enabled on a bus, and a device on that bus refuses to disconnect, it can cause timeouts on other devices.

---

The reason that IRIX uses host adapter drivers is that the SCSI bus is shared among multiple devices of different types, each type controlled by a different driver. A disk, a tape, a CDROM, and a scanner could all be cabled from the same SCSI adapter. Each device has a different driver, but each driver needs to use the adapter, a single chip-set, to communicate with its device.

If IRIX allowed multiple drivers to operate the host adapter, there would be confusion and errors from the conflicting uses. IRIX puts the management of each host adapter under the control of a host adapter driver, whose job is to issue commands on its bus and report the results. The host adapter is tailored to the hardware of the particular host adapter and to the architecture of the host system.

The interface to the host adapter driver is the same no matter what type of hardware the adapter uses. This insulates the individual device drivers from details of the adapter hardware.

The driver for each type of device is responsible for preparing the SCSI command bytes for its device, for passing the command requests to the correct host adapter driver, and for interpreting sense and status data as it comes back.

IRIX 6.2 permits a total of 10 unique host adapter drivers—five supplied by Silicon Graphics and up to five from other vendors. Each host adapter is customized to manage one type of adapter hardware. Each adapter driver has an adapter type number that is declared in sys/scsi.h. The constant names are listed in Table 13-1.

---

Caution: The constant names listed in Table 13-1 compile to different values in different hardware systems. For this reason, you should avoid using these names in your driver; if you use one, your driver object file has to be recompiled for each CPU type.

---

The lboot command loads a host adapter driver for each unique type of adapter in the system. lboot is directed by VECTOR statements in the /var/sysgen/system/irix.sm file (see “Configuring a Kernel”).

You can examine VECTOR lines in /var/sysgen/system/irix.sm to see how many adapters your system has, and which of the host adapter drivers listed in Table 13-1 is loaded for each one.

The adapter number, the target number, and the logical unit number are important parameters to all the functions of the host adapter driver.

IRIX 6.2 permits a total of 10 unique host adapter drivers, but each of the ten must provide the same functional interface, which is based on simple concepts. The interface to host adapter drivers is declared in sys/scsi.h. Each adapter driver must provide the functions listed in Table 13-2.

The normal sequence of operations is as follows:

---

Caution: The program interface to the scsi_abort() and scsi_dump() functions is subject to change. There is no reference page for these functions. The scsi_reset() function that formerly existed has been removed.

---

A SCSI device driver can be asked to manage devices on different adapters. But different adapters can use different hardware, and be managed by different host adapter drivers. When opening one device, the device driver might need to call scsi_alloc() as provided by the wd93 driver. When opening a different device, the driver might need the scsi_alloc() function from the jag driver. How can a driver locate the correct host adapter function for a given device?

The answer is provided by a set of function vector tables that are indexed by adapter number, and that yield the address of the appropriate function for that adapter.

extern void (*scsi_command[])(struct scsi_request *req);

void function(struct scsi_request *req);

#include <sys/scsi.h>
pTargInfo = (*scsi_info[iAdapT])(iAdap,iTarg,iLun);
iAllocRet = (*scsi_alloc[iAdapT])(iAdap,iTarg,iLun,0,NULL);
(void) (*scsi_command[iAdapT])(&request);
(void) (*scsi_free[iAdapT])(iAdap,iTarg,iLun,NULL);

extern u_char scsi_driver_table[];

#include <sys/scsi.h>
typedef struct devVital_s {
   uchar devAdapNum;
   uchar devAdapType;
...} devVital_t;
void hypo_edtinit(edt_t *edt)
{
   devVital_t *pVitals;
   ...
   pVitals->devAdapNum = edt->e_adap;
   pVitals->devAdapType = scsi_driver_table[edt->e_adap];
...
}

/* Hypothetical minor bits: 00 aaaaaaaa ccccuuuu */
#define MINOR_ADAP_SHIFT 8
#define MINOR_ADAP_MASK 0x00ff
#define MINOR_ADAP(devt) (MINOR_ADAP_MASK & \
                  (geteminor(devt) >> MINOR_ADAP_SHIFT))

#define SCSI_ALLOC(adap,targ,lun,opt,func) \
   (*scsi_alloc[scsi_driver_table[adap]]) \
   (adap,targ,lun,opt,func)

Before a SCSI driver tries to access a device, it must call the host adapter scsi_info() function. This function issues an Inquiry command to the specified adapter, target, and logical unit. If the Inquiry is not successful—or if the adapter, target, or LUN is invalid—the return value is NULL. Otherwise, the return value is a pointer to a scsi_target_info structure.

The SCSI driver can learn the following things from a call to scsi_info():

You can also call scsi_info() at other times; some of the returned information can be useful in error recovery. However, be aware that scsi_info() for some host adapters is slow, and can use serialized access to hardware.

Depending on its particular design, the host adapter driver may need to allocate memory for data structures, DMA maps, or buffers for sense and inquiry data, before it is ready to execute commands to a particular target. The call to scsi_alloc() gives the host adapter driver the opportunity to prepare in these ways.

Because the host adapter driver may allocate virtual memory, it may sleep. Some host adapter drivers allocate all the resources they need on the first call to scsi_alloc() and do little or nothing on subsequent calls.

A SCSI device driver will typically call the scsi_alloc() function from the pfxopen() entry point. However, if the driver needs to issue commands to the device at initialization time, it would call scsi_alloc(), use scsi_command(), and call scsi_free(), all within the pfxinit() or pfxedtinit() entry point.

A call to scsi_alloc() specifies these parameters:

The option parameter may include the SCSIALLOC_EXCLUSIVE flag to request exclusive use of the target. If another driver has allocated a path to the same device, scsi_alloc() returns EBUSY. For example, a tape device driver might require exclusive access, while a disk device driver would not.

The option parameter may include SCSIALLOC_NOSYNC to specify that this device should not, or cannot, use synchronous transfer mode. That setting can be overridden for single commands by a flag to scsi_command() (see Table 13-4).

The option parameter can also include a small integer value indicating the maximum queue depth (the number of SCSI commands the driver would like to start before any have completed). The call to scsi_info() returns the default queue depth that will be used if you do not include a nonzero value (typically 1).

The callback function address can be specified as NULL. The specified callback function is called only when sense data is gotten from the allocated device. Only one driver that allocates a path to a device can specify a callback function. If the path is not held exclusively, any other drivers must specify a null address for their callback functions.

A call to scsi_alloc() might resemble the following:

extern void sense_callback(char *pSense);
ret = scsi_alloc[scsi_driver_table[myAdapNum]](
           myAdapNum,myTargNum,myLun,
           SCSIALLOC_NOSYNC | 16, /* flag + max queue depth */
           sense_callback);

A SCSI driver typically calls scsi_free() from the pfxclose() entry point. That is the time when the driver knows that no processes have the device open, so the host adapter should be allowed to release any resources it is holding just for this device.

In addition, scsi_free() releases the device for use by other drivers, if the driver had allocated it for exclusive use.

A SCSI device driver sends SCSI commands to its device by storing information in a scsi_request structure and passing the structure to the scsi_command() function for the adapter. The host adapter driver schedules the command on the SCSI bus that it manages, and returns to the caller. When the command completes, a callback function is invoked.

---

Tip: When debugging a driver using a debugging kernel (see “Preparing the System for Debugging”), you can display the contents of a scsi_request structure using symmon or idbg (see “Commands to Display I/O Status”).

---

The purpose of the scsi_abort() function is to issue a SCSI ABORT command to a specified target and logical unit. The prototype of the function is:

int (*scsi_abort[adapter-type])(struct scsi_request *req);

The only fields of the scsi_request that are input to this function are those that identify the device: sr_ctlr, sr_target, and sr_lun. The ABORT command is issued on the bus as soon as possible but there could be a delay if the bus is busy. Status is returned in sr_status. The function returns a nonzero value when the ABORT command is issued successfully, and a zero when the ABORT command fails (which probably indicates a serious bus problem).

The purpose of scsi_reset() is to reset the adapter hardware and possibly the attached bus, for example by asserting the reset line on the bus for at least 25 microseconds. The prototype of the function is

int (*scsi_reset[adapter-type])(uchar adap);

The adapter number is reset and a nonzero value is returned. If the host adapter driver does not support this function, or if it is unable to reset the hardware, it returns 0.

A SCSI driver can be included in the kernel through a VECTOR, INCLUDE, or USE line in the system file in /var/sysgen/system (see “Configuring a Kernel”). When included through a VECTOR line, the pfxedtinit() entry point is called for each VECTOR line given. The VECTOR can describe a logical unit or a control unit, according to your design choice. However, a VECTOR line for a high-level SCSI driver can not include a probe or exprobe operand, because the hardware is owned by the host adapter driver, not by the SCSI device driver.

When included through a USE line, a SCSI driver is initialized at its pfxinit() entry point. In this case, the driver must obtain the adapter number by some other means. (See “Initialization Entry Points”.)

When the pfxopen() entry point is called, the SCSI driver uses the appropriate scsi_info() function to verify the device and get hardware dependent Inquiry data from it. If the device is operational, the driver calls scsi_alloc() to open a communications path to it.

In general, it is simplest to put all access to a device within a pfxstrategy() entry point, even in a character device driver. When the pfxread(), pfxwrite(), or pfxioctl() entry point needs to read or write data, it can prepare a uio_t to describe the data, and call uiophysio() to direct the operation through the single pfxstrategy() entry point.

The notify routine passed in the sr_notify field plays the same role as the pfxintr() entry point in other device drivers. It is called asynchronously, when the SCSI command completes. It may not call a kernel function that can sleep. However, it does not have to be named pfxintr(), and a SCSI driver does not have to provide a pfxintr() entry point.

A SCSI driver can be either a block or a character driver, or it can support both interfaces. When preparing the descriptive file for /var/sysgen/master.d, you must use the s flag, specifying a software-only driver, and list scsi as a dependency, in the descriptive line in /var/sysgen/master.d. See “Describing the Driver in /var/sysgen/master.d”.

A host adapter driver is a low-level driver for a SCSI bus adapter. A host adapter driver is similar to other device drivers described in this book in many ways:

Unlike other drivers, a host adapter driver does not provide any entry points for serving the needs of system functions, such as pfxread(), pfxpoll(), or pfxstrategy(). Instead, it supplies the entry points used by SCSI device drivers.

In its initialization, the host adapter driver does three things:

uchar get_driver_number(void);

The host adapter drivers such as wd93, wd95, and jag send error messages to the system log using the cmn_err() function (see “Producing Diagnostic Displays”).

These messages almost always contain the adapter number (sometimes called the bus number or controller number). They sometimes contain the number of the target device, and sometimes add the number of the logical unit that was addressed.

Messages from the wd93 driver specify the adapter number as Bus=n. The target device is shown as ID=n and the logical unit as LUN=n.

Messages from the wd95 and jag drivers contain one, two, or three or more decimal numbers. In all cases, the first number is the adapter number, the second is the target ID, and the third (when present) is the logical unit number.

When error messages list a sense code, refer to “SCSI Sense Codes (Table scsi_key_msgtab)” and to “Additional Sense Codes (Table scsi_addit_msgtab)”.

When the error message reports an error from the adapter itself, refer to “Adapter Error Codes (Table scsi_adaperrs_tab)”.

The scsi module contains a set of error message tables that you can use to generate error messages based on SCSI sense codes and other data. The contents of these tables is documented here for reference, and to assist in decoding messages from SCSI drivers.

Each table is an array of pointers to strings; for example the scsi_key_msgtab table is defined beginning as follows:

char *scsi_key_msgtab[SC_NUMSENSE] = {
   "No sense",          /* 0x0 */
   "Recovered Error",   /* 0x1 */
...};

Each of the tables is declared as extern in sys/scsi.h.

Some of the SCSI states and phases that can be detected by the wd93 host adapter driver are listed in Table 13-12 for reference, in case they appear in a debugging log message. These states and phases are declared in the /usr/include/sys/wd93.h header file. The comments in the table have been extracted from that file and supplemented with additional information.

“Out” is from the CPU to the SCSI device in these descriptions, and “receive” and “send” are also from the SCSI device point of view, since the target controls all the bus phases except for initial selection.