JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Writing Device Drivers     Oracle Solaris 11.1 Information Library
search filter icon
search icon

Document Information

Preface

Part I Designing Device Drivers for the Oracle Solaris Platform

1.  Overview of Oracle Solaris Device Drivers

2.  Oracle Solaris Kernel and Device Tree

3.  Multithreading

4.  Properties

5.  Managing Events and Queueing Tasks

6.  Driver Autoconfiguration

7.  Device Access: Programmed I/O

8.  Interrupt Handlers

9.  Direct Memory Access (DMA)

10.  Mapping Device and Kernel Memory

11.  Device Context Management

12.  Power Management

13.  Hardening Oracle Solaris Drivers

14.  Layered Driver Interface (LDI)

Part II Designing Specific Kinds of Device Drivers

15.  Drivers for Character Devices

16.  Drivers for Block Devices

17.  SCSI Target Drivers

Introduction to Target Drivers

Sun Common SCSI Architecture Overview

General Flow of Control

SCSA Functions

Hardware Configuration File

Declarations and Data Structures

scsi_device Structure

scsi_pkt Structure (Target Drivers)

Autoconfiguration for SCSI Target Drivers

probe() Entry Point (SCSI Target Drivers)

attach() Entry Point (SCSI Target Drivers)

detach() Entry Point (SCSI Target Drivers)

getinfo() Entry Point (SCSI Target Drivers)

Resource Allocation

scsi_init_pkt() Function

scsi_sync_pkt() Function

scsi_destroy_pkt() Function

scsi_alloc_consistent_buf() Function

scsi_free_consistent_buf() Function

Building and Transporting a Command

Building a Command

Setting Target Capabilities

Transporting a Command

Synchronous scsi_transport() Function

Command Completion

Reuse of Packets

Auto-Request Sense Mode

Dump Handling

SCSI Options

18.  SCSI Host Bus Adapter Drivers

19.  Drivers for Network Devices

20.  USB Drivers

21.  SR-IOV Drivers

Part III Building a Device Driver

22.  Compiling, Loading, Packaging, and Testing Drivers

23.  Debugging, Testing, and Tuning Device Drivers

24.  Recommended Coding Practices

Part IV Appendixes

A.  Hardware Overview

B.  Summary of Oracle Solaris DDI/DKI Services

C.  Making a Device Driver 64-Bit Ready

D.  Console Frame Buffer Drivers

E.  pci.conf File

Index

Sun Common SCSI Architecture Overview

The Sun Common SCSI Architecture (SCSA) is the Solaris DDI/DKI programming interface for the transmission of SCSI commands from a target driver to a host bus adapter driver. This interface is independent of the type of host bus adapter hardware, the platform, the processor architecture, and the SCSI command being transported across the interface.

Conforming to the SCSA enables the target driver to pass SCSI commands to target devices without knowledge of the hardware implementation of the host bus adapter.

The SCSA conceptually separates building the SCSI command from transporting the command with data across the SCSI bus. The architecture defines the software interface between high-level and low-level software components. The higher level software component consists of one or more SCSI target drivers, which translate I/O requests into SCSI commands appropriate for the peripheral device. The following example illustrates the SCSI architecture.

Figure 17-1 SCSA Block Diagram

image:Diagram shows the role of the Sun Common SCSI Architecture in relation to SCSI drivers in the operating system.

The lower-level software component consists of a SCSA interface layer and one or more host bus adapter drivers. The target driver is responsible for the generation of the proper SCSI commands required to execute the desired function and for processing the results.

General Flow of Control

Assuming no transport errors occur, the following steps describe the general flow of control for a read or write request.

  1. The target driver's read(9E) or write(9E) entry point is invoked. physio(9F) is used to lock down memory, prepare a buf structure, and call the strategy routine.

  2. The target driver's strategy(9E) routine checks the request. strategy() then allocates a scsi_pkt(9S) by using scsi_init_pkt(9F). The target driver initializes the packet and sets the SCSI command descriptor block (CDB) using the scsi_setup_cdb(9F) function. The target driver also specifies a timeout. Then, the driver provides a pointer to a callback function. The callback function is called by the host bus adapter driver on completion of the command. The buf(9S) pointer should be saved in the SCSI packet's target-private space.

  3. The target driver submits the packet to the host bus adapter driver by using scsi_transport(9F). The target driver is then free to accept other requests. The target driver should not access the packet while the packet is in transport. If either the host bus adapter driver or the target supports queueing, new requests can be submitted while the packet is in transport.

  4. As soon as the SCSI bus is free and the target not busy, the host bus adapter driver selects the target and passes the CDB. The target driver executes the command. The target then performs the requested data transfers.

  5. After the target sends completion status and the command completes, the host bus adapter driver notifies the target driver. To perform the notification, the host calls the completion function that was specified in the SCSI packet. At this time the host bus adapter driver is no longer responsible for the packet, and the target driver has regained ownership of the packet.

  6. The SCSI packet's completion routine analyzes the returned information. The completion routine then determines whether the SCSI operation was successful. If a failure has occurred, the target driver retries the command by calling scsi_transport(9F) again. If the host bus adapter driver does not support auto request sense, the target driver must submit a request sense packet to retrieve the sense data in the event of a check condition.

  7. After successful completion or if the command cannot be retried, the target driver calls scsi_destroy_pkt(9F). scsi_destroy_pkt() synchronizes the data. scsi_destroy_pkt() then frees the packet. If the target driver needs to access the data before freeing the packet, scsi_sync_pkt(9F) is called.

  8. Finally, the target driver notifies the requesting application that the read or write transaction is complete. This notification is made by returning from the read(9E) entry point in the driver for character devices. Otherwise, notification is made indirectly through biodone(9F).

SCSA allows the execution of many of such operations, both overlapped and queued, at various points in the process. The model places the management of system resources on the host bus adapter driver. The software interface enables the execution of target driver functions on host bus adapter drivers by using SCSI bus adapters of varying degrees of sophistication.

SCSA Functions

SCSA defines functions to manage the allocation and freeing of resources, the sensing and setting of control states, and the transport of SCSI commands. These functions are listed in the following table.

Table 17-1 Standard SCSA Functions

Function Name
Category
Error handling
Transport information and control
Resource management
Polled I/O
Probe functions
CDB initialization function
Command transport

Note - If your driver needs to work with a SCSI-1 device, use the makecom(9F).