Mac Developer Library

Developer

IOSCSIProtocolInterface Class Reference

Options
Deployment Target:

On This Page
Language:

IOSCSIProtocolInterface

Inheritance


  • IOSCSIProtocolInterface

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.

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

    C++

    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

    C++

    virtual SCSIServiceResponse AbortTask ( UInt8theLogicalUnit, SCSITaggedTaskIdentifiertheTag ) = 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

    C++

    virtual SCSIServiceResponse AbortTaskSet ( UInt8theLogicalUnit ) = 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

    C++

    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

    C++

    virtual SCSIServiceResponse ClearACA ( UInt8theLogicalUnit ) = 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

    C++

    virtual SCSIServiceResponse ClearTaskSet ( UInt8theLogicalUnit ) = 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

    C++

    virtual void ExecuteCommand ( SCSITaskIdentifierrequest ) = 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

    C++

    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

    C++

    virtual void free ( void );

    Discussion

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

  • Accessor method to obtain the IOCommandGate.

    Declaration

    C++

    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

    C++

    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

    C++

    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

    C++

    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

    C++

    void HandleCheckPowerState ( UInt32maxPowerState );

    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

    C++

    void HandleCheckPowerState ( UInt32maxPowerState );

    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

    C++

    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

    C++

    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

    C++

    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

    C++

    virtual bool HandleProtocolServiceFeature ( SCSIProtocolFeaturefeature, 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

    C++

    virtual void HandleSetPowerState ( UInt32powerStateOrdinal );

    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

    C++

    virtual IOReturn HandleSetUserClientExclusivityState ( IOService *userClient, boolstate );

    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

    C++

    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

    C++

    virtual unsigned long initialPowerStateForDomainState ( IOPMPowerFlagsflags );

    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

    C++

    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

    C++

    virtual bool IsProtocolServiceSupported ( SCSIProtocolFeaturefeature, 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

    C++

    virtual SCSIServiceResponse LogicalUnitReset ( UInt8theLogicalUnit ) = 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

    C++

    virtual IOReturn setPowerState ( unsigned longpowerStateOrdinal, 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

    C++

    virtual IOReturn SetUserClientExclusivityState ( IOService *userClient, boolstate );

    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

    C++

    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

    C++

    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

    C++

    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

    C++

    static IOReturn sHandleSetPowerState ( IOSCSIProtocolInterface *self, UInt32powerStateOrdinal );

    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

    C++

    static void sPowerManagement ( thread_call_param_twhichDevice );

    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

    C++

    static void sSetUserClientExclusivityState ( IOSCSIProtocolInterface *self, IOReturn *result, IOService *userClient, boolstate );

    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

    C++

    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

    C++

    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

    C++

    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

    C++

    bool TicklePowerManager ( UInt32maxPowerState );

    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

    C++

    bool TicklePowerManager ( UInt32maxPowerState );

    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

    C++

    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

    C++

    virtual bool willTerminate ( IOService *provider, IOOptionBitsoptions );

    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.