Root/
Source at commit 1165 created 13 years 11 days ago. By slice, new targets: make image and make pkg, Russian localization | |
---|---|
1 | /*␊ |
2 | * Copyright (c) 1998-2008 Apple 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 | #ifndef _IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H␊ |
24 | #define _IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H␊ |
25 | ␊ |
26 | #include <IOKit/IOMemoryCursor.h>␊ |
27 | ␊ |
28 | ␊ |
29 | /*! @class IOMbufMemoryCursor␊ |
30 | @abstract A mechanism to convert mbuf chains to physical addresses.␊ |
31 | @discussion The IOMbufMemoryCursor defines the super class that all␊ |
32 | specific mbuf cursors must inherit from, but a mbuf cursor can be created ␊ |
33 | without a specific formal subclass by just providing a segment function to␊ |
34 | the initializers. This class performs the task of walking a given␊ |
35 | mbuf chain and creating a physical scatter/gather list appropriate for␊ |
36 | the target hardware. When necessary, this class may also coalesce␊ |
37 | mbuf chains when the generated scatter/gather list exceeds the specified ␊ |
38 | hardware limit. However, this should be avoided since it exacts a ␊ |
39 | performance cost.␊ |
40 | <br><br>␊ |
41 | A driver is expected to create a mbuf cursor and configure it to match the␊ |
42 | limitations of it's DMA hardware; for instance the mbuf cursor used by␊ |
43 | an Ethernet controller driver may have a maximum physical segment size␊ |
44 | of 1520, and allow for up to 6 physical segments. Thus it would create a ␊ |
45 | mbuf cursor with a maxSegmentSize of 1520 and a maxNumSegments of 6.␊ |
46 | The driver may choose to supply an OutputSegmentFunc function to␊ |
47 | format the output of each scatter/gather segment to match the␊ |
48 | hardware descriptor format, or it may use a subclass of ␊ |
49 | IOMbufMemoryCursor to generate IOPhysicalSegment segments with ␊ |
50 | various byte orders.␊ |
51 | <br><br>␊ |
52 | A driver may also create more than one mbuf cursor, perhaps one␊ |
53 | dedicated for the transmit thread, and the other for the receive thread.␊ |
54 | This becomes a requirement when the driver is multi-threaded, since the ␊ |
55 | mbuf cursor maintains state and does not support reentrancy. */␊ |
56 | ␊ |
57 | class IOMbufMemoryCursor : public IOMemoryCursor␊ |
58 | {␊ |
59 | OSDeclareDefaultStructors(IOMbufMemoryCursor)␊ |
60 | ␊ |
61 | protected:␊ |
62 | UInt32 maxNumSegments;␊ |
63 | UInt32 coalesceCount;␊ |
64 | UInt32 packetTooBigErrors;␊ |
65 | ␊ |
66 | struct ExpansionData { };␊ |
67 | /*! @var reserved␊ |
68 | Reserved for future use. (Internal use only) */␊ |
69 | ExpansionData *reserved;␊ |
70 | ␊ |
71 | virtual bool initWithSpecification(OutputSegmentFunc outSeg,␊ |
72 | UInt32 maxSegmentSize,␊ |
73 | UInt32 maxTransferSize,␊ |
74 | UInt32 align);␊ |
75 | ␊ |
76 | public:␊ |
77 | /*! @function initWithSpecification␊ |
78 | @abstract Primary initializer for the IOMbufMemoryCursor class.␊ |
79 | @param outSeg Function to call to output one physical segment.␊ |
80 | @param maxSegmentSize Maximum allowable size for one segment.␊ |
81 | @param maxNumSegments Maximum number of segments.␊ |
82 | @result Returns true if the inherited classes and this instance initialized␊ |
83 | successfully.␊ |
84 | */␊ |
85 | ␊ |
86 | virtual bool initWithSpecification(OutputSegmentFunc outSeg,␊ |
87 | UInt32 maxSegmentSize,␊ |
88 | UInt32 maxNumSegments);␊ |
89 | ␊ |
90 | /*! @function genPhysicalSegments␊ |
91 | @abstract Generates a physical scatter/gather list given a mbuf packet.␊ |
92 | @discussion Generates a list of physical segments from the given mbuf.␊ |
93 | @param packet The mbuf packet.␊ |
94 | @param vector Void pointer to base of output physical scatter/gather list.␊ |
95 | Always passed directly onto the OutputSegmentFunc without interpretation␊ |
96 | by the cursor. ␊ |
97 | @param maxSegs Maximum number of segments that can be written to segments␊ |
98 | array.␊ |
99 | @param doCoalesce Set to true to perform coalescing when the required ␊ |
100 | number of segments exceeds the specified limit, otherwise abort and␊ |
101 | return 0.␊ |
102 | @result Returns the number of segments that were filled in, or␊ |
103 | 0 if an error occurred. ␊ |
104 | */␊ |
105 | ␊ |
106 | virtual UInt32 genPhysicalSegments(mbuf_t packet, void * vector,␊ |
107 | UInt32 maxSegs, bool doCoalesce);␊ |
108 | ␊ |
109 | /*! @function getAndResetCoalesceCount␊ |
110 | @abstract Returns a count of the total number of mbuf chains coalesced␊ |
111 | by genPhysicalSegments().␊ |
112 | @discussion This method returns a count of the total number of mbuf chains coalesced␊ |
113 | by genPhysicalSegments(). The counter is then reset to 0.␊ |
114 | @result Returns the coalesce count. ␊ |
115 | */␊ |
116 | ␊ |
117 | UInt32 getAndResetCoalesceCount();␊ |
118 | ␊ |
119 | // Virtual function padding␊ |
120 | OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor, 0);␊ |
121 | OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor, 1);␊ |
122 | OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor, 2);␊ |
123 | OSMetaClassDeclareReservedUnused( IOMbufMemoryCursor, 3);␊ |
124 | };␊ |
125 | ␊ |
126 | ␊ |
127 | /*! @class IOMbufNaturalMemoryCursor␊ |
128 | @abstract An IOMbufMemoryCursor subclass that outputs a vector of␊ |
129 | IOPhysicalSegments in the natural byte orientation for the cpu. ␊ |
130 | @discussion The IOMbufNaturalMemoryCursor would be used when it is too␊ |
131 | difficult to implement an OutputSegmentFunc that is more appropriate for␊ |
132 | your hardware. This cursor just outputs an array of IOPhysicalSegments. ␊ |
133 | */␊ |
134 | ␊ |
135 | class IOMbufNaturalMemoryCursor : public IOMbufMemoryCursor␊ |
136 | {␊ |
137 | OSDeclareDefaultStructors(IOMbufNaturalMemoryCursor)␊ |
138 | ␊ |
139 | public:␊ |
140 | ␊ |
141 | /*! @function withSpecification␊ |
142 | @abstract Factory function that creates and initializes an ␊ |
143 | IOMbufNaturalMemoryCursor in one operation. ␊ |
144 | @discussion See also IOMbufMemoryCursor::initWithSpecification.␊ |
145 | @param maxSegmentSize Maximum allowable size for one segment.␊ |
146 | @param maxNumSegments Maximum number of segments.␊ |
147 | @result Returns a new mbuf cursor if successfully created and initialized,␊ |
148 | 0 otherwise. ␊ |
149 | */␊ |
150 | ␊ |
151 | static IOMbufNaturalMemoryCursor * withSpecification(UInt32 maxSegmentSize, ␊ |
152 | UInt32 maxNumSegments);␊ |
153 | ␊ |
154 | /*! @function getPhysicalSegments␊ |
155 | @abstract Generates 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 Returns the number of segments that were filled in, or␊ |
162 | 0 if an error occurred. ␊ |
163 | */␊ |
164 | ␊ |
165 | UInt32 getPhysicalSegments(mbuf_t packet,␊ |
166 | struct IOPhysicalSegment * vector,␊ |
167 | UInt32 numVectorSegments = 0);␊ |
168 | ␊ |
169 | /*! @function getPhysicalSegmentsWithCoalesce␊ |
170 | @abstract Generates a cpu natural physical scatter/gather list from a given␊ |
171 | mbuf.␊ |
172 | @discussion Generate a cpu natural physical scatter/gather list from a ␊ |
173 | given mbuf. Coalesce mbuf chain when the number of segments in the ␊ |
174 | scatter/gather list exceeds numVectorSegments.␊ |
175 | @param packet The mbuf packet.␊ |
176 | @param vector Pointer to an array of IOPhysicalSegments for the output ␊ |
177 | physical scatter/gather list.␊ |
178 | @param numVectorSegments Maximum number of IOPhysicalSegments accepted.␊ |
179 | @result Returns the number of segments that were filled in, or␊ |
180 | 0 if an error occurred. ␊ |
181 | */␊ |
182 | ␊ |
183 | UInt32 getPhysicalSegmentsWithCoalesce(mbuf_t packet,␊ |
184 | struct IOPhysicalSegment * vector,␊ |
185 | UInt32 numVectorSegments = 0);␊ |
186 | };␊ |
187 | ␊ |
188 | //===========================================================================␊ |
189 | //===========================================================================␊ |
190 | ␊ |
191 | /*! @class IOMbufBigMemoryCursor␊ |
192 | @abstract An IOMbufMemoryCursor subclass that outputs a vector of ␊ |
193 | IOPhysicalSegments in the big endian byte order. ␊ |
194 | @discussion The IOMbufBigMemoryCursor would be used when the DMA hardware ␊ |
195 | requires a big endian address and length pair. This cursor outputs an ␊ |
196 | array of IOPhysicalSegments that are encoded in big-endian format. ␊ |
197 | */␊ |
198 | ␊ |
199 | class IOMbufBigMemoryCursor : public IOMbufMemoryCursor␊ |
200 | {␊ |
201 | OSDeclareDefaultStructors(IOMbufBigMemoryCursor)␊ |
202 | ␊ |
203 | public:␊ |
204 | ␊ |
205 | /*! @function withSpecification␊ |
206 | @abstract Factory function that creates and initializes an ␊ |
207 | IOMbufBigMemoryCursor in one operation.␊ |
208 | @discussion See also IOMbufMemoryCursor::initWithSpecification.␊ |
209 | @param maxSegmentSize Maximum allowable size for one segment.␊ |
210 | @param maxNumSegments Maximum number of segments.␊ |
211 | @result Returns a new mbuf cursor if successfully created and initialized,␊ |
212 | 0 otherwise. ␊ |
213 | */␊ |
214 | ␊ |
215 | static IOMbufBigMemoryCursor * withSpecification(UInt32 maxSegmentSize,␊ |
216 | UInt32 maxNumSegments);␊ |
217 | ␊ |
218 | /*! @function getPhysicalSegments␊ |
219 | @abstract Generates a big endian physical scatter/gather list from a given␊ |
220 | mbuf.␊ |
221 | @param packet The mbuf packet.␊ |
222 | @param vector Pointer to an array of IOPhysicalSegments for the output ␊ |
223 | physical scatter/gather list.␊ |
224 | @param numVectorSegments Maximum number of IOPhysicalSegments accepted.␊ |
225 | @result Returns the number of segments that were filled in, or␊ |
226 | 0 if an error occurred. ␊ |
227 | */␊ |
228 | ␊ |
229 | UInt32 getPhysicalSegments(mbuf_t packet,␊ |
230 | struct IOPhysicalSegment * vector,␊ |
231 | UInt32 numVectorSegments = 0);␊ |
232 | ␊ |
233 | /*! @function getPhysicalSegmentsWithCoalesce␊ |
234 | @abstract Generates a big endian physical scatter/gather list from a given␊ |
235 | mbuf.␊ |
236 | @discussion Generate a big endian physical scatter/gather list from a ␊ |
237 | given mbuf. Coalesce mbuf chain when the number of segments in the ␊ |
238 | scatter/gather list exceeds numVectorSegments.␊ |
239 | @param packet The mbuf packet.␊ |
240 | @param vector Pointer to an array of IOPhysicalSegments for the output ␊ |
241 | physical scatter/gather list.␊ |
242 | @param numVectorSegments Maximum number of IOPhysicalSegments accepted.␊ |
243 | @result Returns the number of segments that were filled in, or␊ |
244 | 0 if an error occurred. ␊ |
245 | */␊ |
246 | ␊ |
247 | UInt32 getPhysicalSegmentsWithCoalesce(mbuf_t packet,␊ |
248 | struct IOPhysicalSegment * vector,␊ |
249 | UInt32 numVectorSegments = 0);␊ |
250 | };␊ |
251 | ␊ |
252 | //===========================================================================␊ |
253 | //===========================================================================␊ |
254 | ␊ |
255 | /*! @class IOMbufLittleMemoryCursor␊ |
256 | @abstract An IOMbufMemoryCursor subclass that outputs a vector of ␊ |
257 | IOPhysicalSegments in the little endian byte order. ␊ |
258 | @discussion The IOMbufLittleMemoryCursor would be used when the DMA ␊ |
259 | hardware requires a little endian address and length pair. This cursor ␊ |
260 | outputs an array of IOPhysicalSegments that are encoded in little endian ␊ |
261 | format. ␊ |
262 | */␊ |
263 | ␊ |
264 | class IOMbufLittleMemoryCursor : public IOMbufMemoryCursor␊ |
265 | {␊ |
266 | OSDeclareDefaultStructors(IOMbufLittleMemoryCursor)␊ |
267 | ␊ |
268 | public:␊ |
269 | ␊ |
270 | /*! @function withSpecification␊ |
271 | @abstract Factory function that creates and initializes an ␊ |
272 | IOMbufLittleMemoryCursor in one operation.␊ |
273 | @discussion See also IOMbufMemoryCursor::initWithSpecification.␊ |
274 | @param maxSegmentSize Maximum allowable size for one segment.␊ |
275 | @param maxNumSegments Maximum number of segments.␊ |
276 | @result Returns a new mbuf cursor if successfully created and initialized,␊ |
277 | 0 otherwise. ␊ |
278 | */␊ |
279 | ␊ |
280 | static IOMbufLittleMemoryCursor * withSpecification(UInt32 maxSegmentSize, ␊ |
281 | UInt32 maxNumSegments);␊ |
282 | ␊ |
283 | /*! @function getPhysicalSegments␊ |
284 | @abstract Generates a little endian physical scatter/gather list from a ␊ |
285 | given mbuf.␊ |
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 Returns the number of segments that were filled in, or␊ |
291 | 0 if an error occurred. ␊ |
292 | */␊ |
293 | ␊ |
294 | UInt32 getPhysicalSegments(mbuf_t packet,␊ |
295 | struct IOPhysicalSegment * vector,␊ |
296 | UInt32 numVectorSegments = 0);␊ |
297 | ␊ |
298 | /*! @function getPhysicalSegmentsWithCoalesce␊ |
299 | @abstract Generates a little endian physical scatter/gather list from a ␊ |
300 | given mbuf.␊ |
301 | @discussion Generate a little endian physical scatter/gather list from a ␊ |
302 | given mbuf. Coalesce mbuf chain when the number of segments in the ␊ |
303 | scatter/gather list exceeds numVectorSegments.␊ |
304 | @param packet The mbuf packet.␊ |
305 | @param vector Pointer to an array of IOPhysicalSegments for the output ␊ |
306 | physical scatter/gather list.␊ |
307 | @param numVectorSegments Maximum number of IOPhysicalSegments accepted.␊ |
308 | @result Returns the number of segments that were filled in, or␊ |
309 | 0 if an error occurred. ␊ |
310 | */␊ |
311 | ␊ |
312 | UInt32 getPhysicalSegmentsWithCoalesce(mbuf_t packet,␊ |
313 | struct IOPhysicalSegment * vector,␊ |
314 | UInt32 numVectorSegments = 0);␊ |
315 | };␊ |
316 | ␊ |
317 | #ifdef __ppc__␊ |
318 | ␊ |
319 | struct IODBDMADescriptor;␊ |
320 | ␊ |
321 | //===========================================================================␊ |
322 | //===========================================================================␊ |
323 | ␊ |
324 | /*! @class IOMbufDBDMAMemoryCursor␊ |
325 | @abstract An IOMbufMemoryCursor subclass that outputs a vector of ␊ |
326 | IODBDMADescriptors. ␊ |
327 | */␊ |
328 | ␊ |
329 | class IOMbufDBDMAMemoryCursor : public IOMbufMemoryCursor␊ |
330 | {␊ |
331 | OSDeclareDefaultStructors(IOMbufDBDMAMemoryCursor)␊ |
332 | ␊ |
333 | public:␊ |
334 | ␊ |
335 | /*! @function withSpecification␊ |
336 | @abstract Factory function that creates and initializes an ␊ |
337 | IOMbufDBDMAMemoryCursor in one operation.␊ |
338 | @discussion See also IOMbufMemoryCursor::initWithSpecification.␊ |
339 | @param maxSegmentSize Maximum allowable size for one segment.␊ |
340 | @param maxNumSegments Maximum number of segments.␊ |
341 | @result Returns a new mbuf cursor if successfully created and initialized,␊ |
342 | 0 otherwise. ␊ |
343 | */␊ |
344 | ␊ |
345 | static IOMbufDBDMAMemoryCursor * withSpecification(UInt32 maxSegmentSize, ␊ |
346 | UInt32 maxNumSegments);␊ |
347 | ␊ |
348 | /*! @function getPhysicalSegments␊ |
349 | @abstract Generates a DBDMA descriptor list from a given mbuf.␊ |
350 | @param packet The mbuf packet.␊ |
351 | @param vector Pointer to an array of IODBDMADescriptor for the output list.␊ |
352 | @param numVectorSegments Maximum number of IODBDMADescriptors accepted.␊ |
353 | @result Returns the number of segments that were filled in, or␊ |
354 | 0 if an error occurred. ␊ |
355 | */␊ |
356 | ␊ |
357 | UInt32 getPhysicalSegments(mbuf_t packet,␊ |
358 | struct IODBDMADescriptor *vector,␊ |
359 | UInt32 numVectorSegments = 0);␊ |
360 | ␊ |
361 | /*! @function getPhysicalSegmentsWithCoalesce␊ |
362 | @abstract Generates a DBDMA descriptor list from a given mbuf.␊ |
363 | @discussion Generate a DBDMA descriptor list from a given mbuf.␊ |
364 | Coalesce mbuf chain when the number of elements in the list exceeds␊ |
365 | numVectorSegments.␊ |
366 | @param packet The mbuf packet.␊ |
367 | @param vector Pointer to an array of IODBDMADescriptor for the output list.␊ |
368 | @param numVectorSegments Maximum number of IODBDMADescriptors accepted.␊ |
369 | @result Returns the number of segments that were filled in, or␊ |
370 | 0 if an error occurred. ␊ |
371 | */␊ |
372 | ␊ |
373 | UInt32 getPhysicalSegmentsWithCoalesce(mbuf_t packet,␊ |
374 | struct IODBDMADescriptor * vector,␊ |
375 | UInt32 numVectorSegments = 0);␊ |
376 | };␊ |
377 | ␊ |
378 | #endif /* __ppc__ */␊ |
379 | ␊ |
380 | #endif /* !_IOKIT_NETWORK_IOMBUFMEMORYCURSOR_H */␊ |
381 | ␊ |
382 |