Commit | Line | Data |
---|---|---|
91447636 | 1 | /* |
2d21ac55 | 2 | * Copyright (c) 2004-2007 Apple Inc. All rights reserved. |
5d5c5d0d | 3 | * |
2d21ac55 | 4 | * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ |
91447636 | 5 | * |
2d21ac55 A |
6 | * This file contains Original Code and/or Modifications of Original Code |
7 | * as defined in and that are subject to the Apple Public Source License | |
8 | * Version 2.0 (the 'License'). You may not use this file except in | |
9 | * compliance with the License. The rights granted to you under the License | |
10 | * may not be used to create, or enable the creation or redistribution of, | |
11 | * unlawful or unlicensed copies of an Apple operating system, or to | |
12 | * circumvent, violate, or enable the circumvention or violation of, any | |
13 | * terms of an Apple operating system software license agreement. | |
8f6c56a5 | 14 | * |
2d21ac55 A |
15 | * Please obtain a copy of the License at |
16 | * http://www.opensource.apple.com/apsl/ and read it before using this file. | |
17 | * | |
18 | * The Original Code and all software distributed under the License are | |
19 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER | |
8f6c56a5 A |
20 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, |
21 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, | |
2d21ac55 A |
22 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. |
23 | * Please see the License for the specific language governing rights and | |
24 | * limitations under the License. | |
8f6c56a5 | 25 | * |
2d21ac55 | 26 | * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ |
91447636 A |
27 | */ |
28 | /*! | |
29 | @header kpi_mbuf.h | |
30 | This header defines an API for interacting with mbufs. mbufs are the | |
31 | primary method of storing packets in the networking stack. | |
32 | ||
33 | mbufs are used to store various items in the networking stack. The | |
34 | most common usage of an mbuf is to store a packet or data on a | |
35 | socket waiting to be sent or received. The mbuf is a contiguous | |
36 | structure with some header followed by some data. To store more data | |
37 | than would fit in an mbuf, external data is used. Most mbufs with | |
38 | external data use clusters to store the external data. | |
39 | ||
40 | mbufs can be chained, contiguous data in a packet can be found by | |
41 | following the m_next chain. Packets may be bundled together using | |
42 | m_nextpacket. Many parts of the stack do not properly handle chains | |
43 | of packets. When in doubt, don't chain packets. | |
44 | */ | |
45 | ||
46 | #ifndef __KPI_MBUF__ | |
47 | #define __KPI_MBUF__ | |
48 | #include <sys/kernel_types.h> | |
49 | #include <mach/vm_types.h> | |
50 | ||
51 | /*! | |
52 | @enum mbuf_flags_t | |
53 | @abstract Constants defining mbuf flags. Only the flags listed below | |
2d21ac55 | 54 | can be set or retrieved. |
91447636 A |
55 | @constant MBUF_EXT Indicates this mbuf has external data. |
56 | @constant MBUF_PKTHDR Indicates this mbuf has a packet header. | |
57 | @constant MBUF_EOR Indicates this mbuf is the end of a record. | |
58 | @constant MBUF_BCAST Indicates this packet will be sent or was | |
59 | received as a brodcast. | |
60 | @constant MBUF_MCAST Indicates this packet will be sent or was | |
61 | received as a multicast. | |
62 | @constant MBUF_FRAG Indicates this packet is a fragment of a larger | |
63 | packet. | |
64 | @constant MBUF_FIRSTFRAG Indicates this packet is the first fragment. | |
65 | @constant MBUF_LASTFRAG Indicates this packet is the last fragment. | |
66 | @constant MBUF_PROMISC Indicates this packet was only received | |
67 | because the interface is in promiscuous mode. This should be set | |
68 | by the demux function. These packets will be discarded after | |
69 | being passed to any interface filters. | |
70 | */ | |
71 | enum { | |
72 | MBUF_EXT = 0x0001, /* has associated external storage */ | |
73 | MBUF_PKTHDR = 0x0002, /* start of record */ | |
74 | MBUF_EOR = 0x0004, /* end of record */ | |
75 | ||
76 | MBUF_BCAST = 0x0100, /* send/received as link-level broadcast */ | |
77 | MBUF_MCAST = 0x0200, /* send/received as link-level multicast */ | |
78 | MBUF_FRAG = 0x0400, /* packet is a fragment of a larger packet */ | |
79 | MBUF_FIRSTFRAG = 0x0800, /* packet is first fragment */ | |
80 | MBUF_LASTFRAG = 0x1000, /* packet is last fragment */ | |
81 | MBUF_PROMISC = 0x2000 /* packet is promiscuous */ | |
82 | }; | |
83 | typedef u_int32_t mbuf_flags_t; | |
84 | ||
85 | /*! | |
86 | @enum mbuf_type_t | |
87 | @abstract Types of mbufs. | |
88 | @discussion Some mbufs represent packets, some represnt data waiting | |
89 | on sockets. Other mbufs store control data or other various | |
90 | structures. The mbuf type is used to store what sort of data the | |
91 | mbuf contains. | |
92 | @constant MBUF_MT_FREE Indicates the mbuf is free and is | |
93 | sitting on the queue of free mbufs. If you find that an mbuf you | |
94 | have a reference to has this type, something has gone terribly | |
95 | wrong. | |
96 | @constant MBUF_MT_DATA Indicates this mbuf is being used to store | |
97 | data. | |
98 | @constant MBUF_MT_HEADER Indicates this mbuf has a packet header, | |
99 | this is probably a packet. | |
100 | @constant MBUF_MT_SOCKET Socket structure. | |
101 | @constant MBUF_MT_PCB Protocol control block. | |
102 | @constant MBUF_MT_RTABLE Routing table entry. | |
103 | @constant MBUF_MT_HTABLE IMP host tables???. | |
104 | @constant MBUF_MT_ATABLE Address resolution table data. | |
105 | @constant MBUF_MT_SONAME Socket name, usually a sockaddr of some | |
106 | sort. | |
107 | @constant MBUF_MT_FTABLE Fragment reassembly header. | |
108 | @constant MBUF_MT_RIGHTS Access rights. | |
109 | @constant MBUF_MT_IFADDR Interface address. | |
110 | @constant MBUF_MT_CONTROL Extra-data protocol message (control | |
111 | message). | |
112 | @constant MBUF_MT_OOBDATA Out of band data. | |
113 | */ | |
114 | enum { | |
115 | MBUF_TYPE_FREE = 0, /* should be on free list */ | |
116 | MBUF_TYPE_DATA = 1, /* dynamic (data) allocation */ | |
117 | MBUF_TYPE_HEADER = 2, /* packet header */ | |
118 | MBUF_TYPE_SOCKET = 3, /* socket structure */ | |
119 | MBUF_TYPE_PCB = 4, /* protocol control block */ | |
120 | MBUF_TYPE_RTABLE = 5, /* routing tables */ | |
121 | MBUF_TYPE_HTABLE = 6, /* IMP host tables */ | |
122 | MBUF_TYPE_ATABLE = 7, /* address resolution tables */ | |
123 | MBUF_TYPE_SONAME = 8, /* socket name */ | |
124 | MBUF_TYPE_SOOPTS = 10, /* socket options */ | |
125 | MBUF_TYPE_FTABLE = 11, /* fragment reassembly header */ | |
126 | MBUF_TYPE_RIGHTS = 12, /* access rights */ | |
127 | MBUF_TYPE_IFADDR = 13, /* interface address */ | |
128 | MBUF_TYPE_CONTROL = 14, /* extra-data protocol message */ | |
129 | MBUF_TYPE_OOBDATA = 15 /* expedited data */ | |
130 | }; | |
131 | typedef u_int32_t mbuf_type_t; | |
132 | ||
133 | /*! | |
134 | @enum mbuf_csum_request_flags_t | |
135 | @abstract Checksum performed/requested flags. | |
136 | @discussion Mbufs often contain packets. Some hardware supports | |
137 | performing checksums in hardware. The stack uses these flags to | |
138 | indicate to the driver what sort of checksumming should be | |
139 | handled in by the driver/hardware. These flags will only be set | |
140 | if the driver indicates that it supports the corresponding | |
141 | checksums using ifnet_set_offload. | |
142 | @constant MBUF_CSUM_REQ_IP Indicates the IP checksum has not been | |
143 | calculated yet. | |
144 | @constant MBUF_CSUM_REQ_TCP Indicates the TCP checksum has not been | |
145 | calculated yet. | |
146 | @constant MBUF_CSUM_REQ_UDP Indicates the UDP checksum has not been | |
147 | calculated yet. | |
148 | */ | |
149 | enum { | |
150 | #ifdef KERNEL_PRIVATE | |
151 | MBUF_CSUM_REQ_SUM16 = 0x1000, /* Weird apple hardware checksum */ | |
152 | #endif KERNEL_PRIVATE | |
153 | MBUF_CSUM_REQ_IP = 0x0001, | |
154 | MBUF_CSUM_REQ_TCP = 0x0002, | |
155 | MBUF_CSUM_REQ_UDP = 0x0004 | |
156 | }; | |
157 | typedef u_int32_t mbuf_csum_request_flags_t; | |
158 | ||
159 | /*! | |
160 | @enum mbuf_csum_performed_flags_t | |
161 | @abstract Checksum performed/requested flags. | |
162 | @discussion Mbufs often contain packets. Some hardware supports | |
163 | performing checksums in hardware. The driver uses these flags to | |
164 | communicate to the stack the checksums that were calculated in | |
165 | hardware. | |
166 | @constant MBUF_CSUM_DID_IP Indicates that the driver/hardware verified | |
167 | the IP checksum in hardware. | |
168 | @constant MBUF_CSUM_IP_GOOD Indicates whether or not the IP checksum | |
169 | was good or bad. Only valid when MBUF_CSUM_DID_IP is set. | |
170 | @constant MBUF_CSUM_DID_DATA Indicates that the TCP or UDP checksum | |
171 | was calculated. The value for the checksum calculated in | |
172 | hardware should be passed as the second parameter of | |
173 | mbuf_set_csum_performed. The hardware calculated checksum value | |
174 | can be retrieved using the second parameter passed to | |
175 | mbuf_get_csum_performed. | |
176 | @constant MBUF_CSUM_PSEUDO_HDR If set, this indicates that the | |
177 | checksum value for MBUF_CSUM_DID_DATA includes the pseudo header | |
178 | value. If this is not set, the stack will calculate the pseudo | |
179 | header value and add that to the checksum. The value of this bit | |
180 | is only valid when MBUF_CSUM_DID_DATA is set. | |
181 | */ | |
182 | enum { | |
183 | #ifdef KERNEL_PRIVATE | |
184 | MBUF_CSUM_TCP_SUM16 = MBUF_CSUM_REQ_SUM16, /* Weird apple hardware checksum */ | |
185 | #endif | |
186 | MBUF_CSUM_DID_IP = 0x0100, | |
187 | MBUF_CSUM_IP_GOOD = 0x0200, | |
188 | MBUF_CSUM_DID_DATA = 0x0400, | |
189 | MBUF_CSUM_PSEUDO_HDR = 0x0800 | |
190 | }; | |
191 | typedef u_int32_t mbuf_csum_performed_flags_t; | |
192 | ||
193 | /*! | |
194 | @enum mbuf_how_t | |
195 | @abstract Method of allocating an mbuf. | |
196 | @discussion Blocking will cause the funnel to be dropped. If the | |
197 | funnel is dropped, other threads may make changes to networking | |
198 | data structures. This can lead to very bad things happening. | |
199 | Blocking on the input our output path can also impact | |
200 | performance. There are some cases where making a blocking call | |
201 | is acceptable. When in doubt, use MBUF_DONTWAIT. | |
202 | @constant MBUF_WAITOK Allow a call to allocate an mbuf to block. | |
203 | @constant MBUF_DONTWAIT Don't allow the mbuf allocation call to | |
204 | block, if blocking is necessary fail and return immediately. | |
205 | */ | |
206 | enum { | |
207 | MBUF_WAITOK = 0, /* Ok to block to get memory */ | |
208 | MBUF_DONTWAIT = 1 /* Don't block, fail if blocking would be required */ | |
209 | }; | |
210 | typedef u_int32_t mbuf_how_t; | |
211 | ||
212 | typedef u_int32_t mbuf_tag_id_t; | |
213 | typedef u_int16_t mbuf_tag_type_t; | |
214 | ||
215 | /*! | |
216 | @struct mbuf_stat | |
217 | @discussion The mbuf_stat contains mbuf statistics. | |
218 | @field mbufs Number of mbufs (free or otherwise). | |
219 | @field clusters Number of clusters (free or otherwise). | |
220 | @field clfree Number of free clusters. | |
221 | @field drops Number of times allocation failed. | |
222 | @field wait Number of times allocation blocked. | |
223 | @field drain Number of times protocol drain functions were called. | |
224 | @field mtypes An array of counts of each type of mbuf allocated. | |
225 | @field mcfail Number of times m_copym failed. | |
226 | @field mpfail Number of times m_pullup failed. | |
227 | @field msize Length of an mbuf. | |
228 | @field mclbytes Length of an mbuf cluster. | |
229 | @field minclsize Minimum length of data to allocate a cluster. | |
230 | Anything smaller than this should be placed in chained mbufs. | |
231 | @field mlen Length of data in an mbuf. | |
232 | @field mhlen Length of data in an mbuf with a packet header. | |
233 | @field bigclusters Number of big clusters. | |
234 | @field bigclfree Number of unused big clusters. | |
235 | @field bigmclbytes Length of a big mbuf cluster. | |
236 | */ | |
237 | struct mbuf_stat { | |
238 | u_long mbufs; /* mbufs obtained from page pool */ | |
239 | u_long clusters; /* clusters obtained from page pool */ | |
240 | u_long clfree; /* free clusters */ | |
241 | u_long drops; /* times failed to find space */ | |
242 | u_long wait; /* times waited for space */ | |
243 | u_long drain; /* times drained protocols for space */ | |
244 | u_short mtypes[256]; /* type specific mbuf allocations */ | |
245 | u_long mcfail; /* times m_copym failed */ | |
246 | u_long mpfail; /* times m_pullup failed */ | |
247 | u_long msize; /* length of an mbuf */ | |
248 | u_long mclbytes; /* length of an mbuf cluster */ | |
249 | u_long minclsize; /* min length of data to allocate a cluster */ | |
250 | u_long mlen; /* length of data in an mbuf */ | |
251 | u_long mhlen; /* length of data in a header mbuf */ | |
252 | u_long bigclusters; /* number of big clusters */ | |
253 | u_long bigclfree; /* number of big clustser free */ | |
254 | u_long bigmclbytes; /* length of data in a big cluster */ | |
255 | }; | |
256 | ||
257 | /* Parameter for m_copym to copy all bytes */ | |
258 | #define MBUF_COPYALL 1000000000 | |
259 | ||
2d21ac55 | 260 | __BEGIN_DECLS |
91447636 A |
261 | /* Data access */ |
262 | /*! | |
263 | @function mbuf_data | |
264 | @discussion Returns a pointer to the start of data in this mbuf. | |
265 | There may be additional data on chained mbufs. The data you're | |
2d21ac55 A |
266 | looking for may not be virtually contiguous if it spans more |
267 | than one mbuf. In addition, data that is virtually contiguous | |
268 | might not be represented by physically contiguous pages; see | |
269 | further comments in mbuf_data_to_physical. Use mbuf_len to | |
270 | determine the lenght of data available in this mbuf. If a data | |
271 | structure you want to access stradles two mbufs in a chain, | |
272 | either use mbuf_pullup to get the data contiguous in one mbuf | |
273 | or copy the pieces of data from each mbuf in to a contiguous | |
274 | buffer. Using mbuf_pullup has the advantage of not having to | |
275 | copy the data. On the other hand, if you don't make sure there | |
276 | is space in the mbuf, mbuf_pullup may fail and free the mbuf. | |
91447636 A |
277 | @param mbuf The mbuf. |
278 | @result A pointer to the data in the mbuf. | |
279 | */ | |
280 | void* mbuf_data(mbuf_t mbuf); | |
281 | ||
282 | /*! | |
283 | @function mbuf_datastart | |
284 | @discussion Returns the start of the space set aside for storing | |
285 | data in an mbuf. An mbuf's data may come from a cluster or be | |
286 | embedded in the mbuf structure itself. The data pointer | |
287 | retrieved by mbuf_data may not be at the start of the data | |
288 | (mbuf_leadingspace will be non-zero). This function will return to | |
289 | you a pointer that matches mbuf_data() - mbuf_leadingspace(). | |
290 | @param mbuf The mbuf. | |
291 | @result A pointer to smallest possible value for data. | |
292 | */ | |
293 | void* mbuf_datastart(mbuf_t mbuf); | |
294 | ||
295 | /*! | |
296 | @function mbuf_setdata | |
297 | @discussion Sets the data and length values for an mbuf. The data | |
298 | value must be in a valid range. In the case of an mbuf with a cluster, | |
299 | the data value must point to a location in the cluster and the data | |
300 | value plus the length, must be less than the end of the cluster. For | |
301 | data embedded directly in an mbuf (no cluster), the data value must | |
302 | fall somewhere between the start and end of the data area in the | |
303 | mbuf and the data + length must also be in the same range. | |
304 | @param mbuf The mbuf. | |
305 | @param data The new pointer value for data. | |
306 | @param len The new length of data in the mbuf. | |
307 | @result 0 on success, errno error on failure. | |
308 | */ | |
309 | errno_t mbuf_setdata(mbuf_t mbuf, void *data, size_t len); | |
310 | ||
311 | /*! | |
312 | @function mbuf_align_32 | |
313 | @discussion mbuf_align_32 is a replacement for M_ALIGN and MH_ALIGN. | |
314 | mbuf_align_32 will set the data pointer to a location aligned on | |
315 | a four byte boundry with at least 'len' bytes between the data | |
316 | pointer and the end of the data block. | |
317 | @param mbuf The mbuf. | |
318 | @param len The minimum length of space that should follow the new | |
319 | data location. | |
320 | @result 0 on success, errno error on failure. | |
321 | */ | |
322 | errno_t mbuf_align_32(mbuf_t mbuf, size_t len); | |
323 | ||
324 | /*! | |
325 | @function mbuf_data_to_physical | |
326 | @discussion mbuf_data_to_physical is a replacement for mcl_to_paddr. | |
327 | Given a pointer returned from mbuf_data of mbuf_datastart, | |
328 | mbuf_data_to_physical will return the phyical address for that | |
2d21ac55 A |
329 | block of data. Note that even though the data is in virtually |
330 | contiguous span, the underlying physical pages might not be | |
331 | physically contiguous. Because of this, callers must ensure | |
332 | to call this routine for each page boundary. Device drivers | |
333 | that deal with DMA are strongly encouraged to utilize the | |
334 | IOMbufNaturalMemoryCursor and walk down the list of vectors | |
335 | instead of using this interface to obtain the physical address. | |
336 | Use of this routine is therefore discouraged. | |
91447636 A |
337 | @param ptr A pointer to data stored in an mbuf. |
338 | @result The 64 bit physical address of the mbuf data or NULL if ptr | |
339 | does not point to data stored in an mbuf. | |
340 | */ | |
341 | addr64_t mbuf_data_to_physical(void* ptr); | |
342 | ||
343 | ||
344 | /* Allocation */ | |
345 | ||
346 | /*! | |
347 | @function mbuf_get | |
348 | @discussion Allocates an mbuf without a cluster for external data. | |
349 | @param how Blocking or non-blocking. | |
350 | @param type The type of the mbuf. | |
351 | @param mbuf The mbuf. | |
352 | @result 0 on success, errno error on failure. | |
353 | */ | |
354 | errno_t mbuf_get(mbuf_how_t how, mbuf_type_t type, mbuf_t* mbuf); | |
355 | ||
356 | /*! | |
357 | @function mbuf_gethdr | |
358 | @discussion Allocates an mbuf without a cluster for external data. | |
359 | Sets a flag to indicate there is a packet header and initializes | |
360 | the packet header. | |
361 | @param how Blocking or non-blocking. | |
362 | @param type The type of the mbuf. | |
363 | @param mbuf The mbuf. | |
364 | @result 0 on success, errno error on failure. | |
365 | */ | |
366 | errno_t mbuf_gethdr(mbuf_how_t how, mbuf_type_t type, mbuf_t* mbuf); | |
367 | ||
2d21ac55 A |
368 | /*! |
369 | @function mbuf_attachcluster | |
370 | @discussion Attach an external buffer as a cluster for an mbuf. If mbuf | |
371 | points to a NULL mbuf_t, an mbuf will be allocated for you. If | |
372 | mbuf points to a non-NULL mbuf_t, the user-supplied mbuf will | |
373 | be used instead. The caller is responsible for allocating the | |
374 | external buffer by calling mbuf_alloccluster(). | |
375 | @param how Blocking or non-blocking. | |
376 | @param type The type of the mbuf if mbuf is non-NULL; otherwise ignored. | |
377 | @param mbuf Pointer to the address of the mbuf; if NULL, an mbuf will | |
378 | be allocated, otherwise, it must point to a valid mbuf address. | |
379 | If the user-supplied mbuf is already attached to a cluster, the | |
380 | current cluster will be freed before the mbuf gets attached to | |
381 | the supplied external buffer. Note that this routine may return | |
382 | a different mbuf_t than the one you passed in. | |
383 | @param extbuf Address of the external buffer. | |
384 | @param extfree Free routine for the external buffer; the caller is | |
385 | required to defined a routine that will be invoked when the | |
386 | mbuf is freed. | |
387 | @param extsize Size of the external buffer. | |
388 | @param extarg Private value that will be passed to the free routine | |
389 | when it is called at the time the mbuf is freed. | |
390 | @result 0 on success | |
391 | EINVAL - Invalid parameter | |
392 | ENOMEM - Not enough memory available | |
393 | */ | |
394 | errno_t | |
395 | mbuf_attachcluster(mbuf_how_t how, mbuf_type_t type, mbuf_t *mbuf, | |
396 | caddr_t extbuf, void (*extfree)(caddr_t , u_int, caddr_t), | |
397 | size_t extsize, caddr_t extarg); | |
398 | ||
399 | /*! | |
400 | @function mbuf_alloccluster | |
401 | @discussion Allocate a cluster that can be later attached to an | |
402 | mbuf by calling mbuf_attachcluster(). The allocated cluster | |
403 | can also be freed (without being attached to an mbuf) by | |
404 | calling mbuf_freecluster(). At the moment this routine | |
405 | will either return a cluster of 2048, 4096 or 16384 bytes | |
406 | depending on the requested size. Note that clusters greater | |
407 | than 4096 bytes might not be available in all configurations; | |
408 | the caller must additionally check for ENOTSUP (see below). | |
409 | @param how Blocking or non-blocking. | |
410 | @param size Pointer to size of requested cluster. Sizes up to 2048 | |
411 | will be rounded up to 2048; sizes greater than 2048 and up | |
412 | to 4096 will be rounded up to 4096. Sizes greater than 4096 | |
413 | will be rounded up to 16384. | |
414 | @param addr Pointer to the address of the requested cluster. | |
415 | @result 0 on success or ENOMEM if failure. If the caller requests | |
416 | greater than 4096 bytes and the system is unable to fulfill | |
417 | the request due to the lack of jumbo clusters support based | |
418 | on the configuration, this routine will return ENOTSUP. | |
419 | In this case, the caller is advised to use 4096 bytes or | |
420 | smaller during subseqent requests. | |
421 | */ | |
422 | errno_t mbuf_alloccluster(mbuf_how_t how, size_t *size, caddr_t *addr); | |
423 | ||
424 | /*! | |
425 | @function mbuf_freecluster | |
426 | @discussion Free a cluster that was previously allocated by a call | |
427 | to mbuf_alloccluster(). The caller must pass the actual | |
428 | size of the cluster as returned by mbuf_alloccluster(), | |
429 | which at this point must be either 2048, 4096 or 16384 bytes. | |
430 | @param addr The address of the cluster. | |
431 | @param size The actual size of the cluster. | |
432 | */ | |
433 | void mbuf_freecluster(caddr_t addr, size_t size); | |
91447636 A |
434 | |
435 | /*! | |
436 | @function mbuf_getcluster | |
437 | @discussion Allocate a cluster of the requested size and attach it to | |
2d21ac55 A |
438 | an mbuf for use as external data. If mbuf points to a NULL |
439 | mbuf_t, an mbuf will be allocated for you. If mbuf points to | |
440 | a non-NULL mbuf_t, mbuf_getcluster may return a different | |
441 | mbuf_t than the one you passed in. | |
91447636 A |
442 | @param how Blocking or non-blocking. |
443 | @param type The type of the mbuf. | |
2d21ac55 A |
444 | @param size The size of the cluster to be allocated. Supported sizes |
445 | for a cluster are be 2048, 4096, or 16384. Any other value | |
446 | with return EINVAL. Note that clusters greater than 4096 | |
447 | bytes might not be available in all configurations; the | |
448 | caller must additionally check for ENOTSUP (see below). | |
91447636 A |
449 | @param mbuf The mbuf the cluster will be attached to. |
450 | @result 0 on success, errno error on failure. If you specified NULL | |
451 | for the mbuf, any intermediate mbuf that may have been allocated | |
452 | will be freed. If you specify an mbuf value in *mbuf, | |
453 | mbuf_mclget will not free it. | |
454 | EINVAL - Invalid parameter | |
455 | ENOMEM - Not enough memory available | |
2d21ac55 A |
456 | ENOTSUP - The caller had requested greater than 4096 bytes |
457 | cluster and the system is unable to fulfill it due to the | |
458 | lack of jumbo clusters support based on the configuration. | |
459 | In this case, the caller is advised to use 4096 bytes or | |
460 | smaller during subsequent requests. | |
91447636 A |
461 | */ |
462 | errno_t mbuf_getcluster(mbuf_how_t how, mbuf_type_t type, size_t size, mbuf_t* mbuf); | |
463 | ||
464 | /*! | |
465 | @function mbuf_mclget | |
466 | @discussion Allocate a cluster and attach it to an mbuf for use as | |
467 | external data. If mbuf points to a NULL mbuf_t, an mbuf will be | |
468 | allocated for you. If mbuf points to a non-NULL mbuf_t, | |
469 | mbuf_mclget may return a different mbuf_t than the one you | |
470 | passed in. | |
471 | @param how Blocking or non-blocking. | |
472 | @param type The type of the mbuf. | |
473 | @param mbuf The mbuf the cluster will be attached to. | |
474 | @result 0 on success, errno error on failure. If you specified NULL | |
475 | for the mbuf, any intermediate mbuf that may have been allocated | |
476 | will be freed. If you specify an mbuf value in *mbuf, | |
477 | mbuf_mclget will not free it. | |
478 | */ | |
479 | errno_t mbuf_mclget(mbuf_how_t how, mbuf_type_t type, mbuf_t* mbuf); | |
480 | ||
481 | /*! | |
482 | @function mbuf_allocpacket | |
2d21ac55 A |
483 | @discussion Allocate an mbuf chain to store a single packet of the |
484 | requested length. According to the requested length, a chain | |
485 | of mbufs will be created. The mbuf type will be set to | |
486 | MBUF_TYPE_DATA. The caller may specify the maximum number of | |
487 | buffer. | |
91447636 A |
488 | @param how Blocking or non-blocking |
489 | @param packetlen The total length of the packet mbuf to be allocated. | |
490 | The length must be greater than zero. | |
2d21ac55 A |
491 | @param maxchunks An input/output pointer to the maximum number of mbufs |
492 | segments making up the chain. On input, if maxchunks is NULL, | |
493 | or the value pointed to by maxchunks is zero, the packet will | |
494 | be made up of as few or as many buffer segments as necessary | |
495 | to fit the length. The allocation will fail with ENOBUFS if | |
496 | the number of segments requested is too small and the sum of | |
497 | the maximum size of each individual segment is less than the | |
498 | packet length. On output, if the allocation succeed and | |
499 | maxchunks is non-NULL, it will point to the actual number | |
500 | of segments allocated. | |
501 | Additional notes for packetlen greater than 4096 bytes: | |
502 | the caller may pass a non-NULL maxchunks and initialize it | |
503 | with zero such that upon success, it can find out whether | |
504 | or not the system configuration allows for larger than | |
505 | 4096 bytes cluster allocations, by checking on the value | |
506 | pointed to by maxchunks. E.g. a request for 9018 bytes may | |
507 | result in 1 chunk when jumbo clusters are available, or | |
508 | 3 chunks otherwise. | |
91447636 A |
509 | @param Upon success, *mbuf will be a reference to the new mbuf. |
510 | @result Returns 0 upon success or the following error code: | |
511 | EINVAL - Invalid parameter | |
512 | ENOMEM - Not enough memory available | |
2d21ac55 A |
513 | ENOBUFS - Buffers not big enough for the maximum number of |
514 | chunks requested | |
91447636 A |
515 | */ |
516 | errno_t mbuf_allocpacket(mbuf_how_t how, size_t packetlen, unsigned int * maxchunks, mbuf_t *mbuf); | |
517 | ||
2d21ac55 A |
518 | /*! |
519 | @function mbuf_allocpacket_list | |
520 | @discussion Allocate a linked list of packets. According to the | |
521 | requested length, each packet will made of a chain of one | |
522 | or more mbufs. The mbuf type will be set to MBUF_TYPE_DATA. | |
523 | The caller may specify the maximum number of element for | |
524 | each mbuf chain making up a packet. | |
525 | @param numpkts Number of packets to allocate | |
526 | @param how Blocking or non-blocking | |
527 | @param packetlen The total length of the packet mbuf to be allocated. | |
528 | The length must be greater than zero. | |
529 | @param maxchunks An input/output pointer to the maximum number of | |
530 | mbufs segments making up the chain. On input, if maxchunks is | |
531 | zero, or the value pointed to by maxchunks is zero, the packet | |
532 | will be made of as few or as many buffer segments as necessary | |
533 | to fit the length. The allocation will fail with ENOBUFS if | |
534 | the number of segments requested is too small and the sum of | |
535 | the maximum size of each individual segment is less than the | |
536 | packet length. On output, if the allocation succeed and | |
537 | maxchunks is non zero, it will point to the actual number | |
538 | of segments allocated. | |
539 | Additional notes for packetlen greater than 4096 bytes: | |
540 | the caller may pass a non-NULL maxchunks and initialize it | |
541 | with zero such that upon success, it can find out whether | |
542 | or not the system configuration allows for larger than | |
543 | 4096 bytes cluster allocations, by checking on the value | |
544 | pointed to by maxchunks. E.g. a request for 9018 bytes may | |
545 | result in 1 chunk when jumbo clusters are available, or | |
546 | 3 chunks otherwise. | |
547 | @param Upon success, *mbuf will be a reference to the new mbuf. | |
548 | @result Returns 0 upon success or the following error code: | |
549 | EINVAL - Invalid parameter | |
550 | ENOMEM - Not enough memory available | |
551 | ENOBUFS - Buffers not big enough for the maximum number of | |
552 | chunks requested | |
553 | */ | |
554 | errno_t mbuf_allocpacket_list(unsigned int numpkts, mbuf_how_t how, size_t packetlen, unsigned int * maxchunks, mbuf_t *mbuf); | |
555 | ||
556 | ||
91447636 A |
557 | /*! |
558 | @function mbuf_getpacket | |
559 | @discussion Allocate an mbuf, allocate and attach a cluster, and set | |
560 | the packet header flag. | |
561 | @param how Blocking or non-blocking. | |
562 | @param mbuf Upon success, *mbuf will be a reference to the new mbuf. | |
563 | @result 0 on success, errno error on failure. | |
564 | */ | |
565 | errno_t mbuf_getpacket(mbuf_how_t how, mbuf_t* mbuf); | |
566 | ||
567 | /*! | |
568 | @function mbuf_free | |
569 | @discussion Frees a single mbuf. Not commonly used because it | |
570 | doesn't touch the rest of the mbufs on the chain. | |
571 | @param mbuf The mbuf to free. | |
572 | @result The next mbuf in the chain. | |
573 | */ | |
574 | mbuf_t mbuf_free(mbuf_t mbuf); | |
575 | ||
576 | /*! | |
577 | @function mbuf_freem | |
578 | @discussion Frees a chain of mbufs link through mnext. | |
579 | @param mbuf The first mbuf in the chain to free. | |
580 | */ | |
581 | void mbuf_freem(mbuf_t mbuf); | |
582 | ||
583 | /*! | |
584 | @function mbuf_freem_list | |
585 | @discussion Frees linked list of mbuf chains. Walks through | |
2d21ac55 | 586 | mnextpackt and does the equivalent of mbuf_freem to each. |
91447636 A |
587 | @param mbuf The first mbuf in the linked list to free. |
588 | @result The number of mbufs freed. | |
589 | */ | |
590 | int mbuf_freem_list(mbuf_t mbuf); | |
591 | ||
592 | /*! | |
593 | @function mbuf_leadingspace | |
594 | @discussion Determines the space available in the mbuf proceeding | |
595 | the current data. | |
596 | @param mbuf The mbuf. | |
597 | @result The number of unused bytes at the start of the mbuf. | |
598 | */ | |
2d21ac55 | 599 | size_t mbuf_leadingspace(const mbuf_t mbuf); |
91447636 A |
600 | |
601 | /*! | |
602 | @function mbuf_trailingspace | |
603 | @discussion Determines the space available in the mbuf following | |
604 | the current data. | |
605 | @param mbuf The mbuf. | |
606 | @result The number of unused bytes following the current data. | |
607 | */ | |
2d21ac55 | 608 | size_t mbuf_trailingspace(const mbuf_t mbuf); |
91447636 A |
609 | |
610 | /* Manipulation */ | |
611 | ||
612 | /*! | |
613 | @function mbuf_copym | |
2d21ac55 A |
614 | @discussion Copies len bytes from offset from src to a new mbuf. If |
615 | the original mbuf contains a packet header, the new mbuf will | |
616 | contain similar packet header except for any tags which may be | |
617 | associated with the original mbuf. mbuf_dup() should be used | |
618 | instead if tags are to be copied to the new mbuf. | |
91447636 A |
619 | @param src The source mbuf. |
620 | @param offset The offset in the mbuf to start copying from. | |
621 | @param len The the number of bytes to copy. | |
622 | @param how To block or not to block, that is a question. | |
623 | @param new_mbuf Upon success, the newly allocated mbuf. | |
624 | @result 0 upon success otherwise the errno error. | |
625 | */ | |
2d21ac55 | 626 | errno_t mbuf_copym(const mbuf_t src, size_t offset, size_t len, |
91447636 A |
627 | mbuf_how_t how, mbuf_t* new_mbuf); |
628 | ||
629 | /*! | |
630 | @function mbuf_dup | |
2d21ac55 A |
631 | @discussion Exactly duplicates an mbuf chain. If the original mbuf |
632 | contains a packet header (including tags), the new mbuf will have | |
633 | the same packet header contents and a copy of each tag associated | |
634 | with the original mbuf. | |
91447636 A |
635 | @param src The source mbuf. |
636 | @param how Blocking or non-blocking. | |
637 | @param new_mbuf Upon success, the newly allocated mbuf. | |
638 | @result 0 upon success otherwise the errno error. | |
639 | */ | |
2d21ac55 | 640 | errno_t mbuf_dup(const mbuf_t src, mbuf_how_t how, mbuf_t* new_mbuf); |
91447636 A |
641 | |
642 | /*! | |
643 | @function mbuf_prepend | |
644 | @discussion Prepend len bytes to an mbuf. If there is space | |
645 | (mbuf_leadingspace >= len), the mbuf's data ptr is changed and | |
646 | the same mbuf is returned. If there is no space, a new mbuf may | |
647 | be allocated and prepended to the mbuf chain. If the operation | |
648 | fails, the mbuf may be freed (*mbuf will be NULL). | |
649 | @param mbuf The mbuf to prepend data to. This may change if a new | |
650 | mbuf must be allocated or may be NULL if the operation fails. | |
651 | @param len The length, in bytes, to be prepended to the mbuf. | |
652 | @param how Blocking or non-blocking. | |
653 | @result 0 upon success otherwise the errno error. | |
654 | */ | |
655 | errno_t mbuf_prepend(mbuf_t* mbuf, size_t len, mbuf_how_t how); | |
656 | ||
657 | /*! | |
658 | @function mbuf_split | |
659 | @discussion Split an mbuf chain at a specific offset. | |
660 | @param src The mbuf to be split. | |
661 | @param offset The offset in the buffer where the mbuf should be | |
662 | split. | |
663 | @param how Blocking or non-blocking. | |
664 | @param new_mbuf Upon success, the second half of the split mbuf | |
665 | chain. | |
666 | @result 0 upon success otherwise the errno error. In the case of | |
667 | failure, the original mbuf chain passed in to src will be | |
668 | preserved. | |
669 | */ | |
670 | errno_t mbuf_split(mbuf_t src, size_t offset, | |
671 | mbuf_how_t how, mbuf_t* new_mbuf); | |
672 | ||
673 | /*! | |
674 | @function mbuf_pullup | |
675 | @discussion Move the next len bytes in to mbuf from other mbufs in | |
676 | the chain. This is commonly used to get the IP and TCP or UDP | |
677 | header contiguous in the first mbuf. If mbuf_pullup fails, the | |
678 | entire mbuf chain will be freed. | |
679 | @param mbuf The mbuf in the chain the data should be contiguous in. | |
680 | @param len The number of bytes to pull from the next mbuf(s). | |
681 | @result 0 upon success otherwise the errno error. In the case of an | |
682 | error, the mbuf chain has been freed. | |
683 | */ | |
684 | errno_t mbuf_pullup(mbuf_t* mbuf, size_t len); | |
685 | ||
686 | /*! | |
687 | @function mbuf_pulldown | |
688 | @discussion Make length bytes at offset in the mbuf chain | |
689 | contiguous. Nothing before offset bytes in the chain will be | |
690 | modified. Upon return, location will be the mbuf the data is | |
691 | contiguous in and offset will be the offset in that mbuf at | |
692 | which the data is located. In the case of a failure, the mbuf | |
693 | chain will be freed. | |
694 | @param src The start of the mbuf chain. | |
695 | @param offset Pass in a pointer to a value with the offset of the | |
696 | data you're interested in making contiguous. Upon success, this | |
697 | will be overwritten with the offset from the mbuf returned in | |
698 | location. | |
699 | @param length The length of data that should be made contiguous. | |
700 | @param location Upon success, *location will be the mbuf the data is | |
701 | in. | |
702 | @result 0 upon success otherwise the errno error. | |
703 | */ | |
704 | errno_t mbuf_pulldown(mbuf_t src, size_t *offset, size_t length, mbuf_t *location); | |
705 | ||
706 | /*! | |
707 | @function mbuf_adj | |
708 | @discussion Trims len bytes from the mbuf. If the length is greater | |
709 | than zero, the bytes are trimmed from the front of the mbuf. If | |
710 | the length is less than zero, the bytes are trimmed from the end | |
711 | of the mbuf chain. | |
712 | @param mbuf The mbuf chain to trim. | |
713 | @param len The number of bytes to trim from the mbuf chain. | |
91447636 A |
714 | */ |
715 | void mbuf_adj(mbuf_t mbuf, int len); | |
716 | ||
2d21ac55 A |
717 | /*! |
718 | @function mbuf_adjustlen | |
719 | @discussion Adds amount to the mbuf len. Verifies that the new | |
720 | length is valid (greater than or equal to zero and less than | |
721 | maximum amount of data that may be stored in the mbuf). This | |
722 | function will not adjust the packet header length field or | |
723 | affect any other mbufs in a chain. | |
724 | @param mbuf The mbuf to adjust. | |
725 | @param amount The number of bytes increment the length by. | |
726 | @result 0 upon success otherwise the errno error. | |
727 | */ | |
728 | errno_t mbuf_adjustlen(mbuf_t mbuf, int amount); | |
729 | ||
91447636 A |
730 | /*! |
731 | @function mbuf_copydata | |
732 | @discussion Copies data out of an mbuf in to a specified buffer. If | |
733 | the data is stored in a chain of mbufs, the data will be copied | |
734 | from each mbuf in the chain until length bytes have been copied. | |
735 | @param mbuf The mbuf chain to copy data out of. | |
736 | @param offset The offset in to the mbuf to start copying. | |
737 | @param length The number of bytes to copy. | |
738 | @param out_data A pointer to the location where the data will be | |
739 | copied. | |
740 | @result 0 upon success otherwise the errno error. | |
741 | */ | |
2d21ac55 | 742 | errno_t mbuf_copydata(const mbuf_t mbuf, size_t offset, size_t length, void* out_data); |
91447636 A |
743 | |
744 | /*! | |
745 | @function mbuf_copyback | |
746 | @discussion Copies data from a buffer to an mbuf chain. | |
747 | mbuf_copyback will grow the chain to fit the specified buffer. | |
748 | ||
749 | If mbuf_copydata is unable to allocate enough mbufs to grow the | |
750 | chain, ENOBUFS will be returned. The mbuf chain will be shorter | |
751 | than expected but all of the data up to the end of the mbuf | |
752 | chain will be valid. | |
753 | ||
754 | If an offset is specified, mbuf_copyback will skip that many | |
755 | bytes in the mbuf chain before starting to write the buffer in | |
756 | to the chain. If the mbuf chain does not contain this many | |
757 | bytes, mbufs will be allocated to create the space. | |
758 | @param mbuf The first mbuf in the chain to copy the data in to. | |
759 | @param offset Offset in bytes to skip before copying data. | |
760 | @param length The length, in bytes, of the data to copy in to the mbuf | |
761 | chain. | |
762 | @param data A pointer to data in the kernel's address space. | |
763 | @param how Blocking or non-blocking. | |
764 | @result 0 upon success, EINVAL or ENOBUFS upon failure. | |
765 | */ | |
766 | errno_t mbuf_copyback(mbuf_t mbuf, size_t offset, size_t length, | |
767 | const void *data, mbuf_how_t how); | |
768 | ||
91447636 A |
769 | /*! |
770 | @function mbuf_mclhasreference | |
771 | @discussion Check if a cluster of an mbuf is referenced by another mbuf. | |
772 | References may be taken, for example, as a result of a call to | |
773 | mbuf_split or mbuf_copym | |
774 | @param mbuf The mbuf with the cluster to test. | |
775 | @result 0 if there is no reference by another mbuf, 1 otherwise. | |
776 | */ | |
777 | int mbuf_mclhasreference(mbuf_t mbuf); | |
778 | ||
779 | ||
780 | /* mbuf header */ | |
781 | ||
782 | /*! | |
783 | @function mbuf_next | |
784 | @discussion Returns the next mbuf in the chain. | |
785 | @param mbuf The mbuf. | |
786 | @result The next mbuf in the chain. | |
787 | */ | |
2d21ac55 | 788 | mbuf_t mbuf_next(const mbuf_t mbuf); |
91447636 A |
789 | |
790 | /*! | |
791 | @function mbuf_setnext | |
792 | @discussion Sets the next mbuf in the chain. | |
793 | @param mbuf The mbuf. | |
794 | @param next The new next mbuf. | |
795 | @result 0 upon success otherwise the errno error. | |
796 | */ | |
797 | errno_t mbuf_setnext(mbuf_t mbuf, mbuf_t next); | |
798 | ||
799 | /*! | |
800 | @function mbuf_nextpkt | |
801 | @discussion Gets the next packet from the mbuf. | |
802 | @param mbuf The mbuf. | |
803 | @result The nextpkt. | |
804 | */ | |
2d21ac55 | 805 | mbuf_t mbuf_nextpkt(const mbuf_t mbuf); |
91447636 A |
806 | |
807 | /*! | |
808 | @function mbuf_setnextpkt | |
809 | @discussion Sets the next packet attached to this mbuf. | |
810 | @param mbuf The mbuf. | |
811 | @param nextpkt The new next packet. | |
812 | */ | |
813 | void mbuf_setnextpkt(mbuf_t mbuf, mbuf_t nextpkt); | |
814 | ||
815 | /*! | |
816 | @function mbuf_len | |
817 | @discussion Gets the length of data in this mbuf. | |
818 | @param mbuf The mbuf. | |
819 | @result The length. | |
820 | */ | |
2d21ac55 | 821 | size_t mbuf_len(const mbuf_t mbuf); |
91447636 A |
822 | |
823 | /*! | |
824 | @function mbuf_setlen | |
825 | @discussion Sets the length of data in this packet. Be careful to | |
826 | not set the length over the space available in the mbuf. | |
827 | @param mbuf The mbuf. | |
828 | @param len The new length. | |
829 | @result 0 upon success otherwise the errno error. | |
830 | */ | |
831 | void mbuf_setlen(mbuf_t mbuf, size_t len); | |
832 | ||
833 | /*! | |
834 | @function mbuf_maxlen | |
835 | @discussion Retrieves the maximum length of data that may be stored | |
836 | in this mbuf. This value assumes that the data pointer was set | |
837 | to the start of the possible range for that pointer | |
838 | (mbuf_data_start). | |
839 | @param mbuf The mbuf. | |
840 | @result The maximum lenght of data for this mbuf. | |
841 | */ | |
2d21ac55 | 842 | size_t mbuf_maxlen(const mbuf_t mbuf); |
91447636 A |
843 | |
844 | /*! | |
845 | @function mbuf_type | |
846 | @discussion Gets the type of mbuf. | |
847 | @param mbuf The mbuf. | |
848 | @result The type. | |
849 | */ | |
2d21ac55 | 850 | mbuf_type_t mbuf_type(const mbuf_t mbuf); |
91447636 A |
851 | |
852 | /*! | |
853 | @function mbuf_settype | |
854 | @discussion Sets the type of mbuf. | |
855 | @param mbuf The mbuf. | |
856 | @param new_type The new type. | |
857 | @result 0 upon success otherwise the errno error. | |
858 | */ | |
859 | errno_t mbuf_settype(mbuf_t mbuf, mbuf_type_t new_type); | |
860 | ||
861 | /*! | |
862 | @function mbuf_flags | |
863 | @discussion Returns the set flags. | |
864 | @param mbuf The mbuf. | |
865 | @result The flags. | |
866 | */ | |
2d21ac55 | 867 | mbuf_flags_t mbuf_flags(const mbuf_t mbuf); |
91447636 A |
868 | |
869 | /*! | |
870 | @function mbuf_setflags | |
871 | @discussion Sets the set of set flags. | |
872 | @param mbuf The mbuf. | |
873 | @param flags The flags that should be set, all other flags will be cleared. | |
874 | @result 0 upon success otherwise the errno error. | |
875 | */ | |
876 | errno_t mbuf_setflags(mbuf_t mbuf, mbuf_flags_t flags); | |
877 | ||
878 | /*! | |
879 | @function mbuf_setflags_mask | |
880 | @discussion Useful for setting or clearing individual flags. Easier | |
881 | than calling mbuf_setflags(m, mbuf_flags(m) | M_FLAG). | |
882 | @param mbuf The mbuf. | |
883 | @param flags The flags that should be set or cleared. | |
884 | @param mask The mask controlling which flags will be modified. | |
885 | @result 0 upon success otherwise the errno error. | |
886 | */ | |
887 | errno_t mbuf_setflags_mask(mbuf_t mbuf, mbuf_flags_t flags, | |
888 | mbuf_flags_t mask); | |
889 | ||
890 | /*! | |
891 | @function mbuf_copy_pkthdr | |
892 | @discussion Copies the packet header from src to dest. | |
893 | @param src The mbuf from which the packet header will be copied. | |
894 | @param mbuf The mbuf to which the packet header will be copied. | |
895 | @result 0 upon success otherwise the errno error. | |
896 | */ | |
2d21ac55 | 897 | errno_t mbuf_copy_pkthdr(mbuf_t dest, const mbuf_t src); |
91447636 A |
898 | |
899 | /*! | |
900 | @function mbuf_pkthdr_len | |
901 | @discussion Returns the length as reported by the packet header. | |
902 | @param mbuf The mbuf containing the packet header with the length to | |
903 | be changed. | |
904 | @result The length, in bytes, of the packet. | |
905 | */ | |
2d21ac55 | 906 | size_t mbuf_pkthdr_len(const mbuf_t mbuf); |
91447636 A |
907 | |
908 | /*! | |
909 | @function mbuf_pkthdr_setlen | |
910 | @discussion Sets the length of the packet in the packet header. | |
911 | @param mbuf The mbuf containing the packet header. | |
912 | @param len The new length of the packet. | |
91447636 A |
913 | */ |
914 | void mbuf_pkthdr_setlen(mbuf_t mbuf, size_t len); | |
915 | ||
2d21ac55 A |
916 | /*! |
917 | @function mbuf_pkthdr_adjustlen | |
918 | @discussion Adjusts the length of the packet in the packet header. | |
919 | @param mbuf The mbuf containing the packet header. | |
920 | @param amount The number of bytes to adjust the packet header length | |
921 | field by. | |
922 | */ | |
923 | void mbuf_pkthdr_adjustlen(mbuf_t mbuf, int amount); | |
924 | ||
91447636 A |
925 | /*! |
926 | @function mbuf_pkthdr_rcvif | |
2d21ac55 A |
927 | @discussion Returns the interface the packet was received on. This |
928 | funciton does not modify the reference count of the interface. | |
929 | The interface is only valid for as long as the mbuf is not freed | |
930 | and the rcvif for the mbuf is not changed. Take a reference on | |
931 | the interface that you will release later before doing any of | |
932 | the following: free the mbuf, change the rcvif, pass the mbuf to | |
933 | any function that may free the mbuf or change the rcvif. | |
91447636 A |
934 | @param mbuf The mbuf containing the packet header. |
935 | @result A reference to the interface. | |
936 | */ | |
2d21ac55 | 937 | ifnet_t mbuf_pkthdr_rcvif(const mbuf_t mbuf); |
91447636 A |
938 | |
939 | /*! | |
940 | @function mbuf_pkthdr_setrcvif | |
941 | @discussion Sets the interface the packet was received on. | |
942 | @param mbuf The mbuf containing the packet header. | |
943 | @param ifnet A reference to an interface. | |
944 | @result 0 upon success otherwise the errno error. | |
945 | */ | |
2d21ac55 | 946 | errno_t mbuf_pkthdr_setrcvif(mbuf_t mbuf, ifnet_t ifp); |
91447636 A |
947 | |
948 | /*! | |
949 | @function mbuf_pkthdr_header | |
950 | @discussion Returns a pointer to the packet header. | |
951 | @param mbuf The mbuf containing the packet header. | |
952 | @result A pointer to the packet header. | |
953 | */ | |
2d21ac55 | 954 | void* mbuf_pkthdr_header(const mbuf_t mbuf); |
91447636 A |
955 | |
956 | /*! | |
957 | @function mbuf_pkthdr_setheader | |
958 | @discussion Sets the pointer to the packet header. | |
959 | @param mbuf The mbuf containing the packet header. | |
960 | @param ifnet A pointer to the header. | |
961 | @result 0 upon success otherwise the errno error. | |
962 | */ | |
963 | void mbuf_pkthdr_setheader(mbuf_t mbuf, void* header); | |
91447636 A |
964 | |
965 | /* Checksums */ | |
966 | ||
967 | /*! | |
968 | @function mbuf_inbound_modified | |
969 | @discussion This function will clear the checksum flags to indicate | |
970 | that a hardware checksum should not be used. Any filter | |
971 | modifying data should call this function on an mbuf before | |
972 | passing the packet up the stack. If a filter modifies a packet | |
973 | in a way that affects any checksum, the filter is responsible | |
974 | for either modifying the checksum to compensate for the changes | |
975 | or verifying the checksum before making the changes and then | |
976 | modifying the data and calculating a new checksum only if the | |
977 | original checksum was valid. | |
978 | @param mbuf The mbuf that has been modified. | |
979 | */ | |
980 | void mbuf_inbound_modified(mbuf_t mbuf); | |
981 | ||
982 | /*! | |
983 | @function mbuf_outbound_finalize | |
984 | @discussion This function will "finalize" the packet allowing your | |
985 | code to inspect the final packet. | |
986 | ||
987 | There are a number of operations that are performed in hardware, | |
988 | such as calculating checksums. This function will perform in | |
989 | software the various opterations that were scheduled to be done | |
990 | in hardware. Future operations may include IPSec processing or | |
991 | vlan support. If you are redirecting a packet to a new interface | |
992 | which may not have the same hardware support or encapsulating | |
993 | the packet, you should call this function to force the stack to | |
994 | calculate and fill out the checksums. This will bypass hardware | |
995 | checksums but give you a complete packet to work with. If you | |
996 | need to inspect aspects of the packet which may be generated by | |
997 | hardware, you must call this function to get an aproximate final | |
998 | packet. If you plan to modify the packet in any way, you should | |
999 | call this function. | |
1000 | ||
1001 | This function should be called before modifying any outbound | |
1002 | packets. | |
1003 | ||
1004 | This function may be called at various levels, in some cases | |
1005 | additional headers may have already been prepended, such as the | |
1006 | case of a packet seen by an interface filter. To handle this, | |
1007 | the caller must pass the protocol family of the packet as well | |
1008 | as the offset from the start of the packet to the protocol | |
1009 | header. | |
1010 | @param mbuf The mbuf that should be finalized. | |
1011 | @param protocol_family The protocol family of the packet in the | |
1012 | mbuf. | |
1013 | @param protocol_offset The offset from the start of the mbuf to the | |
1014 | protocol header. For an IP packet with an ethernet header, this | |
1015 | would be the length of an ethernet header. | |
1016 | */ | |
1017 | void mbuf_outbound_finalize(mbuf_t mbuf, u_long protocol_family, | |
1018 | size_t protocol_offset); | |
1019 | ||
1020 | /*! | |
1021 | @function mbuf_set_vlan_tag | |
1022 | @discussion This function is used by interfaces that support vlan | |
1023 | tagging in hardware. This function will set properties in the | |
1024 | mbuf to indicate which vlan the packet was received for. | |
1025 | @param mbuf The mbuf containing the packet. | |
1026 | @param vlan The protocol family of the aux data to add. | |
1027 | @result 0 upon success otherwise the errno error. | |
1028 | */ | |
1029 | errno_t mbuf_set_vlan_tag(mbuf_t mbuf, u_int16_t vlan); | |
1030 | ||
1031 | /*! | |
1032 | @function mbuf_get_vlan_tag | |
1033 | @discussion This function is used by drivers that support hardware | |
1034 | vlan tagging to determine which vlan this packet belongs to. To | |
1035 | differentiate between the case where the vlan tag is zero and | |
1036 | the case where there is no vlan tag, this function will return | |
1037 | ENXIO when there is no vlan. | |
1038 | @param mbuf The mbuf containing the packet. | |
1039 | @param vlan The protocol family of the aux data to add. | |
1040 | @result 0 upon success otherwise the errno error. ENXIO indicates | |
1041 | that the vlan tag is not set. | |
1042 | */ | |
1043 | errno_t mbuf_get_vlan_tag(mbuf_t mbuf, u_int16_t *vlan); | |
1044 | ||
1045 | /*! | |
1046 | @function mbuf_clear_vlan_tag | |
1047 | @discussion This function will clear any vlan tag associated with | |
1048 | the mbuf. | |
1049 | @param mbuf The mbuf containing the packet. | |
1050 | @result 0 upon success otherwise the errno error. | |
1051 | */ | |
1052 | errno_t mbuf_clear_vlan_tag(mbuf_t mbuf); | |
1053 | ||
1054 | #ifdef KERNEL_PRIVATE | |
2d21ac55 | 1055 | /* |
91447636 A |
1056 | @function mbuf_set_csum_requested |
1057 | @discussion This function is used by the stack to indicate which | |
1058 | checksums should be calculated in hardware. The stack normally | |
1059 | sets these flags as the packet is processed in the outbound | |
1060 | direction. Just before send the packe to the interface, the | |
1061 | stack will look at these flags and perform any checksums in | |
1062 | software that are not supported by the interface. | |
1063 | @param mbuf The mbuf containing the packet. | |
1064 | @param request Flags indicating which checksums are being requested | |
1065 | for this packet. | |
1066 | @param value This parameter is currently unsupported. | |
1067 | @result 0 upon success otherwise the errno error. | |
1068 | */ | |
1069 | errno_t mbuf_set_csum_requested(mbuf_t mbuf, | |
1070 | mbuf_csum_request_flags_t request, u_int32_t value); | |
1071 | #endif | |
1072 | ||
1073 | /*! | |
1074 | @function mbuf_get_csum_requested | |
1075 | @discussion This function is used by the driver to determine which | |
1076 | checksum operations should be performed in hardware. | |
1077 | @param mbuf The mbuf containing the packet. | |
1078 | @param request Flags indicating which checksums are being requested | |
1079 | for this packet. | |
1080 | @param value This parameter is currently unsupported. | |
1081 | @result 0 upon success otherwise the errno error. | |
1082 | */ | |
1083 | errno_t mbuf_get_csum_requested(mbuf_t mbuf, | |
1084 | mbuf_csum_request_flags_t *request, u_int32_t *value); | |
1085 | ||
1086 | /*! | |
1087 | @function mbuf_clear_csum_requested | |
1088 | @discussion This function clears the checksum request flags. | |
1089 | @param mbuf The mbuf containing the packet. | |
1090 | @result 0 upon success otherwise the errno error. | |
1091 | */ | |
1092 | errno_t mbuf_clear_csum_requested(mbuf_t mbuf); | |
1093 | ||
1094 | /*! | |
1095 | @function mbuf_set_csum_performed | |
1096 | @discussion This is used by the driver to indicate to the stack which | |
1097 | checksum operations were performed in hardware. | |
1098 | @param mbuf The mbuf containing the packet. | |
1099 | @param flags Flags indicating which hardware checksum operations | |
1100 | were performed. | |
1101 | @param value If the MBUF_CSUM_DID_DATA flag is set, value should be | |
1102 | set to the value of the TCP or UDP header as calculated by the | |
1103 | hardware. | |
1104 | @result 0 upon success otherwise the errno error. | |
1105 | */ | |
1106 | errno_t mbuf_set_csum_performed(mbuf_t mbuf, | |
1107 | mbuf_csum_performed_flags_t flags, u_int32_t value); | |
1108 | ||
1109 | #ifdef KERNEL_PRIVATE | |
2d21ac55 | 1110 | /* |
91447636 A |
1111 | @function mbuf_get_csum_performed |
1112 | @discussion This is used by the stack to determine which checksums | |
1113 | were calculated in hardware on the inbound path. | |
1114 | @param mbuf The mbuf containing the packet. | |
1115 | @param flags Flags indicating which hardware checksum operations | |
1116 | were performed. | |
1117 | @param value If the MBUF_CSUM_DID_DATA flag is set, value will be | |
1118 | set to the value of the TCP or UDP header as calculated by the | |
1119 | hardware. | |
1120 | @result 0 upon success otherwise the errno error. | |
1121 | */ | |
1122 | errno_t mbuf_get_csum_performed(mbuf_t mbuf, | |
1123 | mbuf_csum_performed_flags_t *flags, u_int32_t *value); | |
1124 | #endif | |
1125 | ||
1126 | /*! | |
1127 | @function mbuf_clear_csum_performed | |
1128 | @discussion Clears the hardware checksum flags and values. | |
1129 | @param mbuf The mbuf containing the packet. | |
1130 | @result 0 upon success otherwise the errno error. | |
1131 | */ | |
1132 | errno_t mbuf_clear_csum_performed(mbuf_t mbuf); | |
1133 | ||
2d21ac55 A |
1134 | /*! |
1135 | @function mbuf_inet_cksum | |
1136 | @discussions Calculates 16-bit 1's complement Internet checksum of the | |
1137 | transport segment with or without the pseudo header checksum | |
1138 | of a given IPv4 packet. If the caller specifies a non-zero | |
1139 | transport protocol, the checksum returned will also include | |
1140 | the pseudo header checksum for the corresponding transport | |
1141 | header. Otherwise, no header parsing will be done and the | |
1142 | caller may use this to calculate the Internet checksum of | |
1143 | an arbitrary span of data. | |
1144 | ||
1145 | This routine does not modify the contents of the packet. If | |
1146 | the caller specifies a non-zero protocol and/or offset, the | |
1147 | routine expects the complete protocol header to be present | |
1148 | at the beginning of the first mbuf. | |
1149 | @param mbuf The mbuf (or chain of mbufs) containing the packet. | |
1150 | @param protocol A zero or non-zero value. A non-zero value specifies | |
1151 | the transport protocol used for pseudo header checksum. | |
1152 | @param offset A zero or non-zero value; if the latter, it specifies | |
1153 | the offset of the transport header from the beginning of mbuf. | |
1154 | @param length The total (non-zero) length of the transport segment. | |
1155 | @param csum Pointer to the checksum variable; upon success, this | |
1156 | routine will return the calculated Internet checksum through | |
1157 | this variable. The caller must set it to a non-NULL value. | |
1158 | @result 0 upon success otherwise the errno error. | |
1159 | */ | |
1160 | errno_t mbuf_inet_cksum(mbuf_t mbuf, int protocol, u_int32_t offset, | |
1161 | u_int32_t length, u_int16_t *csum); | |
1162 | ||
1163 | /*! | |
1164 | @function mbuf_inet6_cksum | |
1165 | @discussions Calculates 16-bit 1's complement Internet checksum of the | |
1166 | transport segment with or without the pseudo header checksum | |
1167 | of a given IPv6 packet. If the caller specifies a non-zero | |
1168 | transport protocol, the checksum returned will also include | |
1169 | the pseudo header checksum for the corresponding transport | |
1170 | header. Otherwise, no header parsing will be done and the | |
1171 | caller may use this to calculate the Internet checksum of | |
1172 | an arbitrary span of data. | |
1173 | ||
1174 | This routine does not modify the contents of the packet. If | |
1175 | the caller specifies a non-zero protocol and/or offset, the | |
1176 | routine expects the complete protocol header(s) to be present | |
1177 | at the beginning of the first mbuf. | |
1178 | @param mbuf The mbuf (or chain of mbufs) containing the packet. | |
1179 | @param protocol A zero or non-zero value. A non-zero value specifies | |
1180 | the transport protocol used for pseudo header checksum. | |
1181 | @param offset A zero or non-zero value; if the latter, it specifies | |
1182 | the offset of the transport header from the beginning of mbuf. | |
1183 | @param length The total (non-zero) length of the transport segment. | |
1184 | @param csum Pointer to the checksum variable; upon success, this | |
1185 | routine will return the calculated Internet checksum through | |
1186 | this variable. The caller must set it to a non-NULL value. | |
1187 | @result 0 upon success otherwise the errno error. | |
1188 | */ | |
1189 | errno_t mbuf_inet6_cksum(mbuf_t mbuf, int protocol, u_int32_t offset, | |
1190 | u_int32_t length, u_int16_t *csum); | |
1191 | ||
91447636 A |
1192 | /* mbuf tags */ |
1193 | ||
1194 | /*! | |
1195 | @function mbuf_tag_id_find | |
1196 | @discussion Lookup the module id for a string. If there is no module | |
1197 | id assigned to this string, a new module id will be assigned. | |
1198 | The string should be the bundle id of the kext. In the case of a | |
1199 | tag that will be shared across multiple kexts, a common bundle id | |
1200 | style string should be used. | |
1201 | ||
1202 | The lookup operation is not optimized. A module should call this | |
1203 | function once during startup and chache the module id. The module id | |
1204 | will not be resassigned until the machine reboots. | |
1205 | @param module_string A unique string identifying your module. | |
1206 | Example: com.apple.nke.SharedIP. | |
1207 | @param module_id Upon return, a unique identifier for use with | |
1208 | mbuf_tag_* functions. This identifier is valid until the machine | |
1209 | is rebooted. | |
1210 | @result 0 upon success otherwise the errno error. | |
1211 | */ | |
1212 | errno_t mbuf_tag_id_find(const char *module_string, | |
1213 | mbuf_tag_id_t *module_id); | |
1214 | ||
1215 | /*! | |
1216 | @function mbuf_tag_allocate | |
1217 | @discussion Allocate an mbuf tag. Mbuf tags allow various portions | |
1218 | of the stack to tag mbufs with data that will travel with the | |
1219 | mbuf through the stack. | |
1220 | ||
1221 | Tags may only be added to mbufs with packet headers | |
1222 | (MBUF_PKTHDR flag is set). Mbuf tags are freed when the mbuf is | |
1223 | freed or when mbuf_tag_free is called. | |
1224 | @param mbuf The mbuf to attach this tag to. | |
1225 | @param module_id A module identifier returned by mbuf_tag_id_find. | |
1226 | @param type A 16 bit type value. For a given module_id, you can use | |
1227 | a number of different tag types. | |
1228 | @param length The length, in bytes, to allocate for storage that | |
1229 | will be associated with this tag on this mbuf. | |
1230 | @param how Indicate whether you want to block and wait for memory if | |
1231 | memory is not immediately available. | |
1232 | @param data_p Upon successful return, *data_p will point to the | |
1233 | buffer allocated for the mtag. | |
1234 | @result 0 upon success otherwise the errno error. | |
1235 | */ | |
1236 | errno_t mbuf_tag_allocate(mbuf_t mbuf, mbuf_tag_id_t module_id, | |
1237 | mbuf_tag_type_t type, size_t length, | |
1238 | mbuf_how_t how, void** data_p); | |
1239 | ||
1240 | /*! | |
1241 | @function mbuf_tag_find | |
1242 | @discussion Find the data associated with an mbuf tag. | |
1243 | @param mbuf The mbuf the tag is attached to. | |
1244 | @param module_id A module identifier returned by mbuf_tag_id_find. | |
1245 | @param type The 16 bit type of the tag to find. | |
1246 | @param length Upon success, the length of data will be store in | |
1247 | *length. | |
1248 | @param data_p Upon successful return, *data_p will point to the | |
1249 | buffer allocated for the mtag. | |
1250 | @result 0 upon success otherwise the errno error. | |
1251 | */ | |
1252 | errno_t mbuf_tag_find(mbuf_t mbuf, mbuf_tag_id_t module_id, | |
1253 | mbuf_tag_type_t type, size_t *length, void** data_p); | |
1254 | ||
1255 | /*! | |
1256 | @function mbuf_tag_free | |
1257 | @discussion Frees a previously allocated mbuf tag. | |
1258 | @param mbuf The mbuf the tag was allocated on. | |
1259 | @param module_id The ID of the tag to free. | |
1260 | @param type The type of the tag to free. | |
1261 | */ | |
1262 | void mbuf_tag_free(mbuf_t mbuf, mbuf_tag_id_t module_id, | |
1263 | mbuf_tag_type_t type); | |
1264 | ||
1265 | /* mbuf stats */ | |
1266 | ||
1267 | /*! | |
1268 | @function mbuf_stats | |
1269 | @discussion Get the mbuf statistics. | |
1270 | @param stats Storage to copy the stats in to. | |
1271 | */ | |
1272 | void mbuf_stats(struct mbuf_stat* stats); | |
1273 | ||
1274 | ||
1275 | ||
1276 | /* IF_QUEUE interaction */ | |
1277 | ||
1278 | #define IF_ENQUEUE_MBUF(ifq, m) { \ | |
1279 | mbuf_setnextpkt((m), 0); \ | |
1280 | if ((ifq)->ifq_tail == 0) \ | |
1281 | (ifq)->ifq_head = (m); \ | |
1282 | else \ | |
1283 | mbuf_setnextpkt((mbuf_t)(ifq)->ifq_tail, (m)); \ | |
1284 | (ifq)->ifq_tail = (m); \ | |
1285 | (ifq)->ifq_len++; \ | |
1286 | } | |
1287 | #define IF_PREPEND_MBUF(ifq, m) { \ | |
1288 | mbuf_setnextpkt((m), (ifq)->ifq_head); \ | |
1289 | if ((ifq)->ifq_tail == 0) \ | |
1290 | (ifq)->ifq_tail = (m); \ | |
1291 | (ifq)->ifq_head = (m); \ | |
1292 | (ifq)->ifq_len++; \ | |
1293 | } | |
1294 | #define IF_DEQUEUE_MBUF(ifq, m) { \ | |
1295 | (m) = (ifq)->ifq_head; \ | |
1296 | if (m) { \ | |
1297 | if (((ifq)->ifq_head = mbuf_nextpkt((m))) == 0) \ | |
1298 | (ifq)->ifq_tail = 0; \ | |
1299 | mbuf_setnextpkt((m), 0); \ | |
1300 | (ifq)->ifq_len--; \ | |
1301 | } \ | |
1302 | } | |
1303 | ||
2d21ac55 | 1304 | __END_DECLS |
91447636 | 1305 | #endif |