Mac Developer Library

Developer

IOSCSIParallelInterfaceController Class Reference

Options
Deployment Target:

On This Page
Language:

IOSCSIParallelInterfaceController

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.2 and later.

Class that represents a SCSI Host Bus Adapter.

Class that represents a SCSI Host Bus Adapter.

  • Parallel Task Completion

    Declaration

    C++

    void CompleteParallelTask ( SCSIParallelTaskIdentifierparallelTask, SCSITaskStatuscompletionStatus, SCSIServiceResponseserviceResponse );

    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.

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

    Declaration

    C++

    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.

  • Method to perform device creation.

    Declaration

    C++

    bool CreateTargetForID ( SCSIDeviceIdentifiertargetID );

    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.

  • Method to perform device creation.

    Declaration

    C++

    bool CreateTargetForID ( SCSIDeviceIdentifiertargetID, 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.

  • Method to perform device destruction.

    Declaration

    C++

    void DestroyTargetForID ( SCSIDeviceIdentifiertargetID );

    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.

  • Disable Interrupt

    Declaration

    C++

    void DisableInterrupt ( void );

    Discussion

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

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

    Declaration

    C++

    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.

  • Determine if HBA will manage devices.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

  • Enable Interrupt

    Declaration

    C++

    void EnableInterrupt ( void );

    Discussion

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

  • Submit a SCSIParallelTask for execution.

    Declaration

    C++

    SCSIServiceResponse ExecuteParallelTask ( SCSIParallelTaskIdentifierparallelRequest );

    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.

  • Filter method called at primary interrupt time.

    Declaration

    C++

    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.

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

    Declaration

    C++

    SCSIParallelTaskIdentifier FindTaskForAddress ( SCSIDeviceIdentifiertheT, SCSILogicalUnitNumbertheL, SCSITaggedTaskIdentifiertheQ );

    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.

  • Find a task for a given Target and Controller Task Identifier

    Declaration

    C++

    SCSIParallelTaskIdentifier FindTaskForControllerIdentifier ( SCSIDeviceIdentifiertheTarget, UInt64theIdentifier );

    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

  • Method to allow the client to release a SCSIParallelTask

    Declaration

    C++

    void FreeSCSIParallelTask ( SCSIParallelTaskIdentifierreturnTask );

    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.

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

    Declaration

    C++

    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

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

    Declaration

    C++

    UInt8 GetAutoSenseDataSize ( SCSIParallelTaskIdentifierparallelTask );

    Parameters

    parallelTask

    A valid SCSIParallelTaskIdentifier.

    Return Value

    returns Size of auto sense data buffer.

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

    Declaration

    C++

    bool GetCommandDescriptorBlock ( SCSIParallelTaskIdentifierparallelTask, 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.

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

    Declaration

    C++

    UInt8 GetCommandDescriptorBlockSize ( SCSIParallelTaskIdentifierparallelTask );

    Parameters

    parallelTask

    A valid SCSIParallelTaskIdentifier.

    Return Value

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

  • Accessor to get an IOCommandGate associated with the workloop.

    Declaration

    C++

    IOCommandGate * GetCommandGate ( void );

    Return Value

    returns pointer to IOCommandGate.

    Discussion

    Accessor to get an IOCommandGate associated with the workloop.

  • Method to retrieve client buffer from the request.

    Declaration

    C++

    IOMemoryDescriptor * GetDataBuffer ( SCSIParallelTaskIdentifierparallelTask );

    Parameters

    parallelTask

    A valid SCSIParallelTaskIdentifier.

    Return Value

    returns pointer to an IOMemoryDescriptor which represents the buffer.

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

    Declaration

    C++

    UInt64 GetDataBufferOffset ( SCSIParallelTaskIdentifierparallelTask );

    Parameters

    parallelTask

    A valid SCSIParallelTaskIdentifier.

    Return Value

    returns offset in bytes

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

    Declaration

    C++

    UInt8 GetDataTransferDirection ( SCSIParallelTaskIdentifierparallelTask );

    Parameters

    parallelTask

    A valid SCSIParallelTaskIdentifier.

    Return Value

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

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

    Declaration

    C++

    IODMACommand * GetDMACommand ( SCSIParallelTaskIdentifierparallelTask );

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

  • Method to retrieve the IOMemoryDescriptor associated with the HBA Data.

    Declaration

    C++

    IOMemoryDescriptor * GetHBADataDescriptor ( SCSIParallelTaskIdentifierparallelTask );

    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.

  • Method to retrieve the HBA Data pointer.

    Declaration

    C++

    void * GetHBADataPointer ( SCSIParallelTaskIdentifierparallelTask );

    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.

  • Method to retrieve the HBA Data Size in bytes.

    Declaration

    C++

    UInt32 GetHBADataSize ( SCSIParallelTaskIdentifierparallelTask );

    Parameters

    parallelTask

    A valid SCSIParallelTaskIdentifier.

    Return Value

    returns HBA Data size in bytes.

    Discussion

    Method to retrieve the HBA Data Size in bytes.

  • Method to retrieve the HBA Data pointer.

    Declaration

    C++

    void * GetHBATargetDataPointer ( SCSITargetIdentifiertargetDevice );

    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.

  • Method to retrieve the HBA Data Size in bytes.

    Declaration

    C++

    UInt32 GetHBATargetDataSize ( SCSITargetIdentifiertargetDevice );

    Parameters

    targetDevice

    A valid SCSITargetIdentifier.

    Return Value

    returns HBA Data size in bytes.

    Discussion

    Method to retrieve the HBA Data Size in bytes.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    SCSILogicalUnitNumber GetLogicalUnitNumber ( SCSIParallelTaskIdentifierparallelTask );

    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.

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

    Declaration

    C++

    IOService * GetProvider ( void );

    Return Value

    returns pointer to IOService.

    Discussion

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

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

    Declaration

    C++

    UInt64 GetRealizedDataTransferCount ( SCSIParallelTaskIdentifierparallelTask );

    Parameters

    parallelTask

    A valid SCSIParallelTaskIdentifier.

    Return Value

    The realized data transfer count in bytes.

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

    Declaration

    C++

    UInt64 GetRequestedDataTransferCount ( SCSIParallelTaskIdentifierparallelTask );

    Parameters

    parallelTask

    A valid SCSIParallelTaskIdentifier.

    Return Value

    The requested data transfer count in bytes.

  • Accessor method to get the SCSI Domain Identifier.

    Declaration

    C++

    SInt32 GetSCSIDomainIdentifier ( void );

    Return Value

    returns SCSI Domain Identifier.

    Discussion

    Accessor method to get the SCSI Domain Identifier.

  • Method to retrieve the requested value for negotiation of the.

    Declaration

    C++

    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.

  • Method to retrieve the number of requested negotiations.

    Declaration

    C++

    UInt64 GetSCSIParallelFeatureNegotiationCount ( SCSIParallelTaskIdentifierparallelTask);

    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.

  • Method to retrieve the result of any wide transfer negotiations.

    Declaration

    C++

    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.

  • Method to retrieve the number of changed negotiations.

    Declaration

    C++

    UInt64 GetSCSIParallelFeatureNegotiationResultCount ( SCSIParallelTaskIdentifierparallelTask);

    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.

  • Method to allow the client to get a SCSIParallelTask

    Declaration

    C++

    SCSIParallelTaskIdentifier GetSCSIParallelTask ( boolblockForCommand );

    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.

  • Method to retrieve a SCSITaskIdentifier from a valid SCSIParallelTaskIdentifier.

    Declaration

    C++

    SCSITaskIdentifier GetSCSITaskIdentifier ( SCSIParallelTaskIdentifierparallelTask );

    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.

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

    Declaration

    C++

    SCSITaggedTaskIdentifier GetTaggedTaskIdentifier ( SCSIParallelTaskIdentifierparallelTask );

    Parameters

    parallelTask

    A valid SCSIParallelTaskIdentifier.

    Return Value

    an SCSITaskAttribute value.

  • Accessor for getting pointer to IOSCSIParallelInterfaceDevice.

    Declaration

    C++

    IOSCSIParallelInterfaceDevice * GetTargetForID ( SCSIDeviceIdentifiertargetID );

    Parameters

    targetID

    SCSIDeviceIdentifier of desired targetID.

    Return Value

    returns pointer to IOSCSIParallelInterfaceDevice or NULL if not found.

  • Method to get the SCSITargetIdentifier associated with a request.

    Declaration

    C++

    SCSITargetIdentifier GetTargetIdentifier ( SCSIParallelTaskIdentifierparallelTask );

    Parameters

    parallelTask

    A valid SCSIParallelTaskIdentifier.

    Return Value

    returns SCSITargetIdentifier

    Discussion

    Method to get the SCSITargetIdentifier associated with a request.

  • Method to retrieve the SCSI Task Attribute of the task

    Declaration

    C++

    SCSITaskAttribute GetTaskAttribute ( SCSIParallelTaskIdentifierparallelTask );

    Parameters

    parallelTask

    A valid SCSIParallelTaskIdentifier.

    Return Value

    an SCSITaskAttribute value.

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

    Declaration

    C++

    UInt32 GetTimeoutDuration ( SCSIParallelTaskIdentifierparallelTask );

    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.

  • Accessor method to get the IOWorkLoop associated with this HBA.

    Declaration

    C++

    IOWorkLoop * GetWorkLoop ( void ) const;

    Return Value

    returns pointer to IOWorkLoop.

    Discussion

    Accessor method to get the IOWorkLoop associated with this HBA.

  • Handle Interrupt Request

    Declaration

    C++

    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.

  • Method to handle command timeouts.

    Declaration

    C++

    virtual void HandleTimeout ( SCSIParallelTaskIdentifierparallelRequest );

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

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

    Declaration

    C++

    void IncrementRealizedDataTransferCount ( SCSIParallelTaskIdentifierparallelTask, UInt64realizedTransferCountInBytes );

    Parameters

    parallelTask

    A valid SCSIParallelTaskIdentifier.

    realizedTransferCountInBytes

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

  • Called to initialize the controller

    Declaration

    C++

    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.

  • Called to initialize an IODMACommand with a DMA specification.

    Declaration

    C++

    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.

  • Called to initialize a target device.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

  • Method called to notify clients of port status change events.

    Declaration

    C++

    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.

  • Called by client to process a parallel task.

    Declaration

    C++

    virtual SCSIServiceResponse ProcessParallelTask ( SCSIParallelTaskIdentifierparallelRequest ) = 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.

  • Accessor for removing a property for this object.

    Declaration

    C++

    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.

  • Accessor for removing a property from a specific target.

    Declaration

    C++

    void RemoveTargetProperty ( SCSIDeviceIdentifierdevice, const char *key );

    Parameters

    device

    A pointer to a valid IOSCSIParallelInterfaceDevice.

    key

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

  • 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>

    Declaration

    C++

    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.

  • Gets the Highest Logical Unit Number.

    Declaration

    C++

    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.

  • Determine memory needed for HBA Device specific use.

    Declaration

    C++

    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.

  • Determine memory needed for HBA Task specific use.

    Declaration

    C++

    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.

  • Get the highest supported SCSI Device Identifier.

    Declaration

    C++

    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.

  • Get the SCSI Device Identifier for the HBA.

    Declaration

    C++

    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.

  • Report Maximum Task Count

    Declaration

    C++

    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.

  • Called to resume controller services

    Declaration

    C++

    virtual void ResumeServices ( void );

    Discussion

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

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

    Declaration

    C++

    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

  • Method to set the Controller Task Identifier.

    Declaration

    C++

    void SetControllerTaskIdentifier ( SCSIParallelTaskIdentifierparallelTask, UInt64newIdentifier );

    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.

  • Accessor for setting a property for this object.

    Declaration

    C++

    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.

  • Sets the realized data transfer count in bytes.

    Declaration

    C++

    bool SetRealizedDataTransferCount ( SCSIParallelTaskIdentifierparallelTask, UInt64realizedTransferCountInBytes );

    Parameters

    parallelTask

    A valid SCSIParallelTaskIdentifier.

    realizedTransferCountInBytes

    is the number of bytes actually transferred.

    Return Value

    true means the data transfer count was successfully set.

  • Method to set the wide data transfer negotiation result.

    Declaration

    C++

    void SetSCSIParallelFeatureNegotiationResult ( SCSIParallelTaskIdentifierparallelTask, SCSIParallelFeaturerequestedFeature, SCSIParallelFeatureResultnewResult );

    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.

  • Accessor for setting a property for a specific target.

    Declaration

    C++

    bool SetTargetProperty ( SCSIDeviceIdentifierdevice, 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.

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

    Declaration

    C++

    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.

  • Signals that an interrupt has occurred.

    Declaration

    C++

    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.

  • Called to start the controller

    Declaration

    C++

    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.

  • Called to stop the controller

    Declaration

    C++

    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.

  • Called to suspend controller services

    Declaration

    C++

    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.

  • Called to terminate the controller

    Declaration

    C++

    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.