Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.


Adopted By: IOSCSIController class
Declared In: driverkit/scsiTypes.h

Protocol Description

Indirect device drivers for devices attached to SCSI controllers use the methods in this protocol to communicate with IOSCSIController.

Method Types

Allocating well-aligned buffers allocateBufferOfLength:actualStart:actualLength:
Requesting I/O executeRequest:buffer:client:
Reserving SCSI targets reserveTarget:lun:forOwner:
Resetting the SCSI bus resetSCSIBus
Getting the IOReturn equivalent of a sc_status_t value

Instance Methods

(void *)allocateBufferOfLength:(unsigned)length
actualStart:(void **)actualStart
actualLength:(unsigned *)actualLength

Allocates and returns a pointer to some well-aligned memory. Well-aligned memory is necessary for calls to executeRequest:buffer:client:. You should use actualStart and actualLength when freeing the memory, as follows (italicized text delineated in angle brackets, that is << >>, is to be filled in with device-specific code):

dataBuffer = [_controller allocateBufferOfLength:block_size
actualStart:&freePtr, actualLength:&freeLength];
<< Use the buffer... >>
IOFree(freePtr, freeLength);

Here's a typical use of this method:

IODMAAlignment    dmaAlign;
unsigned int      alignment, alignedLength, freeLength;
void             *alignedPtr = NULL;
unsigned int      maxLength; /* Max length of the current transfer */
/* . . . */
[_controller getDMAAlignment:&dmaAlign];
if(<< we're doing a write >>)
alignment = dmaAlign.writeLength;
alignment = dmaAlign.readLength;

if(alignment > 1)
alignedLength = IOAlign(unsigned int, maxLength, alignment);
alignedLength = maxLength;

alignedPtr = [_controller allocateBufferOfLength:alignedLength

<< If we're going to do a write, copy the data to alignedPtr.
Set up the request and submit it, as described in the
executeRequest:buffer:client: description. >>
<< Do any post-I/O processing that's necessary. >>

IOFree(freePtr, freeLength);

See also:  getDMAAlignment:

(sc_status_t)executeRequest:(IOSCSIRequest *)scsiRequest
buffer:(void *)buffer

Executes the specified request. Indirect devices invoke this method whenever they need the IOSCSIController to perform I/O.

Subclasses of IOSCSIController must implement this method. A typical implementation of this method consists of the following:

Using IOScheduleFunc() to schedule a timeout function to be called after scsiRequest->timeoutLength time has elapsed without I/O completion
Sending the command descriptor block (CDB) specified in scsiRequest to the controller
When the I/O has completed, unscheduling the timeout function

This method should return scsiRequest->driverStatus, which should be set by the part of the driver that detected I/O completion or timeout.

Indirect devices use this method as shown below (italicized text delineated in angle brackets, that is << >>, is to be filled in with device-specific code):

void             *alignedPtr = NULL;
unsigned int      alignedLength;
IOSCSIRequest     request;
cdb_t             cdb;

/* . . . */
if (<< we're going to be doing DMA >>) {
<< Ensure we have a well-aligned buffer that starts at alignedPtr
and continues for alignedLength bytes.  See the
allocateBuffer: description for one way of doing this. >>
} else {
alignedLength = 0;
alignedPtr = 0;

bzero(&request, sizeof(request)); = [self target];
request.lun    = [self lun]; = << YES if this is a read; NO otherwise >>;
request.maxTransfer = alignedLength;
request.timeoutLength = << some timeout length, in seconds >>;
request.disconnect = << 1 if allowed to disconnect; otherwise 0 >>;
request.cdb = cdb;
<< Set up the cdb (command descriptor block) field. The type of this
field, cdb_t, is defined and described in the header file
bsd/dev/scsireg.h. >>

rtn = [_controller executeRequest:&request

(void)getDMAAlignment:(IODMAAlignment *)alignment

Returns the DMA alignment requirements for the current architecture. IOSCSIController subclasses can override this method to specify any device-specific alignment requirements. See the description of allocateBufferOfLength:actualStart:actualLength: for an example of using this method.

See also:  allocateBufferOfLength:actualStart:actualLength:


Returns the maximum number of bytes per DMA transfer. This is the maximum transfer that can be requested in a call to executeRequest:buffer:client:.

(void)releaseTarget:(unsigned char)target
lun:(unsigned char)lun

Releases the specified target/lun pair. If owner hasn't reserved the pair, this method uses IOLog to print an error message.

See also:  reserveTarget:lun:forOwner:

(int)reserveTarget:(unsigned char)target
lun:(unsigned char)lun

Reserves the specified target/lun pair, if it isn't already reserved. This method is invoked by a client (for example, a SCSIDisk instance) to mark a particular target/lun as being in use by that client. Usually, this happens at probe: time; however, the SCSIGeneric driver uses this method at other times.

This method returns a nonzero value if the target/lun pair is already reserved. Otherwise, it returns zero.

See also:  releaseTarget:lun:forOwner:


Resets the SCSI bus. Subclasses of IOSCSIController must implement this method so that it resets the SCSI bus. The sc_status_t enumerated type is defined and described in the header file bsd/dev/scsireg.h.


Returns the IOReturn value corresponding to the specified sc_status_t value. The sc_status_t enumerated type is defined and described in the header file bsd/dev/scsireg.h.