IOSCSIProtocolInterface

Inherits from:	IOService
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.

Functions

AbortCommand: Obsolete. Do not use this method.
AbortTask: Aborts a task based on the Logical Unit and tagged task identifier.
AbortTaskSet: Aborts a task set based on the Logical Unit.
CheckPowerState: Called by clients to ensure device is in correct power state before issuing I/O.
ClearACA: Clears an Auto-Contingent Allegiance (ACA) for the specified Logical Unit.
ClearTaskSet: Clears a task set for the specified Logical Unit.
ExecuteCommand: Called to send a SCSITask and transport it across the physical wire(s) to the device.
finalize: Finalizes the destruction of an IOService object.
free: Called to release all resources held by the object.
GetCommandGate: Accessor method to obtain the IOCommandGate.
GetInitialPowerState: This method is called to obtain the initial power state of the device (usually the highest).
GetUserClientExclusivityState: Gets the current exclusivity state of the user client.
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.
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.
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.
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.
HandleGetUserClientExclusivityState: Gets the current exclusivity state of the user client.
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.
HandleProtocolServiceFeature: This method is called to enact support of a protocol specific service feature.
HandleSetPowerState: The HandleSetPowerState method is called by the glue code and is on the serialized side of the command gate.
HandleSetUserClientExclusivityState: Sets the current exclusivity state of the user client.
InitializePowerManagement: This method is called to initialize power management.
initialPowerStateForDomainState: Determines which power state a device is in, given the current power domain state.
IsPowerManagementIntialized: Called to determine if power management is initialized.
IsProtocolServiceSupported: This method is called to query for support of a protocol specific service feature.
LogicalUnitReset: Resets the specified Logical Unit.
setPowerState: Requests a power managed driver to change the power state of its device.
SetUserClientExclusivityState: Sets the current exclusivity state of the user client.
sGetPowerTransistionInProgress: 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.
sHandleCheckPowerState: 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.
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.
sSetUserClientExclusivityState: 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.
TargetReset: Resets the target device.
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.
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).
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).
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.
willTerminate: Passes a termination up the stack.

AbortCommand

Obsolete. Do not use this method.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

protected

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.

public

virtual void free (
    void );

Discussion

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

GetCommandGate

Accessor method to obtain the IOCommandGate.

protected

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).

protected

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.

public

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()

protected

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.

protected

void HandleCheckPowerState (
    UInt32 maxPowerState );

Parameters

maxPowerState: The maximum power state in the power state array.

Discussion

HandleCheckPowerState(UInt32)

protected

void HandleCheckPowerState (
    UInt32 maxPowerState );

Parameters

maxPowerState: The maximum power state in the power state array.

Discussion

HandleCheckPowerState(void)

protected

virtual void HandleCheckPowerState (
    void ) = 0;

Discussion

HandleGetUserClientExclusivityState

Gets the current exclusivity state of the user client.

protected

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

protected

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.

public

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.

protected

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.

protected

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.

protected

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(), setIdleTimerPeriod(), 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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

protected

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.

protected

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.

protected

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.

protected

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.

protected

static void sPowerManagement (
    thread_call_param_t whichDevice );

Parameters

whichDevice: The 'this' pointer.

Discussion

sSetUserClientExclusivityState

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

protected

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.

public

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.

public

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.

protected

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).

protected

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)

protected

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.

protected

virtual void TicklePowerManager (
    void ) = 0;

Discussion

willTerminate

Passes a termination up the stack.

public

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.

Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: Kernel Device Drivers Kernel Framework Reference

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Last Updated: 2010-07-29