IOFireWireSBP2ORB

Inherits from
IOCommand
Availability
Available in OS X v10.0 and later.
Declared in
IOFireWireSBP2ORB.h

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

Tasks

Miscellaneous

Instance Methods

allocatePageTable

Allocates memory for the page table.

virtual IOReturn allocatePageTable( UInt32 entryCount );
Parameters
entryCount

number of entries of page table to be allocated.

Discussion

Page table allocation is handle automatically by the ORB, except if the kFWSBP2CommandFixedSize flags is set. In this case we will fail to write a page table if we need more page table space than we have already. This method is exposed so these drivers can preallocate as much page table as they need. This is useful if your driver is part of the paging path and cannot allow allocations to occur.

deallocatePageTable

Frees up memory allocated for the page table.

virtual void deallocatePageTable( void );
Discussion

Frees all memory associated with the page table. Undoes what allocatePageTable does. Calling allocatePageTable again will automatically deallocate the existing page table before allocating a new one, so this method is not used in most cases.

getCommandBufferDescriptor

Returns the memory descriptor representing the command buffer.

virtual IOMemoryDescriptor * getCommandBufferDescriptor( void );
Return Value

Returns memory descriptor representing mapped data buffers.

Discussion

Returns the IOMemoryDescriptor for the data mapped by setCommandBuffer variants. Works for setCommandBuffersAsRanges too.

getCommandFlags

Sets configuration flags for the ORB.

virtual UInt32 getCommandFlags( void );
Return Value

Return The current ORB flags.

Discussion

Returns the current configuration flags set on this ORB.

getCommandGeneration

Gets the command generation.

virtual UInt32 getCommandGeneration( void );
Return Value

Returns the bus generation for command execution.

Discussion

This gets the bus generation this ORB should be appended in.

getCommandTimeout

Gets the timeout of the ORB.

virtual UInt32 getCommandTimeout( void );
Return Value

Returns the timeout for the orb in milliseconds.

Discussion

This method gets the timeout for this ORB in milliseconds.

getLogin

Gets the login associated with this ORB.

virtual IOFireWireSBP2Login * getLogin( void );
Return Value

Returns a pointer to an IOFireWireSBP2Login.

Discussion

Returns the IOFireWireSBP2Login object associated with this ORB.

getMaxPayloadSize

Gets max payload size for the ORB.

virtual UInt32 getMaxPayloadSize( void );
Return Value

Returns the maximum payload size in bytes.

Discussion

This gets the maximum payload size for this ORB only.

getORBAddress

Returns the FireWire address of this ORB.

virtual void getORBAddress( FWAddress *address );
Return Value

Returns the FireWire address of this ORB.

Discussion

Returns the FireWire bus address of this ORB. This is not the same as the Macintosh address for the IOFireWireSBP2ORB.

getRefCon

Returns the refCon set with setRefCon.

virtual void * getRefCon( void );
Return Value

Returns the previously stored user defined value.

Discussion

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

getRefCon64

Returns the 64 bit refCon set with setRefCon64.

virtual UInt64 getRefCon64( void );
Return Value

Returns the previously stored user defined value.

Discussion

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

release

Primary implementation of the release mechanism.

virtual void release() const;
Parameters
when

When retainCount == when then call free().

Discussion

See OSObject.h for more information.

releaseCommandBuffers

Releases SBP2's reference to the command buffers.

virtual IOReturn releaseCommandBuffers( void );
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 manipulated the memory descriptor or released the buffers without calling this method you could leave FW in an inconsistent state.

setBufferConstraints

Configures page table generation parameters

IOReturn setBufferConstraints( UInt64 maxSegmentSize, UInt32 alignment, UInt32 options = 0);
Return Value

May return an error if there is a problem allocating the underlying resources or if buffers are currently attached.

Discussion

Sets the maximums size of any page table segment and the required alignemnt. Double buffering may be used to satisfy these constraints. The only supported option is kFWSBP2ConstraintForceDoubleBuffer which forces a page aligned double buffering of the entire descriptor.

setCommandBlock(IOMemoryDescriptor *)

Sets the command block portion of the ORB.

virtual IOReturn setCommandBlock( IOMemoryDescriptor *memory );
Parameters
memory

IOMemoryDescriptor representing the command block buffer.

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.

setCommandBlock(void *, UInt32)

Sets the command block portion of the ORB.

virtual IOReturn setCommandBlock( void *buffer, UInt32 length );
Parameters
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.

setCommandBuffers

Creates a page table from a list of ranges.

virtual IOReturn setCommandBuffers( IOMemoryDescriptor *memoryDescriptor, UInt32 offset = 0, UInt32 length = 0 );
Parameters
memoryDescriptor

IOMemoryDescriptor describe ranges to be written to a page table.

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.

setCommandBuffersAsRanges(IOMemoryDescriptor *, UInt32, UInt32)

Creates a page table from a list of ranges.

virtual IOReturn setCommandBuffers( IOMemoryDescriptor *memoryDescriptor, UInt32 offset = 0, UInt32 length = 0 );
Parameters
memoryDescriptor

IOMemoryDescriptor describe ranges to be written to a page table.

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.

setCommandBuffersAsRanges(IOVirtualRange *, UInt32, IODirection, task_t, UInt32, UInt32)

Creates a page table from a list of ranges.

virtual IOReturn setCommandBuffersAsRanges( IOVirtualRange *ranges, UInt32 withCount, IODirection withDirection, task_t withTask, UInt32 offset = 0, UInt32 length = 0 );
Parameters
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.

withTask

The task that these adressses reside in.

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.

setCommandBuffersAsRanges64

Creates a page table from a list of 64 bit ranges.

IOReturn setCommandBuffersAsRanges64( IOAddressRange *ranges, uint64_t withCount, IODirection withDirection, task_t withTask, uint64_t offset = 0, uint64_t length = 0);
Parameters
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.

withTask

The task that these adressses reside in.

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. This is a 64 bit compatible version of setCommandBuffersAsRanges.

setCommandFlags

Sets configuration flags for the ORB.

virtual void setCommandFlags( UInt32 flags );
Parameters
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.

virtual void setCommandGeneration( UInt32 gen );
Parameters
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.

virtual void setCommandTimeout( UInt32 timeout );
Parameters
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.

setMaxPayloadSize

Sets max payload size for the ORB.

virtual void setMaxPayloadSize( UInt32 maxPayloadSize );
Parameters
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.

virtual void setRefCon( void *refCon );
Parameters
refCon

a user defined value.

Discussion

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

setRefCon64

Sets the ORB refCon as a 64 bit value.

virtual void setRefCon64( UInt64 refCon );
Parameters
refCon

a user defined value.

Discussion

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