xnu-1228.3.13.tar.gz
[apple/xnu.git] / bsd / sys / kpi_mbuf.h
CommitLineData
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*/
71enum {
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};
83typedef 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*/
114enum {
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};
131typedef 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*/
149enum {
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};
157typedef 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*/
182enum {
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};
191typedef 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*/
206enum {
207 MBUF_WAITOK = 0, /* Ok to block to get memory */
208 MBUF_DONTWAIT = 1 /* Don't block, fail if blocking would be required */
209};
210typedef u_int32_t mbuf_how_t;
211
212typedef u_int32_t mbuf_tag_id_t;
213typedef 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*/
237struct 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 */
280void* 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 */
293void* 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 */
309errno_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 */
322errno_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 */
341addr64_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 */
354errno_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 */
366errno_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 */
394errno_t
395mbuf_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 */
422errno_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 */
433void 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 */
462errno_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 */
479errno_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*/
516errno_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*/
554errno_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 */
565errno_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 */
574mbuf_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 */
581void 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 */
590int 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 599size_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 608size_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 626errno_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 640errno_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 */
655errno_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 */
670errno_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 */
684errno_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 */
704errno_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 */
715void 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 */
728errno_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 742errno_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 */
766errno_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 */
777int 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 788mbuf_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 */
797errno_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 805mbuf_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 */
813void 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 821size_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 */
831void 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 842size_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 850mbuf_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 */
859errno_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 867mbuf_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 */
876errno_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 */
887errno_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 897errno_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 906size_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 */
914void 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 */
923void 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 937ifnet_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 946errno_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 954void* 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 */
963void 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 */
980void 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 */
1017void 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 */
1029errno_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 */
1043errno_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 */
1052errno_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 */
1069errno_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 */
1083errno_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 */
1092errno_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 */
1106errno_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 */
1122errno_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 */
1132errno_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 */
1160errno_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 */
1189errno_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 */
1212errno_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 */
1236errno_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 */
1252errno_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 */
1262void 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 */
1272void 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