Mac Developer Library

Developer

IOFireWireSBP2ORB Class Reference

Options
Deployment Target:

On This Page
Language:

IOFireWireSBP2ORB

Inheritance


  • IOFireWireSBP2ORB

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.

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.

  • Allocates memory for the page table.

    Declaration

    C++

    virtual IOReturn allocatePageTable( UInt32entryCount );

    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.

  • Frees up memory allocated for the page table.

    Declaration

    C++

    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.

  • Returns the memory descriptor representing the command buffer.

    Declaration

    C++

    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.

  • Sets configuration flags for the ORB.

    Declaration

    C++

    virtual UInt32 getCommandFlags( void );

    Return Value

    Return The current ORB flags.

    Discussion

    Returns the current configuration flags set on this ORB.

  • Gets the command generation.

    Declaration

    C++

    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.

  • Gets the timeout of the ORB.

    Declaration

    C++

    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.

  • Gets the login associated with this ORB.

    Declaration

    C++

    virtual IOFireWireSBP2Login * getLogin( void );

    Return Value

    Returns a pointer to an IOFireWireSBP2Login.

    Discussion

    Returns the IOFireWireSBP2Login object associated with this ORB.

  • Gets max payload size for the ORB.

    Declaration

    C++

    virtual UInt32 getMaxPayloadSize( void );

    Return Value

    Returns the maximum payload size in bytes.

    Discussion

    This gets the maximum payload size for this ORB only.

  • Returns the FireWire address of this ORB.

    Declaration

    C++

    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.

  • Returns the refCon set with setRefCon.

    Declaration

    C++

    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.

  • Returns the 64 bit refCon set with setRefCon64.

    Declaration

    C++

    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.

  • Primary implementation of the release mechanism.

    Declaration

    C++

    virtual void release() const;

    Parameters

    when

    When retainCount == when then call free().

    Discussion

    See OSObject.h for more information.

  • Releases SBP2's reference to the command buffers.

    Declaration

    C++

    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.

  • Configures page table generation parameters

    Declaration

    C++

    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.

  • Sets the command block portion of the ORB.

    Declaration

    C++

    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.

  • Sets the command block portion of the ORB.

    Declaration

    C++

    virtual IOReturn setCommandBlock( void *buffer, UInt32length );

    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.

  • Creates a page table from a list of ranges.

    Declaration

    C++

    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.

  • Creates a page table from a list of ranges.

    Declaration

    C++

    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.

  • Creates a page table from a list of ranges.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

  • Sets configuration flags for the ORB.

    Declaration

    C++

    virtual void setCommandFlags( UInt32flags );

    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.

  • Sets the command generation.

    Declaration

    C++

    virtual void setCommandGeneration( UInt32gen );

    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.

  • Sets the timeout of the ORB.

    Declaration

    C++

    virtual void setCommandTimeout( UInt32timeout );

    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.

  • Sets max payload size for the ORB.

    Declaration

    C++

    virtual void setMaxPayloadSize( UInt32maxPayloadSize );

    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.

  • Sets the ORB refCon.

    Declaration

    C++

    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.

  • Sets the ORB refCon as a 64 bit value.

    Declaration

    C++

    virtual void setRefCon64( UInt64refCon );

    Parameters

    refCon

    a user defined value.

    Discussion

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