IOMbufMemoryCursor

Inherits from
IOMemoryCursor
Availability
Available in OS X v10.0 through OS X v10.5.
Declared in
IOMbufMemoryCursor.h

Overview

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.

Tasks

Miscellaneous

Instance Methods

genPhysicalSegments

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

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

The mbuf packet.

vector

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

maxSegs

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

doCoalesce

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.

Discussion

Generates a list of physical segments from the given mbuf.

getAndResetCoalesceCount

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

UInt32 getAndResetCoalesceCount();
Return Value

Returns the coalesce count.

Discussion

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

initWithSpecification

Primary initializer for the IOMbufMemoryCursor class.

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

Function to call to output one physical segment.

maxSegmentSize

Maximum allowable size for one segment.

maxNumSegments

Maximum number of segments.

Return Value

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

Instance Variables

reserved

ExpansionData *reserved;

Reserved for future use. (Internal use only)