IOSCSIProtocolServices

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

Overview

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

Tasks

Miscellaneous

Instance Methods

AbortCommand

Deprecated. Do not use.

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

Deprecated. Do not use.

AbortSCSICommand

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

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.

AbortSCSITaskFromQueue

Deprecated internal method.

bool AbortSCSITaskFromQueue ( SCSITask *request );
Discussion

Deprecated internal method.

AbortTask

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

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.

AbortTaskSet

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

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.

AddSCSITaskToHeadOfQueue

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

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.

AddSCSITaskToQueue

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

void AddSCSITaskToQueue ( SCSITaskIdentifier request );
Parameters
request

A valid SCSITaskIdentifier.

Discussion

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

ClearACA

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

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.

ClearTaskSet

The Task Management function to clear a task set.

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.

CommandCompleted

Method subclass calls to complete a SCSITask.

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.

CreateSCSITargetDevice

Used to create a SCSITargetDevice which will manage logical units.

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.

EnsureAutosenseDescriptorExists

Internal method, not to be called by subclasses.

void EnsureAutosenseDescriptorExists ( SCSITaskIdentifier request );
Parameters
request

A valid SCSITaskIdentifier.

Discussion

Internal method, not to be called by subclasses.

ExecuteCommand

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

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.

free

Frees data structures that were allocated during start().

virtual void free ( void );
Discussion

Frees data structures that were allocated during start().

GetAutosenseRequestedDataTransferCount

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

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.

GetCommandDescriptorBlock

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

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.

GetCommandDescriptorBlockSize

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

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.

GetDataBuffer

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

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.

GetDataBufferOffset

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

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.

GetDataTransferDirection

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

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.

GetInitialPowerState

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

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

GetLogicalUnitBytes

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

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.

GetLogicalUnitNumber

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

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

GetProtocolLayerReference

Accessor method to retrieve the protocol layer reference.

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.

GetRealizedDataTransferCount

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

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.

GetRequestedDataTransferCount

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

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.

GetTaskAttribute

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

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.

GetTaskExecutionMode

Internal method used to retrieve the task execution mode.

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.

GetTaskState

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

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.

GetTimeoutDuration

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

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

HandleAbortTask instructs the Protocol Services driver to abort the task.

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

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

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.

HandleCheckPowerState

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

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

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

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

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

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

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

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.

HandlePowerChange

This method is called to handle a power change.

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.

HandlePowerOff

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

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.

HandlePowerOn

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

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

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

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

HandleTargetReset instructs the Protocol Services driver to reset the target.

virtual SCSIServiceResponse HandleTargetReset ( void );
Return Value

A valid SCSIServiceResponse.

Discussion

HandleTargetReset instructs the Protocol Services driver to reset the target.

init

Standard init method for all IORegistryEntry subclasses.

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.

InitializePowerManagement

Subclasses call this method to initialize power management.

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

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

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.

LogicalUnitReset

The Task Management function to reset a logical unit.

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.

ProcessCompletedTask

Internal method called to process completed SCSITasks.

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.

RegisterSCSITaskCompletionRoutine

Used by IOSCSITargetDevice to register a completion routine.

void RegisterSCSITaskCompletionRoutine ( SCSITaskCompletion completion );
Parameters
completion

A SCSITaskCompletion routine.

Discussion

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

RejectSCSITasksCurrentlyQueued

Internal method called to reject currently enqueued SCSITasks.

void RejectSCSITasksCurrentlyQueued ( void );
Discussion

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

RejectTask

Internal method called to reject a particular SCSITask.

void RejectTask ( SCSITaskIdentifier request );
Parameters
request

A valid SCSITaskIdentifier.

Discussion

Internal method called to reject a particular SCSITask.

RetrieveNextSCSITaskFromQueue

Internal method called to retrieve the next SCSITask to process.

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.

SendNotification_DeviceRemoved

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

void SendNotification_DeviceRemoved ( void );
Discussion

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

SendNotification_VerifyDeviceState

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.

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.

SendSCSICommand

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

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.

SendSCSITasksFromQueue

Internal method called to start processing SCSITasks.

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.

SetAutoSenseData(SCSITaskIdentifier, SCSI_Sense_Data *)

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

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.

SetAutoSenseData(SCSITaskIdentifier, SCSI_Sense_Data *, UInt8)

Accessor method to set the autosense data.

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.

SetProtocolLayerReference

Accessor method to set the protocol layer reference.

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.

SetRealizedDataTransferCount

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

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.

SetTaskExecutionMode

Internal method used to set the task execution mode.

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.

SetTaskState

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

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.

start

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

virtual bool start ( IOService *provider );
Return Value

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

Discussion

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.

TargetReset

The Task Management function to reset a target device.

SCSIServiceResponse TargetReset ( void );
Return Value

A valid SCSIServiceResponse.

Discussion

The Task Management function to reset a target device.

TicklePowerManager

Internal method. Do not use.

virtual void TicklePowerManager ( void );
Discussion

Internal method. Do not use.