Mac Developer Library

Developer

IOMemoryCursor Class Reference

Options
Deployment Target:

On This Page
Language:

IOMemoryCursor

A mechanism to convert memory references to physical addresses. More...

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable @import Kernel;

Availability


Available in OS X v10.0 and later.
  • Generates a physical scatter/gather list given a memory descriptor.

    Declaration

    C++

    virtual UInt32 genPhysicalSegments( IOMemoryDescriptor *descriptor, IOByteCount fromPosition, void *segments, UInt32 maxSegments, UInt32 maxTransferSize = 0, IOByteCount *transferSize = 0);

    Parameters

    descriptor

    IOMemoryDescriptor that describes the data associated with an I/O request.

    fromPosition

    Starting location of the I/O within a memory descriptor.

    segments

    Void pointer to base of output physical scatter/gather list. Always passed directly onto the SegmentFunction without interpretation by the cursor.

    maxSegments

    Maximum number of segments that can be written to segments array.

    maxTransferSize

    Maximum transfer size is limited to that many bytes, otherwise it defaults to the maximum transfer size specified when the memory cursor was initialized.

    transferSize

    Pointer to an IOByteCount variable that can contain the total size of the transfer being described. Defaults to 0 indicating that no transfer size need be returned.

    Return Value

    If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.

    Discussion

    Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.

    Import Statement

  • Primary initializer for the IOMemoryCursor class.

    Declaration

    C++

    virtual bool initWithSpecification( SegmentFunction outSegFunc, IOPhysicalLength maxSegmentSize = 0, IOPhysicalLength maxTransferSize = 0, IOPhysicalLength alignment = 1);

    Parameters

    outSegFunc

    SegmentFunction to call to output one physical segment.

    maxSegmentSize

    Maximum allowable size for one segment. Defaults to 0.

    maxTransferSize

    Maximum size of an entire transfer. Defaults to 0 indicating no maximum.

    alignment

    Alignment restrictions on output physical addresses. Not currently implemented. Defaults to single byte alignment.

    Return Value

    Returns true if the inherited classes and this instance initialize successfully.

    Import Statement

  • Creates and initializes an IOMemoryCursor in one operation.

    Declaration

    C++

    static IOMemoryCursor * withSpecification( SegmentFunction outSegFunc, IOPhysicalLength maxSegmentSize = 0, IOPhysicalLength maxTransferSize = 0, IOPhysicalLength alignment = 1);

    Parameters

    outSegFunc

    SegmentFunction to call to output one physical segment.

    maxSegmentSize

    Maximum allowable size for one segment. Defaults to 0.

    maxTransferSize

    Maximum size of an entire transfer. Defaults to 0 indicating no maximum.

    alignment

    Alignment restrictions on output physical addresses. Not currently implemented. Defaults to single byte alignment.

    Return Value

    Returns a new memory cursor if successfully created and initialized, 0 otherwise.

    Discussion

    Factory function to create and initialize an IOMemoryCursor in one operation. For more information, see IOMemoryCursor::initWithSpecification.

    Import Statement

Callbacks

  • Declaration

    C++

    typedef void ( *SegmentFunction)( PhysicalSegment segment, void *segments, UInt32 segmentIndex);

    Parameters

    segment

    The physical address and length that is next to be output.

    segments

    Base of the output vector of DMA address length pairs.

    segmentIndex

    Index to output 'segment' in the 'segments' array.

    Discussion

    Pointer to a C function that outputs a single physical segment to an element in the array as defined by the segments and segmentIndex parameters.

    Import Statement

    Availability

    Available in OS X v10.0 through OS X v10.5.

Constants

  • Declaration

    CPlusPlus

    #define IOPhysicalSegment IOMemoryCursor::PhysicalSegment #define OutputSegmentFunc IOMemoryCursor::SegmentFunction

    Constants

    • IOPhysicalSegment

      IOPhysicalSegment

      Backward compatibility define for the old non-class scoped type definition. See IOMemoryCursor::PhysicalSegment

      Available in OS X v10.0 and later.

    • OutputSegmentFunc

      OutputSegmentFunc

      Backward compatibility define for the old non-class scoped type definition. See IOMemoryCursor::SegmentFunction

      Available in OS X v10.0 and later.

    Import Statement

  • Data Types

    • Declaration

      C++

      struct PhysicalSegment { IOPhysicalAddress location; IOPhysicalLength length; };

      Discussion

      A physical address/length pair.

    Instance Variables

    • The action method called when an event has been delivered

      Declaration

      C++

      SegmentFunction outSeg;

    • Maximum size of a transfer that this memory cursor is allowed to generate

      Declaration

      C++

      IOPhysicalLength maxTransferSize;

    • Maximum size of one segment in a scatter/gather list

      Declaration

      C++

      IOPhysicalLength maxSegmentSize;

    • Currently unused. Reserved for automated aligment restriction code.

      Declaration

      C++

      IOPhysicalLength alignMask;