![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IOMBufMemoryCursor.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / XNU / iokit / IOKit / network|
Return to IOMBufMemoryCursor.h CVS log | Up to [Apple XNU] / XNU / iokit / IOKit / network |
1.1 root 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: private:
69: virtual bool initWithSpecification(OutputSegmentFunc outSeg,
70: UInt maxSegmentSize,
71: UInt maxTransferSize,
72: UInt align);
73:
74: protected:
75: UInt maxNumSegments;
76: UInt coalesceCount;
77: UInt packetTooBigErrors;
78:
79: /*! @function initWithSpecification
80: @abstract Primary initializer for the IOMBufMemoryCursor class.
81: @param outSeg Function to call to output one physical segment.
82: @param maxSegmentSize Maximum allowable size for one segment.
83: @param maxNumSegments Maximum number of segments.
84: @result true if the inherited classes and this instance initialized
85: successfully. */
86:
87: virtual bool initWithSpecification(OutputSegmentFunc outSeg,
88: UInt maxSegmentSize,
89: UInt maxNumSegments);
90:
91: /*! @function genPhysicalSegments
92: @abstract Generate a physical scatter/gather list given a mbuf packet.
93: @discussion Generates a list of physical segments from the given mbuf.
94: @param packet The mbuf packet.
95: @param vector Void pointer to base of output physical scatter/gather list.
96: Always passed directly onto the OutputSegmentFunc without interpretation
97: by the cursor.
98: @param maxSegs Maximum number of segments that can be written to segments
99: array.
100: @param doCoalesce Set to true to perform coalescing when the required
101: number of segments exceeds the specified limit, otherwise abort and
102: return 0.
103: @result The number of segments that were filled in is returned, or
104: 0 if an error occurred. */
105:
106: virtual UInt genPhysicalSegments(struct mbuf * packet, void * vector,
107: UInt maxSegs, bool doCoalesce);
108:
109: public:
110:
111: /*! @function genPhysicalSegments
112: @abstract Returns a count of the total number of mbuf chains coalesced
113: by genPhysicalSegments(). The counter is then reset to 0.
114: @result The coalesce count. */
115:
116: UInt getAndResetCoalesceCount();
117: };
118:
119:
120: /*! @class IOMBufNaturalMemoryCursor : public IOMBufMemoryCursor
121: @abstract A IOMBufMemoryCursor subclass that outputs a vector of
122: IOPhysicalSegments in the natural byte orientation for the cpu.
123: @discussion The IOMBufNaturalMemoryCursor would be used when it is too
124: difficult to implement an OutputSegmentFunc that is more appropriate for
125: your hardware. This cursor just outputs an array of IOPhysicalSegments. */
126:
127: class IOMBufNaturalMemoryCursor : public IOMBufMemoryCursor
128: {
129: OSDeclareDefaultStructors(IOMBufNaturalMemoryCursor)
130:
131: public:
132:
133: /*! @function withSpecification
134: @abstract Factory function to create and initialize an
135: IOMBufNaturalMemoryCursor in one operation, see
136: IOMBufMemoryCursor::initWithSpecification.
137: @param maxSegmentSize Maximum allowable size for one segment.
138: @param maxNumSegments Maximum number of segments.
139: @result A new mbuf cursor if successfully created and initialized,
140: 0 otherwise. */
141:
142: static IOMBufNaturalMemoryCursor * withSpecification(UInt maxSegmentSize,
143: UInt maxNumSegments);
144:
145: /*! @function getPhysicalSegments
146: @abstract Generate a cpu natural physical scatter/gather list from a given
147: mbuf.
148: @param packet The mbuf packet.
149: @param vector Pointer to an array of IOPhysicalSegments for the output
150: physical scatter/gather list.
151: @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
152: @result The number of segments that were filled in is returned, or
153: 0 if an error occurred. */
154:
155: UInt getPhysicalSegments(struct mbuf * packet,
156: struct IOPhysicalSegment * vector,
157: UInt numVectorSegments = 0);
158:
159: /*! @function getPhysicalSegmentsWithCoalesce
160: @abstract Generate a cpu natural physical scatter/gather list from a given
161: mbuf.
162: @discussion Generate a cpu natural physical scatter/gather list from a
163: given mbuf. Coalesce mbuf chain when the number of segments in the
164: scatter/gather list exceeds numVectorSegments.
165: @param packet The mbuf packet.
166: @param vector Pointer to an array of IOPhysicalSegments for the output
167: physical scatter/gather list.
168: @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
169: @result The number of segments that were filled in is returned, or
170: 0 if an error occurred. */
171:
172: UInt getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
173: struct IOPhysicalSegment * vector,
174: UInt numVectorSegments = 0);
175: };
176:
177: //===========================================================================
178: //===========================================================================
179:
180: /*! @class IOMBufBigMemoryCursor : public IOMBufMemoryCursor
181: @abstract A IOMBufMemoryCursor subclass that outputs a vector of
182: IOPhysicalSegments in the big endian byte order.
183: @discussion The IOMBufBigMemoryCursor would be used when the DMA hardware
184: requires a big endian address and length pair. This cursor outputs an
185: array of IOPhysicalSegments that are encoded in big-endian format. */
186:
187: class IOMBufBigMemoryCursor : public IOMBufMemoryCursor
188: {
189: OSDeclareDefaultStructors(IOMBufBigMemoryCursor)
190:
191: public:
192:
193: /*! @function withSpecification
194: @abstract Factory function to create and initialize an
195: IOMBufBigMemoryCursor in one operation, see
196: IOMBufMemoryCursor::initWithSpecification.
197: @param maxSegmentSize Maximum allowable size for one segment.
198: @param maxNumSegments Maximum number of segments.
199: @result A new mbuf cursor if successfully created and initialized,
200: 0 otherwise. */
201:
202: static IOMBufBigMemoryCursor * withSpecification(UInt maxSegmentSize,
203: UInt maxNumSegments);
204:
205: /*! @function getPhysicalSegments
206: @abstract Generate a big endian physical scatter/gather list from a given
207: mbuf.
208: @param packet The mbuf packet.
209: @param vector Pointer to an array of IOPhysicalSegments for the output
210: physical scatter/gather list.
211: @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
212: @result The number of segments that were filled in is returned, or
213: 0 if an error occurred. */
214:
215: UInt getPhysicalSegments(struct mbuf * packet,
216: struct IOPhysicalSegment * vector,
217: UInt numVectorSegments = 0);
218:
219: /*! @function getPhysicalSegmentsWithCoalesce
220: @abstract Generate a big endian physical scatter/gather list from a given
221: mbuf.
222: @discussion Generate a big endian physical scatter/gather list from a
223: given mbuf. Coalesce mbuf chain when the number of segments in the
224: scatter/gather list exceeds numVectorSegments.
225: @param packet The mbuf packet.
226: @param vector Pointer to an array of IOPhysicalSegments for the output
227: physical scatter/gather list.
228: @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
229: @result The number of segments that were filled in is returned, or
230: 0 if an error occurred. */
231:
232: UInt getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
233: struct IOPhysicalSegment * vector,
234: UInt numVectorSegments = 0);
235: };
236:
237: //===========================================================================
238: //===========================================================================
239:
240: /*! @class IOMBufLittleMemoryCursor : public IOMBufMemoryCursor
241: @abstract A IOMBufMemoryCursor subclass that outputs a vector of
242: IOPhysicalSegments in the little endian byte order.
243: @discussion The IOMBufLittleMemoryCursor would be used when the DMA
244: hardware requires a little endian address and length pair. This cursor
245: outputs an array of IOPhysicalSegments that are encoded in little endian
246: format. */
247:
248: class IOMBufLittleMemoryCursor : public IOMBufMemoryCursor
249: {
250: OSDeclareDefaultStructors(IOMBufLittleMemoryCursor)
251:
252: public:
253:
254: /*! @function withSpecification
255: @abstract Factory function to create and initialize an
256: IOMBufLittleMemoryCursor in one operation, see
257: IOMBufMemoryCursor::initWithSpecification.
258: @param maxSegmentSize Maximum allowable size for one segment.
259: @param maxNumSegments Maximum number of segments.
260: @result A new mbuf cursor if successfully created and initialized,
261: 0 otherwise. */
262:
263: static IOMBufLittleMemoryCursor * withSpecification(UInt maxSegmentSize,
264: UInt maxNumSegments);
265:
266: /*! @function getPhysicalSegments
267: @abstract Generate a little endian physical scatter/gather list from a
268: given mbuf.
269: @param packet The mbuf packet.
270: @param vector Pointer to an array of IOPhysicalSegments for the output
271: physical scatter/gather list.
272: @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
273: @result The number of segments that were filled in is returned, or
274: 0 if an error occurred. */
275:
276: UInt getPhysicalSegments(struct mbuf * packet,
277: struct IOPhysicalSegment * vector,
278: UInt numVectorSegments = 0);
279:
280: /*! @function getPhysicalSegmentsWithCoalesce
281: @abstract Generate a little endian physical scatter/gather list from a
282: given mbuf.
283: @discussion Generate a little endian physical scatter/gather list from a
284: given mbuf. Coalesce mbuf chain when the number of segments in the
285: scatter/gather list exceeds numVectorSegments.
286: @param packet The mbuf packet.
287: @param vector Pointer to an array of IOPhysicalSegments for the output
288: physical scatter/gather list.
289: @param numVectorSegments Maximum number of IOPhysicalSegments accepted.
290: @result The number of segments that were filled in is returned, or
291: 0 if an error occurred. */
292:
293: UInt getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
294: struct IOPhysicalSegment * vector,
295: UInt numVectorSegments = 0);
296: };
297:
298: #ifdef __ppc__
299:
300: struct IODBDMADescriptor;
301:
302: //===========================================================================
303: //===========================================================================
304:
305: /*! @class IOMBufDBDMAMemoryCursor : public IOMBufMemoryCursor
306: @abstract A IOMBufMemoryCursor subclass that outputs a vector of
307: IODBDMADescriptors. */
308:
309: class IOMBufDBDMAMemoryCursor : public IOMBufMemoryCursor
310: {
311: OSDeclareDefaultStructors(IOMBufDBDMAMemoryCursor)
312:
313: public:
314:
315: /*! @function withSpecification
316: @abstract Factory function to create and initialize an
317: IOMBufDBDMAMemoryCursor in one operation, see
318: IOMBufMemoryCursor::initWithSpecification.
319: @param maxSegmentSize Maximum allowable size for one segment.
320: @param maxNumSegments Maximum number of segments.
321: @result A new mbuf cursor if successfully created and initialized,
322: 0 otherwise. */
323:
324: static IOMBufDBDMAMemoryCursor * withSpecification(UInt maxSegmentSize,
325: UInt maxNumSegments);
326:
327: /*! @function getPhysicalSegments
328: @abstract Generate a DBDMA descriptor list from a given mbuf.
329: @param packet The mbuf packet.
330: @param vector Pointer to an array of IODBDMADescriptor for the output list.
331: @param numVectorSegments Maximum number of IODBDMADescriptors accepted.
332: @result The number of segments that were filled in is returned, or
333: 0 if an error occurred. */
334:
335: UInt getPhysicalSegments(struct mbuf * packet,
336: struct IODBDMADescriptor *vector,
337: UInt numVectorSegments = 0);
338:
339: /*! @function getPhysicalSegmentsWithCoalesce
340: @abstract Generate a DBDMA descriptor list from a given mbuf.
341: @discussion Generate a DBDMA descriptor list from a given mbuf.
342: Coalesce mbuf chain when the number of elements in the list exceeds
343: numVectorSegments.
344: @param packet The mbuf packet.
345: @param vector Pointer to an array of IODBDMADescriptor for the output list.
346: @param numVectorSegments Maximum number of IODBDMADescriptors accepted.
347: @result The number of segments that were filled in is returned, or
348: 0 if an error occurred. */
349:
350: UInt getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
351: struct IODBDMADescriptor * vector,
352: UInt numVectorSegments = 0);
353: };
354:
355: #endif /* __ppc__ */
356:
357: inline UInt IOMBufMemoryCursor::getAndResetCoalesceCount()
358: {
359: UInt cnt = coalesceCount; coalesceCount = 0; return cnt;
360: }
361:
362: inline UInt
363: IOMBufNaturalMemoryCursor::getPhysicalSegments(struct mbuf *packet,
364: struct IOPhysicalSegment *vector,
365: UInt numVectorSegments = 0)
366: {
367: return genPhysicalSegments(packet, vector, numVectorSegments, false);
368: }
369:
370: inline UInt
371: IOMBufNaturalMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
372: struct IOPhysicalSegment *vector,
373: UInt numVectorSegments = 0)
374: {
375: return genPhysicalSegments(packet, vector, numVectorSegments, true);
376: }
377:
378: inline UInt
379: IOMBufBigMemoryCursor::getPhysicalSegments(struct mbuf *packet,
380: struct IOPhysicalSegment *vector,
381: UInt numVectorSegments = 0)
382: {
383: return genPhysicalSegments(packet, vector, numVectorSegments, false);
384: }
385:
386: inline UInt
387: IOMBufBigMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
388: struct IOPhysicalSegment *vector,
389: UInt numVectorSegments = 0)
390: {
391: return genPhysicalSegments(packet, vector, numVectorSegments, true);
392: }
393:
394: inline UInt
395: IOMBufLittleMemoryCursor::getPhysicalSegments(struct mbuf *packet,
396: struct IOPhysicalSegment *vector,
397: UInt numVectorSegments = 0)
398: {
399: return genPhysicalSegments(packet, vector, numVectorSegments, false);
400: }
401:
402: inline UInt
403: IOMBufLittleMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
404: struct IOPhysicalSegment *vector,
405: UInt numVectorSegments = 0)
406: {
407: return genPhysicalSegments(packet, vector, numVectorSegments, true);
408: }
409:
410: #ifdef __ppc__
411: inline UInt
412: IOMBufDBDMAMemoryCursor::getPhysicalSegments(struct mbuf *packet,
413: struct IODBDMADescriptor *vector,
414: UInt numVectorSegments = 0)
415: {
416: return genPhysicalSegments(packet, vector, numVectorSegments, false);
417: }
418:
419: inline UInt
420: IOMBufDBDMAMemoryCursor::getPhysicalSegmentsWithCoalesce(struct mbuf *packet,
421: struct IODBDMADescriptor *vector,
422: UInt numVectorSegments = 0)
423: {
424: return genPhysicalSegments(packet, vector, numVectorSegments, true);
425: }
426: #endif /* __ppc__ */
427:
428: #endif /* !_IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H */
429:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.