Mac Developer Library

Developer

IOSCSIProtocolServices Class Reference

Options
Deployment Target:

On This Page

IOSCSIProtocolServices

This class defines the public SCSI Protocol Services Layer API for any class that implements SCSI protocol services. A protocol services layer driver is responsible for taking incoming SCSITaskIdentifier objects and translating them to the native command type for the native protocol interface (e.g. SBP-2 ORB on FireWire).

  • Deprecated. Do not use.

    Declaration

    virtual SCSIServiceResponse AbortCommand ( SCSITaskIdentifier request ) __attribute__ ((deprecated));

    Discussion

    Deprecated. Do not use.

  • Pure virtual method subclasses must implement so that SCSITasks may be aborted.

    Declaration

    virtual SCSIServiceResponse AbortSCSICommand ( SCSITaskIdentifier request ) = 0;

    Parameters

    request

    A valid SCSITaskIdentifier representing the command to be aborted.

    Return Value

    A valid SCSIServiceResponse.

    Discussion

    Provides the capability for a caller to request that a particular SCSITask be aborted.

  • Deprecated internal method.

    Declaration

    bool AbortSCSITaskFromQueue ( SCSITask *request );

    Discussion

    Deprecated internal method.

  • The Task Management function to allow the SCSI Application Layer client to request that a specific task be aborted.

    Declaration

    SCSIServiceResponse AbortTask ( UInt8 theLogicalUnit, SCSITaggedTaskIdentifier theTag );

    Parameters

    theLogicalUnit

    A logical unit for which to abort a task.

    theTag

    A valid SCSITaggedTaskIdentifier used to identify which task to abort.

    Return Value

    A valid SCSIServiceResponse.

    Discussion

    The Task Management function to allow the SCSI Application Layer client to request that a specific task be aborted.

  • The Task Management function to allow the SCSI Application Layer client to request that a complete task set be aborted.

    Declaration

    SCSIServiceResponse AbortTaskSet ( UInt8 theLogicalUnit );

    Parameters

    theLogicalUnit

    A logical unit for which to abort the task set.

    Return Value

    A valid SCSIServiceResponse.

    Discussion

    The Task Management function to allow the SCSI Application Layer client to request that a complete task set be aborted.

  • Internal method called to add a SCSITask to the head of the processing queue.

    Declaration

    void AddSCSITaskToHeadOfQueue ( SCSITask *request );

    Parameters

    request

    A valid SCSITask pointer.

    Discussion

    Internal method called to add a SCSITask to the head of the processing queue.

  • Internal method called to add a SCSITask to the processing queue.

    Declaration

    void AddSCSITaskToQueue ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Discussion

    Internal method called to add a SCSITask to the processing queue.

  • The Task Management function to clear an Auto-Contingent Allegiance condition.

    Declaration

    SCSIServiceResponse ClearACA ( UInt8 theLogicalUnit );

    Parameters

    theLogicalUnit

    A logical unit for which to clear the ACA.

    Return Value

    A valid SCSIServiceResponse.

    Discussion

    The Task Management function to clear an Auto-Contingent Allegiance condition.

  • The Task Management function to clear a task set.

    Declaration

    SCSIServiceResponse ClearTaskSet ( UInt8 theLogicalUnit );

    Parameters

    theLogicalUnit

    A logical unit for which to clear a task set.

    Return Value

    A valid SCSIServiceResponse.

    Discussion

    The Task Management function to clear a task set.

  • Method subclass calls to complete a SCSITask.

    Declaration

    void CommandCompleted ( SCSITaskIdentifier request, SCSIServiceResponse serviceResponse, SCSITaskStatus taskStatus );

    Parameters

    request

    A valid SCSITaskIdentifier indicating the request to complete.

    serviceResponse

    A valid SCSIServiceResponse value.

    taskStatus

    A valid SCSITaskStatus value.

    Discussion

    Subclasses will call this inherited method when the command executed by SendSCSICommand has completed.

  • Used to create a SCSITargetDevice which will manage logical units.

    Declaration

    virtual bool CreateSCSITargetDevice ( void );

    Return Value

    True if successful, otherwise false.

    Discussion

    The CreateSCSITargetDevice member routine will create the appropriate object to represent the Target portion of a SCSI Device. This object is responsible for managing the Target functions of the SCSI Device including the Task Manager and Logical Units.

  • Internal method, not to be called by subclasses.

    Declaration

    void EnsureAutosenseDescriptorExists ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Discussion

    Internal method, not to be called by subclasses.

  • ExecuteCommand method will take a SCSI Task and transport it across the physical wire(s) to the device.

    Declaration

    void ExecuteCommand ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Discussion

    ExecuteCommand method will take a SCSI Task and transport it across the physical wire(s) to the device.

  • Frees data structures that were allocated during start().

    Declaration

    virtual void free ( void );

    Discussion

    Frees data structures that were allocated during start().

  • Accessor method to retrieve the requested data transfer count for autosense data associated with the specified request.

    Declaration

    UInt64 GetAutosenseRequestedDataTransferCount ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Return Value

    The requested autosense data transfer count.

    Discussion

    Accessor method to retrieve the requested data transfer count for autosense data associated with the specified request.

  • Accessor method to retrieve the Command Descriptor Block associated with the specified request.

    Declaration

    bool GetCommandDescriptorBlock ( SCSITaskIdentifier request, SCSICommandDescriptorBlock *cdbData );

    Parameters

    request

    A valid SCSITaskIdentifier.

    cdbData

    A pointer to SCSICommandDescriptorBlock to be filled in by this method. NOTE: This routine will always fill in 16 bytes, so if the protocol layer driver supports less than this amount it will have to create a local SCSICommandDescriptorBlock variable to get the CDB data.

    Return Value

    True on success, otherwise false.

    Discussion

    Accessor method to retrieve the Command Descriptor Block associated with the specified request.

  • Accessor method to retrieve the Command Descriptor Block size associated with the specified request.

    Declaration

    UInt8 GetCommandDescriptorBlockSize ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Return Value

    A valid CDB size (e.g. 6, 10, 12, or 16 bytes).

    Discussion

    Accessor method to retrieve the Command Descriptor Block size associated with the specified request.

  • Accessor method to retrieve the data buffer associated with the specified request.

    Declaration

    IOMemoryDescriptor * GetDataBuffer ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Return Value

    An IOMemoryDescriptor associated with the request. May be NULL if data transfer direction is kSCSIDataTransfer_NoDataTransfer.

    Discussion

    Accessor method to retrieve the data buffer associated with the specified request.

  • Accessor method to retrieve the data buffer offset associated with the specified request.

    Declaration

    UInt64 GetDataBufferOffset ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Return Value

    Offset into the data buffer at which to start the transfer of data.

    Discussion

    Accessor method to retrieve the data buffer offset associated with the specified request.

  • Accessor method to retrieve the data transfer direction associated with the specified request.

    Declaration

    UInt8 GetDataTransferDirection ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Return Value

    The data transfer direction (e.g. kSCSIDataTransfer_NoDataTransfer).

    Discussion

    Accessor method to retrieve the data transfer direction associated with the specified request.

  • This method is called once, right after InitializePowerManagement() in order to determine what state the device is initially in at startup time (usually the highest power mode).

    Declaration

    virtual UInt32 GetInitialPowerState ( void );

    Return Value

    The power state the device is currently in.

    Discussion

    This method is called once, right after InitializePowerManagement() in order to determine what state the device is initially in at startup time (usually the highest power mode).

  • Accessor method to retrieve the logical unit bytes associated with the specified request.

    Declaration

    void GetLogicalUnitBytes ( SCSITaskIdentifier request, SCSILogicalUnitBytes *lunBytes );

    Parameters

    request

    A valid SCSITaskIdentifier.

    lunBytes

    A pointer to SCSILogicalUnitBytes to be filled in by this method.

    Discussion

    Accessor method to retrieve the logical unit bytes associated with the specified request.

  • Accessor method to retrieve the logical unit number associated with the specified request.

    Declaration

    UInt8 GetLogicalUnitNumber ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Return Value

    A valid single-byte LUN value.

    Discussion

    Accessor method to retrieve the logical unit number associated with the specified request. NOTE: This method is deprecated in favor of GetLogicalUnitBytes().

  • Accessor method to retrieve the protocol layer reference.

    Declaration

    void * GetProtocolLayerReference ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Return Value

    The protocol layer reference value. May be NULL.

    Discussion

    Accessor method to retrieve the protocol layer reference.

  • Accessor method to retrieve the realized data transfer count associated with the specified request.

    Declaration

    UInt64 GetRealizedDataTransferCount ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Return Value

    The realized data transfer count.

    Discussion

    Accessor method to retrieve the realized data transfer count associated with the specified request.

  • Accessor method to retrieve the requested data transfer count associated with the specified request.

    Declaration

    UInt64 GetRequestedDataTransferCount ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Return Value

    The requested data transfer count.

    Discussion

    Accessor method to retrieve the requested data transfer count associated with the specified request.

  • Accessor method to retrieve the SCSITaskAttribute associated with the specified request.

    Declaration

    SCSITaskAttribute GetTaskAttribute ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Return Value

    A valid SCSITaskAttribute value.

    Discussion

    Accessor method to retrieve the SCSITaskAttribute associated with the specified request.

  • Internal method used to retrieve the task execution mode.

    Declaration

    SCSITaskMode GetTaskExecutionMode ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Return Value

    A valid SCSITaskMode value.

    Discussion

    Internal method used to retrieve the task execution mode.

  • Accessor method to retrieve the SCSITaskState associated with the specified request.

    Declaration

    SCSITaskState GetTaskState ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Return Value

    A valid SCSITaskState value.

    Discussion

    Accessor method to retrieve the SCSITaskState associated with the specified request.

  • Accessor method to retrieve the timeout duration in milliseconds associated with the specified request.

    Declaration

    UInt32 GetTimeoutDuration ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Return Value

    Timeout duration in milliseconds.

    Discussion

    Accessor method to retrieve the timeout duration in milliseconds associated with the specified request.

  • HandleAbortTask instructs the Protocol Services driver to abort the task.

    Declaration

    virtual SCSIServiceResponse HandleAbortTask ( UInt8 theLogicalUnit, SCSITaggedTaskIdentifier theTag );

    Parameters

    theLogicalUnit

    A valid logical unit number.

    theTag

    The tag of the command to abort.

    Return Value

    A valid SCSIServiceResponse.

    Discussion

    HandleAbortTask instructs the Protocol Services driver to abort the task.

  • HandleAbortTaskSet instructs the Protocol Services driver to abort the task set.

    Declaration

    virtual SCSIServiceResponse HandleAbortTaskSet ( UInt8 theLogicalUnit );

    Parameters

    theLogicalUnit

    A valid logical unit number.

    Return Value

    A valid SCSIServiceResponse.

    Discussion

    HandleAbortTaskSet instructs the Protocol Services driver to abort the task set.

  • Method called to check if the device is in the correct power state for an I/O.

    Declaration

    virtual void HandleCheckPowerState ( void );

    Discussion

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

  • HandleClearACA instructs the Protocol Services driver to clear an auto-contingent allegiance.

    Declaration

    virtual SCSIServiceResponse HandleClearACA ( UInt8 theLogicalUnit );

    Parameters

    theLogicalUnit

    A valid logical unit number.

    Return Value

    A valid SCSIServiceResponse.

    Discussion

    HandleClearACA instructs the Protocol Services driver to clear an auto-contingent allegiance.

  • HandleClearTaskSet instructs the Protocol Services driver to clear the task set.

    Declaration

    virtual SCSIServiceResponse HandleClearTaskSet ( UInt8 theLogicalUnit );

    Parameters

    theLogicalUnit

    A valid logical unit number.

    Return Value

    A valid SCSIServiceResponse.

    Discussion

    HandleClearTaskSet instructs the Protocol Services driver to clear the task set.

  • HandleLogicalUnitReset instructs the Protocol Services driver to reset the logical unit.

    Declaration

    virtual SCSIServiceResponse HandleLogicalUnitReset ( UInt8 theLogicalUnit );

    Parameters

    theLogicalUnit

    A valid logical unit number.

    Return Value

    A valid SCSIServiceResponse.

    Discussion

    HandleLogicalUnitReset instructs the Protocol Services driver to reset the logical unit.

  • This method is called to handle a power change.

    Declaration

    virtual void HandlePowerChange ( void );

    Discussion

    This method is called to handle a power change. It is called from a clean thread context (i.e. new thread, no locks held) and can make synchronous or asynchronous calls.

  • Convenience method for a protocol service driver to handle a power off call (called on the way to sleep).

    Declaration

    virtual IOReturn HandlePowerOff ( void );

    Return Value

    A valid IOReturn code.

    Discussion

    Convenience method for a protocol service driver to handle a power off call (called on the way to sleep). This method is guaranteed to be called after application layer drivers have been put to sleep.

  • Convenience method for a protocol service driver to handle a power on call (called on the way back up from sleep).

    Declaration

    virtual IOReturn HandlePowerOn ( void );

    Return Value

    A valid IOReturn code.

    Discussion

    Convenience method for a protocol service driver to handle a power on call (called on the way back up from sleep). Driver should perform any bus specific activity necessary to recover from power-on/wake from sleep (e.g. bus reset on ATAPI). This method is guaranteed to be called before application layer drivers have been awakened.

  • HandleProtocolServiceFeature instructs the Protocol Services driver to perform the necessary tasks for the indicated feature.

    Declaration

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

    Parameters

    feature

    A valid SCSIProtocolFeature.

    serviceValue

    A pointer to a value for the protocol feature.

    Return Value

    True if successful, otherwise false.

    Discussion

    HandleProtocolServiceFeature instructs the Protocol Services driver to perform the necessary tasks for the indicated feature.

  • HandleTargetReset instructs the Protocol Services driver to reset the target.

    Declaration

    virtual SCSIServiceResponse HandleTargetReset ( void );

    Return Value

    A valid SCSIServiceResponse.

    Discussion

    HandleTargetReset instructs the Protocol Services driver to reset the target.

  • Standard init method for all IORegistryEntry subclasses.

    Declaration

    virtual bool init ( OSDictionary *propTable = 0 );

    Parameters

    A

    dictionary that will become the registry entry's property table (retaining it), or zero which will cause an empty property table to be created.

    Return Value

    true on success, or false on a resource failure.

    Discussion

    A registry entry must be initialized with this method before it can be used. A property dictionary may passed and will be retained by this method for use as the registry entry's property table, or an empty one will be created.

  • Subclasses call this method to initialize power management.

    Declaration

    virtual void InitializePowerManagement ( IOService *provider );

    Parameters

    provider

    The provider to be joined to in the power management tree.

    Discussion

    Subclasses call this method to initialize power management. In the protocol services layer, this method calls the protocol interface layer to initialize power management state variables and then registers the protocol layer driver with the power manager with two(2) states, ON and OFF. Subclasses may override this behavior.

  • IsProtocolServiceSupported will return true if the specified feature is supported by the protocol layer.

    Declaration

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

    Parameters

    feature

    A valid SCSIProtocolFeature.

    serviceValue

    A pointer to a value for the protocol feature.

    Return Value

    True if the requested service is supported, otherwise false.

    Discussion

    IsProtocolServiceSupported will return true if the specified feature is supported by the protocol layer.

  • The Task Management function to reset a logical unit.

    Declaration

    SCSIServiceResponse LogicalUnitReset ( UInt8 theLogicalUnit );

    Parameters

    theLogicalUnit

    A logical unit for which to clear a task set.

    Return Value

    A valid SCSIServiceResponse.

    Discussion

    The Task Management function to reset a logical unit.

  • Internal method called to process completed SCSITasks.

    Declaration

    void ProcessCompletedTask ( SCSITaskIdentifier request, SCSIServiceResponse serviceResponse, SCSITaskStatus taskStatus );

    Parameters

    request

    A valid SCSITaskIdentifier.

    serviceResponse

    A valid SCSIServiceResponse value.

    taskStatus

    A valid SCSITaskStatus value.

    Discussion

    Internal method called to process completed SCSITasks. This method determines if a CHECK_CONDITION has occurred and if sense data was requested and autosense data is not present. If so, it will change the execution mode of the SCSITask and request sense data on behalf of the caller.

  • Used by IOSCSITargetDevice to register a completion routine.

    Declaration

    void RegisterSCSITaskCompletionRoutine ( SCSITaskCompletion completion );

    Parameters

    completion

    A SCSITaskCompletion routine.

    Discussion

    Used by IOSCSITargetDevice to register a completion routine. Internal use only.

  • Internal method called to reject currently enqueued SCSITasks.

    Declaration

    void RejectSCSITasksCurrentlyQueued ( void );

    Discussion

    Internal method called to reject currently enqueued SCSITasks. This method is typically called in response to device termination.

  • Internal method called to reject a particular SCSITask.

    Declaration

    void RejectTask ( SCSITaskIdentifier request );

    Parameters

    request

    A valid SCSITaskIdentifier.

    Discussion

    Internal method called to reject a particular SCSITask.

  • Internal method called to retrieve the next SCSITask to process.

    Declaration

    SCSITask * RetrieveNextSCSITaskFromQueue ( void );

    Return Value

    A valid SCSITask pointer or NULL if there are no tasks to process.

    Discussion

    Internal method called to retrieve the next SCSITask to process.

  • Method called by subclasses when a device is physically removed from the bus.

    Declaration

    void SendNotification_DeviceRemoved ( void );

    Discussion

    Method called by subclasses when a device is physically removed from the bus.

  • Method called by subclasses when a device state needs to be re-verified due to some bus condition which may have changed the device state.

    Declaration

    void SendNotification_VerifyDeviceState ( void );

    Discussion

    Method called by subclasses when a device state needs to be re-verified due to some bus condition which may have changed the device state.

  • Pure virtual method subclasses must implement in order to send SCSITasks on the wire.

    Declaration

    virtual bool SendSCSICommand ( SCSITaskIdentifier request, SCSIServiceResponse *serviceResponse, SCSITaskStatus *taskStatus ) = 0;

    Parameters

    request

    A valid SCSITaskIdentifier representing the command to send on the wire.

    serviceResponse

    Pointer to a SCSIServiceResponse value returned to the caller.

    taskStatus

    Pointer to a SCSITaskStatus value returned to the caller.

    Return Value

    False if no more commands can be processed at this time, otherwise true.

    Discussion

    Send a SCSI Command to the device. If the command was sent to the device and is pending completion, the subclass should return true and return back the kSCSIServiceResponse_Request_In_Process response. If the command completes immediately with an error, the subclass will return true and return back the appropriate status. If the subclass is currently processing all the commands it can, the subclass will return false and the command will be resent next time CommandCompleted is called.

  • Internal method called to start processing SCSITasks.

    Declaration

    void SendSCSITasksFromQueue ( void );

    Discussion

    Internal method called to start processing SCSITasks. Only one client or workloop thread may process SCSITasks at any point in time. This method coordinates to ensure only one thread does so.

  • Accessor method to set the autosense data. NOTE: This method is deprecated.

    Declaration

    bool SetAutoSenseData ( SCSITaskIdentifier request, SCSI_Sense_Data *senseData ) __attribute__ ((deprecated));

    Parameters

    request

    A valid SCSITaskIdentifier.

    senseData

    A pointer to a SCSI_Sense_Data structure to be copied. Only sizeof(struct SCSI_Sense_Data) bytes will be copied.

    Return Value

    True if sense data was successfully copied, otherwise false.

    Discussion

    Accessor method to set the autosense data. NOTE: This method is deprecated.

  • Accessor method to set the autosense data.

    Declaration

    bool SetAutoSenseData ( SCSITaskIdentifier request, SCSI_Sense_Data *senseData, UInt8 senseDataSize );

    Parameters

    request

    A valid SCSITaskIdentifier.

    senseData

    A pointer to sense data to be copied.

    senseDataSize

    Number of bytes to copy.

    Return Value

    True if sense data was successfully copied, otherwise false.

    Discussion

    Accessor method to set the autosense data.

  • Accessor method to set the protocol layer reference.

    Declaration

    bool SetProtocolLayerReference ( SCSITaskIdentifier request, void *newReferenceValue );

    Parameters

    request

    A valid SCSITaskIdentifier.

    newReferenceValue

    Pointer to reference data.

    Return Value

    True on success, otherwise false.

    Discussion

    Accessor method to set the protocol layer reference.

  • Accessor method to set the realized (actual) data transfer count associated with the specified request.

    Declaration

    bool SetRealizedDataTransferCount ( SCSITaskIdentifier request, UInt64 newRealizedDataCount );

    Parameters

    request

    A valid SCSITaskIdentifier.

    newRealizedDataCount

    The realized (actual) data count transferred.

    Return Value

    True on success, otherwise false.

    Discussion

    Accessor method to set the realized (actual) data transfer count associated with the specified request.

  • Internal method used to set the task execution mode.

    Declaration

    bool SetTaskExecutionMode ( SCSITaskIdentifier request, SCSITaskMode newTaskMode );

    Parameters

    request

    A valid SCSITaskIdentifier.

    newTaskMode

    A valid SCSITaskMode value.

    Return Value

    True on success, otherwise false.

    Discussion

    Internal method used to set the task execution mode.

  • Accessor method to set the SCSITaskState associated with the specified request.

    Declaration

    bool SetTaskState ( SCSITaskIdentifier request, SCSITaskState newTaskState );

    Parameters

    request

    A valid SCSITaskIdentifier.

    newTaskState

    A valid SCSITaskState value.

    Return Value

    True on success, otherwise false.

    Discussion

    Accessor method to set the SCSITaskState associated with the specified request.

  • 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

    The start method of an IOService instance is called by its provider when it has been selected (due to its probe score and match category) as the winning client. The client is already attached to the provider when start is called.

    Implementations of start must call start on their superclass at an appropriate point. If an implementation of start has already called super::start but subsequently determines that it will fail, it must call super::stop to balance the prior call to super::start and prevent reference leaks.

  • The Task Management function to reset a target device.

    Declaration

    SCSIServiceResponse TargetReset ( void );

    Return Value

    A valid SCSIServiceResponse.

    Discussion

    The Task Management function to reset a target device.

  • Internal method. Do not use.

    Declaration

    virtual void TicklePowerManager ( void );

    Discussion

    Internal method. Do not use.