ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference

IOFireWireSBP2LibORBInterface

Declared In:

Overview

Represents an SBP2 normal command ORB. Supplies the APIs for configuring normal command ORBs. This includes setting the command block and writing the page tables for I/O. The ORBs are executed using the submitORB method in IOFireWireSBP2LibLoginInterface.

Functions

getRefCon: Returns the refCon set with setRefCon.
LSIWorkaroundSetCommandBuffersAsRanges: Creates a page table with the LSI workaround from a list of ranges.
LSIWorkaroundSyncBuffersForInput: Synchronize the buffers for input.
LSIWorkaroundSyncBuffersForOutput: Synchronize the buffers for output.
releaseCommandBuffers: Releases SBP2's reference to the command buffers.
setCommandBlock: Sets the command block portion of the ORB.
setCommandBuffersAsRanges: Creates a page table from a list of ranges.
setCommandFlags: Sets configuration flags for the ORB.
setCommandGeneration: Sets the command generation.
setCommandTimeout: Sets the timeout of the ORB.
setMaxORBPayloadSize: Sets max payload size for the ORB.
setRefCon: Sets the ORB refCon.

getRefCon

Returns the refCon set with setRefCon.

void * ( *getRefCon)(
    void *self );

Parameters

self: Pointer to IOFireWireSBP2LibORBInterface.

Return Value

Returns the previously stored user defined value.

Discussion

Returns the user defined value previously stored in the ORB with setRefCon.

LSIWorkaroundSetCommandBuffersAsRanges

Creates a page table with the LSI workaround from a list of ranges.

IOReturn ( *LSIWorkaroundSetCommandBuffersAsRanges)(
    void *self,
    FWSBP2VirtualRange *ranges,
    UInt32 withCount, 
    UInt32 withDirection,
    UInt32 offset, 
    UInt32 length );

Parameters

self: Pointer to IOFireWireSBP2LibORBInterface.
ranges: An array of ranges representing the data to be transfered.
withCount: The number of ranges in the ranges array.
withDirection: An IODirection indicating the direction of data transfer.
offset: Offset in bytes into data to begin writing table at.
length: Number of bytes of data to map from offset.

Return Value

Returns KIOReturnSuccess if the page table was written successfully.

Discussion

Creates an LSI workaround page table with the given parameters. Any addresses mapped by this method routine must remain valid until setCommandBuffers is called again or releaseCommandBuffers is called. The SBP2 services do not release references to the command buffers just because the command has completed.

LSIWorkaroundSyncBuffersForInput

Synchronize the buffers for input.

IOReturn ( *LSIWorkaroundSyncBuffersForInput)(
    void *self );

Parameters

self: Pointer to IOFireWireSBP2LibORBInterface.

Return Value

Returns kIOReturnSuccess if sync was successful.

Discussion

Since double buffering may be invovled in the workaround. The driver needs to indicate when these buffers should be syncronized with the original descriptor. For data that will be input LSIWorkaroundSyncBuffersForInput should be called after receiving completion status for the ORB.

LSIWorkaroundSyncBuffersForOutput

Synchronize the buffers for output.

IOReturn ( *LSIWorkaroundSyncBuffersForOutput)(
    void *self );

Parameters

self: Pointer to IOFireWireSBP2LibORBInterface.

Return Value

Returns kIOReturnSuccess if sync was successful.

Discussion

Since double buffering may be invovled in the workaround. The driver needs to indicate when these buffers should be syncronized with the original descriptor. For data that will be output LSIWorkaroundSyncBuffersForOutput should be called before submiting the ORB.

releaseCommandBuffers

Releases SBP2's reference to the command buffers.

IOReturn ( *releaseCommandBuffers)(
    void *self );

Parameters

self: Pointer to IOFireWireSBP2LibORBInterface.

Return Value

Returns KIOReturnSuccess if the page table was cleared successfully.

Discussion

When you create a page table with one of the variants of setCommandBuffers. SBP2 holds on to a reference to the buffers until this method is called. This means that if a command completed and you released the buffers without calling this method you could leave FW in an inconsistent state.

setCommandBlock

Sets the command block portion of the ORB.

IOReturn ( *setCommandBlock)(
    void *self,
    void *buffer,
    UInt32 length );

Parameters

self: Pointer to IOFireWireSBP2LibORBInterface.
buffer: Pointer to buffer to copy command block from.
length: Number of bytes of data to copy.

Return Value

Returns KIOReturnSuccess if the command block was updated successfully.

Discussion

Copys the data provided in the buffer to the command block portion of the ORB.

setCommandBuffersAsRanges

Creates a page table from a list of ranges.

IOReturn ( *setCommandBuffersAsRanges)(
    void *self,
    FWSBP2VirtualRange *ranges,
    UInt32 withCount, 
    UInt32 withDirection,
    UInt32 offset, 
    UInt32 length );

Parameters

self: Pointer to IOFireWireSBP2LibORBInterface.
ranges: An array of ranges representing the data to be transfered.
withCount: The number of ranges in the ranges array.
withDirection: An IODirection indicating the direction of data transfer.
offset: Offset in bytes into data to begin writing table at.
length: Number of bytes of data to map from offset.

Return Value

Returns KIOReturnSuccess if the page table was written successfully.

Discussion

Creates a page table with the given parameters. Any addresses mapped by this method must remain valid until setCommandBuffers is called again or releaseCommandBuffers is called. The SBP2 services do not release references to the command buffers just because the command has completed.

setCommandFlags

Sets configuration flags for the ORB.

void ( *setCommandFlags)(
    void *self,
    UInt32 flags );

Parameters

self: Pointer to IOFireWireSBP2LibORBInterface.
flags: The flags to be set.

Discussion

Sets the configuration flags for the ORB. These can be any of the following:

kFWSBP2CommandCompleteNotify - Set the notify bit as specified in SBP2 standard. Set to receive completion/timeout notification on this ORB. You almost always want to set this.

kFWSBP2CommandTransferDataFromTarget - Transfer direction as specified in SBP2 standard. Set if data is to be written by the device into the host's memory.

kFWSBP2CommandImmediate - Immediate Append. ORB address will be written to fetch agent and not chained. It is only legal to have one immediate ORB in progress at a time.

kFWSBP2CommandNormalORB - ORB format 0 - Format specified by SBP2 standard. Set this for most ORBs.

kFWSBP2CommandReservedORB - ORB format 1 - Format reserved by SBP2 standard for future standardization.

kFWSBP2CommandVendorORB - ORB format 2 - Format specified by SBP2 standard for vendor dependent ORBs.

kFWSBP2CommandDummyORB - ORB format 3 - Format specified by SBP2 standard for dummy ORBs.

kFWSBP2CommandCheckGeneration - If set upon submitORB, the ORB will only be appended if generation set with setCommandGeneration() matches the current generation. Pretty much all SBP2 drivers need sophisticated logic to track login state, so this is generally not used.

kFWSBP2CommandFixedSize - Do not allocate more memory for page table if needed. If there is not enough space in the currently allocated page table, the setCommandBuffers call will fail. This is important to set if your device is the backing store, as we don't want to cause memory allocations on the paging path.

kFWSBP2CommandVirtualORBs - Normally ORBs are backed by physical address spaces. Setting this flag makes this ORB backed by a pseudo address space. This can make ORBs easier to see in a bus trace. Virtual ORBs will have an address in the form of ffcX.XXXX.0000.0000. Pseudo address space backed ORBs are slower, so you won't want to set for deployment builds.

setCommandGeneration

Sets the command generation.

void ( *setCommandGeneration)(
    void *self,
    UInt32 generation );

Parameters

self: Pointer to IOFireWireSBP2LibORBInterface.
gen: The bus generation for command execution.

Discussion

This sets the bus generation this ORB should be appended in. It is only meaningful when combined with the kFWSBP2CommandCheckGeneration flags above.

setCommandTimeout

Sets the timeout of the ORB.

void ( *setCommandTimeout)(
    void *self,
    UInt32 timeout );

Parameters

self: Pointer to IOFireWireSBP2LibORBInterface.
timeout: The timeout duration in milliseconds.

Discussion

This sets the timeout for the ORB in milliseconds. Note that ORBs without timeouts can be "lost." You will obviously not recieve timeout notification for timeouts of zero. But perhaps less obviously you will not recieve orb reset notification, which is really a sort of accelerated timeout notification for bus reset situations.

setMaxORBPayloadSize

Sets max payload size for the ORB.

void ( *setMaxORBPayloadSize)(
    void *self,
    UInt32 size );

Parameters

self: Pointer to IOFireWireSBP2LibORBInterface.
maxPayloadSize: The maximum payload size in bytes.

Discussion

This sets the maximum payload size for this ORB only. This size is clipped by the global max payload size set in the login object.

setRefCon

Sets the ORB refCon.

void ( *setRefCon)(
    void *self,
    void *refCon );

Parameters

self: Pointer to IOFireWireSBP2LibORBInterface.
refCon: a user defined value.

Discussion

Sets a user defined value on the ORB that can be retrieved later with the method getRefCon.

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.

Last Updated: 2009-02-23