|
ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference
|
IOFireWireSBP2ORB |
| Inherits from: | |
| Declared In: |
Represents an SBP2 normal command ORB.
This class 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.
Allocates memory for the page table.
Frees up memory allocated for the page table.
Returns the memory descriptor representing the command buffer.
Gets configuration flags for the ORB.
Gets the command generation.
Gets the timeout of the ORB.
Gets the login associated with this ORB.
Gets max payload size for the ORB.
Returns the FireWire address of this ORB.
Returns the refCon set with setRefCon.
Returns the 64 bit refCon set with setRefCon64.
Primary implementation of the release mechanism.
Releases SBP2's reference to the command buffers.
Configures page table generation parameters
Sets the command block portion of the ORB.
Sets the command block portion of the ORB.
Creates a page table from a list of ranges.
Creates a page table from a list of ranges.
Creates a page table from a list of ranges.
Creates a page table from a list of 64 bit ranges.
Sets configuration flags for the ORB.
Sets the command generation.
Sets the timeout of the ORB.
Sets max payload size for the ORB.
Sets the ORB refCon.
Sets the ORB refCon as a 64 bit value.
allocatePageTable |
Allocates memory for the page table.
public
virtual IOReturn allocatePageTable( UInt32 entryCount );
entryCountnumber of entries of page table to be allocated.
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.
protected
virtual void deallocatePageTable( void );
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.
public
virtual IOMemoryDescriptor * getCommandBufferDescriptor( void );
Returns memory descriptor representing mapped data buffers.
Returns the IOMemoryDescriptor for the data mapped by setCommandBuffer variants. Works for setCommandBuffersAsRanges too.
getCommandFlags |
Gets configuration flags for the ORB.
public
virtual UInt32 getCommandFlags( void );
Return The current ORB flags.
Returns the current configuration flags set on this ORB.
getCommandGeneration |
Gets the command generation.
public
virtual UInt32 getCommandGeneration( void );
Returns the bus generation for command execution.
This gets the bus generation this ORB should be appended in.
getCommandTimeout |
Gets the timeout of the ORB.
public
virtual UInt32 getCommandTimeout( void );
Returns the timeout for the orb in milliseconds.
This method gets the timeout for this ORB in milliseconds.
getLogin |
Gets the login associated with this ORB.
public
virtual IOFireWireSBP2Login * getLogin( void );
Returns a pointer to an IOFireWireSBP2Login.
Returns the IOFireWireSBP2Login object associated with this ORB.
getMaxPayloadSize |
Gets max payload size for the ORB.
public
virtual UInt32 getMaxPayloadSize( void );
Returns the maximum payload size in bytes.
This gets the maximum payload size for this ORB only.
getORBAddress |
Returns the FireWire address of this ORB.
public
virtual void getORBAddress( FWAddress *address );
Returns the FireWire address of this ORB.
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.
public
virtual void * getRefCon( void );
Returns the previously stored user defined value.
Returns the user defined value previously stored in the ORB with setRefCon.
getRefCon64 |
Returns the 64 bit refCon set with setRefCon64.
public
virtual UInt64 getRefCon64( void );
Returns the previously stored user defined value.
Returns the user defined value previously stored in the ORB with setRefCon.
release |
Primary implementation of the release mechanism.
public
virtual void release() const;
whenWhen retainCount == when then call free().
See OSObject.h for more information.
releaseCommandBuffers |
Releases SBP2's reference to the command buffers.
public
virtual IOReturn releaseCommandBuffers( void );
Returns KIOReturnSuccess if the page table was cleared successfully.
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
public
IOReturn setBufferConstraints( UInt64 maxSegmentSize, UInt32 alignment, UInt32 options = 0);
May return an error if there is a problem allocating the underlying resources or if buffers are currently attached.
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.
public
virtual IOReturn setCommandBlock( IOMemoryDescriptor *memory );
memoryIOMemoryDescriptor representing the command block buffer.
Returns KIOReturnSuccess if the command block was updated successfully.
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.
public
virtual IOReturn setCommandBlock( void *buffer, UInt32 length );
bufferPointer to buffer to copy command block from.
lengthNumber of bytes of data to copy.
Returns KIOReturnSuccess if the command block was updated successfully.
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.
public
virtual IOReturn setCommandBuffers( IOMemoryDescriptor *memoryDescriptor, UInt32 offset = 0, UInt32 length = 0 );
memoryDescriptorIOMemoryDescriptor describe ranges to be written to a page table.
offsetOffset in bytes into data to begin writing table at.
lengthNumber of bytes of data to map from offset.
Returns KIOReturnSuccess if the page table was written successfully.
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.
public
virtual IOReturn setCommandBuffers( IOMemoryDescriptor *memoryDescriptor, UInt32 offset = 0, UInt32 length = 0 );
memoryDescriptorIOMemoryDescriptor describe ranges to be written to a page table.
offsetOffset in bytes into data to begin writing table at.
lengthNumber of bytes of data to map from offset.
Returns KIOReturnSuccess if the page table was written successfully.
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.
public
virtual IOReturn setCommandBuffersAsRanges( IOVirtualRange *ranges, UInt32 withCount, IODirection withDirection, task_t withTask, UInt32 offset = 0, UInt32 length = 0 );
rangesAn array of ranges representing the data to be transfered.
withCountThe number of ranges in the ranges array.
withDirectionAn IODirection indicating the direction of data transfer.
withTaskThe task that these adressses reside in.
offsetOffset in bytes into data to begin writing table at.
lengthNumber of bytes of data to map from offset.
Returns KIOReturnSuccess if the page table was written successfully.
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.
public
IOReturn setCommandBuffersAsRanges64( IOAddressRange *ranges, uint64_t withCount, IODirection withDirection, task_t withTask, uint64_t offset = 0, uint64_t length = 0);
rangesAn array of ranges representing the data to be transfered.
withCountThe number of ranges in the ranges array.
withDirectionAn IODirection indicating the direction of data transfer.
withTaskThe task that these adressses reside in.
offsetOffset in bytes into data to begin writing table at.
lengthNumber of bytes of data to map from offset.
Returns KIOReturnSuccess if the page table was written successfully.
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.
public
virtual void setCommandFlags( UInt32 flags );
flagsThe flags to be set.
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.
public
virtual void setCommandGeneration( UInt32 gen );
genThe bus generation for command execution.
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.
public
virtual void setCommandTimeout( UInt32 timeout );
timeoutThe timeout duration in milliseconds.
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.
public
virtual void setMaxPayloadSize( UInt32 maxPayloadSize );
maxPayloadSizeThe maximum payload size in bytes.
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.
public
virtual void setRefCon( void *refCon );
refCona user defined value.
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.
public
virtual void setRefCon64( UInt64 refCon );
refCona user defined value.
Sets a user defined value on the ORB that can be retrieved later with the method getRefCon.
|
Last Updated: 2008-12-19