Legacy Document

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

Chapter 4 - SCSI Manager 4.3 / SCSI Manager 4.3 Reference

SCSI I/O Parameter Block
You use the SCSI I/O parameter block to pass information to the SCSIExecIO function. The SCSI I/O parameter block is defined by the SCSIExecIOPB data type.
#define SCSI_IO_Macro \
   SCSIPBHdr                                 \
   UInt16         scsiResultFlags;           \
   UInt16         scsiReserved12;            \
   UInt8          *scsiDataPtr;              \
   SInt32         scsiDataLength;            \
   UInt8          *scsiSensePtr;             \
   SInt8          scsiSenseLength;           \
   UInt8          scsiCDBLength;             \
   UInt16         scsiSGListCount;           \
   UInt32         scsiReserved4;             \
   UInt8          scsiSCSIstatus;            \
   SInt8          scsiSenseResidual;         \
   UInt16         scsiReserved5;             \
   SInt32         scsiDataResidual;          \
   CDB            scsiCDB;                   \
   SInt32         scsiTimeout;               \
   UInt8          *scsiReserved13;           \
   UInt16         scsiReserved14;            \
   UInt16         scsiIOFlags;               \
   UInt8          scsiTagAction;             \
   UInt8          scsiReserved6;             \
   UInt16         scsiReserved7;             \
   UInt16         scsiSelectTimeout;         \
   UInt8          scsiDataType;              \
   UInt8          scsiTransferType;          \
   UInt32         scsiReserved8;             \
   UInt32         scsiReserved9;             \
   UInt16         scsiHandshake[8];          \
   UInt32         scsiReserved10;            \
   UInt32         scsiReserved11;            \
   struct SCSI_IO *scsiCommandLink;          \
   UInt8          scsiSIMpublics[8];         \
   UInt8          scsiAppleReserved6[8];     \
   UInt16         scsiCurrentPhase;          \
   SInt16         scsiSelector;              \
   OSErr          scsiOldCallResult;         \
   UInt8          scsiSCSImessage;           \
   UInt8          XPTprivateFlags;           \
   UInt8          XPTextras[12];

struct SCSI_IO
{
   SCSI_IO_Macro
};
typedef struct SCSI_IO SCSI_IO;
typedef SCSI_IO SCSIExecIOPB;
Field Description

SCSIPBHdr
A macro that includes the SCSI Manager parameter block header, described on page 4-21.
scsiResultFlags
Output flags that modify the scsiResult field.
scsiSIMQFrozenThe SIM queue for this LUN is frozen because of an error. You must call the SCSIReleaseQ function to release the queue and resume processing requests.
scsiAutosenseValidAn automatic REQUEST SENSE was performed after this I/O because of a CHECK CONDITION status message from the device. The data contained in the scsiSensePtr buffer is valid.
scsiBusNotFreeThe SCSI Manager was unable to clear the bus after an error. You may need to call the SCSIResetBus function to restore operation.

scsiDataPtr
A pointer to a data buffer or scatter/gather list. You specify the data type using the scsiDataType field.
scsiDataLength
The amount of data to be transferred, in bytes.
scsiSensePtr
A pointer to the autosense data buffer. If autosense is enabled (the scsiDisableAutosense flag is not set), the SCSI Manager returns REQUEST SENSE information in this buffer.
scsiSenseLength
The size of the autosense data buffer, in bytes.
scsiCDBLength
The length of the SCSI command descriptor block, in bytes.
scsiSGListCount
The number of elements in the scatter/gather list.
scsiSCSIstatus
The status returned by the SCSI device.
scsiSenseResidual
The automatic REQUEST SENSE residual length (that is, the number of bytes that were expected but not transferred). This number is negative if extra bytes had to be transferred to force the target off of the bus.
scsiDataResidual
The data transfer residual length (that is, the number of bytes that were expected but not transferred). This number is negative if extra bytes had to be transferred to force the target off the bus.
scsiCDB
This field can contain either the actual CDB or a pointer to the CDB. You set the scsiCDBIsPointer flag if this field contains a pointer.
scsiTimeout
The length of time the SIM should allow before reporting a timeout of the SCSI bus. The time value is represented in Time Manager format (positive values for milliseconds, negative values for microseconds). The timer is started when the I/O request is sent to the target. If the request does not complete within the specified time, the SIM attempts to issue an ABORT message, either by reselecting the device or by asserting the attention (/ATN) signal. A value of 0 specifies the default timeout for the SIM. The default timeout for the SCSI Manager 4.3 SIM is infinite (that is, no timeout).
scsiIOFlags
Additional I/O flags describing the data transfer.
scsiNoParityCheckDisable parity error detection for this transaction.
scsiDisableSelectWAtnDo not send the IDENTIFY message for LUN selection. The LUN is still required in the scsiDevice field so that the request can be placed in the proper queue. The LUN field in the CDB is untouched. The purpose is to provide compatibility with older devices that do not support this aspect of the SCSI-2 specification.
scsiSavePtrOnDisconnectPerform a SAVE DATA POINTER operation automatically in response to a DISCONNECT message from the target. The purpose of this flag is to provide compatibility with devices that do not properly implement this aspect of the SCSI-2 specification.
scsiNoBucketInProhibit bit-bucketing during the data-in phase of the transaction. Bit-bucketing is the practice of throwing away excess data bytes when a target tries to supply more data than the initiator expects. For example, if the CDB requests more data than you specified in the scsiDataLength field, the SCSI Manager normally throws away the excess and returns the scsiDataRunError result code. If this flag is set, the SCSI Manager refuses any extra data, terminates the I/O request, and leaves the bus in the data-in phase. You must reset the bus to restore operation. This flag is intended only for debugging purposes.
scsiNoBucketOutProhibit bit-bucketing during the data-out phase of the transaction. If a target requests more data than you specified in the scsiDataLength field, the SCSI Manager normally sends an arbitrary number of meaningless bytes (0xEE) until the target releases the bus. If this flag is set, the SCSI Manager terminates the I/O request when the last byte is sent and leaves the bus in the data-out phase. You must reset the bus to restore operation. This flag is intended only for debugging purposes.
scsiDisableWideDisable wide data transfer negotiation for this transaction if it had been previously enabled. This option may not be supported by all SIMs.
scsiInitiateWideAttempt wide data transfer negotiation for this transaction if it is not already enabled. This option may not be supported by all SIMs.
scsiRenegotiateSenseAttempt to renegotiate synchronous or wide transfers before issuing a REQUEST SENSE. This is necessary when the error was caused by problems operating in synchronous or wide transfer mode. It is optional because some devices flush sense data after performing negotiation.

scsiTagAction
Reserved.
scsiSelectTimeout
An optional SELECT timeout value, in milliseconds. The default is 250 ms, as specified by SCSI-2. The accuracy of this period is dependent on the HBA.A value of 0 specifies the default timeout. Some SIMs ignore this parameter and always use a value of 250 ms.
scsiDataType
The data type pointed to by the scsiDataPtr field. You specify the type using one of the following constants:
scsiDataBufferThe scsiDataPtr field contains a pointer to a contiguous data buffer, and the scsiDataLength field contains the length of the buffer, in bytes.
scsiDataSG The scsiDataPtr field contains a pointer to a scatter/gather list. The scsiDataLength field contains the total number of bytes to be transferred, and the scsiSGListCount field contains the number of elements in the scatter/gather list.
scsiDataTIB The scsiDataPtr field contains a pointer to a transfer instruction block. This is used by the XPT during original SCSI Manager emulation, when communicating with a SIM that supports this.

scsiTransferType
The type of transfer mode to use during the data phase. You specify the type using one of the following constants:
scsiTransferBlindUse DMA, if available; otherwise, perform a blind transfer using the handshaking information contained in the scsiHandshake field.
scsiTransferPolledUse polled transfer mode. The scsiHandshake field is not required for this mode.

scsiHandshake[8]
Handshaking instructions for blind transfers, consisting of an array of word values, terminated by 0. The SIM polls for data ready after transferring the amount of data specified in each successive scsiHandshake entry. When it encounters a 0 value, the SIM starts over at the beginning of the list. Handshaking always starts from the beginning of the list every time a device transitions to data phase. See "Handshaking Instructions," beginning on page 4-9, for more information.
scsiCommandLink
A pointer to a linked parameter block. This field provides support for SCSI linked commands. This optional feature ensures that a set of commands sent to a device are executed in sequential order without interference from other applications. You create a list of commands using this pointer to link additional parameter blocks. Each parameter block except the last should have the scsiCDBLinked flag set in the scsiFlags field. A CHECK CONDITION status from the device will abort linked command execution. Linked commands may not be supported by all SIMs.
scsiSIMpublics[8]
An additional input field available for use by SIM developers.
scsiCurrentPhase
The current SCSI bus phase reported by the SIM after handling an original SCSI Manager function. This field is used only by the XPT and SIM during original SCSI Manager emulation. The phases are defined by the following constant values:
enum {
	kDataOutPhase,
	kDataInPhase,
	kCommandPhase,
	kStatusPhase,
	kPhaseIllegal0,
	kPhaseIllegal1,
	kMessageOutPhase,
	kMessageInPhase,
	kBusFreePhase,
	kArbitratePhase,
	kSelectPhase
};
scsiSelector
The function selector code that was passed to the _SCSIDispatch trap during original SCSI Manager emulation. The SIM uses this field to determine which original SCSI Manager function to perform.
scsiOldCallResult
The result code from an emulated original SCSI Manager function. The SIM returns results to all original SCSI Manager functions in this field, except for the SCSIComplete result, which it returns in scsiResult.
scsiSCSIMessage
The message byte returned by an emulated SCSIComplete function. This field is only used by the XPT and SIM during original SCSI Manager emulation.
XPTprivateFlags
Reserved.
XPTextras[12]
Reserved.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

	`scsiSIMQFrozen`The SIM queue for this LUN is frozen because of an error. You must call the `SCSIReleaseQ` function to release the queue and resume processing requests.
	`scsiAutosenseValid`An automatic `REQUEST SENSE` was performed after this I/O because of a `CHECK CONDITION` status message from the device. The data contained in the scsiSensePtr buffer is valid.
	`scsiBusNotFree`The SCSI Manager was unable to clear the bus after an error. You may need to call the `SCSIResetBus` function to restore operation.

	`scsiNoParityCheck`Disable parity error detection for this transaction.
	`scsiDisableSelectWAtn`Do not send the `IDENTIFY` message for LUN selection. The LUN is still required in the `scsiDevice` field so that the request can be placed in the proper queue. The LUN field in the CDB is untouched. The purpose is to provide compatibility with older devices that do not support this aspect of the SCSI-2 specification.
	`scsiSavePtrOnDisconnect`Perform a `SAVE DATA POINTER` operation automatically in response to a `DISCONNECT` message from the target. The purpose of this flag is to provide compatibility with devices that do not properly implement this aspect of the SCSI-2 specification.
	`scsiNoBucketIn`Prohibit bit-bucketing during the data-in phase of the transaction. Bit-bucketing is the practice of throwing away excess data bytes when a target tries to supply more data than the initiator expects. For example, if the CDB requests more data than you specified in the `scsiDataLength` field, the SCSI Manager normally throws away the excess and returns the `scsiDataRunError` result code. If this flag is set, the SCSI Manager refuses any extra data, terminates the I/O request, and leaves the bus in `the data-in` phase. You must reset the bus to restore operation. This flag is intended only for debugging purposes.
	`scsiNoBucketOut`Prohibit bit-bucketing during the data-out phase of the transaction. If a target requests more data than you specified in the `scsiDataLength` field, the SCSI Manager normally sends an arbitrary number of meaningless bytes (0xEE) until the target releases the bus. If this flag is set, the SCSI Manager terminates the I/O request when the last byte is sent and leaves the bus in `the data-out` phase. You must reset the bus to restore operation. This flag is intended only for debugging purposes.
	`scsiDisableWide`Disable wide data transfer negotiation for this transaction if it had been previously enabled. This option may not be supported by all SIMs.
	`scsiInitiateWide`Attempt wide data transfer negotiation for this transaction if it is not already enabled. This option may not be supported by all SIMs.
	`scsiRenegotiateSense`Attempt to renegotiate synchronous or wide transfers before issuing a `REQUEST SENSE`. This is necessary when the error was caused by problems operating in synchronous or wide transfer mode. It is optional because some devices flush sense data after performing negotiation.

	`scsiDataBuffer`The `scsiDataPtr` field contains a pointer to a contiguous data buffer, and the `scsiDataLength` field contains the length of the buffer, in bytes.
	`scsiDataSG` The `scsiDataPtr` field contains a pointer to a scatter/gather list. The `scsiDataLength` field contains the total number of bytes to be transferred, and the `scsiSGListCount` field contains the number of elements in the scatter/gather list.
	`scsiDataTIB` The `scsiDataPtr` field contains a pointer to a transfer instruction block. This is used by the XPT during original SCSI Manager emulation, when communicating with a SIM that supports this.

	`scsiTransferBlind`Use DMA, if available; otherwise, perform a blind transfer using the handshaking information contained in the `scsiHandshake` field.
	`scsiTransferPolled`Use polled transfer mode. The `scsiHandshake` field is not required for this mode.