ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

---

IOMbufMemoryCursor

Overview

A mechanism to convert mbuf chains to physical addresses.

Discussion

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.

---

Functions

genPhysicalSegments

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

getAndResetCoalesceCount

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

initWithSpecification

Primary initializer for the IOMbufMemoryCursor class.

---

genPhysicalSegments

---

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

public

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().

public

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.

public

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.

Member Data

---

reserved

---

protected

ExpansionData *reserved; 

Discussion

Reserved for future use. (Internal use only)

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

 

Last Updated: 2008-12-19