Mac Developer Library

Developer

IOSCSIProtocolInterface Class Reference

Options
Deployment Target:

On This Page

IOSCSIProtocolInterface

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.

  • Obsolete. Do not use this method.

    Declaration

    virtual SCSIServiceResponse AbortCommand ( SCSITaskIdentifier request ) = 0;

    Discussion

    Obsolete. Do not use this method.

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

    Declaration

    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.

  • Aborts a task set based on the Logical Unit.

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

    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.

  • Clears a task set for the specified Logical Unit.

    Declaration

    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.

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

    Declaration

    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.

  • Finalizes the destruction of an IOService object.

    Declaration

    virtual bool finalize ( IOOptionBits options );

    Return Value

    true.

    Discussion

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

  • Called to release all resources held by the object.

    Declaration

    virtual void free ( void );

    Discussion

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

  • Accessor method to obtain the IOCommandGate.

    Declaration

    IOCommandGate * GetCommandGate ( void );

    Return Value

    The IOCommandGate for this instance. May return NULL.

    Discussion

    Accessor method to obtain the IOCommandGate.

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

    Declaration

    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.

  • Gets the current exclusivity state of the user client.

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

    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.

  • Gets the current exclusivity state of the user client.

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

    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.

  • Sets the current exclusivity state of the user client.

    Declaration

    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.

  • This method is called to initialize power management.

    Declaration

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

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

    Declaration

    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.

  • Called to determine if power management is initialized.

    Declaration

    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.

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

    Declaration

    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.

  • Resets the specified Logical Unit.

    Declaration

    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.

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

    Declaration

    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.

  • Sets the current exclusivity state of the user client.

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

    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.

  • Resets the target device.

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

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

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

    Declaration

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

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

    Declaration

    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.

  • Passes a termination up the stack.

    Declaration

    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.