Functions



allocateLun

Abstract: Notifies driver of allocation of per-Lun resources.
public:

bool allocateLun( SCSITargetLun targetLun );

Your driver will be called at its allocateLun() function when a Lun is about to be probed. The your driver should initialize its per-lun data at this time. If the subclass wishes to prevent probing of this lun, it should return false as the result of this function call.

This is an optional function. Your driver is not required to implement it.

Parameters

NameDescription
targetLunSCSITargetLun structure containing the SCSI Id of the target/lun that is about to be allocated.

allocateTarget

Abstract: Notifies driver of allocation of per-Target resources.
public:

bool allocateTarget( SCSITargetLun targetLun );

Your driver will be called at its allocateTarget() function when a target is about to be probed. The your driver should initialize its per-target data at this time. If the subclass wishes to prevent probing of this target, it should return false as the result of this function call.

This is an optional function. Your driver is not required to implement it.

Parameters

NameDescription
targetLunSCSITargetLun structure containing the SCSI Id of the target that is about to be allocated.

cancelCommand

Abstract: Cancels a IOSCSICommand previously submitted to the driver.
public:

void cancelCommand( IOSCSICommand *scsiCommand );

The cancelCommand() function is called to inform your subclass to force completion of a SCSI command.

Your subclass should call the getOriginalCmd() to determine the command to complete.

After calling complete() on the original command, you should complete the IOSCSICommand passed to the cancelCommand() function

Note: When a cancelCommand is issued, your subclass may presume that any activity to remove an active command from the SCSI Target, i.e. (abort tag/abort) has already occurred.

Parameters

NameDescription
scsiCommandPointer to a IOSCSICommand. See IOSCSICommand for more information.

configure

Abstract: Driver configuration/initialization request.
public:

bool configure( IOService *provider, SCSIControllerInfo *controllerInfo );

The configure() member function is the first call your subclass will receive. You should provide the information requested in the SCSIControllerInfo structure and enable your hardware for operation. If your driver initialized successfully, you should return true, otherwise, your driver should return false.

Parameters

NameDescription
providerPointer to an object (usually IOPCIDevice) which represents the bus of your device is attached to . Typically your driver will use functions supplied by this object to access PCI space on your hardware. See IOPCIDevice for a description of PCI services.
controllerInfoPointer to a SCSIControllerInfo structure. Your driver should provide the information requested in this structure prior to returning from the configure() call.

deallocateLun

Abstract: Notifies driver of deallocation of per-Lun resources.
public:

bool allocateLun( SCSITargetLun targetLun );

Your driver will be called at its deallocateLun() function when a Lun is about deallocated. The your driver must insure that there will be no further access to the per-lun data allocated to this lun.

This is an optional function. Your driver is not required to implement it.

Parameters

NameDescription
targetLunSCSITargetLun structure containing the SCSI Id of the target/lun that is about to be deallocated.

deallocateTarget

Abstract: Notifies driver that target resources will be deallocated.
public:

bool deallocateTarget( SCSITargetLun targetLun );

Your driver will be called at its deallocateTarget() function when a target is about deallocated. The your driver must insure that there will be no further access to the per-target data allocated to this target.

This is an optional function. Your driver is not required to implement it.

Parameters

NameDescription
targetLunSCSITargetLun structure containing the SCSI Id of the target that is about to be deallocated.

disableCommands

Abstract: Suspend sending I/O commands to your driver.
public:

void disableCommands( UInt32 timeoutmS );

In cases where your executeCommand() member function cannot accept commands, you may disable further calls by invoking disableCommands(). Use enableCommands() to resume receiving commands.

Note: The resetCommand() and cancelCommands() entry points are not affected by the use of this function.

Note: The default timeout for disableCommands() is 5s. If this timeout is exceeded the IOSCSIController class will call your driver's disableTimeoutOccurred() function. The default action of this function is to issue a SCSI Bus Reset by calling your driver's resetCommand() function.

Parameters

NameDescription
timeoutmSYour driver may override the default timeout by specifying a timeout value in milliseconds.

disableTimeoutOccurred

Abstract: Indicates your driver has suspended commands too long.
public:

void disableTimeoutOccurred();

The IOSCSIController superclass will timeout disableCommand() requests to preclude the possibility of a hung SCSI bus. If a timeout occurs, then disableTimeoutOccurred() will be called. The default action of this routine is to do a SCSI Bus Reset by calling resetCommand(). Your subclass may choose to modify the default behavior of this routine to do additional adapter specific error recovery.


enableCommands

Abstract: Resume sending I/O commands to your driver.
public:

void enableCommands();

Resumes sending I/O commands to your driver that were previously suspended by calling disableCommands().


executeCommand

Abstract: Execute a IOSCSICommand.
public:

void executeCommand( IOSCSICommand *scsiCommand );

The executeCommand() function is called for all 'routine' I/O requests including abort requests. The driver is passed a pointer to an IOSCSICommand object. The driver obtains information about the I/O request by using function calls provided by the IOSCSICommand class.

Parameters

NameDescription
scsiCommandPointer to a IOSCSICommand. See IOSCSICommand for more information.

findCommandWithNexus

Abstract: Locate an active IOSCSICommand using target/lun/tag values.
public:

IOSCSICommand *findCommandWithNexus( SCSITargetLun targetLun, UInt32 tagValue = (UInt32) -1 );

Your subclass can use this function to search for an active IOSCSICommand by providing the target/lun/tag values for the command. In the case of a non-tagged command the second parameter must either be omitted or set to -1.

An unsuccessful search will return 0.

Parameters

NameDescription
targetLunStructure of type SCSITargetLun, initialized to the target/lun value you wish to search for.
tagValueOptional tag value you wish to search for.

getLunData

Abstract: Obtains a pointer to per-Lun data allocated by IOSCSIController.
public:

void *getLunData( SCSITargetLun targetLun );

This function returns a pointer to per-Lun workarea allocated for your driver's use. The size of this area must be specified during the configure() function. See struct SCSIControllerInfo, field lunDataSize.


getTargetData

Abstract: Obtains a pointer to per-Target data allocated by IOSCSIController.
public:

void *getTargetData( SCSITargetLun targetLun );

This function returns a pointer to per-Target workarea allocated for your driver's use. The size of this area must be specified in the during the configure() function. See struct SCSIControllerInfo, field targetDataSize.

Parameters

NameDescription
targetLunSCSITargetLun structure containing the SCSI Id of the target who's workarea you are requesting a pointer to.

getWorkLoop

Abstract: Returns the IOWorkLoop object that services your driver.
public:

IOWorkloop *getWorkLoop();


rescheduleCommand

Abstract: Return a IOSCSICommand for rescheduling.
public:

void rescheduleCommand( IOSCSICommand *scsiCommand );

If your subclass function cannot start processing an otherwise acceptable IOSCSICommand due to resource constraints, i.e. MailBox full, lost SCSI Bus arbitration, you may have the IOSCSICommand rescheduled by calling rescheduleCommand(). A IOSCSICommand passed to this function should be treated as 'complete', i.e. you should make no further accesses to it.

Note: If you cannot process further commands, you should call the disableCommands() function to prevent receiving additional commands until you are ready to accept them.

Parameters

NameDescription
scsiCommandPointer to IOSCSICommand your driver needs to reschedule.

resetCommand

Abstract: Request the driver issue a SCSI Bus reset.
public:

void resetCommand( IOSCSICommand *scsiCommand );

The resetCommand() function indicates you should do a SCSI Bus Reset. After issuing the reset you should complete to IOSCSICommand passed.

Note: After you report the IOSCSICommand Reset complete, you will receive cancelCommand() requests for all outstanding commands.

Parameters

NameDescription
scsiCommandPointer to a IOSCSICommand. See IOSCSICommand for more information.

resetOccurred

Abstract: Inform the IOSCSIController class of an unsolicited SCSI Bus reset.
public:

void resetOccurred();

Your subclass should call this function if you detect a target initiated bus reset, or need to do an unplanned SCSI Bus Reset as part of adapter error recovery.

Note: After you call the resetOccurred() function, you will receive cancelCommand() requests for all outstanding IOSCSICommand(s).


© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)