SCSI Host Bus Adapter Drivers

This chapter contains information on creating SCSI host bus adapter (HBA) drivers and provides sample code illustrating the structure of a typical HBA driver and showing the use of the HBA driver interfaces provided by the Sun Common SCSI Architecture (SCSA). This chapter provides information on the following subjects:

• Introduction to Host Bus Adapter Drivers

• SCSI Interface

• SCSA HBA Interfaces

• HBA Driver Dependency and Configuration Issues

• SCSA HBA Entry Points

• SCSI HBA Driver Specific Issues

• Support for Queuing

Introduction to Host Bus Adapter Drivers

As described in Chapter 14, SCSI Target Drivers, the Solaris 9 DDI/DKI divides the software interface to SCSI devices into two major parts:

• Target devices and drivers

• Host bus adapter devices and drivers

Target device refers to a device on a SCSI bus, such as a disk or a tape drive. Target driver refers to a software component installed as a device driver. Each target device on a SCSI bus is controlled by one instance of the target driver.

Host bus adapter device refers to HBA hardware, such as an SBus or PCI SCSI adapter card. Host bus adapter driver refers to a software component installed as a device driver, such as the esp driver on a SPARC machine or the ncrs driver on an IA machine, and the isp driver, which works on both. An instance of the HBA driver controls each of its host bus adapter devices configured in the system.

The Sun Common SCSI Architecture (SCSA) defines the interface between these target and HBA components.

Note - Understanding SCSI target drivers is an essential prerequisite to writing effective SCSI HBA drivers. For information on SCSI target drivers, see Chapter 14, SCSI Target Drivers. Target driver developers can also benefit from reading this chapter.

The host bus adapter driver is responsible for:

• Managing host bus adapter hardware

• Accepting SCSI commands from the SCSI target driver

• Transporting the commands to the specified SCSI target device

• Performing any data transfers that the command requires

• Collecting status

• Handling auto-request sense (optional)

• Informing the target driver of command completion (or failure)

SCSI Interface

SCSA is the Solaris 9 DDI/DKI programming interface for the transmission of SCSI commands from a target driver to a host adapter driver. By conforming to the SCSA, the target driver can pass any combination of SCSI commands and sequences to a target device without knowledge of the hardware implementation of the host adapter. SCSA conceptually separates the building of a SCSI command (by the target driver) from the transporting of the command to and data to and from the SCSI bus (by the HBA driver) for the appropriate target device. SCSA manages the connections between the target and HBA drivers through an HBA transport layer, as shown in the following figure.

Figure 15-1 SCSA Interface

The HBA transport layer is a software and hardware layer responsible for transporting a SCSI command to a SCSI target device. The HBA driver provides resource allocation, DMA management, and transport services in response to requests made by SCSI target drivers through SCSA. The host adapter driver also manages the host adapter hardware and the SCSI protocols necessary to perform the commands. When a command has been completed, the HBA driver calls the target driver's SCSI pkt command completion routine.

Figure 15-2 illustrates this flow, with emphasis placed on the transfer of information from target drivers to SCSA to HBA drivers. The following figure also shows typical transport entry points and function calls.

Figure 15-2 Transport Layer Flow

SCSA HBA Interfaces

SCSA HBA interfaces include HBA entry points, HBA data structures, and an HBA framework.

SCSA HBA Entry Point Summary

SCSA defines a number of HBA driver entry points, listed in the following table. These entry points are called by the system when configuring a target driver instance connected to the HBA driver, or when the target driver makes a SCSA request. See SCSA HBA Entry Points for more information.

Table 15-1 SCSA HBA Entry Point Summary

SCSA HBA Data Structures

SCSA defines data structures to enable the exchange of information between the target and HBA drivers. These data structures include:

• scsi_hba_tran(9S)

• scsi_address(9S)

• scsi_device(9S)

• scsi_pkt(9S)