IOSCSIParallelInterfaceController

Inherits from
IOService
Availability
Available in OS X v10.2 and later.
Declared in
IOSCSIParallelInterfaceController.h

Overview

Class that represents a SCSI Host Bus Adapter.

Class that represents a SCSI Host Bus Adapter.

Tasks

Miscellaneous

Instance Methods

CompleteParallelTask

Parallel Task Completion

void CompleteParallelTask ( SCSIParallelTaskIdentifier parallelRequest, SCSITaskStatus completionStatus, SCSIServiceResponse serviceResponse );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

completionStatus

The status of the SCSI bus.

serviceResponse

(see <IOKit/scsi/SCSITask.h>)

Discussion

The HBA specific sublcass inherits the CompleteParallelTask() method which shall be called when the HBA has completed the processing of a parallel task.

CreateDeviceInterrupt

Called to create an IOInterruptEventSource for the device. Subclasses may wish to use a different interrupt index than 0 (e.g. for using PCI Message Signaled Interrupts) or might not need an interrupt at all (virtual HBA).

virtual IOInterruptEventSource * CreateDeviceInterrupt ( IOInterruptEventSource::Action action, IOFilterInterruptEventSource::Filter filter, IOService *provider );
Parameters
action

A pointer to the action routine that should be passed to either IOInterruptEventSource::interruptEventSource() or IOFilterInterruptEventSource::filterInterruptEventSource as the method to call when an interrupt occurs for the device (sometimes called the "deferred procedure call" or the "secondary context method". By passing this routine along, it will properly wire up the HandleInterruptRequest() method you should override to handle interrupts.

filter

A pointer to the filter routine that should be passed to IOFilterInterruptEventSource::filterInterruptEventSource as the method to call at primary interrupt time when an interrupt occurs for the device. By passing this routine along, it will properly wire up the FilterInterruptRequest() method you may override to handle primary interrupts.

Return Value

IOInterruptEventSource. May return NULL if and only if there is no hardware interrupt associated with this device.

CreateTargetForID(SCSIDeviceIdentifier)

Method to perform device creation.

bool CreateTargetForID ( SCSIDeviceIdentifier targetID );
Parameters
targetID

SCSIDeviceIdentifier of desired targetID.

Return Value

returns true if successful.

Discussion

For HBA child classes that report true to the DoesHBAPerformDeviceManagement() method, the child class will be responsible for all device management by using these methods; otherwise, the superclass will be responsible for all device management. This method must be used to perform SCSI Parallel Device creation and cannot be overridden.

CreateTargetForID(SCSIDeviceIdentifier, OSDictionary *)

Method to perform device creation.

bool CreateTargetForID ( SCSIDeviceIdentifier targetID, OSDictionary *properties );
Parameters
targetID

SCSIDeviceIdentifier of desired targetID.

properties

A dictionary of properties to associate with the device upon creation. The list of valid property keys is as follows: kIOPropertySASAddressKey, kIOPropertyFibreChannelNodeWorldWideNameKey, kIOPropertyFibreChannelPortWorldWideNameKey, kIOPropertyFibreChannelAddressIdentifierKey, kIOPropertyFibreChannelALPAKey, and kIOPropertyRetryCountKey These keys are defined in <IOKit/storage/IOStorageProtocolCharacteristics.h> and the values associated with these keys must be of the proper type/size, or the target creation will not succeed.

Return Value

returns true if successful.

Discussion

For HBA child classes that report true to the DoesHBAPerformDeviceManagement() method, the child class will be responsible for all device management by using these methods; otherwise, the superclass will be responsible for all device management. This method must be used to perform SCSI Parallel Device creation and cannot be overridden.

DestroyTargetForID

Method to perform device destruction.

void DestroyTargetForID ( SCSIDeviceIdentifier targetID );
Parameters
targetID

SCSIDeviceIdentifier of desired targetID.

Discussion

For HBA child classes that report true to the DoesHBAPerformDeviceManagement() method, the child class will be responsible for all device management by using these methods; otherwise, the superclass will be responsible for all device management. This method must be used to perform SCSI Parallel Device destruction and cannot be overridden.

DisableInterrupt

Disable Interrupt

void DisableInterrupt ( void );
Discussion

Method that the HBA child class can call to disable the associated IOInterruptEventSource.

DoesHBAPerformAutoSense

Queries the HBA child class to determine if it automatically performs AutoSense and provides AutoSense data for each I/O. If the HBA allocates space for AutoSense in its HBA specific data region on a per task basis, the HBA should respond true.

virtual bool DoesHBAPerformAutoSense ( void );
Return Value

Return true if HBA performs AutoSense into its own private data buffer.

Discussion

Queries the HBA child class to determine if it automatically performs AutoSense and provides AutoSense data for each I/O. If the HBA allocates space for AutoSense in its HBA specific data region on a per task basis, the HBA should respond true.

DoesHBAPerformDeviceManagement

Determine if HBA will manage devices.

virtual bool DoesHBAPerformDeviceManagement ( void ) = 0;
Return Value

return true means objects for target devices will only be created when the child class calls the CreateTargetForID method.

Discussion

This method is used to determine if the HBA will manage target device creation and destruction.

DoesHBASupportMultiPathing

Queries the HBA child class to determine if it supports Multi-Pathing.

virtual bool DoesHBASupportMultiPathing ( void );
Return Value

Returns true if requested feature is supported.

Discussion

Queries the HBA child class to determine if it supports Multi-Pathing.

DoesHBASupportSCSIParallelFeature

Queries the HBA child class to determine if it supports a specific SPI feature.

virtual bool DoesHBASupportSCSIParallelFeature ( SCSIParallelFeature theFeature ) = 0;
Return Value

Returns true if requested feature is supported.

Discussion

Queries the HBA child class to determine if it supports the specified feature as defined by the SCSI Parallel Interconnect specifications.

EnableInterrupt

Enable Interrupt

void EnableInterrupt ( void );
Discussion

Method that the HBA child class can call to enable the associated IOInterruptEventSource.

ExecuteParallelTask

Submit a SCSIParallelTask for execution.

SCSIServiceResponse ExecuteParallelTask ( SCSIParallelTaskIdentifier parallelRequest );
Parameters
parallelRequest

is a reference to the SCSIParallelTaskIdentifier to be executed.

Return Value

is an appropriate SCSIServiceResponse which are defined in the file <IOKit/scsi/SCSITask.h>.

Discussion

The ExecuteParallelTask call is made by the client to submit a SCSIParallelTask for execution.

FilterInterruptRequest

Filter method called at primary interrupt time.

virtual bool FilterInterruptRequest ( void );
Return Value

True if the hardware interrupt line should be disabled, otherwise false.

Discussion

Filter method called at primary interrupt time. This should only be overridden by the child class in order to determine if an interrupt occurred for this controller instance. Since all work occurs at primary interrupt time, this routine should be quick and efficient and defer as much processing as possible to the HandleInterruptRequest() method.

NOTE: Unlike the HandleInterruptRequest() and HandleTimeout() methods, FilterInterruptRequest() is NOT called with the workloop lock held.

If the value returned by FilterInterruptRequest() is true, the secondary interrupt thread will be scheduled and the hardware interrupt line will be disabled. If the controller instance shares that interrupt line with other devices, it can cause large interrupt latencies. If the controller instance can disable the interrupt in the chip itself, the following can be done to reduce interrupt latencies:

- Interrupt occurs - FilterInterruptRequest() method is called. - If the interrupt is not for this controller, return false immediately. - If the interrupt is for this controller, and the controller can disable interrupts for this chip, the controller should disable the interrupts for this chip, call SignalInterrupt(), and return false. This causes the secondary interrupt thread to get scheduled, yet does not disable the interrupt line for all devices tied to that interrupt. This effectively allows other devices to process their interrrupts, thus reducing interrupt latency for those devices. - HandleInterruptRequest() method is called. - Controller processes interrupt and completes I/O requests. - Controller re-enables interrupts for the device.

NOTE: If you use this approach, the interrupting condition MUST be cleared from the hardware, otherwise an infinite process interrupt loop will occur.

If the controller cannot disable interrupts on the chip, it should simply return true if an interrupt has occurred for its device.

FindTaskForAddress

Find a task for a given Task Address, if one exists.

SCSIParallelTaskIdentifier FindTaskForAddress ( SCSIDeviceIdentifier theT, SCSILogicalUnitNumber theL, SCSITaggedTaskIdentifier theQ );
Parameters
theT

is the Target component of the I_T_L or I_T_L_Q nexus.

theL

is the Logical Unit component of the I_T_L or I_T_L_Q nexus.

theQ

is the Queue Tag component of the I_T_L_Q nexus. If this is an I_T_L nexus, then the kSCSIUntaggedTaskIdentifier constant should be used for theQ.

Return Value

returns a valid SCSIParallelTaskIdentifier or NULL if none found.

Discussion

If a valid Tagged Task Identifier is specified, this method will return the task specified by the Tagged Task Address if one is found, or else NULL will be returned. If zero is used as the Tagged Task Identifier, then this routine will search for an outstanding task based on the Untagged Task Address and return the task or else, if one is not found, return NULL.

FindTaskForControllerIdentifier

Find a task for a given Target and Controller Task Identifier

SCSIParallelTaskIdentifier FindTaskForControllerIdentifier ( SCSIDeviceIdentifier theTarget, UInt64 theIdentifier );
Parameters
theTarget

is the Target that the task .

theIdentifier

is the controller task identifier set using the SCSI Parallel Task's SetControllerTaskIdentifier() method.

Return Value

returns a valid SCSIParallelTaskIdentifier or NULL if none found.

Discussion

Allows the controller child class to find an outstanding task for a specified target and controller task identifier

FreeSCSIParallelTask

Method to allow the client to release a SCSIParallelTask

void FreeSCSIParallelTask ( SCSIParallelTaskIdentifier returnTask );
Parameters
returnTask

is a reference to the SCSIParallelTaskIdentifier to be returned.

Discussion

The FreeSCSIParallelTask method is called by the client when a SCSIParallelTask has been completed and the associated returnTask needs to be returned to the pool.

GetAutoSenseData

Method to retrieve auto sense data buffer associated with a request.

bool GetAutoSenseData ( SCSIParallelTaskIdentifier parallelTask, SCSI_Sense_Data *receivingBuffer, UInt8 senseDataSize );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

receivingBuffer

pointer to auto sense data buffer

Return Value

returns true if successfully copied data into receivingBuffer

GetAutoSenseDataSize

Method to retrieve auto sense data buffer size associated with a request.

UInt8 GetAutoSenseDataSize ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

returns Size of auto sense data buffer.

GetCommandDescriptorBlock

Method to retrieve the SCSI Command Descriptor Block (CDB).

bool GetCommandDescriptorBlock ( SCSIParallelTaskIdentifier parallelTask, SCSICommandDescriptorBlock *cdbData );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

cdbData

is a SCSICommandDescriptorBlock pointer to 16 byte CDB

Return Value

returns true if data was copied to cdbData pointer

Discussion

This will always return a 16 Byte CDB. If the Protocol Layer driver does not support 16 Byte CDBs, it will have to create a local SCSICommandDescriptorBlock variable to get the CDB data and then transfer the needed bytes from there.

GetCommandDescriptorBlockSize

Method to retrieve the size of the SCSI Command Descriptor Block (CDB).

UInt8 GetCommandDescriptorBlockSize ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

returns the size of the SCSI Command Descriptor Block in bytes.

GetCommandGate

Accessor to get an IOCommandGate associated with the workloop.

IOCommandGate * GetCommandGate ( void );
Return Value

returns pointer to IOCommandGate.

Discussion

Accessor to get an IOCommandGate associated with the workloop.

GetDataBuffer

Method to retrieve client buffer from the request.

IOMemoryDescriptor * GetDataBuffer ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

returns pointer to an IOMemoryDescriptor which represents the buffer.

GetDataBufferOffset

Method to retrieve offset into client buffer at which to start processing.

UInt64 GetDataBufferOffset ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

returns offset in bytes

GetDataTransferDirection

Retrieves the data transfer direction for any data associated with the request.

UInt8 GetDataTransferDirection ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

One of the valid data transfer directions described in <IOKit/scsi/SCSITask.h>

GetDMACommand

Method to retrieve a pointer to an IODMACommand from the request.

IODMACommand * GetDMACommand ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

returns pointer to an IODMACommand which is used in conjunction with the task.

Discussion

For devices utilizing DMA, the IODMACommand object should be obtained via GetDMACommand(). The subclass is responsible for calling prepare() on the IODMACommand object using the proper offset obtained via GetDataBufferOffset() and correct size obtained via GetRequestedDataTransferCount(). The subclass is further responsible for calling complete() on the IODMACommand object once all DMA operations have finished. NB: Subclasses should not call IODMACommand::setMemoryDescriptor().

GetHBADataDescriptor

Method to retrieve the IOMemoryDescriptor associated with the HBA Data.

IOMemoryDescriptor * GetHBADataDescriptor ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

returns pointer to an IOMemoryDescriptor that wraps the HBA specific data buffer, NULL if none found or GetHBADataSize() returns zero.

Discussion

Method to retrieve the IOMemoryDescriptor associated with the HBA Data.

GetHBADataPointer

Method to retrieve the HBA Data pointer.

void * GetHBADataPointer ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

returns pointer to buffer for HBA specific data, NULL if none found or GetHBADataSize() returns zero.

Discussion

Method to retrieve the HBA Data pointer.

GetHBADataSize

Method to retrieve the HBA Data Size in bytes.

UInt32 GetHBADataSize ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

returns HBA Data size in bytes.

Discussion

Method to retrieve the HBA Data Size in bytes.

GetHBATargetDataPointer

Method to retrieve the HBA Data pointer.

void * GetHBATargetDataPointer ( SCSITargetIdentifier targetID );
Parameters
targetDevice

A valid SCSITargetIdentifier.

Return Value

returns pointer to buffer for HBA specific data, NULL if none found or GetHBADataSize is zero.

Discussion

Method to retrieve the HBA Data pointer.

GetHBATargetDataSize

Method to retrieve the HBA Data Size in bytes.

UInt32 GetHBATargetDataSize ( SCSITargetIdentifier targetID );
Parameters
targetDevice

A valid SCSITargetIdentifier.

Return Value

returns HBA Data size in bytes.

Discussion

Method to retrieve the HBA Data Size in bytes.

GetLogicalUnitBytes

Method to get the logical unit bytes associated with a request.

void GetLogicalUnitBytes ( SCSIParallelTaskIdentifier parallelTask, SCSILogicalUnitBytes *logicalUnitBytes );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

returns a valid 8-byte logical unit address.

Discussion

Method to get the logical unit bytes associated with a request.

GetLogicalUnitNumber

Method to get the logical unit number associated with a request.

SCSILogicalUnitNumber GetLogicalUnitNumber ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

returns a valid 64-bit logical unit number.

Discussion

Method to get the logical unit number associated with a request.

GetProvider

Accessor method to get the IOService which is the controller's provider.

IOService * GetProvider ( void );
Return Value

returns pointer to IOService.

Discussion

Accessor method to get the IOService which is the controller's provider.

GetRealizedDataTransferCount

Retrieves the realized data transfer count for any data associated with the request.

UInt64 GetRealizedDataTransferCount ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

The realized data transfer count in bytes.

GetRequestedDataTransferCount

Retrieves the requested data transfer count for any data associated with the request.

UInt64 GetRequestedDataTransferCount ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

The requested data transfer count in bytes.

GetSCSIDomainIdentifier

Accessor method to get the SCSI Domain Identifier.

SInt32 GetSCSIDomainIdentifier ( void );
Return Value

returns SCSI Domain Identifier.

Discussion

Accessor method to get the SCSI Domain Identifier.

GetSCSIParallelFeatureNegotiation

Method to retrieve the requested value for negotiation of the.

SCSIParallelFeatureRequest GetSCSIParallelFeatureNegotiation ( SCSIParallelTaskIdentifier parallelTask, SCSIParallelFeature requestedFeature );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

A valid SCSIParallelFeatureControl.

Discussion

Query as to whether the SCSI Parallel Device object has negotiated wide data transfers.

GetSCSIParallelFeatureNegotiationCount

Method to retrieve the number of requested negotiations.

UInt64 GetSCSIParallelFeatureNegotiationCount ( SCSIParallelTaskIdentifier parallelTask);
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

an unsigned integer up to 64 bits in size.

Discussion

Query as to the number of SCSI Parallel Features that are requested to either be negotitated or cleared. These are all features that are set to either kSCSIParallelFeature_AttemptNegotiation or kSCSIParallelFeature_ClearNegotiation. If the return value is zero, then all features are set to kSCSIParallelFeature_NoNegotiation and all feature negotiations are to remain as they currently exist.

GetSCSIParallelFeatureNegotiationResult

Method to retrieve the result of any wide transfer negotiations.

SCSIParallelFeatureResult GetSCSIParallelFeatureNegotiationResult ( SCSIParallelTaskIdentifier parallelTask, SCSIParallelFeature requestedFeature );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

A valid SCSIParallelFeatureResult.

Discussion

Query as to whether the SCSI Parallel Controller object has negotiated wide data transfers.

GetSCSIParallelFeatureNegotiationResultCount

Method to retrieve the number of changed negotiations.

UInt64 GetSCSIParallelFeatureNegotiationResultCount ( SCSIParallelTaskIdentifier parallelTask);
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

an unsigned integer up to 64 bits in size.

Discussion

Query as to the number of SCSI Parallel Features that have been changed to either negotitated or cleared. These are all features that are set to either kSCSIParallelFeature_NegotitiationCleared or kSCSIParallelFeature_NegotitiationSuccess. If the return value is zero, then all features are set to kSCSIParallelFeature_NegotitiationUnchanged.

GetSCSIParallelTask

Method to allow the client to get a SCSIParallelTask

SCSIParallelTaskIdentifier GetSCSIParallelTask ( bool blockForCommand );
Parameters
blockForCommand

If the blockForCommand parameter is set to false and there are no free SCSIParallelTasks, this method will return NULL, otherwise it will wait for one to become available before returning.

Return Value

If there is a SCSI Parallel Task available, a reference to it will be returned.

Discussion

Get a SCSIParallelTask from the controller so that a request can be issued to the HBA driver.

GetSCSITaskIdentifier

Method to retrieve a SCSITaskIdentifier from a valid SCSIParallelTaskIdentifier.

SCSITaskIdentifier GetSCSITaskIdentifier ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

returns SCSITaskIdentifier that represents the original request from the SCSI Application Layer client.

Discussion

Method to retrieve a SCSITaskIdentifier from a valid SCSIParallelTaskIdentifier.

GetTaggedTaskIdentifier

Method to retrieve the SCSI Tagged Task Identifier of the task. If the returned value is equal to kSCSIUntaggedTaskIdentifier, then this task is untagged.

SCSITaggedTaskIdentifier GetTaggedTaskIdentifier ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

an SCSITaskAttribute value.

GetTargetForID

Accessor for getting pointer to IOSCSIParallelInterfaceDevice.

IOSCSIParallelInterfaceDevice * GetTargetForID ( SCSIDeviceIdentifier targetID );
Parameters
targetID

SCSIDeviceIdentifier of desired targetID.

Return Value

returns pointer to IOSCSIParallelInterfaceDevice or NULL if not found.

GetTargetIdentifier

Method to get the SCSITargetIdentifier associated with a request.

SCSITargetIdentifier GetTargetIdentifier ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

returns SCSITargetIdentifier

Discussion

Method to get the SCSITargetIdentifier associated with a request.

GetTaskAttribute

Method to retrieve the SCSI Task Attribute of the task

SCSITaskAttribute GetTaskAttribute ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

an SCSITaskAttribute value.

GetTimeoutDuration

Method to retrieve the timeout duration in milliseconds for a request.

UInt32 GetTimeoutDuration ( SCSIParallelTaskIdentifier parallelTask );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

Return Value

returns timeout duration in milliseconds

Discussion

Method to retrieve the timeout duration in milliseconds for a request. A value of zero represents an infinite timeout, or on hardware where infinite timeouts are not possible, substitute the longest timeout possible.

GetWorkLoop

Accessor method to get the IOWorkLoop associated with this HBA.

IOWorkLoop * GetWorkLoop ( void ) const;
Return Value

returns pointer to IOWorkLoop.

Discussion

Accessor method to get the IOWorkLoop associated with this HBA.

HandleInterruptRequest

Handle Interrupt Request

virtual void HandleInterruptRequest ( void ) = 0;
Discussion

The HandleInterruptRequest is used to notify an HBA specific subclass that an interrupt request needs to be serviced. It is called on the workloop (it holds the gate) at secondary interrupt level.

HandleTimeout

Method to handle command timeouts.

virtual void HandleTimeout ( SCSIParallelTaskIdentifier parallelRequest );
Parameters
parallelRequest

A valid SCSIParallelTaskIdentifier.

Discussion

Method to handle command timeouts. This should be overridden by the child class in order to clean up HBA specific structures after a timeout has occurred. This method is called on the workloop (it holds the gate).

IncrementRealizedDataTransferCount

Increments the realized data transfer count. This method is helpful for when the HBA has to do multiple passes of DMA because there are more scatter-gather elements than it can process in one pass.

void IncrementRealizedDataTransferCount ( SCSIParallelTaskIdentifier parallelTask, UInt64 realizedTransferCountInBytes );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

realizedTransferCountInBytes

is the number of bytes to add to the realized data count for the task.

InitializeController

Called to initialize the controller

virtual bool InitializeController ( void ) = 0;
Return Value

return true means that initialization was successful.

Discussion

It is guaranteed that the InitializeController() will only be called once per instantiation. The InitializeController() methods allows the subclass driver to do all the necessary initialization required by the hardware before it is able to accept requests to execute. All necessary allocation of resources should be made during this method call. This is the first method that will be called in the subclass.

InitializeDMASpecification

Called to initialize an IODMACommand with a DMA specification.

virtual bool InitializeDMASpecification ( IODMACommand *command );
Parameters
command

A pointer to a valid IODMACommand object. Subclasses should override this method and call IODMACommand::initWithSpecification() supplying the proper arguments to that method based on the DMA strategy.

Return Value

boolean value indicating success or failure.

InitializeTargetForID

Called to initialize a target device.

virtual bool InitializeTargetForID ( SCSITargetIdentifier targetID ) = 0;
Return Value

Returns true if the target was successfully initialized.

Discussion

This method will be called to initialize a target device in a single-threaded manner. The HBA can use this method to probe the target or do anything else necessary before the device object is registered with IOKit for matching.

NotifyClientsOfBusReset

Method called to notify clients that a bus reset has occurred.

void NotifyClientsOfBusReset ( void );
Discussion

This method is used by the HBA child class to inform the parent class and any clients that a bus reset has occurred.

NotifyClientsOfPortStatusChange

Method called to notify clients of port status change events.

void NotifyClientsOfPortStatusChange ( SCSIPortStatus newStatus );
Discussion

This method is used by the HBA child class to inform the parent class and any clients that a port has changed status.

ProcessParallelTask

Called by client to process a parallel task.

virtual SCSIServiceResponse ProcessParallelTask ( SCSIParallelTaskIdentifier parallelRequest ) = 0;
Parameters
parallelRequest

A valid SCSIParallelTaskIdentifier.

Return Value

serviceResponse (see <IOKit/scsi/SCSITask.h>)

Discussion

This method is called to process a parallel task (i.e. put the command on the bus). The HBA specific sublcass must implement this method.

RemoveHBAProperty

Accessor for removing a property for this object.

void RemoveHBAProperty ( const char *key );
Parameters
key

A pointer to a valid OSString object which represents the key. See the SetHBAProperty() method for a list of valid keys.

RemoveTargetProperty

Accessor for removing a property from a specific target.

void RemoveTargetProperty ( SCSIDeviceIdentifier targetID, const char *key );
Parameters
device

A pointer to a valid IOSCSIParallelInterfaceDevice.

key

A pointer to a valid OSString object which represents the key.

ReportHBAConstraints

Called to report the I/O constraints for this controller. A list of valid keys includes: kIOMaximumSegmentCountReadKey, (required) kIOMaximumSegmentCountWriteKey, (required) kIOMaximumSegmentByteCountReadKey, (required) kIOMaximumSegmentByteCountWriteKey, (required) kIOMinimumSegmentAlignmentByteCountKey, (required) kIOMaximumSegmentAddressableBitCountKey, (required) kIOMinimumHBADataAlignmentMaskKey (required) kIOHierarchicalLogicalUnitSupportKey (optional). NB: These keys and their values are described in this header and <IOKit/IOKitKeys.h>

virtual void ReportHBAConstraints ( OSDictionary *constraints );
Parameters
constraints.

An OSDictionary object used to aggregate the key/value pairs. Subclasses must set the required keys if they override this method. If a subclass does not provide the required keys, the system will panic.

ReportHBAHighestLogicalUnitNumber

Gets the Highest Logical Unit Number.

virtual SCSILogicalUnitNumber ReportHBAHighestLogicalUnitNumber ( void ) = 0;
Return Value

returns a valid 64-bit logical unit number.

Discussion

This method is used to query the HBA child class to determine what the highest Logical Unit Number that the controller can address.

ReportHBASpecificDeviceDataSize

Determine memory needed for HBA Device specific use.

virtual UInt32 ReportHBASpecificDeviceDataSize ( void ) = 0;
Return Value

returns memory required in bytes

Discussion

This method is used to retrieve the amount of memory that will be allocated in the SCSI Parallel Device for HBA specific use.

ReportHBASpecificTaskDataSize

Determine memory needed for HBA Task specific use.

virtual UInt32 ReportHBASpecificTaskDataSize ( void ) = 0;
Return Value

returns memory required in bytes

Discussion

This method is used to retrieve the amount of memory that will be allocated in the SCSI Parallel Task for HBA specific use.

ReportHighestSupportedDeviceID

Get the highest supported SCSI Device Identifier.

virtual SCSIDeviceIdentifier ReportHighestSupportedDeviceID ( void ) = 0;
Return Value

returns highest SCSIDeviceIdentifier

Discussion

This method will be called to determine the value of the highest SCSI Device Identifier supported by the HBA. This value will be used to determine the last ID to process.

ReportInitiatorIdentifier

Get the SCSI Device Identifier for the HBA.

virtual SCSIInitiatorIdentifier ReportInitiatorIdentifier ( void ) = 0;
Return Value

returns SCSIInitiatorIdentifier.

Discussion

This method will be called to determine the SCSI Device Identifier that the Initiator has assigned for this HBA.

ReportMaximumTaskCount

Report Maximum Task Count

virtual UInt32 ReportMaximumTaskCount ( void ) = 0;
Return Value

returns maximum (non-zero) task count.

Discussion

This method will be called to retrieve the maximum number of outstanding tasks the HBA can process. This number must be greater than zero or the controller driver will fail to match and load.

ResumeServices

Called to resume controller services

virtual void ResumeServices ( void );
Discussion

Method that will be called to resume services provided by the driver. ( See SuspendServices discussion )

SetAutoSenseData

Method to set the auto sense data buffer associated with a request.

bool SetAutoSenseData ( SCSIParallelTaskIdentifier parallelTask, SCSI_Sense_Data *newSenseData, UInt8 senseDataSize );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

newSensedata

pointer to auto sense data buffer

Return Value

returns true if data in newSenseData was succesfully into the task object

SetControllerTaskIdentifier

Method to set the Controller Task Identifier.

void SetControllerTaskIdentifier ( SCSIParallelTaskIdentifier parallelTask, UInt64 newIdentifier );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

newIdentifier

unsigned 64 bit integer token.

Return Value

none

Discussion

This method allows the Controller Child Class driver to set a unique identifier to associate with the specified SCSI Parallel Task. This identifier is designed to be used by controllers that do not have access to the LUN and Tag information when notified by the HBA that a request has completed. If the kSCSIParallelTaskControllerIDQueueHead is used, this member routine will return the first Task on the queue.

SetHBAProperty

Accessor for setting a property for this object.

bool SetHBAProperty ( const char *key, OSObject *value );
Parameters
key

A pointer to a valid OSString object which represents the key. A list of valid keys includes: kIOPropertyVendorNameKey, kIOPropertyProductNameKey, kIOPropertyProductRevisionLevelKey, kIOPropertyPortDescriptionKey, kIOPropertyPortSpeedKey, kIOPropertyPortTopologyKey, kIOPropertySCSIParallelSignalingTypeKey, kIOPropertyFibreChannelCableDescriptionKey, kIOPropertyFibreChannelNodeWorldWideNameKey, kIOPropertyFibreChannelPortWorldWideNameKey, kIOPropertyFibreChannelAddressIdentifierKey, kIOPropertyFibreChannelALPAKey, and kIOPropertySASAddressKey. NB: These keys and their values are described in <IOKit/storage/IOStorageDeviceCharacteristics.h> and <IOKit/storage/IOStorageProtocolCharacteristics.h>

value

Pointer to an OSObject (one of type OSData, OSString, etc.) which represents the value for the property. The value must be of the proper type, and/or size for the specified key.

Return Value

returns true if identifier was properly set, otherwise false.

SetRealizedDataTransferCount

Sets the realized data transfer count in bytes.

bool SetRealizedDataTransferCount ( SCSIParallelTaskIdentifier parallelTask, UInt64 realizedTransferCountInBytes );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

realizedTransferCountInBytes

is the number of bytes actually transferred.

Return Value

true means the data transfer count was successfully set.

SetSCSIParallelFeatureNegotiationResult

Method to set the wide data transfer negotiation result.

void SetSCSIParallelFeatureNegotiationResult ( SCSIParallelTaskIdentifier parallelTask, SCSIParallelFeature requestedFeature, SCSIParallelFeatureResult newResult );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

requestedFeature

The SCSIParallelFeature that the has been set to newResult.

newResult

A valid SCSIParallelFeatureResult value.

Discussion

Method to set the wide data transfer negotiation result.

SetTargetProperty

Accessor for setting a property for a specific target.

bool SetTargetProperty ( SCSIDeviceIdentifier targetID, const char *key, OSObject *value );
Parameters
device

A pointer to a valid IOSCSIParallelInterfaceDevice.

key

A pointer to a valid OSString object which represents the key. A list of valid keys includes: kIOPropertySASAddressKey, kIOPropertyFibreChannelNodeWorldWideNameKey, kIOPropertyFibreChannelPortWorldWideNameKey, kIOPropertyFibreChannelAddressIdentifierKey, and kIOPropertyFibreChannelALPAKey. NB: These keys and their values are described in <IOKit/storage/IOStorageProtocolCharacteristics.h>

value

Pointer to an OSObject (one of type OSData, OSString, etc.) which represents the value for the property. The value must be of the proper type and size for the specified key.

Return Value

returns true if identifier was properly set, otherwise false.

SetTimeoutForTask

Method to set the timeout duration in milliseconds for a request.

void SetTimeoutForTask ( SCSIParallelTaskIdentifier parallelTask, UInt32 timeoutOverride = 0 );
Parameters
parallelTask

A valid SCSIParallelTaskIdentifier.

timeoutOverride

A timeout value in milliseconds in case the HBA driver wishes to override the default value provided in the parallelTask.

Discussion

Method to set the timeout duration in milliseconds for a request.

SignalInterrupt

Signals that an interrupt has occurred.

void SignalInterrupt ( void );
Discussion

Subclasses of IOSCSIParallelInterfaceController should call this method in order to get the secondary interrupt thread scheduled if and only if they will be returning false from their overriden FilterInterruptRequest() method. See the discussion for the FilterInterruptRequest() method for more details.

NOTE: This method should only be called from within the FilterInterruptRequest() method and at no other time.

Available in 10.3.3 or later.

StartController

Called to start the controller

virtual bool StartController ( void ) = 0;
Return Value

return true means that start was successful.

Discussion

The StartController will always be called before any requests are sent to the driver for execution. This method is called after an initialize to start the services provided by the specific HBA driver or called after a StopController call to restart those services. After this call completes, all services provided by the HBA driver are available to the client.

StopController

Called to stop the controller

virtual void StopController ( void ) = 0;
Discussion

The StopController method will be called any time that the system wants the card to stop accepting requests. ( See StartController discussion ). The subclass should disable the hardware interrupt for the particular controller (if possible) in this method.

SuspendServices

Called to suspend controller services

virtual void SuspendServices ( void );
Discussion

Method will be called when the system wants to suspend the services that are provided by the HBA driver. This call is not a reset and the driver shall retain all state data between this so that if a ResumeServices call is received, the driver can continue providing services without a visible difference to the client. The driver may receive multiple SuspendServices calls without receiving a ResumeServices call and should ignore any after the first until a ResumeServices call is received.

TerminateController

Called to terminate the controller

virtual void TerminateController ( void ) = 0;
Discussion

It is guaranteed that the TerminateController() will only be called once and only after the InitializeController() method and only if true was returned in response to the InitializeController() method. The TerminateController() method allows the subclass to release all resources that were acquired for operation of the hardware and shutdown all hardware services. This is the last method of the subclass that will be called before the class is destroyed.