[apple/xnu.git] / iokit / IOKit / network / IOMbufMemoryCursor.h

/*
 * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 * 
 * This Original Code and all software distributed under the License are
 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
 * License for the specific language governing rights and limitations
 * under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */
/*
 * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved. 
 *
 * IOMbufMemoryCursor.h created by gvdl on 1999-1-20
 *
 */

#ifndef _IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H
#define _IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H

#include <IOKit/IOMemoryCursor.h>

struct mbuf;

/*! @class IOMbufMemoryCursor : public IOMemoryCursor
    @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. */

class IOMbufMemoryCursor : public IOMemoryCursor
{
    OSDeclareAbstractStructors(IOMbufMemoryCursor)

protected:
    UInt32 maxNumSegments;
    UInt32 coalesceCount;
    UInt32 packetTooBigErrors;

    struct ExpansionData { };
    /*! @var reserved
        Reserved for future use.  (Internal use only)  */
    ExpansionData *reserved;

    virtual bool initWithSpecification(OutputSegmentFunc outSeg,
                                       UInt32 maxSegmentSize,
                                       UInt32 maxTransferSize,
                                       UInt32 align);

public:
/*! @function initWithSpecification
    @abstract Primary initializer for the IOMbufMemoryCursor class.
    @param outSeg Function to call to output one physical segment.
    @param maxSegmentSize Maximum allowable size for one segment.
    @param maxNumSegments Maximum number of segments.
    @result true if the inherited classes and this instance initialized
    successfully. */

    virtual bool initWithSpecification(OutputSegmentFunc outSeg,
                                       UInt32 maxSegmentSize,
                                       UInt32 maxNumSegments);

/*! @function genPhysicalSegments
    @abstract Generate a physical scatter/gather list given a mbuf packet.
    @discussion Generates a list of physical segments from the given mbuf.
    @param packet The mbuf packet.
    @param vector Void pointer to base of output physical scatter/gather list.
    Always passed directly onto the OutputSegmentFunc without interpretation
    by the cursor. 
    @param maxSegs Maximum number of segments that can be written to segments
    array.
    @param doCoalesce Set to true to perform coalescing when the required 
    number of segments exceeds the specified limit, otherwise abort and
    return 0.
    @result The number of segments that were filled in is returned, or
    0 if an error occurred. */

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

/*! @function getAndResetCoalesceCount
    @abstract Returns a count of the total number of mbuf chains coalesced
    by genPhysicalSegments(). The counter is then reset to 0.
    @result The coalesce count. */

    UInt32 getAndResetCoalesceCount();

    // Virtual function padding
    OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor,  0);
    OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor,  1);
    OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor,  2);
    OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor,  3);
};


/*! @class IOMbufNaturalMemoryCursor : public IOMbufMemoryCursor
    @abstract A IOMbufMemoryCursor subclass that outputs a vector of
    IOPhysicalSegments in the natural byte orientation for the cpu.  
    @discussion The IOMbufNaturalMemoryCursor would be used when it is too
    difficult to implement an OutputSegmentFunc that is more appropriate for
    your hardware.  This cursor just outputs an array of IOPhysicalSegments. */

class IOMbufNaturalMemoryCursor : public IOMbufMemoryCursor
{
    OSDeclareDefaultStructors(IOMbufNaturalMemoryCursor)

public:

/*! @function withSpecification
    @abstract Factory function to create and initialize an 
    IOMbufNaturalMemoryCursor in one operation, see
    IOMbufMemoryCursor::initWithSpecification.
    @param maxSegmentSize Maximum allowable size for one segment.
    @param maxNumSegments Maximum number of segments.
    @result A new mbuf cursor if successfully created and initialized,
    0 otherwise. */

    static IOMbufNaturalMemoryCursor * withSpecification(UInt32 maxSegmentSize, 
                                                         UInt32 maxNumSegments);

/*! @function getPhysicalSegments
    @abstract Generate a cpu natural physical scatter/gather list from a given
    mbuf.
    @param packet The mbuf packet.
    @param vector Pointer to an array of IOPhysicalSegments for the output 
    physical scatter/gather list.
    @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
    @result The number of segments that were filled in is returned, or
    0 if an error occurred. */

    UInt32 getPhysicalSegments(struct mbuf * packet,
                               struct IOPhysicalSegment * vector,
                               UInt32 numVectorSegments = 0);

/*! @function getPhysicalSegmentsWithCoalesce
    @abstract Generate a cpu natural physical scatter/gather list from a given
    mbuf.
    @discussion Generate a cpu natural physical scatter/gather list from a 
    given mbuf. Coalesce mbuf chain when the number of segments in the 
    scatter/gather list exceeds numVectorSegments.
    @param packet The mbuf packet.
    @param vector Pointer to an array of IOPhysicalSegments for the output 
    physical scatter/gather list.
    @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
    @result The number of segments that were filled in is returned, or
    0 if an error occurred. */

    UInt32 getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
                                           struct IOPhysicalSegment * vector,
                                           UInt32 numVectorSegments = 0);
};

//===========================================================================
//===========================================================================

/*! @class IOMbufBigMemoryCursor : public IOMbufMemoryCursor
    @abstract A IOMbufMemoryCursor subclass that outputs a vector of 
    IOPhysicalSegments in the big endian byte order.  
    @discussion The IOMbufBigMemoryCursor would be used when the DMA hardware 
    requires a big endian address and length pair.  This cursor outputs an 
    array of IOPhysicalSegments that are encoded in big-endian format. */

class IOMbufBigMemoryCursor : public IOMbufMemoryCursor
{
    OSDeclareDefaultStructors(IOMbufBigMemoryCursor)

public:

/*! @function withSpecification
    @abstract Factory function to create and initialize an 
    IOMbufBigMemoryCursor in one operation, see
    IOMbufMemoryCursor::initWithSpecification.
    @param maxSegmentSize Maximum allowable size for one segment.
    @param maxNumSegments Maximum number of segments.
    @result A new mbuf cursor if successfully created and initialized,
    0 otherwise. */

    static IOMbufBigMemoryCursor * withSpecification(UInt32 maxSegmentSize,
                                                     UInt32 maxNumSegments);

/*! @function getPhysicalSegments
    @abstract Generate a big endian physical scatter/gather list from a given
    mbuf.
    @param packet The mbuf packet.
    @param vector Pointer to an array of IOPhysicalSegments for the output 
    physical scatter/gather list.
    @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
    @result The number of segments that were filled in is returned, or
    0 if an error occurred. */

    UInt32 getPhysicalSegments(struct mbuf * packet,
                               struct IOPhysicalSegment * vector,
                               UInt32 numVectorSegments = 0);

/*! @function getPhysicalSegmentsWithCoalesce
    @abstract Generate a big endian physical scatter/gather list from a given
    mbuf.
    @discussion Generate a big endian physical scatter/gather list from a 
    given mbuf. Coalesce mbuf chain when the number of segments in the 
    scatter/gather list exceeds numVectorSegments.
    @param packet The mbuf packet.
    @param vector Pointer to an array of IOPhysicalSegments for the output 
    physical scatter/gather list.
    @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
    @result The number of segments that were filled in is returned, or
    0 if an error occurred. */

    UInt32 getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
                                           struct IOPhysicalSegment * vector,
                                           UInt32 numVectorSegments = 0);
};

//===========================================================================
//===========================================================================

/*! @class IOMbufLittleMemoryCursor : public IOMbufMemoryCursor
    @abstract A IOMbufMemoryCursor subclass that outputs a vector of 
    IOPhysicalSegments in the little endian byte order.  
    @discussion The IOMbufLittleMemoryCursor would be used when the DMA 
    hardware requires a little endian address and length pair.  This cursor 
    outputs an array of IOPhysicalSegments that are encoded in little endian 
    format. */

class IOMbufLittleMemoryCursor : public IOMbufMemoryCursor
{
    OSDeclareDefaultStructors(IOMbufLittleMemoryCursor)

public:

/*! @function withSpecification
    @abstract Factory function to create and initialize an 
    IOMbufLittleMemoryCursor in one operation, see
    IOMbufMemoryCursor::initWithSpecification.
    @param maxSegmentSize Maximum allowable size for one segment.
    @param maxNumSegments Maximum number of segments.
    @result A new mbuf cursor if successfully created and initialized,
    0 otherwise. */

    static IOMbufLittleMemoryCursor * withSpecification(UInt32 maxSegmentSize, 
                                                        UInt32 maxNumSegments);

/*! @function getPhysicalSegments
    @abstract Generate a little endian physical scatter/gather list from a 
    given mbuf.
    @param packet The mbuf packet.
    @param vector Pointer to an array of IOPhysicalSegments for the output 
    physical scatter/gather list.
    @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
    @result The number of segments that were filled in is returned, or
    0 if an error occurred. */

    UInt32 getPhysicalSegments(struct mbuf * packet,
                               struct IOPhysicalSegment * vector,
                               UInt32 numVectorSegments = 0);

/*! @function getPhysicalSegmentsWithCoalesce
    @abstract Generate a little endian physical scatter/gather list from a 
    given mbuf.
    @discussion Generate a little endian physical scatter/gather list from a 
    given mbuf. Coalesce mbuf chain when the number of segments in the 
    scatter/gather list exceeds numVectorSegments.
    @param packet The mbuf packet.
    @param vector Pointer to an array of IOPhysicalSegments for the output 
    physical scatter/gather list.
    @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
    @result The number of segments that were filled in is returned, or
    0 if an error occurred. */

    UInt32 getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
                                           struct IOPhysicalSegment * vector,
                                           UInt32 numVectorSegments = 0);
};

#ifdef __ppc__

struct IODBDMADescriptor;

//===========================================================================
//===========================================================================

/*! @class IOMbufDBDMAMemoryCursor : public IOMbufMemoryCursor
    @abstract A IOMbufMemoryCursor subclass that outputs a vector of 
    IODBDMADescriptors. */

class IOMbufDBDMAMemoryCursor : public IOMbufMemoryCursor
{
    OSDeclareDefaultStructors(IOMbufDBDMAMemoryCursor)

public:

/*! @function withSpecification
    @abstract Factory function to create and initialize an 
    IOMbufDBDMAMemoryCursor in one operation, see
    IOMbufMemoryCursor::initWithSpecification.
    @param maxSegmentSize Maximum allowable size for one segment.
    @param maxNumSegments Maximum number of segments.
    @result A new mbuf cursor if successfully created and initialized,
    0 otherwise. */

    static IOMbufDBDMAMemoryCursor * withSpecification(UInt32 maxSegmentSize, 
                                                       UInt32 maxNumSegments);

/*! @function getPhysicalSegments
    @abstract Generate a DBDMA descriptor list from a given mbuf.
    @param packet The mbuf packet.
    @param vector Pointer to an array of IODBDMADescriptor for the output list.
    @param numVectorSegments Maximum number of IODBDMADescriptors accepted.
    @result The number of segments that were filled in is returned, or
    0 if an error occurred. */

    UInt32 getPhysicalSegments(struct mbuf * packet,
                               struct IODBDMADescriptor *vector,
                               UInt32 numVectorSegments = 0);

/*! @function getPhysicalSegmentsWithCoalesce
    @abstract Generate a DBDMA descriptor list from a given mbuf.
    @discussion Generate a DBDMA descriptor list from a given mbuf.
    Coalesce mbuf chain when the number of elements in the list exceeds
    numVectorSegments.
    @param packet The mbuf packet.
    @param vector Pointer to an array of IODBDMADescriptor for the output list.
    @param numVectorSegments Maximum number of IODBDMADescriptors accepted.
    @result The number of segments that were filled in is returned, or
    0 if an error occurred. */

    UInt32 getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
                                           struct IODBDMADescriptor * vector,
                                           UInt32 numVectorSegments = 0);
};

#endif /* __ppc__ */

inline UInt32 IOMbufMemoryCursor::getAndResetCoalesceCount()
{
    UInt32 cnt = coalesceCount; coalesceCount = 0; return cnt;
}

inline UInt32
IOMbufNaturalMemoryCursor::getPhysicalSegments(struct mbuf *packet,
                       struct IOPhysicalSegment *vector,
                       UInt32 numVectorSegments = 0)
{
    return genPhysicalSegments(packet, vector, numVectorSegments, false);
}

inline UInt32
IOMbufNaturalMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
                                   struct IOPhysicalSegment *vector,
                                   UInt32 numVectorSegments = 0)
{
    return genPhysicalSegments(packet, vector, numVectorSegments, true);
}

inline UInt32
IOMbufBigMemoryCursor::getPhysicalSegments(struct mbuf *packet,
                       struct IOPhysicalSegment *vector,
                       UInt32 numVectorSegments = 0)
{
    return genPhysicalSegments(packet, vector, numVectorSegments, false);
}

inline UInt32
IOMbufBigMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
                                   struct IOPhysicalSegment *vector,
                                   UInt32 numVectorSegments = 0)
{
    return genPhysicalSegments(packet, vector, numVectorSegments, true);
}

inline UInt32
IOMbufLittleMemoryCursor::getPhysicalSegments(struct mbuf *packet,
                       struct IOPhysicalSegment *vector,
                       UInt32 numVectorSegments = 0)
{
    return genPhysicalSegments(packet, vector, numVectorSegments, false);
}

inline UInt32
IOMbufLittleMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
                                   struct IOPhysicalSegment *vector,
                                   UInt32 numVectorSegments = 0)
{
    return genPhysicalSegments(packet, vector, numVectorSegments, true);
}

#ifdef __ppc__
inline UInt32
IOMbufDBDMAMemoryCursor::getPhysicalSegments(struct mbuf *packet,
                                   struct IODBDMADescriptor *vector,
                                   UInt32 numVectorSegments = 0)
{
    return genPhysicalSegments(packet, vector, numVectorSegments, false);
}

inline UInt32
IOMbufDBDMAMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
                                   struct IODBDMADescriptor *vector,
                                   UInt32 numVectorSegments = 0)
{
    return genPhysicalSegments(packet, vector, numVectorSegments, true);
}
#endif /* __ppc__ */

#endif /* !_IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H */
Commit	Line	Data
1c79356b A	1	/*
	2	* Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
	6	* The contents of this file constitute Original Code as defined in and
	7	* are subject to the Apple Public Source License Version 1.1 (the
	8	* "License"). You may not use this file except in compliance with the
	9	* License. Please obtain a copy of the License at
	10	* http://www.apple.com/publicsource and read it before using this file.
	11	*
	12	* This Original Code and all software distributed under the License are
	13	* distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	14	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	15	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	16	* FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
	17	* License for the specific language governing rights and limitations
	18	* under the License.
	19	*
	20	* @APPLE_LICENSE_HEADER_END@
	21	*/
	22	/*
	23	* Copyright (c) 1999 Apple Computer, Inc. All rights reserved.
	24	*
	25	* IOMbufMemoryCursor.h created by gvdl on 1999-1-20
	26	*
	27	*/
	28
	29	#ifndef _IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H
	30	#define _IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H
	31
	32	#include <IOKit/IOMemoryCursor.h>
	33
	34	struct mbuf;
	35
	36	/*! @class IOMbufMemoryCursor : public IOMemoryCursor
	37	@abstract A mechanism to convert mbuf chains to physical addresses.
	38	@discussion The IOMbufMemoryCursor defines the super class that all
	39	specific mbuf cursors must inherit from, but a mbuf cursor can be created
	40	without a specific formal subclass by just providing a segment function to
	41	the initializers. This class performs the task of walking a given
	42	mbuf chain and creating a physical scatter/gather list appropriate for
	43	the target hardware. When necessary, this class may also coalesce
	44	mbuf chains when the generated scatter/gather list exceeds the specified
	45	hardware limit. However, this should be avoided since it exacts a
	46	performance cost.
	47	<br><br>
	48	A driver is expected to create a mbuf cursor and configure it to match the
	49	limitations of it's DMA hardware; for instance the mbuf cursor used by
	50	an Ethernet controller driver may have a maximum physical segment size
	51	of 1520, and allow for up to 6 physical segments. Thus it would create a
	52	mbuf cursor with a maxSegmentSize of 1520 and a maxNumSegments of 6.
	53	The driver may choose to supply an OutputSegmentFunc function to
	54	format the output of each scatter/gather segment to match the
	55	hardware descriptor format, or it may use a subclass of
	56	IOMbufMemoryCursor to generate IOPhysicalSegment segments with
	57	various byte orders.
	58	<br><br>
	59	A driver may also create more than one mbuf cursor, perhaps one
	60	dedicated for the transmit thread, and the other for the receive thread.
	61	This becomes a requirement when the driver is multi-threaded, since the
	62	mbuf cursor maintains state and does not support reentrancy. */
	63
	64	class IOMbufMemoryCursor : public IOMemoryCursor
65	{
66	OSDeclareAbstractStructors(IOMbufMemoryCursor)
67
68	protected:
69	UInt32 maxNumSegments;
70	UInt32 coalesceCount;
71	UInt32 packetTooBigErrors;
72
73	struct ExpansionData { };
74	/*! @var reserved
75	Reserved for future use. (Internal use only) */
76	ExpansionData *reserved;
77
78	virtual bool initWithSpecification(OutputSegmentFunc outSeg,
79	UInt32 maxSegmentSize,
80	UInt32 maxTransferSize,
81	UInt32 align);
82
83	public:
84	/*! @function initWithSpecification
85	@abstract Primary initializer for the IOMbufMemoryCursor class.
86	@param outSeg Function to call to output one physical segment.
87	@param maxSegmentSize Maximum allowable size for one segment.
88	@param maxNumSegments Maximum number of segments.
89	@result true if the inherited classes and this instance initialized
90	successfully. */
91
92	virtual bool initWithSpecification(OutputSegmentFunc outSeg,
93	UInt32 maxSegmentSize,
94	UInt32 maxNumSegments);
95
96	/*! @function genPhysicalSegments
97	@abstract Generate a physical scatter/gather list given a mbuf packet.
98	@discussion Generates a list of physical segments from the given mbuf.
99	@param packet The mbuf packet.
100	@param vector Void pointer to base of output physical scatter/gather list.
101	Always passed directly onto the OutputSegmentFunc without interpretation
102	by the cursor.
103	@param maxSegs Maximum number of segments that can be written to segments
104	array.
105	@param doCoalesce Set to true to perform coalescing when the required
106	number of segments exceeds the specified limit, otherwise abort and
107	return 0.
108	@result The number of segments that were filled in is returned, or
109	0 if an error occurred. */
110
111	virtual UInt32 genPhysicalSegments(struct mbuf * packet, void * vector,
112	UInt32 maxSegs, bool doCoalesce);
113
114	/*! @function getAndResetCoalesceCount
115	@abstract Returns a count of the total number of mbuf chains coalesced
116	by genPhysicalSegments(). The counter is then reset to 0.
117	@result The coalesce count. */
118
119	UInt32 getAndResetCoalesceCount();
120
121	// Virtual function padding
122	OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor, 0);
123	OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor, 1);
124	OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor, 2);
125	OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor, 3);
126	};
127
128
129	/*! @class IOMbufNaturalMemoryCursor : public IOMbufMemoryCursor
130	@abstract A IOMbufMemoryCursor subclass that outputs a vector of
131	IOPhysicalSegments in the natural byte orientation for the cpu.
132	@discussion The IOMbufNaturalMemoryCursor would be used when it is too
133	difficult to implement an OutputSegmentFunc that is more appropriate for
134	your hardware. This cursor just outputs an array of IOPhysicalSegments. */
135
136	class IOMbufNaturalMemoryCursor : public IOMbufMemoryCursor
137	{
138	OSDeclareDefaultStructors(IOMbufNaturalMemoryCursor)
139
140	public:
141
142	/*! @function withSpecification
143	@abstract Factory function to create and initialize an
144	IOMbufNaturalMemoryCursor in one operation, see
145	IOMbufMemoryCursor::initWithSpecification.
146	@param maxSegmentSize Maximum allowable size for one segment.
147	@param maxNumSegments Maximum number of segments.
148	@result A new mbuf cursor if successfully created and initialized,
149	0 otherwise. */
150
151	static IOMbufNaturalMemoryCursor * withSpecification(UInt32 maxSegmentSize,
152	UInt32 maxNumSegments);
153
154	/*! @function getPhysicalSegments
155	@abstract Generate a cpu natural physical scatter/gather list from a given
156	mbuf.
157	@param packet The mbuf packet.
158	@param vector Pointer to an array of IOPhysicalSegments for the output
159	physical scatter/gather list.
160	@param numVectorSegments Maximum number of IOPhysicalSegments accepted.
161	@result The number of segments that were filled in is returned, or
162	0 if an error occurred. */
163
164	UInt32 getPhysicalSegments(struct mbuf * packet,
165	struct IOPhysicalSegment * vector,
166	UInt32 numVectorSegments = 0);
167
168	/*! @function getPhysicalSegmentsWithCoalesce
169	@abstract Generate a cpu natural physical scatter/gather list from a given
170	mbuf.
171	@discussion Generate a cpu natural physical scatter/gather list from a
172	given mbuf. Coalesce mbuf chain when the number of segments in the
173	scatter/gather list exceeds numVectorSegments.
174	@param packet The mbuf packet.
175	@param vector Pointer to an array of IOPhysicalSegments for the output
176	physical scatter/gather list.
177	@param numVectorSegments Maximum number of IOPhysicalSegments accepted.
178	@result The number of segments that were filled in is returned, or
179	0 if an error occurred. */
180
181	UInt32 getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
182	struct IOPhysicalSegment * vector,
183	UInt32 numVectorSegments = 0);
184	};
185
186	//===========================================================================
187	//===========================================================================
188
189	/*! @class IOMbufBigMemoryCursor : public IOMbufMemoryCursor
190	@abstract A IOMbufMemoryCursor subclass that outputs a vector of
191	IOPhysicalSegments in the big endian byte order.
192	@discussion The IOMbufBigMemoryCursor would be used when the DMA hardware
193	requires a big endian address and length pair. This cursor outputs an
194	array of IOPhysicalSegments that are encoded in big-endian format. */
195
196	class IOMbufBigMemoryCursor : public IOMbufMemoryCursor
197	{
198	OSDeclareDefaultStructors(IOMbufBigMemoryCursor)
199
200	public:
201
202	/*! @function withSpecification
203	@abstract Factory function to create and initialize an
204	IOMbufBigMemoryCursor in one operation, see
205	IOMbufMemoryCursor::initWithSpecification.
206	@param maxSegmentSize Maximum allowable size for one segment.
207	@param maxNumSegments Maximum number of segments.
208	@result A new mbuf cursor if successfully created and initialized,
209	0 otherwise. */
210
211	static IOMbufBigMemoryCursor * withSpecification(UInt32 maxSegmentSize,
212	UInt32 maxNumSegments);
213
214	/*! @function getPhysicalSegments
215	@abstract Generate a big endian physical scatter/gather list from a given
216	mbuf.
217	@param packet The mbuf packet.
218	@param vector Pointer to an array of IOPhysicalSegments for the output
219	physical scatter/gather list.
220	@param numVectorSegments Maximum number of IOPhysicalSegments accepted.
221	@result The number of segments that were filled in is returned, or
222	0 if an error occurred. */
223
224	UInt32 getPhysicalSegments(struct mbuf * packet,
225	struct IOPhysicalSegment * vector,
226	UInt32 numVectorSegments = 0);
227
228	/*! @function getPhysicalSegmentsWithCoalesce
229	@abstract Generate a big endian physical scatter/gather list from a given
230	mbuf.
231	@discussion Generate a big endian physical scatter/gather list from a
232	given mbuf. Coalesce mbuf chain when the number of segments in the
233	scatter/gather list exceeds numVectorSegments.
234	@param packet The mbuf packet.
235	@param vector Pointer to an array of IOPhysicalSegments for the output
236	physical scatter/gather list.
237	@param numVectorSegments Maximum number of IOPhysicalSegments accepted.
238	@result The number of segments that were filled in is returned, or
239	0 if an error occurred. */
240
241	UInt32 getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
242	struct IOPhysicalSegment * vector,
243	UInt32 numVectorSegments = 0);
244	};
245
246	//===========================================================================
247	//===========================================================================
248
249	/*! @class IOMbufLittleMemoryCursor : public IOMbufMemoryCursor
250	@abstract A IOMbufMemoryCursor subclass that outputs a vector of
251	IOPhysicalSegments in the little endian byte order.
252	@discussion The IOMbufLittleMemoryCursor would be used when the DMA
253	hardware requires a little endian address and length pair. This cursor
254	outputs an array of IOPhysicalSegments that are encoded in little endian
255	format. */
256
257	class IOMbufLittleMemoryCursor : public IOMbufMemoryCursor
258	{
259	OSDeclareDefaultStructors(IOMbufLittleMemoryCursor)
260
261	public:
262
263	/*! @function withSpecification
264	@abstract Factory function to create and initialize an
265	IOMbufLittleMemoryCursor in one operation, see
266	IOMbufMemoryCursor::initWithSpecification.
267	@param maxSegmentSize Maximum allowable size for one segment.
268	@param maxNumSegments Maximum number of segments.
269	@result A new mbuf cursor if successfully created and initialized,
270	0 otherwise. */
271
272	static IOMbufLittleMemoryCursor * withSpecification(UInt32 maxSegmentSize,
273	UInt32 maxNumSegments);
274
275	/*! @function getPhysicalSegments
276	@abstract Generate a little endian physical scatter/gather list from a
277	given mbuf.
278	@param packet The mbuf packet.
279	@param vector Pointer to an array of IOPhysicalSegments for the output
280	physical scatter/gather list.
281	@param numVectorSegments Maximum number of IOPhysicalSegments accepted.
282	@result The number of segments that were filled in is returned, or
283	0 if an error occurred. */
284
285	UInt32 getPhysicalSegments(struct mbuf * packet,
286	struct IOPhysicalSegment * vector,
287	UInt32 numVectorSegments = 0);
288
289	/*! @function getPhysicalSegmentsWithCoalesce
290	@abstract Generate a little endian physical scatter/gather list from a
291	given mbuf.
292	@discussion Generate a little endian physical scatter/gather list from a
293	given mbuf. Coalesce mbuf chain when the number of segments in the
294	scatter/gather list exceeds numVectorSegments.
295	@param packet The mbuf packet.
296	@param vector Pointer to an array of IOPhysicalSegments for the output
297	physical scatter/gather list.
298	@param numVectorSegments Maximum number of IOPhysicalSegments accepted.
299	@result The number of segments that were filled in is returned, or
300	0 if an error occurred. */
301
302	UInt32 getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
303	struct IOPhysicalSegment * vector,
304	UInt32 numVectorSegments = 0);
305	};
306
307	#ifdef __ppc__
308
309	struct IODBDMADescriptor;
310
311	//===========================================================================
312	//===========================================================================
313
314	/*! @class IOMbufDBDMAMemoryCursor : public IOMbufMemoryCursor
315	@abstract A IOMbufMemoryCursor subclass that outputs a vector of
316	IODBDMADescriptors. */
317
318	class IOMbufDBDMAMemoryCursor : public IOMbufMemoryCursor
319	{
320	OSDeclareDefaultStructors(IOMbufDBDMAMemoryCursor)
321
322	public:
323
324	/*! @function withSpecification
325	@abstract Factory function to create and initialize an
326	IOMbufDBDMAMemoryCursor in one operation, see
327	IOMbufMemoryCursor::initWithSpecification.
328	@param maxSegmentSize Maximum allowable size for one segment.
329	@param maxNumSegments Maximum number of segments.
330	@result A new mbuf cursor if successfully created and initialized,
331	0 otherwise. */
332
333	static IOMbufDBDMAMemoryCursor * withSpecification(UInt32 maxSegmentSize,
334	UInt32 maxNumSegments);
335
336	/*! @function getPhysicalSegments
337	@abstract Generate a DBDMA descriptor list from a given mbuf.
338	@param packet The mbuf packet.
339	@param vector Pointer to an array of IODBDMADescriptor for the output list.
340	@param numVectorSegments Maximum number of IODBDMADescriptors accepted.
341	@result The number of segments that were filled in is returned, or
342	0 if an error occurred. */
343
344	UInt32 getPhysicalSegments(struct mbuf * packet,
345	struct IODBDMADescriptor *vector,
346	UInt32 numVectorSegments = 0);
347
348	/*! @function getPhysicalSegmentsWithCoalesce
349	@abstract Generate a DBDMA descriptor list from a given mbuf.
350	@discussion Generate a DBDMA descriptor list from a given mbuf.
351	Coalesce mbuf chain when the number of elements in the list exceeds
352	numVectorSegments.
353	@param packet The mbuf packet.
354	@param vector Pointer to an array of IODBDMADescriptor for the output list.
355	@param numVectorSegments Maximum number of IODBDMADescriptors accepted.
356	@result The number of segments that were filled in is returned, or
357	0 if an error occurred. */
358
359	UInt32 getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
360	struct IODBDMADescriptor * vector,
361	UInt32 numVectorSegments = 0);
362	};
363
364	#endif /* __ppc__ */
365
366	inline UInt32 IOMbufMemoryCursor::getAndResetCoalesceCount()
367	{
368	UInt32 cnt = coalesceCount; coalesceCount = 0; return cnt;
369	}
370
371	inline UInt32
372	IOMbufNaturalMemoryCursor::getPhysicalSegments(struct mbuf *packet,
373	struct IOPhysicalSegment *vector,
374	UInt32 numVectorSegments = 0)
375	{
376	return genPhysicalSegments(packet, vector, numVectorSegments, false);
377	}
378
379	inline UInt32
380	IOMbufNaturalMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
381	struct IOPhysicalSegment *vector,
382	UInt32 numVectorSegments = 0)
383	{
384	return genPhysicalSegments(packet, vector, numVectorSegments, true);
385	}
386
387	inline UInt32
388	IOMbufBigMemoryCursor::getPhysicalSegments(struct mbuf *packet,
389	struct IOPhysicalSegment *vector,
390	UInt32 numVectorSegments = 0)
391	{
392	return genPhysicalSegments(packet, vector, numVectorSegments, false);
393	}
394
395	inline UInt32
396	IOMbufBigMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
397	struct IOPhysicalSegment *vector,
398	UInt32 numVectorSegments = 0)
399	{
400	return genPhysicalSegments(packet, vector, numVectorSegments, true);
401	}
402
403	inline UInt32
404	IOMbufLittleMemoryCursor::getPhysicalSegments(struct mbuf *packet,
405	struct IOPhysicalSegment *vector,
406	UInt32 numVectorSegments = 0)
407	{
408	return genPhysicalSegments(packet, vector, numVectorSegments, false);
409	}
410
411	inline UInt32
412	IOMbufLittleMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
413	struct IOPhysicalSegment *vector,
414	UInt32 numVectorSegments = 0)
415	{
416	return genPhysicalSegments(packet, vector, numVectorSegments, true);
417	}
418
419	#ifdef __ppc__
420	inline UInt32
421	IOMbufDBDMAMemoryCursor::getPhysicalSegments(struct mbuf *packet,
422	struct IODBDMADescriptor *vector,
423	UInt32 numVectorSegments = 0)
424	{
425	return genPhysicalSegments(packet, vector, numVectorSegments, false);
426	}
427
428	inline UInt32
429	IOMbufDBDMAMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
430	struct IODBDMADescriptor *vector,
431	UInt32 numVectorSegments = 0)
432	{
433	return genPhysicalSegments(packet, vector, numVectorSegments, true);
434	}
435	#endif /* __ppc__ */
436
437	#endif /* !_IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H */
438