ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

\xA0

IOSCSIParallelInterfaceController.h

Includes:

Overview

The IOSCSIParallelInterfaceController class and the associated HBA child class is responsible for the management of all related hardware. This includes the onboard HBA controller chip and the physical state of the bus. These classes are not responsible for any of the management of the SCSI Devices on the bus with the exception of maintaining the queue that holds the objects representing those SCSI Devices.

Functions

CompleteParallelTask: Parallel Task Completion
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).
CreateTargetForID(SCSIDeviceIdentifier): Method to perform device creation.
CreateTargetForID(SCSIDeviceIdentifier, OSDictionary *): Method to perform device creation.
DestroyTargetForID: Method to perform device destruction.
DisableInterrupt: Disable Interrupt
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.
DoesHBAPerformDeviceManagement: Determine if HBA will manage devices.
DoesHBASupportSCSIParallelFeature: Queries the HBA child class to determine if it supports a specific SPI feature.
EnableInterrupt: Enable Interrupt
ExecuteParallelTask: Submit a SCSIParallelTask for execution.
FilterInterruptRequest: Filter method called at primary interrupt time.
FindTaskForAddress: Find a task for a given Task Address, if one exists.
FindTaskForControllerIdentifier: Find a task for a given Target and Controller Task Identifier
FreeSCSIParallelTask: Method to allow the client to release a SCSIParallelTask
GetAutoSenseData: Method to retrieve auto sense data buffer associated with a request.
GetAutoSenseDataSize: Method to retrieve auto sense data buffer size associated with a request.
GetCommandDescriptorBlock: Method to retrieve the SCSI Command Descriptor Block (CDB).
GetCommandDescriptorBlockSize: Method to retrieve the size of the SCSI Command Descriptor Block (CDB).
GetCommandGate: Accessor to get an IOCommandGate associated with the workloop.
GetDataBuffer: Method to retrieve client buffer from the request.
GetDataBufferOffset: Method to retrieve offset into client buffer at which to start processing.
GetDataTransferDirection: Retrieves the data transfer direction for any data associated with the request.
GetDMACommand: Method to retrieve a pointer to an IODMACommand from the request.
GetHBADataDescriptor: Method to retrieve the IOMemoryDescriptor associated with the HBA Data.
GetHBADataPointer: Method to retrieve the HBA Data pointer.
GetHBADataSize: Method to retrieve the HBA Data Size in bytes.
GetHBATargetDataPointer: Method to retrieve the HBA Data pointer.
GetHBATargetDataSize: Method to retrieve the HBA Data Size in bytes.
GetLogicalUnitNumber: Method to get the logical unit number associated with a request.
GetProvider: 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.
GetRequestedDataTransferCount: Retrieves the requested data transfer count for any data associated with the request.
GetSCSIDomainIdentifier: Accessor method to get the SCSI Domain Identifier.
GetSCSIParallelFeatureNegotiation: Method to retrieve the requested value for negotiation of the.
GetSCSIParallelFeatureNegotiationCount: Method to retrieve the number of requested negotiations.
GetSCSIParallelFeatureNegotiationResult: Method to retrieve the result of any wide transfer negotiations.
GetSCSIParallelFeatureNegotiationResultCount: Method to retrieve the number of changed negotiations.
GetSCSIParallelTask: Method to allow the client to get a SCSIParallelTask
GetSCSITaskIdentifier: 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.
GetTargetForID: Accessor for getting pointer to IOSCSIParallelInterfaceDevice.
GetTargetIdentifier: Method to get the SCSITargetIdentifier associated with a request.
GetTaskAttribute: Method to retrieve the SCSI Task Attribute of the task
GetTimeoutDuration: Method to retrieve the timeout duration in milliseconds for a request.
GetWorkLoop: Accessor method to get the IOWorkLoop associated with this HBA.
HandleInterruptRequest: Handle Interrupt Request
HandleTimeout: Method to handle command timeouts.
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.
InitializeController: Called to initialize the controller
InitializeDMASpecification: Called to initialize an IODMACommand with a DMA specification.
InitializeTargetForID: Called to initialize a target device.
NotifyClientsOfBusReset: Method called to notify clients that a bus reset has occurred.
NotifyClientsOfPortStatusChange: Method called to notify clients of port status change events.
ProcessParallelTask: Called by client to process a parallel task.
RemoveHBAProperty: Accessor for removing a property for this object.
RemoveTargetProperty: Accessor for removing a property from a specific target.
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). NB: These keys and their values are described in this header and
ReportHBAHighestLogicalUnitNumber: Gets the Highest Logical Unit Number.
ReportHBASpecificDeviceDataSize: Determine memory needed for HBA Device specific use.
ReportHBASpecificTaskDataSize: Determine memory needed for HBA Task specific use.
ReportHighestSupportedDeviceID: Get the highest supported SCSI Device Identifier.
ReportInitiatorIdentifier: Get the SCSI Device Identifier for the HBA.
ReportMaximumTaskCount: Report Maximum Task Count
ResumeServices: Called to resume controller services
SetAutoSenseData: Method to set the auto sense data buffer associated with a request.
SetControllerTaskIdentifier: Method to set the Controller Task Identifier.
SetHBAProperty: Accessor for setting a property for this object.
SetRealizedDataTransferCount: Sets the realized data transfer count in bytes.
SetSCSIParallelFeatureNegotiationResult: Method to set the wide data transfer negotiation result.
SetTargetProperty: Accessor for setting a property for a specific target.
SetTimeoutForTask: Method to set the timeout duration in milliseconds for a request.
SignalInterrupt: Signals that an interrupt has occurred.
StartController: Called to start the controller
StopController: Called to stop the controller
SuspendServices: Called to suspend controller services
TerminateController: Called to terminate the controller

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 )

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, and kIOPropertyFibreChannelALPAKey. These keys are defined in and the values associated with these keys must be of the proper type/size, or the target creation will not succeed. NB: Correct FibreChannel multipathing requires the kIOPropertyFibreChannelNodeWorldWideNameKey property be passed in and this method used to create the target device. The other keys are optional upon creation and may be added later using SetTargetProperty().

Return Value

returns true if successful.

Discussion

DestroyTargetForID

Method to perform device destruction.

void DestroyTargetForID (
    SCSIDeviceIdentifier targetID );

Parameters

targetID: SCSIDeviceIdentifier of desired targetID.

Discussion

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

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.

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 .

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

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.

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.

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 )

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). NB: These keys and their values are described in this header and

  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, and kIOPropertyFibreChannelALPAKey. NB: These keys and their values are described in and
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
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.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

\xA0

Last Updated: 2008-12-19