CHAPTER 9
`
`SCSI Manager 4.3
`
`SCSIGet calls are handled entirely within the XPT; the XPT simply notes that the call
`was made by setting an internal flag and returning back to the caller. SCS I Select calls
`cause the XPT to generate a SCSI_ExeCIO parameter block and submit it to the SIM via
`the S IMaction entry point. This parameter block is filled in with an s cFunctionCode
`field of SCS I_OldCal 1 and an scDevice Ident field containing the bus number of this
`SIM, the target ID requested in the SCS I Select call, and a LUN of 0. This parameter
`block should be queued with all other scs I_I3xecIO_PBs.
`
`The SIM should attempt a select of the specified device and return the result of that
`select back to the XPT (scsiReqComplete if successful and scs iSelTimeout if not).
`Old call results are not communicated through the scResult field, as this would be
`interpreted as completion of the entire transaction rather than only the portion of the
`transaction resulting from the single old call. Instead, the SIM should place the result in
`the oldCallResult field. As additional old calls are made, the XPT fills in the
`
`appropriate fields of the SCS I_ExecIO_PB and calls the SIM’s NewOldCall entry
`point. Table 9-2 shows the old call parameters and the fields that are filled in by the XPT.
`
`Table 9-2
`
`Call
`
`SCSIGet
`
`SCSISelect/
`SCSISelAtn
`
`SCSICmd
`
`SCSI<data>
`
`SCSIComplete
`
`SCSIMsgIn
`
`SCSIMsgOut
`
`SCSIReset
`
`SCSIStat
`
`Old call parameter conversion
`
`Parameter
`
`Dir
`
`ExeclO field
`
`Notes
`
`targetID
`
`*buffer
`
`count
`
`*tibPtr
`
`*stat
`
`*message
`wait
`
`*message
`
`message
`
`¢TlTTiil
`
`scDeviceIdent
`
`scCDB
`
`scCDBLen
`
`scDataPtr
`
`XPT only
`
`bus ID = this SIM,
`LUN = O
`
`Pointer in field
`
`Pointer in field
`
`scSCSIstatus
`
`Status in field
`
`scSCSImessage
`
`Message in field
`
`scConnTimer
`
`TimeMgr format
`
`scSCSImessage
`
`Message in field
`
`scSCSImessage
`
`Message in field
`
`SCSI_ResetBus_PB
`
`XPT only
`
`To provide the highest level of compatibility with the old SCSI Manager, every SIM
`should be able to perform a SCSI arbitration and selection process independently
`of a SCSI message—out or command phase, in order to register itself as being capable
`of handling old SCSI calls. If it must have the CDB or message—out bytes in order
`to perform the selection operation, then it will be unable to adequately execute
`the SCS I Select call. Without this ability, the SIM must always return noErr to a
`
`Guidelines for SIM/HBA Developers
`
`379
`
`Page 401 of 500
`
`PUMA EXHIBIT 2005
`
`PART 9 OF 10
`
`Page 401 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`S C S I Se 1 e ct (S C S I_O1 dCa 1 1 function), a result that produces a false indication of the
`presence of a device at that ID. This would cause all future SCS I Selects to that ID to
`be directed to only this bus. The result would be that no devices installed on buses that
`registered after this bus would be accessible through the old API.
`
`Interrupt Support
`
`Each SIM passes the address of its interrupt service routine and an interrupt source
`identifier (ISR) to the XPT during the SOS IRegisterBus routine. The XPT installs an
`ISR at the specified source so that when that interrupt happens, it can make the call
`to the SIM_I SR routine, passing the address of the SIM’s static data space. The XPT
`performs some VM-required operations before and after the call to the S IM_I SR when
`VM is turned on.
`
`The same S IM_I SR entry point is used by the XPT to get the SIM to check for the
`presence of an interrupt. Checking for an interrupt is required during Various situations
`where interrupts are disabled but SCSI operations may still be in operation. Hence the
`S IM_I SR must be written to verify that the interrupt is in fact present before attempting
`to handle it. If an interrupt is handled during the routine, the SIM should return a
`nonzero result to the XPT.
`
`Handshaking of Data Bytes
`
`The old SCSI Manager provided TIBs to perform two functions: designation of data
`buffers (scatter/ gather) and designation of handshaking requirements for a transfer. The
`latter function refers to the handshaking between the processor and the SCSI controller
`chip. This was originally required during Macintosh Plus blind transfers because there
`was no hardware handshaking that prevented the processor from overflowing or
`underflowing the 5380 chip.
`
`In Apple platforms after the Macintosh Plus, the handshaking information was used to
`prevent bus errors when the target failed to deliver the next byte within a processor bus
`error timeout or when the SCSI Manager attempted to read it from the SCSI interface
`chip. This timeout is 250 ms for the Macintosh SE and 16 us for the Macintosh II and all
`Macintosh models since. The SCSI Manager blindly read (or wrote) data bytes until it
`reached the end of an sclnc or scNoInc pseudoinstruction. When the next scInc or
`scNoInc was encountered, the SCSI Manager first explicitly polled the SCSI chip to
`make sure that it was ready with data (for a read) or ready to accept data (for a write). In
`this way, TIBs were used to make the SCSI Manager synchronize with the target at times
`in the transfer when the target was slow in accepting bytes.
`
`The new SCSI Manager still requires this handshaking information for non-DMA SCSI
`transfers such as those used on all earlier models. There is no possibility of bus errors
`with the Macintosh Quadra 84OAV or Macintosh Centris 660AV, because the DMA
`
`hardware does not attempt to transfer data until the SCSI controller indicates that it
`is ready.
`
`Guidelines for SIM/HBA Developers
`
`Page 402 of 500
`
`Page 402 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`Handshaking is handled similarly for third-party HBAS. With DMA there is no need for
`the explicit handshaking. With non—DMA transfers, however, a SIM must pay attention
`to the handshaking description that is part of the sCSI_ExecIO_PB. The form of the
`descriptor is much simpler than TIBs and explicitly specifies which bytes in which to
`expect delays from the target. In an environment Where bus errors may occur if the
`handshaking description is inaccurate, the SIM should provide a bus error handler that
`can recover, retry, and pick up the transfer where it was interrupted. Because bus-error
`exception processing differs among the members of the 68000 processor family, several
`handlers are required, some of which are not trivial. In addition, it is impossible to
`predict what will happen in later 68000 processors with different exception handling that
`might force rewriting and redistribution of any SIMs with bus error handlers.
`
`DMA Support
`
`For HBAs with DMA support, the direct memory access process typically requires that
`the data buffer affected by the transfer be locked down (so that the physical addresses
`won't change) and that it be noncacheable. Locking data buffers was previously difficult
`to manage because of severe restrictions on when LockMemory could be called.
`
`LockMemory is now allowed at interrupt time but only if the affected pages are already
`held. GetPhys ical is also allowed at interrupt time and continues to have its
`previously restriction of only working with pages that are locked.
`
`SCSI Manager 4.3 Reference
`
`Many SCSI bus—related functions are available to the client. All of them are accessed by
`calling a single entry point (SCS IAction) with a SCSI parameter block (SCS I_PB) and
`are designated by the function code element of the SCS I_PB header. The structure of the
`SCSI_PB body (past the header) varies depending upon the function requested.
`
`The parameter block consists of function types, parameter structures, action flags and
`status flags necessary to perform most SCSI requests. SCSI I/ 0 requests are performed
`by allocating a SCSI parameter block and filling in the necessary fields to describe and
`specify the necessary actions the SCSI Manager needs to perform the requested function.
`The status of both the I / 0 request and actual SCSI bus transaction are returned through
`the parameter block. These functions may be specified to complete either synchronously
`or asynchronously with respect to the calling client.
`
`By far the most important and commonly used request passed to SCS IAction is to
`execute a SCSI I/ 0 request. It is this request that actually performs the SCSI transaction
`between the computer and the target. All of the parameters required by the SCSI
`Manager to accomplish a complete transaction are contained in the SCS I_ExecIO_PB
`parameter block that is passed to SCS IAct i on.
`
`Besides routines driven by SCSI_PB, the XPT provides several others as well. These
`routines fall into two categories: routines of interest to a driver-type client and routines
`of interest to an operating system module (such as a SIM).
`
`SCSI Manager 4.3 Reference
`
`Page 403 of 500
`
`Page 403 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`Note that in the remainder of this chapter, certain data types have the following
`definitions:
`
`#define ushort
`uchar
`
`#define
`
`#define
`
`ulong
`
`unsigned short
`
`unsigned char
`
`unsigned long
`
`typedef
`{
`
`uchar
`
`uchar
`
`uchar
`
`uchar
`
`struct DeviceIdent
`
`diReserved;
`
`bus;
`
`targetID;
`LUN;
`
`unused
`
`SCSI — Bus #
`
`SCSI — Target SCSI
`SCSI - LUN
`
`ID
`
`} Deviceldent;
`
`Data Structure
`
`This section describes the general parameter block data structure that provides
`information and control in SCSI Manager 4.3. There are many different parameter blocks
`all using the same template, SCS I_PB. Specific parameter blocks are discussed with the
`routines that use them. This section describes the parameter block header and the
`construction of the SCS I_PB parameter block.
`
`SCSI Manager Parameter Block
`
`Each client of the SCSI Manager allocates a SCS I_PB parameter block and fills in the
`required fields before passing it to the SCS IAction function. A function-specific
`SCS I_PB consists of two parts: the SCSI_PB header (SCSIHdr), that part common to all
`types of SCS I_PB s, and the SCS I_PB body, containing SCSI parameters specific to the
`function's SCS I_PB (the size and fields of which vary depending on the function).
`
`The common parameter block header definition is the following:
`
`#define SCSIPBHdr \
`
`struct SCSIHdr *qLink;
`
`//
`
`//
`
`//
`
`//
`
`//
`
`//
`
`//
`
`(internal) Q link to next PB
`
`(unused) Q type
`version of the PB
`
`length of the entire PB
`function selector
`
`returned result
`
`(bus + target + LUN)
`
`callback on completion function
`
`flags for operation
`
`short
`ushort
`
`ushort
`
`FunctionType
`OSErr
`
`DeviceIdent
`
`CallbackProc
`
`qType;
`scVer;
`
`scPBLen;
`
`scFunctionCode;//
`scResult;
`
`//
`
`scDeviceIdent;
`
`scCompFn;
`
`scFlags;
`ulong
`// end of SCSIPBHdr
`
`SCSI Manager 4.3 Reference
`
`Page 404 of 500
`
`Page 404 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`Note
`
`Several fields in the parameter block are operating system dependent. In
`this document the direction shown by arrows is with respect to the SCSI
`Manager—for example, in SCS I PBHdr. This is opposite to the
`convention followed by ANSI X3T9, the Common Access Method
`document, as explained in ”CAM Deviations,” earlier in this chapter. 6
`
`The SCSI parameter block header structure uses SCS I PBHdr, as follows:
`
`typedef struct SCSIHdr
`{
`
`SCSIPBHdr
`
`} SCSIHdr;
`
`*qLink
`
`qT ype
`
`scver
`
`Reserved for Apple use only. A pointer to the next parameter block in the
`SCSI queue.
`
`Reserved for Apple use only. The queue type.
`
`Version of the parameter block. Used by SCSI Manager to determine the
`format of this parameter block.
`
`The length in bytes of the PB, including the PB header.
`scPBlen
`scFunctionCode
`
`A function selector that specifies the service being requested by the SCSI
`device driver. See also ”SCSIAction,” later in this chapter.
`scDeviceIdent
`
`scResult
`
`A function selector that specifies the device that the request is directed
`towards. This field is of type Devi celdent, defined above.
`
`A value returned by the SCSI Manager after the function is completed. A
`scsiReqInProg status indicates that the request is still in progress or
`queued.
`Valid s cRe s u l t return values are:
`
`n oE r 1:
`
`Request completed without error
`
`scsiReqInProg
`
`Request in progress
`
`s c s i Re qAbo r t e d
`
`Request aborted by the host
`
`scsiUr1ableToAbort
`
`Unable to abort request
`
`s c s i Re qCmp 1 WE r r
`
`Request completed with an error
`
`s c s iBu s y
`
`SCSI subsystem busy
`
`scsiReqInval id
`
`Request invalid
`
`scsiBus Inval id
`
`Bus ID supplied invalid
`
`s c s i DevNo t T he re
`
`SCSI device not installed / there
`
`s c s iUnabl eTe rmI 0
`
`Unable to terminate I/ 0 request
`
`s c s i S e l T ime o u t
`s c s i CmdT ime o u t
`
`Target selection timeout
`Command timeout
`
`s cs iMsgRej ectRcvd
`
`Message reject received
`
`SCSI Manager 4.3 Reference
`
`Page 405 of 500
`
`Page 405 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`scsiSCSIBusReset
`
`SCSI bus reset sent/ received
`
`scsiUncorParity
`scsiAutosenseFail
`
`scsiNoHBA
`
`scsiDataRunErr
`
`scsiUnexpBusFree
`
`scsiSequenceFail
`scsiPBLenErr
`
`scsiProvideFail
`
`scsiBDRsent
`
`scsiReqTermIO
`scsiLUNInvalid
`
`scsiTIDInValid
`
`scsiFuncNotAvail
`
`scsiNoNexus
`
`Uncorrectable parity error occurred
`
`Autosense: request sense command fail
`No HBA detected
`
`Data overrun/underrun
`
`Unexpected bus free
`
`Target bus phase sequence failure
`
`Parameter block length supplied is
`inadequate
`
`Unable to provide requested capability
`
`A SCSI BDR bus request message was sent
`to the target
`
`Request terminated by the host
`
`LUN supplied is invalid
`
`Target ID supplied is invalid
`
`The requested function is not available
`Nexus not established
`
`scsiIIDInvalid
`
`Initiator ID invalid
`
`scsiCDBRcvd
`
`The SCSI CDB has been received
`
`scsiSCSIBusy
`
`scsiSIMQFrozen
`
`scsiAutosenseValid
`
`SCSI bus busy
`
`The SIM queue frozen with this error
`
`Autosense data Valid for target
`
`scDeviceIdent
`
`A longword that uniquely identifies a device that this request is directed
`toward. The Devi celdent designates a bus ID, target SCSI ID, and
`LUN. A routine is provided to decode a Devi celdent value into these
`components if required, but the objective is to eliminate the physical
`addressing characteristics of the transport layer (SCSI bus) from the API.
`
`A pointer to the callback completion function.
`
`A longword that contains the bit settings to indicate special handling of
`the requested function. The number and meaning of the flags vary by
`function code and are described in function-specific areas:
`
`scCompFn
`
`scFlags
`
`Flag descriptions
`scsiDirMask
`
`Bit field used to specify direction of transfer. Values can be
`scsiDirIn
`scsiDirOut
`scsiDirNone
`
`Data direction in
`Data direction out
`No data movement
`
`SCSI Manager 4.3 Reference
`
`Page 406 of 500
`
`Page 406 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`scsiDisAutosense
`Disable autosense feature
`
`scsiscattervalid
`
`Scatter / gather list is Valid. If this flag is clear, the Values in
`the scData and scDataLen fields are the starting address
`and length of a block of data. If this flag is set, the scData
`field is a pointer to an S / G list. Each element of the S/ G
`list is itself a description of a block of data. In addition,
`when set, the scSGlistCnt field contains the number
`of S/ G entries, and the scDataLen field contains the total
`number of bytes in the data transfer. This last field is
`required for easy calculation of the scDataRes idLen
`value.
`
`scsiCDBLinked
`
`The PB contains a linked CDB. This bit/ function is not
`
`supported in the built—in SIM.
`
`scsiQEnable
`
`SIM queue actions are enabled. This bit/ function is not
`supported in the built-in SIM.
`scsiCDBIsPointer
`
`The CDB field contains a pointer. If clear, the scCDB field
`contains the actual CDB. If set, the scCDB field contains a
`pointer to the CDB. In either case, the scCDBLen field
`contains the number of bytes in the command.
`scsiDisDisconnect
`
`Disable disconnect. This flag, when set, prevents the SIM
`from setting the Di scPriv bit in the identify message
`used for this I/O. If clear (default), DiscPriv is set,
`allowing the target to disconnect.
`
`scsilnitiatesync
`
`Attempt sync data xfer, and SDTR
`
`scsiDisSync
`
`Disable sync; go to async
`
`scsiSIMQHead
`
`Place parameter block at the head of SIM queue
`
`scsiSIMQFreeze
`
`Return the SIM queue to frozen state
`
`scsiSIMQNoFreeze
`
`Disallow SIM queue freezing
`
`scsiCDBPhys
`
`CDB pointer is physical
`
`scsiDataPhys
`SG/ buffer data pointers are physical
`
`SCSI Manager 4.3 Reference
`
`Page 407 of 500
`
`Page 407 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`scsiSenseBufPhys
`
`Autosense data pointer is physical
`
`scsiMsgBufPhys
`
`Message buffer pointer is physical
`
`scsiNxtPBPhys
`
`Next parameter block pointer is physical
`
`scsiCallBackPhys
`Callback function pointer is physical
`
`scsiPhysMask
`At least one pointer is physical
`scsiDataBufValid
`Data buffer valid
`
`scsiStatusBufValid
`Status buffer valid
`
`scsiMsgBufValid
`
`Message buffer valid
`
`scsiTgtPhaseMode
`
`The SIM will run in phase mode
`
`scsiTgtPBAvail
`
`Target parameter block available
`scsiDisAutoDisc
`
`Disable autodisconnect
`
`scsiDisAutsaveRest
`
`Disable autosave / restore pointers
`
`Routines
`
`This section describes the routines used to control and inquire from the different layers
`of the SCSI Manager hierarchy, as shown in Figure 8-1 (page 366). The order of
`discussion is:
`
`1. Driver routines
`
`2. SCSI Interface Modules calls to the transport layer
`
`3. Transport layer calls to SCSI Interface Modules
`
`Driver Routines
`
`Driver routines are used by the client to control and inquire from the transport layer. For
`most operations using the SCSI Manager, these are the only routines that are needed.
`
`SCSI Manager 4.3 Reference
`
`Page 408 of 500
`
`Page 408 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`SCSIAction
`
`The SCS IAction routine executes the request specified in the SCS I_PB parameter
`block. Certain types of requests are handled by the XPT (such as those dealing with the
`SCSI device table), but most are handled by the SIM/ HBA. The SCS I_PB header
`contains a function code specifying the requested operation. The codes are described
`later in this section, along with the parameter blocks that correspond to those functions.
`
`void SCSIAction (SCSI_PB *)
`
`Operation
`
`Drivers make all of their SCSI I / O requests using this function. It is designed to take
`advantage of all features of SCSI that could be provided by virtually any HBA/ SIM
`combination. The parameter SCSI_PB block contains all of the parameters that the XPT
`and SIM need to completely transact the I/ 0 request.
`
`The SCS IAction function typically returns with a status of 0 indicating that the request
`was queued successfully. Function completion can be determined by polling for nonzero
`status or through the use of the callback on completion field. When the completion
`routine is called, it has the same static variable pointer (A5) that existed when the
`Execute SCSI I/ 0 request was received. If A5 was invalid when the I/ 0 request was
`made, it is also invalid when in the callback.
`
`The callback routine should follow this format:
`
`void CompFn (SCSI_ExecIO_PB *
`
`thePB);
`
`When issued asynchronously, execute SCSI I/ 0 requests are performed as such; in other
`words, the resulting action may start anytime and may end at any time. There is no
`implied ordering of these events with respect to earlier or later requests. An earlier
`request may be started later and a later request may complete earlier. However, a series
`of requests to the same device (bus ID + target ID + LUN) is issued to that device in the
`order received.
`
`SCSlAction Function Codes
`
`SCSIAction function codes are used by SCSI Manager clients to specify requests.
`Table 9-3 lists the hexadecimal function codes that SCSI Manager 4.3 supports on its
`initial release.
`
`In Table 9-3, note that codes $00 through $0F cover common functions; codes $10
`through $1F cover SCSI control functions; and codes above $7F are reserved by Apple.
`
`SCSI Manager 4.3 Reference
`
`Page 409 of 500
`
`Page 409 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`Table 9-3
`
`SCSI Manager 4.3 function codes
`
`Code
`
`Function
`
`Operation (CAM names)
`
`Supported
`
`$00
`
`$01
`
`$02
`
`$03
`
`$04
`
`SCS I_Nop
`
`SCSI_ExecIO
`
`(reserved)
`
`NOP (No Operation)
`
`Execute SCSI 1/0
`
`Get Device Type
`
`\/
`
`«I
`
`SCSI_BusInquiry
`
`Pmh(Bu®Inqufiy
`
`SC S I_Re l ea s eQ
`
`Release SIM Queue
`
`$05—$0F
`
`(reserved)
`
`Set Async callback
`
`$10
`
`$11
`
`$12
`
`$13
`
`SCSI_AbortCommand
`
`AbortSCSIconunand
`
`SCSI_ResetBus
`
`RamtSCSIbus
`
`SCSI_ResetDevice
`
`Re&fiSCSIdevke
`
`SCSI_TerminateIO
`
`Terminate I / 0 process
`
`$14—$7F
`
`(reserved)
`
`$80
`
`SCSI_GetVirtualIDInfo
`
`GetDeviceIDofvfihmlH
`
`* Not recommended; see warning on page 392.
`
`SCSI_ExecIO
`
`The most commonly executed request of the SCSI Manager is to perform an I / 0
`command, as defined by the SCS I_PB parameter block with a selector code of
`SCS I_I3xecIO. The resulting data structure is the following:
`
`typedef struct SCSI_ExecIO_PB
`{
`
`SCSIPBHdr
`
`// header information fields
`
`uchar
`
`*scDrvrStorage;// <> ptr used by the driver
`
`struct SCSI_IO *scCmdLink;
`ulong
`scAppleRsvdO;
`
`// —> ptr to the next linked cmd
`//
`reserved
`
`uchar
`
`*scDataPtr;
`
`scDataLen;
`
`//
`//
`
`//
`
`ptr to data buffer
`or S/G list
`
`data transfer length
`
`*scSenseBufPtr;//
`scSenseBufLen; //
`
`ptr to autosense buffer
`size of autosense buffer
`
`scCDBLen;
`scSGlistCnt;
`
`//
`//
`
`number of bytes for the CDB
`number of S/G list entries
`
`scAppleRsvdl;
`scSCSIstatus;
`
`reserved
`//
`// <— returned SCSI device status
`
`scSenseResidLen;// <—autosense residual length
`
`ulong
`
`uchar
`uchar
`
`uchar
`ushort
`
`ulong
`uchar
`
`char
`
`SCSI Manager 4.3 Reference
`
`Page 410 of 500
`
`Page 410 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`ushort
`
`long
`CDB
`
`long
`
`uchar
`
`ushort
`
`ushort
`
`uchar
`uchar
`
`ushort
`
`scAppleRsvd2;
`scDataResidLen;//
`scCDB;
`
`//
`
`//
`
`scTimeout;
`
`*scMsgPtr;
`
`scMsgLen;
`
`scVUFlags;
`
`scTagAction;
`
`scAppleRsvd3;
`
`scAppleRsvd4;
`
`//
`
`//
`
`//
`
`//
`
`//
`
`//
`
`//
`
`//
`
`// Apple-specific public fields
`uchar
`*scSGBase;
`//
`ushort
`
`scSelTimeout;
`
`//
`
`reserved
`
`transfer residual length
`
`actual CDB or ptr to CDB
`timeout value (Time
`
`Manager format)
`
`pointer to message buffer
`
`num bytes in msg buffer
`
`vendor
`
`(Apple) unique flags
`
`what to do for tag queuing
`reserved
`
`reserved
`
`base data for S/G entries
`select timeout Value
`
`ushort
`DataXferProc
`DataXferProc
`
`scXferType;
`scDIxfer;
`
`scDOxfer;
`
`//
`//
`
`//
`
`transfer type
`data in function
`data out function
`
`ushort
`
`ulong
`
`long
`uchar
`
`uchar
`
`scHandshake[8];//
`
`handshaking structure
`
`//
`scAppleRsvd5;
`scConnTimeout; //
`
`reserved
`
`connection timeout value
`
`scSIMpublics[8];//
`
`for use by 3rd—party SIMS
`
`publicExtras[4];//
`
`for a total of 48 bytes
`
`// XPT layer privates (for old API emulation)
`Ptr
`savedA5;
`// the A5 of the client
`
`ushort
`short
`
`ushort
`
`uchar
`
`uchar
`
`uchar
`
`scCurren:Phase;// <— phase upon compieting o'd ca"
`selector;
`//
`
`—> selector specified in o d ca
`I/O status of old call
`
`oldCallS:atus; //
`
`scSCSImessage; //
`
`<— Returned SCSI device message
`
`XPTprivFlags;
`
`// <> various flags
`
`XP7eXtraS[4];
`
`// for a total of 16 bytes
`
`} SCSI_ExecIO_PB;
`
`Field descriptions
`
`SCSIPBHdr
`
`*scDrvrStorage
`*scCmdLink
`
`scAppleRsvdO
`*scDataPtr
`
`scDataLen
`*scSenseBufPtr
`
`Shorthand for the SCSI Manager parameter block structure. See
`”SCSI Manager Parameter Block,” earlier in this chapter, for details.
`
`A pointer used by the peripheral driver to access the SCS IHdr .
`
`A pointer to the next linked command.
`Reserved.
`
`A pointer to the data buffer or the S / G list.
`
`Length of data buffer to be transferred.
`
`A pointer to the autosense data buffer. Used to get information
`about the autosense status.
`
`scSenseBuf Len
`
`Size of the autosense data buffer.
`
`SCSI Manager 4.3 Reference
`
`Page 411 of 500
`
`Page 411 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`scCDBLen
`
`scSGlistCnt
`
`scAppleRsvdl
`scSCSIstatus
`
`Length of the CDB in bytes.
`
`Reserved. Number of entries in the S / G list. Used only by the
`operating system.
`Reserved.
`
`A byte that returns the SCSI device status. Contains the status of the
`specified SCSI device.
`
`s c S e n s e Re s i dLe n Autosense residual length.
`Reserved.
`scAppleRsvd2
`scDataResidLen
`
`Data transfer residual length.
`
`scCDB
`
`scTimeout
`
`*scMsgPtr
`
`scMsgLen
`
`scVUFlags
`
`Actual or a pointer to the CDB.
`
`Length of time specified before timeout of the SCSI bus.
`
`A pointer to the message buffer.
`
`Number of bytes in the message buffer.
`
`Apple-specific flags. These flags define the Apple-specific
`operations supported by SCSI Manager 4.3.
`Flag Descriptions
`
`scsiNoParityCk
`
`Disables the checking of parity on incoming data. Parity
`continues to be generated for outgoing data.
`scsiDisSelAtn
`
`Disables the sending of the Identify message for LUN
`selection. The Device Ident still specifies the LUN so
`that the request gets placed in the proper queue. As
`always, the LUN field in the CDB is untouched. The
`purpose is to provide compatibility with pre-SCSI-2
`devices that did not support the inquiry+LUN concept as
`described in the SCSI-2 documentation.
`
`scsiSavePtrOnDisc
`
`If this flag is set, the SCSI Manager automatically does
`a Save Data Pointer operation when it receives a
`Disconnect message from the target. If this flag were
`clear, operation would be as specified in SCSI-2; in
`particular, there is no implied Save Data Pointer when
`a Disconnect message is received, and if a disconnect
`actually did occur, the data pointer would revert to the
`value last saved. The purpose of this bit is to provide
`compatibility with devices whose designers did not
`understand the function of the Save Data Pointer and
`
`Disconnect messages.
`scsiNoBucketIn
`
`SCSI Manager 4.3 Reference
`
`Page 412 of 500
`
`Page 412 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`When set, no bit-bucketing on data-in is performed for
`this transaction. Bit-bucketing normally occurs when
`the device (target) wants to supply more data than the
`computer (initiator) is expecting. This can happen if
`the SCS I_Exec_IO parameter block has inconsistent
`parameters—with the CDB indicating a request for more
`data than the S/ G list provides. If this bit is set and the
`extra data condition occurs, the SCSI Manager request
`
`terminates and the bus is left in data_in phase. A
`S C S I_Re s e tBu s request must be issued to clear the bus.
`Due to the impact of a SCSI Reset, this bit should only be
`set for debugging.
`scsiNoBucketOut
`
`When set, no bit-bucketing on data-out is performed for
`this transaction. This is the inverse of bit-bucketing
`described above and normally occurs when the target is
`asking for more data than was supplied in the I / 0
`request. Again, this bit should only be used for
`debugging purposes.
`
`Execsync
`
`This flag causes I / O to be executed synchronously (it
`returns from a SCS IAction call only when complete).
`
`scTagAction
`
`scAppleRsvd3
`
`scAppleRsvd4
`
`Specifies what action is taken for tag queuing.
`
`Reserved. SCSI Manager private data area.
`
`Reserved. SCSI Manager private data area.
`
`Apple-specific fields
`*scSGBLase
`
`scSelTimeout
`
`scXferType
`
`*scDIxfer
`
`*scDOxfer
`
`A pointer to the base data in an S/ G entry.
`A field that allows the client to set an alternate select timeout value.
`
`The timeout is specified in milliseconds but there is no guaranteed
`accuracy because different HBAs have different capabilities,
`including only being able to handle the standard 250 ms. A value of
`0 designates this default time length.
`
`An option that selects which type of transfer to use during the data
`phase. This roughly corresponds to blind versus polled. This option
`is provided for backward compatibility with a few devices. For
`nearly every device, this field should be zero, which selects the
`default, fastest, most reliable transfer routine for the selected bus.
`The number of specialized transfer types available on a particular
`HBA is available in the scXferTypes field of the Bus Inquiry
`parameter block.
`
`A pointer to a client—supplied function used by the SCSI Manager
`during the data in phase. If null, the SIM’s routine is used.
`
`A pointer to a client—supplied function used by the SCSI Manager
`during the data—out phase. If null, the SIM’s routine is used.
`
`scHandshake[8]
`
`A structure used for handshake operations.
`
`scAppleRsvd5
`
`Reserved for Apple use only.
`
`SCSI Manager 4.3 Reference
`
`Page 413 of 500
`
`Page 413 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`scConnTimeout A value used to time out SCSI operations.
`scSIMpublics[8]
`
`Basic allocation for use by third-party SIM vendors.
`
`publicExtras[4]
`
`Expanded allocation for third-party SIM vendors, providing a total
`of 48 bytes.
`
`SCSI_AbortCommand
`
`The SCSI_AbortCommand function asks that a SCSI Manager request be canceled by
`identifying the parameter block associated with the request. It should be issued on any
`I/ 0 request (not completed) that the driver wishes to cancel. Success of the Cancel
`function is never assured. This request does not necessarily result in an Abort message
`being issued over SCSI.
`
`// Abort SCSI Manager Request parameter block
`
`typedef struct SCSI_AbortCommand_PB
`{
`
`SCSIPBHdr
`
`// header information fields
`
`SCSIHdr
`
`*scThePB;
`
`// —> pointer to the PB to abort
`
`} SCSI_AbortCommand_PB;
`
`SCS I PBHdr
`
`Shorthand for the SCSI Manager parameter block structure. See ”SCSI
`Manager Parameter Block,” earlier in this chapter, for details.
`
`* s cThe PB
`
`A pointer to the parameter block to be canceled.
`
`SCSI_ResetBus
`
`This SCSI_ResetBus function is used to reset the specified SCSI bus.
`
`typedef struct SCSI_ResetBus_PB
`{
`
`SCSIPBHdr
`
`// header information fields
`
`} SCSI_ResetBus_PB;
`
`SCS I PBHdr
`
`Shorthand for the SCSI Manager parameter block structure. See ”SCSI
`Manager Parameter Block,” earlier in this chapter, for details.
`
`A WARNING
`
`This function should not be used in normal operation. It can be used
`only in the unlikely event that a client is unable to use the SIM/ HBA
`due to a faulty device disabling the bus. A
`
`SCSI Manager 4.3 Reference
`
`Page 414 of 500
`
`Page 414 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`SCSI_ResetDevice
`
`The SCS I_ResetDevice function is used to reset the specified SCSI target. This
`function should not be used in normal operation, but if I/ O to a particular device hangs
`up for some reason, drivers can abort the I/ O and reset the device before trying again.
`This request shall always result in a Bus Device Reset message being issued over SCSI.
`
`typedef struct SCSI_ResetDevice_PB
`{
`
`SCSIPBHdr
`
`// header information fields
`
`} SCSI_ResetDevice_PB;
`
`SCSIPBHdr
`
`Shorthand for the SCSI Manager parameter block structure. See ”SCSI
`Manager Parameter Block,” earlier in this chapter, for details.
`
`SCSI_TerminateIO
`
`The SCS I_TerminateIO function requests that a SCSI Manager I/ 0 request be
`terminated by identifying the parameter block associated with the request. This function
`should be called for any I/ 0 request that has not completed and that the driver wishes
`to terminate. Success of the termination process is never assured. This request does not
`necessarily result in a TerminateIOProces s message being issued over the SCSI bus.
`
`typedef struct SCSI_TerminateIO_PB
`{
`
`SCSIPBHdr
`
`// header information fields
`
`SCSIHdr
`
`*scThePB;
`
`// -> a pointer to the parameter block
`// to terminate
`
`} SCSI_TerminateIO_PB;
`
`SCS I PBHdr
`
`Shorthand for the SCSI Manager parameter block structure. See ”SCSI
`Manager Parameter Block,” earlier in this chapter, for details.
`
`* s cThe PB
`
`A pointer to the parameter block to be canceled.
`
`SCSI Manager 4.3 Reference
`
`Page 415 of 500
`
`Page 415 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`SCSI_GetVirtualIDInfo (Apple-specific)
`
`The S C S I_Ge tvi rtua l I D I n f o routine returns the device ID for the specified virtual
`ID. This function is typically used by a peripheral driver during the transition from
`ROM-based previous SCSI Manager to a system file-based SCSI Manager 4.3. If no
`device has yet been found on any of the o ldCal lcapable buses, the s cExi s t s
`Boolean value is FALSE and the Device Ident field should be ignored.
`
`typedef struct SCSI_GetVirtualInfo_PB
`{
`
`SCSIPBHdr
`
`// header information fields
`
`ushort
`
`scVirtualID;
`
`// —> SCSI
`
`ID of device
`
`Boolean
`
`scExists;
`
`} SCSI_GetVirtualInfo_PB;
`
`in question
`//
`// <— true if device exists
`
`scHdr
`
`scVirtualID
`
`Shorthand for the SCSI Manager parameter block structure. See ”SCSI
`Manager Parameter Block,” earlier in this chapter, for details.
`
`Identification of a device on either internal or external bus.
`
`scExists
`
`A Boolean value that returns true if the device exists on the bus.
`
`Note
`
`The DeviceIdent value is returned in the header of this parameter
`block which makes this the only function that returns a Value in the
`SCSIHdr outside of the scstatus field. 0
`
`SCSI_ReleaseQ
`
`The SCSI_ReleaseQ function releases a frozen SIM queue for the selected LUN.
`
`typedef struct SCSI_ReleaseQ_PB
`{
`
`SCSIPBHdr
`
`// header information fields
`
`} SCSI_ReleaseQ_PB;
`
`SCS I PBHdr
`
`Shorthand for the SCSI Manager parameter block structure. See ”SCSI
`Manager Parameter Block,” earlier in this chapter, for details.
`
`SCSI Manager 4.3 Reference
`
`Page 416 of 500
`
`Page 416 of 500
`
`

`
`CHAPTER 9
`
`SCSI Manager 4.3
`
`SCSI_BusInquiry
`
`TheSCSI_BusInquiryfuncfionisusedtogethfionnafiononthespedfiedI{BAb
`including the number of HBAs installed.
`
`typedef struct SCSI_BusInquiry_PB
`{
`
`SCSIPBHdr
`
`// header information fields