Writing a SCSI Interface ModuleThis section provides additional information that HBA developers need to write a SCSI interface module.
SIM Initialization and OperationWhen SCSI Manager 4.3 is present in ROM, the Start Manager loads any SIM drivers it finds in the declaration ROM of all installed expansion cards. A SIM driver may contain the actual SIM, or it may contain code to load the SIM from some other location (such as a device attached to the expansion card). The Start Manager searches for SIM drivers using the Slot Manager
SNextTypeSRsrcfunction, and loads all drivers matching the following criteria:
sResource type Constant Value
CatIntBus 12 spCType TypSIM 12 spDrvrSW DrvrSwScsi43 1
After loading a SIM driver, the Start Manager calls the driver's open routine. If the SIM is contained in the driver, it should register itself with the XPT at this time. If the registration is successful, the open routine should return
noErr. If the open routine returns an error result, the Start Manager removes the driver from the unit table and releases it from memory. A SIM loader can use this technique to remove itself after loading and registering the actual SIM. Because no other driver entry points are used, you do not need to implement the close, prime, status, or control routines, but they should return appropriate errors.
For Macintosh models that do not include SCSI Manager 4.3 in ROM, your SIM can either provide its own temporary XPT or wait until SCSI Manager 4.3 is installed by the system before registering with the XPT. If you wait for SCSI Manager 4.3 to load, devices on your bus cannot be used as the boot device or as the paging device for virtual memory but can be mounted after SCSI Manager 4.3 is running and your bus is registered.
If your SIM supplies its own XPT, your SIM and XPT must be prepared for the possibility that a system patch will install a new XPT later. To provide a consistent environment for driver clients of your SIM when the XPT is replaced, your XPT must maintain information about any virtual ID numbers it assigns (including a driver registration table) and correctly fill in the XPT fields of the bus inquiry record. When the SCSI Manager4.3 XPT loads, it uses the
SCSIBusInquiryfunctions to query your XPT, then calls the
SetTrapAddressfunction to install itself. Next, it uses your XPT to send a
SCSIRegisterWithNewXPTcommand to each registered SIM. A SIM must respond by using the
SCSIReregisterBusfunction to export its assigned bus number, entry points, and static data storage pointer to the new XPT. Finally, the SCSI Manager 4.3 XPT calls your XPT with a
SCSIKillXPTcommand. Your XPT should then release any memory it has allocated and remove or disable any patches it may have installed.
Your XPT must reserve bus number 0 for the built-in SCSI bus. For Macintosh computers with dual SCSI buses, you must reserve bus numbers 0 and 1. If the SCSI Manager 4.3 XPT is installed after your XPT, it will assign these bus numbers to the built-in buses.
After determining the presence of the XPT, a SIM should register itself using the
SCSIRegisterBusfunction. The SIM initialization record for this request contains the SIM's function entry points, required static data storage size, and the
oldCallCapablestatus of the SIM. The SIM initialization record, defined by the
SIMInitInfodata type, is shown on page 4-36. The XPT allocates the requested number of bytes for the SIM's static storage, fills in the appropriate fields of the SIM initialization record, and then calls the SIM's
SIMInitfunction. If the
noErr, the XPT completes the registration process, making the SIM available to the system. If
SIMInitreturns an error, the registration request fails.
Once the registration is complete, the XPT makes calls to the
SIMActionentry point whenever a
SCSIActionrequest is received that is destined for this bus. The XPT passes a pointer to the parameter block and a pointer to the SIM's static storage to the
SIMActionfunction. The SIM should parse the parameter block for illegal or unsupported parameters and return an error result if necessary. After queuing the request, the
SIMActionfunction should return to the XPT. When the request completes, the SIM calls the XPT's
MakeCallbackfunction with the appropriate parameter block. The XPT then calls the client's completion routine.
Other types of requests should be implemented to conform to the function descriptions provided in this chapter. Functions or features not implemented by the SIM should return appropriate errors (for example,
SIMInteruptPollfunction is called during the Device Manager's synchronous wait loop to give time to the SIM when interrupts are masked. The sole parameter is a pointer to the SIM's static data, which is passed on the stack. Because this call does not imply the presence of an interrupt, the SIM should check for interrupts before proceeding.
ExitingSIMfunctions provide compatibility with the Virtual Memory Manager and should be called every time the SIM is entered and exited, respectively. In other words, these two function calls should surround all SIM entry and exit points, including interrupt handlers and callbacks to client code made through the
Parameter blocks must appear to the client to be queued on a per-LUN basis, because queue freezing and unfreezing are performed one LUN at a time. The actual implementation may vary as long as this appearance is maintained.
Supporting the Original SCSI ManagerIf your SIM indicates that it is capable of supporting original SCSI Manager functions, the XPT adds it to the list of buses that are searched when a
SCSISelectrequest is received.
The XPT is responsible for converting original SCSI Manager functions into the proper format and submitting them to the SIM. It also receives the results for each of the functions from the SIM and returns them to the client.
When it receives a
SCSIGetrequest, the XPT simply notes that the call was made by setting an internal flag, then returns to the caller. In response to a
SCSISelectrequest, the XPT generates a
SCSIOldCallrequest and submits it to the SIM's
SIMActionentry point. The
scsiDevicefield of the parameter block contains the bus number of the SIM, the target ID specified in the
SCSISelectrequest, and a LUN of 0. This parameter block should be queued like any other.
When your SIM receives a
SCSIOldCallrequest, it should attempt to select the device and return a result code to the XPT in the
scsiOldCallResultfield of the parameter block (
scsiRequestCompleteif successful and
scsiSelectTimeoutif not). Intermediate function results are not communicated through the
scsiResultfield because this would be interpreted as completion of the entire transaction rather than only the portion of the transaction resulting from a single original function. As subsequent original function calls are made, the XPT fills in the appropriate fields of the parameter block and calls the SIM's
NewOldCallentry point. Table 4-1 shows the original function parameters and the fields that are filled in by the XPT.
Table 4-1 Original SCSI Manager parameter conversion Function Parameter Direction Parameter block field Notes SCSIGet XPT handles internally. SCSISelect targetID --> scsiDevice
busset by XPT,
Field is a pointer. SCSIRead, SCSIWrite, SCSIRBlind,
tibPtr --> scsiDataPtr Field is a pointer. SCSIComplete stat
Field contains status.
Field contains message.
Time in Time Manager format.
SCSIMsgIn message <-- scsiSCSImessage Field contains message. SCSIMsgOut message --> scsiSCSImessage Field contains message. SCSIReset
Translated to SCSIResetBus.
SCSIStat XPT handles internally.
To provide the highest level of compatibility with the original SCSI Manager, a SIM should be able to perform a SCSI arbitration and select process independently of a SCSI message-out or command phase. A SIM that requires the CDB or message-out bytes in order to perform a select operation will be unable to execute the
SCSISelectfunction properly, and must always return
SCSISelectrequest. This can create a false indication of the presence of a device at a SCSI ID, causing all future
SCSISelectrequests to that SCSI ID to be directed only to that bus. Devices installed on buses that registered after that bus would not be accessible through the original interface.
Handshaking of Blind TransfersHandshaking instructions are used to prevent bus errors when a target fails to deliver the next byte within the processor bus error timeout period. This timeout is 250 milliseconds for the Macintosh SE and 16 microseconds for all Macintosh models since the Macintosh II.
The SCSI Manager 4.3 SIM requires this handshaking information for blind transfers when DMA is not available. Your SIM does not need to pay attention to the
scsiHandshakefield unless your hardware requires it.
Supporting DMADMA typically requires that the data buffer affected by the transfer be locked (so that the physical address does not change) and that it be non-cacheable. SCSI Manager 4.3 provides an improved version of the
LockMemoryfunction, which you can call at interrupt time as long as the affected pages are already held in real memory. You can also call the
GetPhysicalfunction at interrupt time, but only on pages that are locked.
Loading DriversThe Start Manager is normally responsible for loading SCSI drivers. However, if the startup device specified in PRAM is on a third-party HBA and the SIM is a Slot Manager device, the Start Manager will call the boot record of the card's declaration ROM. The boot record code should examine the
dCtlExtDevfield to determine which SCSI device is the startup device and then load a driver from that device (and only that device).
All other drivers are loaded by the Start Manager, but SIMs are given the opportunity to override this if necessary. Before the Start Manager attempts to load a driver from a device, it calls the SIM with a
SCSILoadDriverrequest. If the function succeeds, the Start Manager does nothing further with that device. If the function fails (the normal case), the Start Manager reads the partition map on the device and loads a driver from it. If this fails, the Start Manager calls the SIM again with a
SCSILoadDriverrequest, this time with the
scsiDiskLoadFailedparameter set to indicate that no driver was available on the media.
This facility allows a SIM to provide a default driver to be used instead of any driver that may be on the device. For example, if a SIM does support the original SCSI Manager, it can use the second
SCSILoadDriverrequest to load a SCSI Manager 4.3-compatible driver if none is present on the device.
© Apple Computer, Inc.
3 JUL 1996