Important: The information in this document is obsolete and should not be used for new development.
Writing a SCSI Interface Module
This section provides additional information that HBA developers need to write a SCSI interface module.SIM Initialization and Operation
When 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 ManagerSNextTypeSRsrc
function, and loads all drivers matching the following criteria:
sResource type Constant Value spCatagory
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
SCSIGetVirtualIDInfo
,SCSILookupRefNumXref
, andSCSIBusInquiry
functions to query your XPT, then calls theSetTrapAddress
function to install itself. Next, it uses your XPT to send aSCSIRegisterWithNewXPT
command to each registered SIM. A SIM must respond by using theSCSIReregisterBus
function 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 aSCSIKillXPT
command. 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
SCSIRegisterBus
function. The SIM initialization record for this request contains the SIM's function entry points, required static data storage size, and theoldCallCapable
status of the SIM. The SIM initialization record, defined by theSIMInitInfo
data 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'sSIMInit
function. If theSIMInit
function returnsnoErr
, the XPT completes the registration process, making the SIM available to the system. IfSIMInit
returns an error, the registration request fails.Once the registration is complete, the XPT makes calls to the
SIMAction
entry point whenever aSCSIAction
request 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 theSIMAction
function. The SIM should parse the parameter block for illegal or unsupported parameters and return an error result if necessary. After queuing the request, theSIMAction
function should return to the XPT. When the request completes, the SIM calls the XPT'sMakeCallback
function 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,
scsiFunctionNotAvailable
orscsiProvideFail
).The
SIMInteruptPoll
function 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.The
EnteringSIM
andExitingSIM
functions 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 theMakeCallback
function.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 Manager
If 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 aSCSISelect
request 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
SCSIGet
request, the XPT simply notes that the call was made by setting an internal flag, then returns to the caller. In response to aSCSISelect
request, the XPT generates aSCSIOldCall
request and submits it to the SIM'sSIMAction
entry point. ThescsiDevice
field of the parameter block contains the bus number of the SIM, the target ID specified in theSCSISelect
request, and a LUN of 0. This parameter block should be queued like any other.When your SIM receives a
SCSIOldCall
request, it should attempt to select the device and return a result code to the XPT in thescsiOldCallResult
field of the parameter block (scsiRequestComplete
if successful andscsiSelectTimeout
if not). Intermediate function results are not communicated through thescsiResult
field 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'sNewOldCall
entry point. Table 4-1 shows the original function parameters and the fields that are filled in by the XPT.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
SCSISelect
function properly, and must always returnnoErr
to aSCSISelect
request. This can create a false indication of the presence of a device at a SCSI ID, causing all futureSCSISelect
requests 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 Transfers
Handshaking 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
scsiHandshake
field unless your hardware requires it.Supporting DMA
DMA 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 theLockMemory
function, which you can call at interrupt time as long as the affected pages are already held in real memory. You can also call theGetPhysical
function at interrupt time, but only on pages that are locked.Loading Drivers
The 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 thedCtlExtDev
field 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
SCSILoadDriver
request. 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 aSCSILoadDriver
request, this time with thescsiDiskLoadFailed
parameter 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
SCSILoadDriver
request to load a SCSI Manager 4.3-compatible driver if none is present on the device.
© Apple Computer, Inc.
3 JUL 1996