Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Devices /
Chapter 4 - SCSI Manager 4.3

Using SCSI Manager 4.3

A fundamental difference between SCSI Manager 4.3 and the original SCSI Manager is that a single function, SCSIAction, handles an entire SCSI transaction. You do not need to explicitly arbitrate for the bus, select a device, or send a SCSI command. In most cases, your program does not need to be aware of SCSI bus phases.

The SCSIAction function is the entry point for all SCSI Manager 4.3 client functions. These functions provide the services that clients (applications and device drivers) need to communicate with SCSI devices. The only parameter to SCSIAction is a pointer to a SCSI Manager parameter block data structure. You use the scsiFunctionCode field of the parameter block to specify which function to perform. Most functions use specialized versions of the parameter block to carry the input parameters and return the results. For example, the SCSIBusInquiry function requires a SCSI bus inquiry parameter block (SCSIBusInquiryPB).

Perhaps the most important SCSIAction function is SCSIExecIO, which you use to request a SCSI I/O transaction. This function uses the SCSI I/O parameter block (SCSIExecIOPB), which specifies the destination of the request (the bus, target, and logical unit), the command descriptor block (CDB), the data buffers that either contain or receive the data, and a variety of other fields and flags required to fulfill the transaction.

You can call the SCSIExecIO function either synchronously or asynchronously. If the scsiCompletion field of the parameter block contains a pointer to a completion routine, the SCSI Manager executes the function asynchronously. If you set the scsiCompletion field to nil, the request is executed synchronously.

Because of interrupt handling considerations, device drivers must issue synchronous SCSIExecIO requests as such, rather than issuing them asynchronously and creating a synchronous wait loop inside the device driver. See "Writing a SCSI Device Driver," beginning on page 4-11, for more information about the proper handling of synchronous and asynchronous requests by device drivers. Applications are not subject to the same restrictions as device drivers and may create synchronous wait loops if desired.

Different SIM implementations may require additional fields beyond the standard fields of the SCSI I/O parameter block. Some of these may be input or output fields providing access to special capabilities of a SIM; others may be private fields required during the processing of the request. You can use the SCSIBusInquiry function to determine the size of the SCSI I/O parameter block for a particular SIM, as well as the largest parameter block required by any registered SIM.

You can also use the SCSIBusInquiry function to get information about various hardware and software characteristics of a SIM and its HBA. You can use this information to form a request that takes advantage of all the capabilities of a SIM.

Parameter blocks are queued separately for each logical unit (LUN) on a target device. When an error occurs during a SCSIExecIO request, the SIM freezes the queue for the LUN on which the error occurred, to allow you to perform any necessary error recovery. After correcting the error condition, you must use the SCSIReleaseQ function to enable normal handling of I/O requests to that LUN. See "Error Recovery Techniques" on page 4-10 for more information.

Locating SCSI Devices

SCSI Manager 4.3 supports multiple buses, allowing a client to specify a device based on its bus number as well as its target ID and LUN. To emulate original SCSI Manager functions that understand only a target ID, the technique first used in the Macintosh Quadra 900 has been expanded to include not only built-in SCSI buses but any compatible HBA installed in a NuBus or PDS expansion slot.

When multiple buses are registered with the XPT, emulated original SCSI Manager transactions are directed to the first bus that responds to a selection for the requested target ID. The target ID specified in a SCSISelect function is called the virtual ID because it designates a device on the single virtual bus (which encompasses all original SCSI Manager-compatible buses).

When you make a SCSISelect request, the XPT first attempts to select a device on the built-in internal bus. If there is no response on that bus, the XPT tries the built-in external bus (on models that include two SCSI buses), or the first registered add-on bus. Additional buses are searched in the order they were registered.

When the XPT finds a device that responds to the selection, all subsequent SCSISelect requests are directed to the bus on which that selection occurred. Until a successful selection occurs on one of the buses, the virtual ID is not assigned to any physical bus. Once established, the mapping of virtual ID to physical bus is not changed until restart. You can use the SCSIGetVirtualIDInfo function to determine which physical bus a device is attached to.

It is possible for devices to be available through the original SCSI Manager interface but not through the SCSI Manager 4.3 interface. For example, a third-party SIM may install its own XPT if SCSI Manager 4.3 is not available. This creates a functional SCSI Manager 4.3 interface that does not include the built-in SCSI bus. Another possibility is the presence of a third-party SCSI adapter that does not comply with SCSI Manager 4.3 but patches the original SCSI Manager interface to create its own virtual bus. To locate all SCSI devices in these environments you must use the SCSI Manager 4.3 functions to scan for devices on all SIMs and then use the original SCSI Manager functions to scan for devices that are not accessible through the SCSI Manager 4.3 interface.

Describing Data Buffers

SCSI Manager 4.3 recognizes three data types for describing the source and destination memory buffers for a SCSI data transfer. The most familiar is a simple buffer, consisting of a single contiguous block of memory. An extension of this is the scatter/gather list, which consists of one or more elements, each of which describes the location and size of one buffer. Scatter/gather lists allow you to group multiple buffers of any size into a single virtual buffer for an I/O transaction.

In addition to these, SCSI Manager 4.3 supports the transfer instruction block (TIB) data type used by the original SCSI Manager interface. This structure is used only for emulating original SCSI Manager functions. During the execution of a SCSIRead, SCSIWrite, SCSIRBlind, or SCSIWBlind function, TIB instructions are interpreted by the SCSI Manager to determine the source and destination of the data. See the chapter "SCSI Manager" in this book for more information about TIB instructions.

Handshaking Instructions

In the original SCSI Manager interface, you use TIB instructions to show the SCSI Manager where long delays (greater than 16 microseconds) may occur in a blind transfer. Without these instructions, the SCSI Manager can lose data or crash the system if delays occur at unexpected times in a data transfer.

You use the scsiHandshake field of the SCSI I/O parameter block to specify handshaking instructions to SCSI Manager 4.3. This field contains a series of word values, each of which specifies the number of bytes between potential delays in the SCSI data transfer. You terminate the instructions with a value of 0.

For example, a "1, 511" TIB is a common TIB structure used with disk drives that have a 512-byte block size and sometimes experience a delay between the first and second bytes in the block, as well as a delay between the last byte of a block and the first byte of the following block. This TIB structure translates to a scsiHandshake field of "1, 511, 0", which indicates a request to synchronize and transfer 1 byte, synchronize and transfer 511 bytes, synchronize and transfer 1 byte, and so on.

Like the original SCSI Manager, SCSI Manager 4.3 always synchronizes on the first byte of a data phase. In addition, the handshaking cycle is reset whenever a device disconnects. That is, the cycle starts over from the beginning when a device reconnects. The scsiHandshake field should also indicate where a device may disconnect.

The handshaking cycle continues across scatter/gather list elements. For example, if the handshake array contains "2048, 0" and the scatter/gather list specifies a transfer of 512 bytes and then 8192 bytes, a handshake synchronization will occur 1536 bytes into the second scatter/gather element.

You should use polled transfers for devices that may experience unpredictable delays during the data phase or can disconnect at unpredictable times.

Error Recovery Techniques

SCSI Manager 4.3 provides a feature called queue freezing that you can use to recover from I/O errors. When a SCSIExecIO request returns an error, the SIM freezes the I/O queue for the LUN that caused the error. You can then issue additional requests with the scsiSIMQHead flag set so that they will be inserted in front of any requests that were already in the queue. You can use this method to perform retries, block remapping, or other error recovery techniques. After inserting your error handling requests, you call the SCSIReleaseQ function to allow the request at the head of the queue to be dispatched. If necessary, multiple requests can be single-stepped by setting the scsiSIMQFreeze flag as well as the scsiSIMQHead flag on each of the requests and following each with a SCSIReleaseQ call.

Note
You can disable queue freezing for a single transaction by setting the scsiSIMQNoFreeze flag.

Optional Features

The following optional features may not be supported by all SIMs. You should use the SCSIBusInquiry function to determine which features are supported by a particular bus.

Previous Book Contents Book Index Next

© Apple Computer, Inc.
3 JUL 1996