Other SCSI Design Considerations

The following topics cover design considerations of SCSI device and adapter device drivers:

• Responsibilities of the SCSI Device Driver
• SCSI Options to the openx Subroutine
• Using the SC_FORCED_OPEN Option
• Using the SC_RETAIN_RESERVATION Option
• Using the SC_DIAGNOSTIC Option
• Using the SC_NO_RESERVE Option
• Using the SC_SINGLE Option
• Closing the SCSI Device
• SCSI Error Processing
• Device Driver and Adapter Device Driver Interfaces
• Performing SCSI Dumps

Responsibilities of the SCSI Device Driver

SCSI device drivers are responsible for the following actions:

• Interfacing with block I/O and logical-volume device-driver code in the operating system.
• Translating I/O requests from the operating system into SCSI commands suitable for the particular SCSI device. These commands are then given to the SCSI adapter device driver for execution.
• Issuing any and all SCSI commands to the attached device. The SCSI adapter device driver sends no SCSI commands except those it is directed to send by the calling SCSI device driver.
• Managing SCSI device reservations and releases. In the operating system, it is assumed that other SCSI initiators may be active on the SCSI bus. Usually, the SCSI device driver reserves the SCSI device at open time and releases it at close time (except when told to do otherwise through parameters in the SCSI device driver interface). Once the device is reserved, the SCSI device driver must be prepared to reserve the SCSI device again whenever a Unit Attention condition is reported through the SCSI request-sense data.

SCSI Options to the openx Subroutine

SCSI device drivers in the operating system must support eight defined extended options in their open routine (that is, an openx subroutine). Additional extended options to the open are also allowed, but they must not conflict with predefined open options. The defined extended options are bit flags in the ext open parameter. These options can be specified singly or in combination with each other. The required ext options are defined in the /usr/include/sys/scsi.h header file and can have one of the following values:

Using the SC_FORCED_OPEN Option

The SC_FORCED_OPEN option causes the SCSI device driver to call the SCSI adapter device driver's Bus Device Reset ioctl (SCIORESET) operation on the first open. This forces the device to release another initiator's reservation. After the SCIORESET command is completed, other SCSI commands are sent as in a normal open. If any of the SCSI commands fail due to a reservation conflict, the open registers the failure as an EBUSY status. This is also the result if a reservation conflict occurs during a normal open. The SCSI device driver should require the caller to have appropriate authority to request the SC_FORCED_OPEN option since this request can force a device to drop a SCSI reservation. If the caller attempts to execute this system call without the proper authority, the SCSI device driver should return a value of -1, with the errno global variable set to a value of EPERM.

Using the SC_RETAIN_RESERVATION Option

The SC_RETAIN_RESERVATION option causes the SCSI device driver not to issue the SCSI release command during the close of the device. This guarantees a calling program control of the device (using SCSI reservation) through open and close cycles. For shared devices (for example, disk or CD-ROM), the SCSI device driver must OR together this option for all opens to a given device. If any caller requests this option, the close routine does not issue the release even if other opens to the device do not set SC_RETAIN_RESERVATION. The SCSI device driver should require the caller to have appropriate authority to request the SC_RETAIN_RESERVATION option since this request can allow a program to monopolize a device (for example, if this is a nonshared device). If the caller attempts to execute this system call without the proper authority, the SCSI device driver should return a value of -1, with the errno global variable set to a value of EPERM.

Using the SC_DIAGNOSTIC Option

The SC_DIAGNOSTIC option causes the SCSI device driver to enter Diagnostic mode for the given device. This option directs the SCSI device driver to perform only minimal operations to open a logical path to the device. No SCSI commands should be sent to the device in the open or close routine when the device is in Diagnostic mode. One or more ioctl operations should be provided by the SCSI device driver to allow the caller to issue SCSI commands to the attached device for diagnostic purposes.

The SC_DIAGNOSTIC option gives the caller an exclusive open to the selected device. This option requires appropriate authority to execute. If the caller attempts to execute this system call without the proper authority, the SCSI device driver should return a value of -1, with the errno global variable set to a value of EPERM. The SC_DIAGNOSTIC option may be executed only if the device is not already opened for normal operation. If this ioctl operation is attempted when the device is already opened, or if an openx call with the SC_DIAGNOSTIC option is already in progress, a return value of -1 should be passed, with the errno global variable set to a value of EACCES. Once successfully opened with the SC_DIAGNOSTIC flag, the SCSI device driver is placed in Diagnostic mode for the selected device.

Using the SC_NO_RESERVE Option

The SC_NO_RESERVE option causes the SCSI device driver not to issue the SCSI reserve command during the opening of the device and not to issue the SCSI release command during the close of the device. This allows multiple hosts to share the device. The SCSI device driver should require the caller to have appropriate authority to request the SC_NO_RESERVE option, since this request allows other hosts to modify data on the device. If a caller does this kind of request then the caller must ensure data integrity between multiple hosts. If the caller attempts to execute this system call without the proper authority, the SCSI device driver should return a value of -1, with the errno global variable set to a value of EPERM.

Using the SC_SINGLE Option

The SC_SINGLE option causes the SCSI device driver to issue a normal open, but does not allow another caller to issue another open until the first caller has closed the device. This request gives the caller an exclusive open to the selected device. If this openx is attempted when the device is already open, a return value of -1 is passed, with the errno global variable set to a value of EBUSY.

Once sucessfully opened, the device is placed in Exclusive Access mode. If another caller tries to do any type of open, a return value of -1 is passed, with the errno global variable set to a value of EACCES.

The remaining options for the ext parameter are reserved for future requirements.

Implementation note: The following table shows how the various combinations of ext options should be handled in the SCSI device driver.

Closing the SCSI Device

When a SCSI device driver is preparing to close a device through the SCSI adapter device driver, it must ensure that all transactions are complete. When the SCSI adapter device driver receives a SCIOSTOP ioctl operation and there are pending I/O requests, the ioctl operation does not return until all have completed. New requests received during this time are rejected from the adapter device driver's ddstrategy routine.

When the SCSI adapter device driver receives an SCIOSTOPTGT ioctl operation, it must forcibly free any receive data buffers that have been queued to the SCSI device driver for this device and have not been returned to the SCSI adapter device driver through the buffer free routine. The SCSI device driver is responsible for making sure all the receive data buffers are freed before calling the SCIOSTOPTGT ioctl operation. However, the SCSI adapter device driver must check that this is done, and, if necessary, forcibly free the buffers. The buffers must be freed because those not freed result in memory areas being permanently lost to the system (until the next boot).

To allow the SCSI adapter device driver to free buffers that are sent to the SCSI device driver but never returned, it must track which tm_bufs are currently queued to the SCSI device driver. Tracking tm_bufs requires the SCSI adapter device driver to violate the general SCSI rule, which states the SCSI adapter device driver should not modify the tm_bufs structure while it is queued to the SCSI device driver. This exception to the rule is necessary since it is never acceptable not to free memory allocated from the system.

SCSI Error Processing

It is the responsibility of the SCSI device driver to process SCSI check conditions and other returned errors properly. The SCSI adapter device driver only passes SCSI commands without otherwise processing them and is not responsible for device error recovery.

Device Driver and Adapter Device Driver Interfaces

The SCSI device drivers can have both character (raw) and block special files in the /dev directory. The SCSI adapter device driver has only character (raw) special files in the /dev directory and has only the ddconfig, ddopen, ddclose, dddump, and ddioctl entry points available to operating system programs. The ddread and ddwrite entry points are not implemented.

Internally, the devsw table has entry points for the ddconfig, ddopen, ddclose, dddump, ddioctl, and ddstrategy routines. The SCSI device drivers pass their SCSI commands to the SCSI adapter device driver by calling the SCSI adapter device driver ddstrategy routine. (This routine is unavailable to other operating system programs due to the lack of a block-device special file.)

Access to the SCSI adapter device driver's ddconfig, ddopen, ddclose, dddump, ddioctl, and ddstrategy entry points by the SCSI device drivers is performed through the kernel services provided. These include such services as fp_opendev, fp_close, fp_ioctl, devdump, and devstrategy.

Performing SCSI Dumps

A SCSI adapter device driver must have a dddump entry point if it is used to access a system dump device. A SCSI device driver must have a dddump entry point if it drives a dump device. Examples of dump devices are disks and tapes.

Note: SCSI adapter-device-driver writers should be aware that system services providing interrupt and timer services are unavailable for use in the dump routine. Kernel DMA services are assumed to be available for use by the dump routine. The SCSI adapter device driver should be designed to ignore extra DUMPINIT and DUMPSTART commands to the dddump entry point.

The DUMPQUERY option should return a minimum transfer size of 0 bytes, and a maximum transfer size equal to the maximum transfer size supported by the SCSI adapter device driver.

Calls to the SCSI adapter device driver DUMPWRITE option should use the arg parameter as a pointer to the sc_buf structure to be processed. Using this interface, a SCSI write command can be executed on a previously started (opened) target device. The uiop parameter is ignored by the SCSI adapter device driver during the DUMPWRITE command. Spanned, or consolidated, commands are not supported using the DUMPWRITE option. Gathered write commands are also not supported using the DUMPWRITE option. No queuing of sc_buf structures is supported during dump processing since the dump routine runs essentially as a subroutine call from the caller's dump routine. Control is returned when the entire sc_buf structure has been processed.

Attention: Also, both adapter-device-driver and device-driver writers should be aware that any error occurring during the DUMPWRITE option is considered unsuccessful. Therefore, no error recovery is employed during the DUMPWRITE. Return values from the call to the dddump routine indicate the specific nature of the failure.

Successful completion of the selected operation is indicated by a 0 return value to the subroutine. Unsuccessful completion is indicated by a return code set to one of the following values for the errno global variable. The various sc_buf status fields, including the b_error field, are not set by the SCSI adapter device driver at completion of the DUMPWRITE command. Error logging is, of necessity, not supported during the dump.

• An errno value of EINVAL indicates that a request that was not valid passed to the SCSI adapter device driver, such as to attempt a DUMPSTART command before successfully executing a DUMPINIT command.
• An errno value of EIO indicates that the SCSI adapter device driver was unable to complete the command due to a lack of required resources or an I/O error.
• An errno value of ETIMEDOUT indicates that the adapter did not respond with completion status before the passed command time-out value expired.

Related Information

A Typical Initiator-Mode SCSI Driver Transaction Sequence.

Required SCSI Adapter Device Driver ioctl Commands.

Understanding the Execution of Initiator I/O Requests.

SCSI Error Recovery.

Understanding the sc_buf Structure.