Important: The information in this document is obsolete and should not be used for new development.
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 toSCSIAction
is a pointer to a SCSI Manager parameter block data structure. You use thescsiFunctionCode
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, theSCSIBusInquiry
function requires a SCSI bus inquiry parameter block (SCSIBusInquiryPB
).Perhaps the most important
SCSIAction
function isSCSIExecIO
, 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 thescsiCompletion
field of the parameter block contains a pointer to a completion routine, the SCSI Manager executes the function asynchronously. If you set thescsiCompletion
field tonil
, 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 theSCSIReleaseQ
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 theSCSIGetVirtualIDInfo
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
, orSCSIWBlind
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 aSCSIExecIO
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 thescsiSIMQHead
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 theSCSIReleaseQ
function to allow the request at the head of the queue to be dispatched. If necessary, multiple requests can be single-stepped by setting thescsiSIMQFreeze
flag as well as thescsiSIMQHead
flag on each of the requests and following each with aSCSIReleaseQ
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 theSCSIBusInquiry
function to determine which features are supported by a particular bus.
- synchronous data transfer
- target command queuing
- HBA engine support
- target mode
- asynchronous event notification
© Apple Computer, Inc.
3 JUL 1996