IOKit/network/IOMbufMemoryCursor.h Kernel.framework

@class IOMbufMemoryCursor @abstract 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. <br><br> 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. <br><br> 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.