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
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
Function Name | Called as a Result of |
|---|---|
tran_tgt_init(9E) | System attaching target device instance |
tran_tgt_probe(9E) | Target driver calling scsi_probe(9F) |
tran_tgt_free(9E) | System detaching target device instance |
tran_start(9E) | Target driver calling scsi_transport(9F) |
tran_reset(9E) | Target driver calling scsi_reset(9F) |
tran_abort(9E) | Target driver calling scsi_abort(9F) |
tran_getcap(9E) | Target driver calling scsi_ifgetcap(9F) |
tran_setcap(9E) | Target driver calling scsi_ifsetcap(9F) |
tran_init_pkt(9E) | Target driver calling scsi_init_pkt(9F) |
tran_destroy_pkt(9E) | Target driver calling scsi_destroy_pkt(9F) |
tran_dmafree(9E) | Target driver calling scsi_dmafree(9F) |
tran_sync_pkt(9E) | Target driver calling scsi_sync_pkt(9F) |
(9E)tran_reset_notify | Target driver calling scsi_reset_notify(9F) |
tran_quiesce(9E) | System quiescing bus |
tran_unquiesce(9E) | System resuming activity on bus |
tran_bus_reset(9E) | System resetting bus |
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)