Mac Developer Library


IOMbufMemoryCursor Class Reference

Deployment Target:

On This Page


A mechanism to convert mbuf chains to physical addresses.

The IOMbufMemoryCursor defines the super class that all specific mbuf cursors must inherit from, but a mbuf cursor can be created without a specific formal subclass by just providing a segment function to the initializers. This class performs the task of walking a given mbuf chain and creating a physical scatter/gather list appropriate for the target hardware. When necessary, this class may also coalesce mbuf chains when the generated scatter/gather list exceeds the specified hardware limit. However, this should be avoided since it exacts a performance cost.

A driver is expected to create a mbuf cursor and configure it to match the limitations of it's DMA hardware; for instance the mbuf cursor used by an Ethernet controller driver may have a maximum physical segment size of 1520, and allow for up to 6 physical segments. Thus it would create a mbuf cursor with a maxSegmentSize of 1520 and a maxNumSegments of 6. The driver may choose to supply an OutputSegmentFunc function to format the output of each scatter/gather segment to match the hardware descriptor format, or it may use a subclass of IOMbufMemoryCursor to generate IOPhysicalSegment segments with various byte orders.

A driver may also create more than one mbuf cursor, perhaps one dedicated for the transmit thread, and the other for the receive thread. This becomes a requirement when the driver is multi-threaded, since the mbuf cursor maintains state and does not support reentrancy.

  • Generates a physical scatter/gather list given a mbuf packet.


    virtual UInt32 genPhysicalSegments( mbuf_t packet, void *vector, UInt32 maxSegs, bool doCoalesce);



    The mbuf packet.


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


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


    Set to true to perform coalescing when the required number of segments exceeds the specified limit, otherwise abort and return 0.

    Return Value

    Returns the number of segments that were filled in, or 0 if an error occurred.


    Generates a list of physical segments from the given mbuf.

  • Returns a count of the total number of mbuf chains coalesced by genPhysicalSegments().


    UInt32 getAndResetCoalesceCount();

    Return Value

    Returns the coalesce count.


    This method returns a count of the total number of mbuf chains coalesced by genPhysicalSegments(). The counter is then reset to 0.

  • Primary initializer for the IOMbufMemoryCursor class.


    virtual bool initWithSpecification( IOMemoryCursor::SegmentFunction outSeg, UInt32 maxSegmentSize, UInt32 maxNumSegments);



    Function to call to output one physical segment.


    Maximum allowable size for one segment.


    Maximum number of segments.

    Return Value

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

Instance Variables

  • Reserved for future use. (Internal use only)


    ExpansionData *reserved;