IOSCSIProtocolInterface

Inherits from
IOService
Availability
Available in OS X v10.0 and later.
Declared in
IOSCSIProtocolInterface.h

Overview

This class defines the public SCSI Protocol Layer API for any class that provides Protocol services or needs to provide the Protocol Service API for passing service requests to a Protocol Service driver.

Tasks

Miscellaneous

Instance Methods

AbortCommand

Obsolete. Do not use this method.

virtual SCSIServiceResponse AbortCommand ( SCSITaskIdentifier request ) = 0;
Discussion

Obsolete. Do not use this method.

AbortTask

Aborts a task based on the Logical Unit and tagged task identifier.

virtual SCSIServiceResponse AbortTask ( UInt8 theLogicalUnit, SCSITaggedTaskIdentifier theTag ) = 0;
Parameters
theLogicalUnit

This value should be zero unless the device driver is more complex and managing multiple Logical Units.

theTag

A valid SCSITaggedTaskIdentifier representing an outstanding SCSITask.

Return Value

A valid SCSIServiceResponse code.

Discussion

Aborts a task based on the Logical Unit and tagged task identifier. Subclasses must override this method. Third party subclasses should not need to override this method.

AbortTaskSet

Aborts a task set based on the Logical Unit.

virtual SCSIServiceResponse AbortTaskSet ( UInt8 theLogicalUnit ) = 0;
Parameters
theLogicalUnit

This value should be zero unless the device driver is more complex and managing multiple Logical Units.

Return Value

A valid SCSIServiceResponse code.

Discussion

Aborts a task set based on the Logical Unit. Subclasses must override this method. Third party subclasses should not need to override this method.

CheckPowerState

Called by clients to ensure device is in correct power state before issuing I/O.

virtual void CheckPowerState ( void );
Discussion

Called by clients to ensure device is in correct power state before issuing I/O. If the device is not ready to handle such requests, it gives the driver a chance to block the thread until the device is ready. Subclasses should not need to override this method.

ClearACA

Clears an Auto-Contingent Allegiance (ACA) for the specified Logical Unit.

virtual SCSIServiceResponse ClearACA ( UInt8 theLogicalUnit ) = 0;
Parameters
theLogicalUnit

This value should be zero unless the device driver is more complex and managing multiple Logical Units.

Return Value

A valid SCSIServiceResponse code.

Discussion

Clears an Auto-Contingent Allegiance (ACA) for the specified Logical Unit. Subclasses must override this method. Third party subclasses should not need to override this method.

ClearTaskSet

Clears a task set for the specified Logical Unit.

virtual SCSIServiceResponse ClearTaskSet ( UInt8 theLogicalUnit ) = 0;
Parameters
theLogicalUnit

This value should be zero unless the device driver is more complex and managing multiple Logical Units.

Return Value

A valid SCSIServiceResponse code.

Discussion

Clears a task set for the specified Logical Unit. Subclasses must override this method. Third party subclasses should not need to override this method.

ExecuteCommand

Called to send a SCSITask and transport it across the physical wire(s) to the device.

virtual void ExecuteCommand ( SCSITaskIdentifier request ) = 0;
Parameters
request

A valid SCSITaskIdentifier representing the task to transport across the wire(s).

Discussion

Called to send a SCSITask and transport it across the physical wire(s) to the device. Subclasses internal to IOSCSIArchitectureModelFamily will need to override this method. Third party subclasses should not need to override this method.

finalize

Finalizes the destruction of an IOService object.

virtual bool finalize ( IOOptionBits options );
Return Value

true.

Discussion

See IOService.h Subclasses may override this method, but should call super::finalize().

free

Called to release all resources held by the object.

virtual void free ( void );
Discussion

Release all resources held by the object, then call super::free().

GetCommandGate

Accessor method to obtain the IOCommandGate.

IOCommandGate * GetCommandGate ( void );
Return Value

The IOCommandGate for this instance. May return NULL.

Discussion

Accessor method to obtain the IOCommandGate.

GetInitialPowerState

This method is called to obtain the initial power state of the device (usually the highest).

virtual UInt32 GetInitialPowerState ( void ) = 0;
Return Value

A power state ordinal.

Discussion

This method is called to obtain the initial power state of the device (usually the highest). Subclasses must override this method.

GetUserClientExclusivityState

Gets the current exclusivity state of the user client.

virtual bool GetUserClientExclusivityState ( void );
Return Value

true if a user client is in exclusive control of the device, false otherwise.

Discussion

The GetUserClientExclusivityState() method is called by the SCSITaskUserClient to determine if any user client is holding exclusive access at the current time. This is simply a preflight check and a return value of false does not guarantee that a subsequent call to SetUserClientExclusivityState() will return successfully.

HandleCheckPowerState()

The HandleCheckPowerState (void) method is on the serialized side of the command gate and can change member variables safely without multi-threading issues. It's main purpose is to call the superclass' HandleCheckPowerState ( UInt32 maxPowerState ) with the max power state the class registered with.

virtual void HandleCheckPowerState ( void ) = 0;
Discussion

The HandleCheckPowerState (void) method is on the serialized side of the command gate and can change member variables safely without multi-threading issues. It's main purpose is to call the superclass' HandleCheckPowerState ( UInt32 maxPowerState ) with the max power state the class registered with. Subclasses must override this method. Third party subclasses shouldn't need to override this method but can to alter the default behavior.

HandleCheckPowerState(UInt32 maxPowerState)

The HandleCheckPowerState(UInt32 maxPowerState) method is called by the subclasses and is passed the maxPowerState number given to the power manager at initialization time. This guarantees the threads block until that power state has been achieved.

void HandleCheckPowerState ( UInt32 maxPowerState );
Parameters
maxPowerState

The maximum power state in the power state array.

Discussion

The HandleCheckPowerState(UInt32 maxPowerState) method is called by the subclasses and is passed the maxPowerState number given to the power manager at initialization time. This guarantees the threads block until that power state has been achieved.

HandleCheckPowerState(UInt32)

The HandleCheckPowerState(UInt32 maxPowerState) method is called by the subclasses and is passed the maxPowerState number given to the power manager at initialization time. This guarantees the threads block until that power state has been achieved.

void HandleCheckPowerState ( UInt32 maxPowerState );
Parameters
maxPowerState

The maximum power state in the power state array.

Discussion

The HandleCheckPowerState(UInt32 maxPowerState) method is called by the subclasses and is passed the maxPowerState number given to the power manager at initialization time. This guarantees the threads block until that power state has been achieved.

HandleCheckPowerState(void)

The HandleCheckPowerState (void) method is on the serialized side of the command gate and can change member variables safely without multi-threading issues. It's main purpose is to call the superclass' HandleCheckPowerState ( UInt32 maxPowerState ) with the max power state the class registered with.

virtual void HandleCheckPowerState ( void ) = 0;
Discussion

The HandleCheckPowerState (void) method is on the serialized side of the command gate and can change member variables safely without multi-threading issues. It's main purpose is to call the superclass' HandleCheckPowerState ( UInt32 maxPowerState ) with the max power state the class registered with. Subclasses must override this method. Third party subclasses shouldn't need to override this method but can to alter the default behavior.

HandleGetUserClientExclusivityState

Gets the current exclusivity state of the user client.

virtual bool HandleGetUserClientExclusivityState ( void );
Return Value

true if a user client is in exclusive control of the device, false otherwise.

Discussion

The HandleGetUserClientExclusivityState() method is called on the serialized side of the command gate to determine if any user client is holding exclusive access at the current time. See discussion for GetUserClientExclusivityState(). Subclasses may override this method to alter default behavior. Third party subclasses should not need to override this method.

HandlePowerChange

The HandlePowerChange method is pure virtual and is left to each protocol or application layer driver to implement. It is guaranteed to be called on its own thread of execution and can make synchronous or asynchronous calls.

virtual void HandlePowerChange ( void ) = 0;
Discussion

The HandlePowerChange method is pure virtual and is left to each protocol or application layer driver to implement. It is guaranteed to be called on its own thread of execution and can make synchronous or asynchronous calls. Subclasses must override this method. Third party subclasses shouldn't need to override this method but can to alter the default behavior.

HandleProtocolServiceFeature

This method is called to enact support of a protocol specific service feature.

virtual bool HandleProtocolServiceFeature ( SCSIProtocolFeature feature, void *serviceValue ) = 0;
Parameters
feature

A valid SCSIProtocolFeature. See enums for SCSIProtocolFeature.

serviceValue

A pointer to a structure/value that is used in conjunction with the feature requested. See enums for SCSIProtocolFeature. NB: This parameter may be NULL for certain feature requests.

Return Value

true if the service feature request succeeded, false otherwise.

Discussion

This method is called to enact support of a protocol specific service feature. Subclasses of IOSCSIProtocolServices should override this method.

HandleSetPowerState

The HandleSetPowerState method is called by the glue code and is on the serialized side of the command gate.

virtual void HandleSetPowerState ( UInt32 powerStateOrdinal );
Parameters
powerStateOrdinal

The power state to which device shall be changed.

Discussion

The HandleSetPowerState method is called by the glue code and is on the serialized side of the command gate. This allows us to touch any member variables as necessary without any multi-threading issues. Subclasses may override this method to change behavior. Third party subclasses should not need to override this method, but may.

HandleSetUserClientExclusivityState

Sets the current exclusivity state of the user client.

virtual IOReturn HandleSetUserClientExclusivityState ( IOService *userClient, bool state );
Parameters
userClient

The instance of SCSITaskUserClient for which to change exclusivity state.

state

Exclusivity state. true means exclusive access is desired, false means exclusive access is being released.

Return Value

A valid IOReturn code indicating success or the type of failure.

Discussion

The HandleSetUserClientExclusivityState() method is called on the serialized side of the command gate to set the exclusive access mode.

InitializePowerManagement

This method is called to initialize power management.

virtual void InitializePowerManagement ( IOService *provider );
Parameters
provider

The power management provider (i.e. the provider to attach to in the PowerManagement tree). This may be a device that is not in the PM Tree itself, in which case, the IOService plane is traversed towards the root node in an effort to find a node in the PM Tree.

Discussion

This method is called to initialize power management. It will call PMinit(), joinPMTree(), and makeUsable(). This method does not call registerPowerDriver(). Subclasses may override this method to change the behavior (such as the number of power states).

initialPowerStateForDomainState

Determines which power state a device is in, given the current power domain state.

virtual unsigned long initialPowerStateForDomainState ( IOPMPowerFlags flags );
Parameters
flags

Flags that describe the character of "domain power"; they represent the outputPowerCharacter field of a state in the power domain's power state array.

Return Value

A state number.

Discussion

Power management calls this method once, when the driver is initializing power management. Subclasses should not need to override this method.

IsPowerManagementIntialized

Called to determine if power management is initialized.

virtual bool IsPowerManagementIntialized ( void );
Return Value

true if power management has been initialized, false otherwise.

Discussion

Called to determine if power management is initialized. Subclasses should not need to override this method.

IsProtocolServiceSupported

This method is called to query for support of a protocol specific service feature.

virtual bool IsProtocolServiceSupported ( SCSIProtocolFeature feature, void *serviceValue ) = 0;
Parameters
feature

A valid SCSIProtocolFeature. See enums for SCSIProtocolFeature.

serviceValue

A pointer to a structure/value that is used in conjunction with the feature requested. See enums for SCSIProtocolFeature. NB: This parameter may be NULL for certain feature requests.

Return Value

true if the feature is supported, false otherwise.

Discussion

This method is called to query for support of a protocol specific service feature. Subclasses of IOSCSIProtocolServices should override this method.

LogicalUnitReset

Resets the specified Logical Unit.

virtual SCSIServiceResponse LogicalUnitReset ( UInt8 theLogicalUnit ) = 0;
Parameters
theLogicalUnit

This value should be zero unless the device driver is more complex and managing multiple Logical Units.

Return Value

A valid SCSIServiceResponse code.

Discussion

Resets the specified Logical Unit. Subclasses must override this method. Third party subclasses should not need to override this method.

setPowerState

Requests a power managed driver to change the power state of its device.

virtual IOReturn setPowerState ( unsigned long powerStateOrdinal, IOService *whichDevice );
Parameters
powerStateOrdinal

The number in the power state array to which the drive is being instructed to change.

whichDevice

A pointer to the power management object which registered to manage power for this device. The whichDevice field is not pertinent to us since the driver is both the "policy maker" for the device, and the "policy implementor" for the device.

Return Value

See IOService.h for details.

Discussion

Requests a power managed driver to change the power state of its device. Most subclasses of IOSCSIProtocolInterface have class-specific mechanisms and should not override this routine. See IOSCSIProtocolServices.h, IOSCSIBlockCommandsDevice.h, IOSCSIReducedBlockCommandsDevice.h, and IOSCSIMultimediaCommandsDevice.h for more information about power management changes. Subclasses should not need to override this method.

SetUserClientExclusivityState

Sets the current exclusivity state of the user client.

virtual IOReturn SetUserClientExclusivityState ( IOService *userClient, bool state );
Parameters
userClient

The instance of SCSITaskUserClient for which to change exclusivity state.

state

Exclusivity state. true means exclusive access is desired, false means exclusive access is being released.

Return Value

A valid IOReturn code indicating success or the type of failure.

Discussion

The SetUserClientExclusivityState() method is called by the SCSITaskUserClient to set the exclusive access mode.

sGetPowerTransistionInProgress

The sGetPowerTransistionInProgress method is a static function used as C->C++ glue for going behind the command gate.

static bool sGetPowerTransistionInProgress ( IOSCSIProtocolInterface *self );
Parameters
self

The 'this' pointer for the class.

Return Value

true if a power state is in progress, otherwise false.

Discussion

The sGetPowerTransistionInProgress method is a static function used as C->C++ glue for going behind the command gate.

sGetUserClientExclusivityState

The sGetUserClientExclusivityState method is a static function used as C->C++ glue for going behind the command gate.

static void sGetUserClientExclusivityState ( IOSCSIProtocolInterface *self, bool *state );
Parameters
self

The 'this' pointer for the class.

state

A pointer to a bool in which the state should be set.

Discussion

The sGetUserClientExclusivityState method is a static function used as C->C++ glue for going behind the command gate.

sHandleCheckPowerState

The sHandleCheckPowerState method is a static function used as C->C++ glue for going behind the command gate.

static void sHandleCheckPowerState ( IOSCSIProtocolInterface *self );
Parameters
self

The 'this' pointer for the class.

Discussion

The sHandleCheckPowerState method is a static function used as C->C++ glue for going behind the command gate.

sHandleSetPowerState

The sHandleSetPowerState method is a static function used as C->C++ glue for going behind the command gate.

static IOReturn sHandleSetPowerState ( IOSCSIProtocolInterface *self, UInt32 powerStateOrdinal );
Parameters
self

The 'this' pointer for the class.

powerStateOrdinal

The power state to which device shall be changed.

Return Value

A valid IOReturn code indicating success or failure.

Discussion

The sHandleSetPowerState method is a static function used as C->C++ glue for going behind the command gate.

sPowerManagement

The sPowerManagement method is a static C-function which is called using mach's thread_call API. It guarantees us a thread of execution which is different than the power management thread and the workloop thread on which we can issue commands to the device synchronously or asynchronously without worrying about deadlocks. It calls through to HandlePowerChange, which is a state machine used to direct power management.

static void sPowerManagement ( thread_call_param_t whichDevice );
Parameters
whichDevice

The 'this' pointer.

Discussion

The sPowerManagement method is a static C-function which is called using mach's thread_call API. It guarantees us a thread of execution which is different than the power management thread and the workloop thread on which we can issue commands to the device synchronously or asynchronously without worrying about deadlocks. It calls through to HandlePowerChange, which is a state machine used to direct power management.

sSetUserClientExclusivityState

The sSetUserClientExclusivityState method is a static function used as C->C++ glue for going behind the command gate.

static void sSetUserClientExclusivityState ( IOSCSIProtocolInterface *self, IOReturn *result, IOService *userClient, bool state );
Parameters
self

The 'this' pointer for the class.

result

A pointer to an IOReturn for the resulting status.

userClient

The instance of SCSITaskUserClient for which to change exclusivity state.

state

A bool indicating the desired state to set.

Discussion

The sSetUserClientExclusivityState method is a static function used as C->C++ glue for going behind the command gate.

start

During an IOService object's instantiation, starts the IOService object that has been selected to run on the provider.

virtual bool start ( IOService *provider );
Return Value

true if the start was successful; false otherwise (which will cause the instance to be detached and usually freed).

Discussion

See IOService.h for details.

TargetReset

Resets the target device.

virtual SCSIServiceResponse TargetReset ( void ) = 0;
Return Value

A valid SCSIServiceResponse code.

Discussion

Resets the target device. Subclasses must override this method. Third party subclasses should not need to override this method.

TicklePowerManager()

The TicklePowerManager(void) method is called by CheckPowerState and sends an activity tickle to the power manager so that the idle timer is reset.

virtual void TicklePowerManager ( void ) = 0;
Discussion

The TicklePowerManager(void) method is called by CheckPowerState and sends an activity tickle to the power manager so that the idle timer is reset. Subclasses must override this method. Third party subclasses shouldn't need to override this method but can to alter the default behavior.

TicklePowerManager(UInt32 maxPowerState)

The TicklePowerManager(UInt32 maxPowerState) method is a convenience function which can be called by subclasses in TicklePowerManager (void) in order to tell the power manager to reset idle timer or bring the device into the requested state. It returns whatever is returned by activityTickle (true if device is in the requested state, false if it is not).

bool TicklePowerManager ( UInt32 maxPowerState );
Parameters
maxPowerState

The maximum power state in the power state array.

Return Value

The result of the call to activityTickle(). See IOService.h for details.

Discussion

The TicklePowerManager(UInt32 maxPowerState) method is a convenience function which can be called by subclasses in TicklePowerManager(void) in order to tell the power manager to reset idle timer or bring the device into the requested state. It returns whatever is returned by activityTickle (true if device is in the requested state, false if it is not).

TicklePowerManager(UInt32)

The TicklePowerManager(UInt32 maxPowerState) method is a convenience function which can be called by subclasses in TicklePowerManager (void) in order to tell the power manager to reset idle timer or bring the device into the requested state. It returns whatever is returned by activityTickle (true if device is in the requested state, false if it is not).

bool TicklePowerManager ( UInt32 maxPowerState );
Parameters
maxPowerState

The maximum power state in the power state array.

Return Value

The result of the call to activityTickle(). See IOService.h for details.

Discussion

The TicklePowerManager(UInt32 maxPowerState) method is a convenience function which can be called by subclasses in TicklePowerManager(void) in order to tell the power manager to reset idle timer or bring the device into the requested state. It returns whatever is returned by activityTickle (true if device is in the requested state, false if it is not).

TicklePowerManager(void)

The TicklePowerManager(void) method is called by CheckPowerState and sends an activity tickle to the power manager so that the idle timer is reset.

virtual void TicklePowerManager ( void ) = 0;
Discussion

The TicklePowerManager(void) method is called by CheckPowerState and sends an activity tickle to the power manager so that the idle timer is reset. Subclasses must override this method. Third party subclasses shouldn't need to override this method but can to alter the default behavior.

willTerminate

Passes a termination up the stack.

virtual bool willTerminate ( IOService *provider, IOOptionBits options );
Parameters
provider

The terminated provider of this object.

options

Options originally passed to terminate().

Return Value

true.

Discussion

Notification that a provider has been terminated, sent before recursing up the stack, in root-to-leaf order.