1/*
2 * Copyright (c) 2008-2017 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
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.
14 *
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
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
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.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
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#ifdef KERNEL_PRIVATE
51#include <mach/kern_return.h>
52#endif /* KERNEL_PRIVATE */
53
54/*!
55 @enum mbuf_flags_t
56 @abstract Constants defining mbuf flags. Only the flags listed below
57 can be set or retrieved.
58 @constant MBUF_EXT Indicates this mbuf has external data.
59 @constant MBUF_PKTHDR Indicates this mbuf has a packet header.
60 @constant MBUF_EOR Indicates this mbuf is the end of a record.
61 @constant MBUF_LOOP Indicates this packet is looped back.
62 @constant MBUF_BCAST Indicates this packet will be sent or was
63 received as a brodcast.
64 @constant MBUF_MCAST Indicates this packet will be sent or was
65 received as a multicast.
66 @constant MBUF_FRAG Indicates this packet is a fragment of a larger
67 packet.
68 @constant MBUF_FIRSTFRAG Indicates this packet is the first fragment.
69 @constant MBUF_LASTFRAG Indicates this packet is the last fragment.
70 @constant MBUF_PROMISC Indicates this packet was only received
71 because the interface is in promiscuous mode. This should be set
72 by the demux function. These packets will be discarded after
73 being passed to any interface filters.
74*/
75enum {
76 MBUF_EXT = 0x0001, /* has associated external storage */
77 MBUF_PKTHDR = 0x0002, /* start of record */
78 MBUF_EOR = 0x0004, /* end of record */
79 MBUF_LOOP = 0x0040, /* packet is looped back */
80
81 MBUF_BCAST = 0x0100, /* send/received as link-level broadcast */
82 MBUF_MCAST = 0x0200, /* send/received as link-level multicast */
83 MBUF_FRAG = 0x0400, /* packet is a fragment of a larger packet */
84 MBUF_FIRSTFRAG = 0x0800, /* packet is first fragment */
85 MBUF_LASTFRAG = 0x1000, /* packet is last fragment */
86 MBUF_PROMISC = 0x2000, /* packet is promiscuous */
87 MBUF_HASFCS = 0x4000 /* packet has FCS */
88};
89typedef u_int32_t mbuf_flags_t;
90
91/*!
92 @enum mbuf_type_t
93 @abstract Types of mbufs.
94 @discussion Some mbufs represent packets, some represnt data waiting
95 on sockets. Other mbufs store control data or other various
96 structures. The mbuf type is used to store what sort of data the
97 mbuf contains.
98 @constant MBUF_MT_FREE Indicates the mbuf is free and is
99 sitting on the queue of free mbufs. If you find that an mbuf you
100 have a reference to has this type, something has gone terribly
101 wrong.
102 @constant MBUF_MT_DATA Indicates this mbuf is being used to store
103 data.
104 @constant MBUF_MT_HEADER Indicates this mbuf has a packet header,
105 this is probably a packet.
106 @constant MBUF_MT_SOCKET Socket structure.
107 @constant MBUF_MT_PCB Protocol control block.
108 @constant MBUF_MT_RTABLE Routing table entry.
109 @constant MBUF_MT_HTABLE IMP host tables???.
110 @constant MBUF_MT_ATABLE Address resolution table data.
111 @constant MBUF_MT_SONAME Socket name, usually a sockaddr of some
112 sort.
113 @constant MBUF_MT_FTABLE Fragment reassembly header.
114 @constant MBUF_MT_RIGHTS Access rights.
115 @constant MBUF_MT_IFADDR Interface address.
116 @constant MBUF_MT_CONTROL Extra-data protocol message (control
117 message).
118 @constant MBUF_MT_OOBDATA Out of band data.
119*/
120enum {
121 MBUF_TYPE_FREE = 0, /* should be on free list */
122 MBUF_TYPE_DATA = 1, /* dynamic (data) allocation */
123 MBUF_TYPE_HEADER = 2, /* packet header */
124 MBUF_TYPE_SOCKET = 3, /* socket structure */
125 MBUF_TYPE_PCB = 4, /* protocol control block */
126 MBUF_TYPE_RTABLE = 5, /* routing tables */
127 MBUF_TYPE_HTABLE = 6, /* IMP host tables */
128 MBUF_TYPE_ATABLE = 7, /* address resolution tables */
129 MBUF_TYPE_SONAME = 8, /* socket name */
130 MBUF_TYPE_SOOPTS = 10, /* socket options */
131 MBUF_TYPE_FTABLE = 11, /* fragment reassembly header */
132 MBUF_TYPE_RIGHTS = 12, /* access rights */
133 MBUF_TYPE_IFADDR = 13, /* interface address */
134 MBUF_TYPE_CONTROL = 14, /* extra-data protocol message */
135 MBUF_TYPE_OOBDATA = 15 /* expedited data */
136};
137typedef u_int32_t mbuf_type_t;
138
139/*!
140 @enum mbuf_csum_request_flags_t
141 @abstract Checksum performed/requested flags.
142 @discussion Mbufs often contain packets. Some hardware supports
143 performing checksums in hardware. The stack uses these flags to
144 indicate to the driver what sort of checksumming should be
145 handled in by the driver/hardware. These flags will only be set
146 if the driver indicates that it supports the corresponding
147 checksums using ifnet_set_offload.
148 @constant MBUF_CSUM_REQ_IP Indicates the IP checksum has not been
149 calculated yet.
150 @constant MBUF_CSUM_REQ_TCP Indicates the TCP checksum has not been
151 calculated yet.
152 @constant MBUF_CSUM_REQ_UDP Indicates the UDP checksum has not been
153 calculated yet.
154 @constant MBUF_CSUM_REQ_TCPIPV6 Indicates the TCP checksum for IPv6
155 has not been calculated yet.
156 @constant MBUF_CSUM_REQ_UDPIPV6 Indicates the UDP checksum for IPv6
157 has not been calculated yet.
158*/
159enum {
160 MBUF_TSO_IPV4 = 0x100000,
161 MBUF_TSO_IPV6 = 0x200000
162};
163typedef u_int32_t mbuf_tso_request_flags_t;
164
165enum {
166#ifdef KERNEL_PRIVATE
167 MBUF_CSUM_PARTIAL = 0x1000, /* 16-bit 1's complement sum */
168 MBUF_CSUM_REQ_SUM16 = MBUF_CSUM_PARTIAL,
169 MBUF_CSUM_REQ_ZERO_INVERT = 0x2000,
170#endif /* KERNEL_PRIVATE */
171 MBUF_CSUM_REQ_IP = 0x0001,
172 MBUF_CSUM_REQ_TCP = 0x0002,
173 MBUF_CSUM_REQ_UDP = 0x0004,
174 MBUF_CSUM_REQ_TCPIPV6 = 0x0020,
175 MBUF_CSUM_REQ_UDPIPV6 = 0x0040
176};
177typedef u_int32_t mbuf_csum_request_flags_t;
178
179/*!
180 @enum mbuf_csum_performed_flags_t
181 @abstract Checksum performed/requested flags.
182 @discussion Mbufs often contain packets. Some hardware supports
183 performing checksums in hardware. The driver uses these flags to
184 communicate to the stack the checksums that were calculated in
185 hardware.
186 @constant MBUF_CSUM_DID_IP Indicates that the driver/hardware verified
187 the IP checksum in hardware.
188 @constant MBUF_CSUM_IP_GOOD Indicates whether or not the IP checksum
189 was good or bad. Only valid when MBUF_CSUM_DID_IP is set.
190 @constant MBUF_CSUM_DID_DATA Indicates that the TCP or UDP checksum
191 was calculated. The value for the checksum calculated in
192 hardware should be passed as the second parameter of
193 mbuf_set_csum_performed. The hardware calculated checksum value
194 can be retrieved using the second parameter passed to
195 mbuf_get_csum_performed. This should be done for IPv4 or IPv6.
196 @constant MBUF_CSUM_PSEUDO_HDR If set, this indicates that the
197 checksum value for MBUF_CSUM_DID_DATA includes the pseudo header
198 value. If this is not set, the stack will calculate the pseudo
199 header value and add that to the checksum. The value of this bit
200 is only valid when MBUF_CSUM_DID_DATA is set.
201*/
202enum {
203#ifdef KERNEL_PRIVATE
204 MBUF_CSUM_TCP_SUM16 = MBUF_CSUM_PARTIAL,
205#endif /* KERNEL_PRIVATE */
206 MBUF_CSUM_DID_IP = 0x0100,
207 MBUF_CSUM_IP_GOOD = 0x0200,
208 MBUF_CSUM_DID_DATA = 0x0400,
209 MBUF_CSUM_PSEUDO_HDR = 0x0800
210};
211typedef u_int32_t mbuf_csum_performed_flags_t;
212
213/*!
214 @enum mbuf_how_t
215 @abstract Method of allocating an mbuf.
216 @discussion Blocking on the input or output path can impact
217 performance. There are some cases where making a blocking call
218 is acceptable. When in doubt, use MBUF_DONTWAIT.
219 @constant MBUF_WAITOK Allow a call to allocate an mbuf to block.
220 @constant MBUF_DONTWAIT Don't allow the mbuf allocation call to
221 block, if blocking is necessary fail and return immediately.
222*/
223enum {
224 MBUF_WAITOK = 0, /* Ok to block to get memory */
225 MBUF_DONTWAIT = 1 /* Don't block, fail if blocking would be required */
226};
227typedef u_int32_t mbuf_how_t;
228
229typedef u_int32_t mbuf_tag_id_t;
230typedef u_int16_t mbuf_tag_type_t;
231
232/*!
233 @struct mbuf_stat
234 @discussion The mbuf_stat contains mbuf statistics.
235 @field mbufs Number of mbufs (free or otherwise).
236 @field clusters Number of clusters (free or otherwise).
237 @field clfree Number of free clusters.
238 @field drops Number of times allocation failed.
239 @field wait Number of times allocation blocked.
240 @field drain Number of times protocol drain functions were called.
241 @field mtypes An array of counts of each type of mbuf allocated.
242 @field mcfail Number of times m_copym failed.
243 @field mpfail Number of times m_pullup failed.
244 @field msize Length of an mbuf.
245 @field mclbytes Length of an mbuf cluster.
246 @field minclsize Minimum length of data to allocate a cluster.
247 Anything smaller than this should be placed in chained mbufs.
248 @field mlen Length of data in an mbuf.
249 @field mhlen Length of data in an mbuf with a packet header.
250 @field bigclusters Number of big clusters.
251 @field bigclfree Number of unused big clusters.
252 @field bigmclbytes Length of a big mbuf cluster.
253*/
254struct mbuf_stat {
255 u_int32_t mbufs; /* mbufs obtained from page pool */
256 u_int32_t clusters; /* clusters obtained from page pool */
257 u_int32_t clfree; /* free clusters */
258 u_int32_t drops; /* times failed to find space */
259 u_int32_t wait; /* times waited for space */
260 u_int32_t drain; /* times drained protocols for space */
261 u_short mtypes[256]; /* type specific mbuf allocations */
262 u_int32_t mcfail; /* times m_copym failed */
263 u_int32_t mpfail; /* times m_pullup failed */
264 u_int32_t msize; /* length of an mbuf */
265 u_int32_t mclbytes; /* length of an mbuf cluster */
266 u_int32_t minclsize; /* min length of data to allocate a cluster */
267 u_int32_t mlen; /* length of data in an mbuf */
268 u_int32_t mhlen; /* length of data in a header mbuf */
269 u_int32_t bigclusters; /* number of big clusters */
270 u_int32_t bigclfree; /* number of big clustser free */
271 u_int32_t bigmclbytes; /* length of data in a big cluster */
272};
273
274/* Parameter for m_copym to copy all bytes */
275#define MBUF_COPYALL 1000000000
276
277__BEGIN_DECLS
278/* Data access */
279/*!
280 @function mbuf_data
281 @discussion Returns a pointer to the start of data in this mbuf.
282 There may be additional data on chained mbufs. The data you're
283 looking for may not be virtually contiguous if it spans more
284 than one mbuf. In addition, data that is virtually contiguous
285 might not be represented by physically contiguous pages; see
286 further comments in mbuf_data_to_physical. Use mbuf_len to
287 determine the length of data available in this mbuf. If a data
288 structure you want to access stradles two mbufs in a chain,
289 either use mbuf_pullup to get the data contiguous in one mbuf
290 or copy the pieces of data from each mbuf in to a contiguous
291 buffer. Using mbuf_pullup has the advantage of not having to
292 copy the data. On the other hand, if you don't make sure there
293 is space in the mbuf, mbuf_pullup may fail and free the mbuf.
294 @param mbuf The mbuf.
295 @result A pointer to the data in the mbuf.
296 */
297extern void *mbuf_data(mbuf_t mbuf);
298
299/*!
300 @function mbuf_datastart
301 @discussion Returns the start of the space set aside for storing
302 data in an mbuf. An mbuf's data may come from a cluster or be
303 embedded in the mbuf structure itself. The data pointer
304 retrieved by mbuf_data may not be at the start of the data
305 (mbuf_leadingspace will be non-zero). This function will return
306 a pointer that matches mbuf_data() - mbuf_leadingspace().
307 @param mbuf The mbuf.
308 @result A pointer to smallest possible value for data.
309 */
310extern void *mbuf_datastart(mbuf_t mbuf);
311
312/*!
313 @function mbuf_setdata
314 @discussion Sets the data and length values for an mbuf. The data
315 value must be in a valid range. In the case of an mbuf with a cluster,
316 the data value must point to a location in the cluster and the data
317 value plus the length, must be less than the end of the cluster. For
318 data embedded directly in an mbuf (no cluster), the data value must
319 fall somewhere between the start and end of the data area in the
320 mbuf and the data + length must also be in the same range.
321 @param mbuf The mbuf.
322 @param data The new pointer value for data.
323 @param len The new length of data in the mbuf.
324 @result 0 on success, errno error on failure.
325 */
326extern errno_t mbuf_setdata(mbuf_t mbuf, void *data, size_t len);
327
328/*!
329 @function mbuf_align_32
330 @discussion mbuf_align_32 is a replacement for M_ALIGN and MH_ALIGN.
331 mbuf_align_32 will set the data pointer to a location aligned on
332 a four byte boundry with at least 'len' bytes between the data
333 pointer and the end of the data block.
334 @param mbuf The mbuf.
335 @param len The minimum length of space that should follow the new
336 data location.
337 @result 0 on success, errno error on failure.
338 */
339extern errno_t mbuf_align_32(mbuf_t mbuf, size_t len);
340
341/*!
342 @function mbuf_data_to_physical
343 @discussion mbuf_data_to_physical is a replacement for mcl_to_paddr.
344 Given a pointer returned from mbuf_data of mbuf_datastart,
345 mbuf_data_to_physical will return the phyical address for that
346 block of data. Note that even though the data is in virtually
347 contiguous span, the underlying physical pages might not be
348 physically contiguous. Because of this, callers must ensure
349 to call this routine for each page boundary. Device drivers
350 that deal with DMA are strongly encouraged to utilize the
351 IOMbufNaturalMemoryCursor and walk down the list of vectors
352 instead of using this interface to obtain the physical address.
353 Use of this routine is therefore discouraged.
354 @param ptr A pointer to data stored in an mbuf.
355 @result The 64 bit physical address of the mbuf data or NULL if ptr
356 does not point to data stored in an mbuf.
357 */
358extern addr64_t mbuf_data_to_physical(void *ptr);
359
360
361/* Allocation */
362
363/*!
364 @function mbuf_get
365 @discussion Allocates an mbuf without a cluster for external data.
366 @param how Blocking or non-blocking.
367 @param type The type of the mbuf.
368 @param mbuf The mbuf.
369 @result 0 on success, errno error on failure.
370 */
371extern errno_t mbuf_get(mbuf_how_t how, mbuf_type_t type, mbuf_t *mbuf);
372
373/*!
374 @function mbuf_gethdr
375 @discussion Allocates an mbuf without a cluster for external data.
376 Sets a flag to indicate there is a packet header and initializes
377 the packet header.
378 @param how Blocking or non-blocking.
379 @param type The type of the mbuf.
380 @param mbuf The mbuf.
381 @result 0 on success, errno error on failure.
382 */
383extern errno_t mbuf_gethdr(mbuf_how_t how, mbuf_type_t type, mbuf_t *mbuf);
384
385/*!
386 @function mbuf_attachcluster
387 @discussion Attach an external buffer as a cluster for an mbuf. If mbuf
388 points to a NULL mbuf_t, an mbuf will be allocated for you. If
389 mbuf points to a non-NULL mbuf_t, the user-supplied mbuf will
390 be used instead. The caller is responsible for allocating the
391 external buffer by calling mbuf_alloccluster().
392 @param how Blocking or non-blocking.
393 @param type The type of the mbuf if mbuf is non-NULL; otherwise ignored.
394 @param mbuf Pointer to the address of the mbuf; if NULL, an mbuf will
395 be allocated, otherwise, it must point to a valid mbuf address.
396 If the user-supplied mbuf is already attached to a cluster, the
397 current cluster will be freed before the mbuf gets attached to
398 the supplied external buffer. Note that this routine may return
399 a different mbuf_t than the one you passed in.
400 @param extbuf Address of the external buffer.
401 @param extfree Free routine for the external buffer; the caller is
402 required to defined a routine that will be invoked when the
403 mbuf is freed.
404 @param extsize Size of the external buffer.
405 @param extarg Private value that will be passed to the free routine
406 when it is called at the time the mbuf is freed.
407 @result 0 on success
408 EINVAL - Invalid parameter
409 ENOMEM - Not enough memory available
410 */
411extern errno_t mbuf_attachcluster(mbuf_how_t how, mbuf_type_t type,
412 mbuf_t *mbuf, caddr_t extbuf, void (*extfree)(caddr_t , u_int, caddr_t),
413 size_t extsize, caddr_t extarg);
414
415/*!
416 @function mbuf_alloccluster
417 @discussion Allocate a cluster that can be later attached to an
418 mbuf by calling mbuf_attachcluster(). The allocated cluster
419 can also be freed (without being attached to an mbuf) by
420 calling mbuf_freecluster(). At the moment this routine
421 will either return a cluster of 2048, 4096 or 16384 bytes
422 depending on the requested size. Note that clusters greater
423 than 4096 bytes might not be available in all configurations;
424 the caller must additionally check for ENOTSUP (see below).
425 @param how Blocking or non-blocking.
426 @param size Pointer to size of requested cluster. Sizes up to 2048
427 will be rounded up to 2048; sizes greater than 2048 and up
428 to 4096 will be rounded up to 4096. Sizes greater than 4096
429 will be rounded up to 16384.
430 @param addr Pointer to the address of the requested cluster.
431 @result 0 on success or ENOMEM if failure. If the caller requests
432 greater than 4096 bytes and the system is unable to fulfill
433 the request due to the lack of jumbo clusters support based
434 on the configuration, this routine will return ENOTSUP.
435 In this case, the caller is advised to use 4096 bytes or
436 smaller during subseqent requests.
437 */
438extern errno_t mbuf_alloccluster(mbuf_how_t how, size_t *size, caddr_t *addr);
439
440/*!
441 @function mbuf_freecluster
442 @discussion Free a cluster that was previously allocated by a call
443 to mbuf_alloccluster(). The caller must pass the actual
444 size of the cluster as returned by mbuf_alloccluster(),
445 which at this point must be either 2048, 4096 or 16384 bytes.
446 @param addr The address of the cluster.
447 @param size The actual size of the cluster.
448 */
449extern void mbuf_freecluster(caddr_t addr, size_t size);
450
451#ifdef BSD_KERNEL_PRIVATE
452/*
453 * For now, restrict these to BSD kernel privates, since they are
454 * used only by the Nexus netif compatibility code.
455 */
456extern errno_t mbuf_ring_cluster_alloc(mbuf_how_t how, mbuf_type_t type,
457 mbuf_t *mbuf, void (*extfree)(caddr_t, u_int, caddr_t), size_t *size);
458extern int mbuf_ring_cluster_is_active(mbuf_t mbuf);
459extern errno_t mbuf_ring_cluster_activate(mbuf_t mbuf);
460extern errno_t mbuf_cluster_set_prop(mbuf_t mbuf, u_int32_t oldprop,
461 u_int32_t newprop);
462extern errno_t mbuf_cluster_get_prop(mbuf_t mbuf, u_int32_t *prop);
463#endif /* BSD_KERNEL_PRIVATE */
464
465/*!
466 @function mbuf_getcluster
467 @discussion Allocate a cluster of the requested size and attach it to
468 an mbuf for use as external data. If mbuf points to a NULL
469 mbuf_t, an mbuf will be allocated for you. If mbuf points to
470 a non-NULL mbuf_t, mbuf_getcluster may return a different
471 mbuf_t than the one you passed in.
472 @param how Blocking or non-blocking.
473 @param type The type of the mbuf.
474 @param size The size of the cluster to be allocated. Supported sizes
475 for a cluster are be 2048, 4096, or 16384. Any other value
476 with return EINVAL. Note that clusters greater than 4096
477 bytes might not be available in all configurations; the
478 caller must additionally check for ENOTSUP (see below).
479 @param mbuf The mbuf the cluster will be attached to.
480 @result 0 on success, errno error on failure. If you specified NULL
481 for the mbuf, any intermediate mbuf that may have been allocated
482 will be freed. If you specify an mbuf value in *mbuf,
483 mbuf_mclget will not free it.
484 EINVAL - Invalid parameter
485 ENOMEM - Not enough memory available
486 ENOTSUP - The caller had requested greater than 4096 bytes
487 cluster and the system is unable to fulfill it due to the
488 lack of jumbo clusters support based on the configuration.
489 In this case, the caller is advised to use 4096 bytes or
490 smaller during subsequent requests.
491 */
492extern errno_t mbuf_getcluster(mbuf_how_t how, mbuf_type_t type, size_t size,
493 mbuf_t *mbuf);
494
495/*!
496 @function mbuf_mclget
497 @discussion Allocate a cluster and attach it to an mbuf for use as
498 external data. If mbuf points to a NULL mbuf_t, an mbuf will be
499 allocated for you. If mbuf points to a non-NULL mbuf_t,
500 mbuf_mclget may return a different mbuf_t than the one you
501 passed in.
502 @param how Blocking or non-blocking.
503 @param type The type of the mbuf.
504 @param mbuf The mbuf the cluster will be attached to.
505 @result 0 on success, errno error on failure. If you specified NULL
506 for the mbuf, any intermediate mbuf that may have been allocated
507 will be freed. If you specify an mbuf value in *mbuf,
508 mbuf_mclget will not free it.
509 */
510extern errno_t mbuf_mclget(mbuf_how_t how, mbuf_type_t type, mbuf_t *mbuf);
511
512/*!
513 @function mbuf_allocpacket
514 @discussion Allocate an mbuf chain to store a single packet of the
515 requested length. According to the requested length, a chain
516 of mbufs will be created. The mbuf type will be set to
517 MBUF_TYPE_DATA. The caller may specify the maximum number of
518 buffer.
519 @param how Blocking or non-blocking
520 @param packetlen The total length of the packet mbuf to be allocated.
521 The length must be greater than zero.
522 @param maxchunks An input/output pointer to the maximum number of mbufs
523 segments making up the chain. On input, if maxchunks is NULL,
524 or the value pointed to by maxchunks is zero, the packet will
525 be made up of as few or as many buffer segments as necessary
526 to fit the length. The allocation will fail with ENOBUFS if
527 the number of segments requested is too small and the sum of
528 the maximum size of each individual segment is less than the
529 packet length. On output, if the allocation succeed and
530 maxchunks is non-NULL, it will point to the actual number
531 of segments allocated.
532 Additional notes for packetlen greater than 4096 bytes:
533 the caller may pass a non-NULL maxchunks and initialize it
534 with zero such that upon success, it can find out whether
535 or not the system configuration allows for larger than
536 4096 bytes cluster allocations, by checking on the value
537 pointed to by maxchunks. E.g. a request for 9018 bytes may
538 result in 1 chunk when jumbo clusters are available, or
539 3 chunks otherwise.
540 @param mbuf Upon success, *mbuf will be a reference to the new mbuf.
541 @result Returns 0 upon success or the following error code:
542 EINVAL - Invalid parameter
543 ENOMEM - Not enough memory available
544 ENOBUFS - Buffers not big enough for the maximum number of
545 chunks requested
546*/
547extern errno_t mbuf_allocpacket(mbuf_how_t how, size_t packetlen,
548 unsigned int * maxchunks, mbuf_t *mbuf);
549
550/*!
551 @function mbuf_allocpacket_list
552 @discussion Allocate a linked list of packets. According to the
553 requested length, each packet will made of a chain of one
554 or more mbufs. The mbuf type will be set to MBUF_TYPE_DATA.
555 The caller may specify the maximum number of element for
556 each mbuf chain making up a packet.
557 @param numpkts Number of packets to allocate
558 @param how Blocking or non-blocking
559 @param packetlen The total length of the packet mbuf to be allocated.
560 The length must be greater than zero.
561 @param maxchunks An input/output pointer to the maximum number of
562 mbufs segments making up the chain. On input, if maxchunks is
563 zero, or the value pointed to by maxchunks is zero, the packet
564 will be made of as few or as many buffer segments as necessary
565 to fit the length. The allocation will fail with ENOBUFS if
566 the number of segments requested is too small and the sum of
567 the maximum size of each individual segment is less than the
568 packet length. On output, if the allocation succeed and
569 maxchunks is non zero, it will point to the actual number
570 of segments allocated.
571 Additional notes for packetlen greater than 4096 bytes:
572 the caller may pass a non-NULL maxchunks and initialize it
573 with zero such that upon success, it can find out whether
574 or not the system configuration allows for larger than
575 4096 bytes cluster allocations, by checking on the value
576 pointed to by maxchunks. E.g. a request for 9018 bytes may
577 result in 1 chunk when jumbo clusters are available, or
578 3 chunks otherwise.
579 @param mbuf Upon success, *mbuf will be a reference to the new mbuf.
580 @result Returns 0 upon success or the following error code:
581 EINVAL - Invalid parameter
582 ENOMEM - Not enough memory available
583 ENOBUFS - Buffers not big enough for the maximum number of
584 chunks requested
585*/
586extern errno_t mbuf_allocpacket_list(unsigned int numpkts, mbuf_how_t how,
587 size_t packetlen, unsigned int * maxchunks, mbuf_t *mbuf);
588
589
590/*!
591 @function mbuf_getpacket
592 @discussion Allocate an mbuf, allocate and attach a cluster, and set
593 the packet header flag.
594 @param how Blocking or non-blocking.
595 @param mbuf Upon success, *mbuf will be a reference to the new mbuf.
596 @result 0 on success, errno error on failure.
597 */
598extern errno_t mbuf_getpacket(mbuf_how_t how, mbuf_t *mbuf);
599
600/*!
601 @function mbuf_free
602 @discussion Frees a single mbuf. Not commonly used because it
603 doesn't touch the rest of the mbufs on the chain.
604 @param mbuf The mbuf to free.
605 @result The next mbuf in the chain.
606 */
607extern mbuf_t mbuf_free(mbuf_t mbuf);
608
609/*!
610 @function mbuf_freem
611 @discussion Frees a chain of mbufs link through mnext.
612 @param mbuf The first mbuf in the chain to free.
613 */
614extern void mbuf_freem(mbuf_t mbuf);
615
616/*!
617 @function mbuf_freem_list
618 @discussion Frees linked list of mbuf chains. Walks through
619 mnextpackt and does the equivalent of mbuf_freem to each.
620 @param mbuf The first mbuf in the linked list to free.
621 @result The number of mbufs freed.
622 */
623extern int mbuf_freem_list(mbuf_t mbuf);
624
625/*!
626 @function mbuf_leadingspace
627 @discussion Determines the space available in the mbuf proceeding
628 the current data.
629 @param mbuf The mbuf.
630 @result The number of unused bytes at the start of the mbuf.
631 */
632extern size_t mbuf_leadingspace(const mbuf_t mbuf);
633
634/*!
635 @function mbuf_trailingspace
636 @discussion Determines the space available in the mbuf following
637 the current data.
638 @param mbuf The mbuf.
639 @result The number of unused bytes following the current data.
640 */
641extern size_t mbuf_trailingspace(const mbuf_t mbuf);
642
643/* Manipulation */
644
645/*!
646 @function mbuf_copym
647 @discussion Copies len bytes from offset from src to a new mbuf. If
648 the original mbuf contains a packet header, the new mbuf will
649 contain similar packet header except for any tags which may be
650 associated with the original mbuf. mbuf_dup() should be used
651 instead if tags are to be copied to the new mbuf.
652 @param src The source mbuf.
653 @param offset The offset in the mbuf to start copying from.
654 @param len The the number of bytes to copy.
655 @param how To block or not to block, that is a question.
656 @param new_mbuf Upon success, the newly allocated mbuf.
657 @result 0 upon success otherwise the errno error.
658 */
659extern errno_t mbuf_copym(const mbuf_t src, size_t offset, size_t len,
660 mbuf_how_t how, mbuf_t *new_mbuf);
661
662/*!
663 @function mbuf_dup
664 @discussion Exactly duplicates an mbuf chain. If the original mbuf
665 contains a packet header (including tags), the new mbuf will have
666 the same packet header contents and a copy of each tag associated
667 with the original mbuf.
668 @param src The source mbuf.
669 @param how Blocking or non-blocking.
670 @param new_mbuf Upon success, the newly allocated mbuf.
671 @result 0 upon success otherwise the errno error.
672 */
673extern errno_t mbuf_dup(const mbuf_t src, mbuf_how_t how, mbuf_t *new_mbuf);
674
675/*!
676 @function mbuf_prepend
677 @discussion Prepend len bytes to an mbuf. If there is space
678 (mbuf_leadingspace >= len), the mbuf's data ptr is changed and
679 the same mbuf is returned. If there is no space, a new mbuf may
680 be allocated and prepended to the mbuf chain. If the operation
681 fails, the mbuf may be freed (*mbuf will be NULL).
682 @param mbuf The mbuf to prepend data to. This may change if a new
683 mbuf must be allocated or may be NULL if the operation fails.
684 @param len The length, in bytes, to be prepended to the mbuf.
685 @param how Blocking or non-blocking.
686 @result 0 upon success otherwise the errno error.
687 */
688extern errno_t mbuf_prepend(mbuf_t *mbuf, size_t len, mbuf_how_t how);
689
690/*!
691 @function mbuf_split
692 @discussion Split an mbuf chain at a specific offset.
693 @param src The mbuf to be split.
694 @param offset The offset in the buffer where the mbuf should be
695 split.
696 @param how Blocking or non-blocking.
697 @param new_mbuf Upon success, the second half of the split mbuf
698 chain.
699 @result 0 upon success otherwise the errno error. In the case of
700 failure, the original mbuf chain passed in to src will be
701 preserved.
702 */
703extern errno_t mbuf_split(mbuf_t src, size_t offset, mbuf_how_t how,
704 mbuf_t *new_mbuf);
705
706/*!
707 @function mbuf_pullup
708 @discussion Move the next len bytes in to mbuf from other mbufs in
709 the chain. This is commonly used to get the IP and TCP or UDP
710 header contiguous in the first mbuf. If mbuf_pullup fails, the
711 entire mbuf chain will be freed.
712 @param mbuf The mbuf in the chain the data should be contiguous in.
713 @param len The number of bytes to pull from the next mbuf(s).
714 @result 0 upon success otherwise the errno error. In the case of an
715 error, the mbuf chain has been freed.
716 */
717extern errno_t mbuf_pullup(mbuf_t *mbuf, size_t len);
718
719/*!
720 @function mbuf_pulldown
721 @discussion Make length bytes at offset in the mbuf chain
722 contiguous. Nothing before offset bytes in the chain will be
723 modified. Upon return, location will be the mbuf the data is
724 contiguous in and offset will be the offset in that mbuf at
725 which the data is located. In the case of a failure, the mbuf
726 chain will be freed.
727 @param src The start of the mbuf chain.
728 @param offset Pass in a pointer to a value with the offset of the
729 data you're interested in making contiguous. Upon success, this
730 will be overwritten with the offset from the mbuf returned in
731 location.
732 @param length The length of data that should be made contiguous.
733 @param location Upon success, *location will be the mbuf the data is
734 in.
735 @result 0 upon success otherwise the errno error.
736 */
737extern errno_t mbuf_pulldown(mbuf_t src, size_t *offset, size_t length,
738 mbuf_t *location);
739
740/*!
741 @function mbuf_adj
742 @discussion Trims len bytes from the mbuf. If the length is greater
743 than zero, the bytes are trimmed from the front of the mbuf. If
744 the length is less than zero, the bytes are trimmed from the end
745 of the mbuf chain.
746 @param mbuf The mbuf chain to trim.
747 @param len The number of bytes to trim from the mbuf chain.
748 */
749extern void mbuf_adj(mbuf_t mbuf, int len);
750
751/*!
752 @function mbuf_adjustlen
753 @discussion Adds amount to the mbuf len. Verifies that the new
754 length is valid (greater than or equal to zero and less than
755 maximum amount of data that may be stored in the mbuf). This
756 function will not adjust the packet header length field or
757 affect any other mbufs in a chain.
758 @param mbuf The mbuf to adjust.
759 @param amount The number of bytes increment the length by.
760 @result 0 upon success otherwise the errno error.
761 */
762extern errno_t mbuf_adjustlen(mbuf_t mbuf, int amount);
763
764/*!
765 @function mbuf_concatenate
766 @discussion Concatenate mbuf chain src to dst using m_next and return
767 a chain which represents the concatenated chain. The routine
768 does not prevent two chains of different mbuf types to be
769 concatenated, nor does it modify any packet header in the
770 destination chain. Therefore, it's the responsibility of the
771 caller to ensure that the resulted concatenated mbuf chain is
772 correct for further usages.
773 @param dst The destination mbuf chain.
774 @param src The source mbuf chain.
775 @result A pointer to the head of the concatenated mbuf chain. This
776 should be treated as the updated destination mbuf chain; the
777 caller must no longer refer to the original src or dst mbuf
778 chain. Otherwise it returns NULL if the original dst mbuf
779 chain is NULL.
780 */
781extern mbuf_t mbuf_concatenate(mbuf_t dst, mbuf_t src);
782
783/*!
784 @function mbuf_copydata
785 @discussion Copies data out of an mbuf in to a specified buffer. If
786 the data is stored in a chain of mbufs, the data will be copied
787 from each mbuf in the chain until length bytes have been copied.
788 @param mbuf The mbuf chain to copy data out of.
789 @param offset The offset in to the mbuf to start copying.
790 @param length The number of bytes to copy.
791 @param out_data A pointer to the location where the data will be
792 copied.
793 @result 0 upon success otherwise the errno error.
794 */
795extern errno_t mbuf_copydata(const mbuf_t mbuf, size_t offset, size_t length,
796 void *out_data);
797
798/*!
799 @function mbuf_copyback
800 @discussion Copies data from a buffer to an mbuf chain.
801 mbuf_copyback will grow the chain to fit the specified buffer.
802
803 If mbuf_copydata is unable to allocate enough mbufs to grow the
804 chain, ENOBUFS will be returned. The mbuf chain will be shorter
805 than expected but all of the data up to the end of the mbuf
806 chain will be valid.
807
808 If an offset is specified, mbuf_copyback will skip that many
809 bytes in the mbuf chain before starting to write the buffer in
810 to the chain. If the mbuf chain does not contain this many
811 bytes, mbufs will be allocated to create the space.
812 @param mbuf The first mbuf in the chain to copy the data in to.
813 @param offset Offset in bytes to skip before copying data.
814 @param length The length, in bytes, of the data to copy in to the mbuf
815 chain.
816 @param data A pointer to data in the kernel's address space.
817 @param how Blocking or non-blocking.
818 @result 0 upon success, EINVAL or ENOBUFS upon failure.
819 */
820extern errno_t mbuf_copyback(mbuf_t mbuf, size_t offset, size_t length,
821 const void *data, mbuf_how_t how);
822
823/*!
824 @function mbuf_mclhasreference
825 @discussion Check if a cluster of an mbuf is referenced by another mbuf.
826 References may be taken, for example, as a result of a call to
827 mbuf_split or mbuf_copym
828 @param mbuf The mbuf with the cluster to test.
829 @result 0 if there is no reference by another mbuf, 1 otherwise.
830 */
831extern int mbuf_mclhasreference(mbuf_t mbuf);
832
833
834/* mbuf header */
835
836/*!
837 @function mbuf_next
838 @discussion Returns the next mbuf in the chain.
839 @param mbuf The mbuf.
840 @result The next mbuf in the chain.
841 */
842extern mbuf_t mbuf_next(const mbuf_t mbuf);
843
844/*!
845 @function mbuf_setnext
846 @discussion Sets the next mbuf in the chain.
847 @param mbuf The mbuf.
848 @param next The new next mbuf.
849 @result 0 upon success otherwise the errno error.
850 */
851extern errno_t mbuf_setnext(mbuf_t mbuf, mbuf_t next);
852
853/*!
854 @function mbuf_nextpkt
855 @discussion Gets the next packet from the mbuf.
856 @param mbuf The mbuf.
857 @result The nextpkt.
858 */
859extern mbuf_t mbuf_nextpkt(const mbuf_t mbuf);
860
861/*!
862 @function mbuf_setnextpkt
863 @discussion Sets the next packet attached to this mbuf.
864 @param mbuf The mbuf.
865 @param nextpkt The new next packet.
866 */
867extern void mbuf_setnextpkt(mbuf_t mbuf, mbuf_t nextpkt);
868
869/*!
870 @function mbuf_len
871 @discussion Gets the length of data in this mbuf.
872 @param mbuf The mbuf.
873 @result The length.
874 */
875extern size_t mbuf_len(const mbuf_t mbuf);
876
877/*!
878 @function mbuf_setlen
879 @discussion Sets the length of data in this packet. Be careful to
880 not set the length over the space available in the mbuf.
881 @param mbuf The mbuf.
882 @param len The new length.
883 */
884extern void mbuf_setlen(mbuf_t mbuf, size_t len);
885
886/*!
887 @function mbuf_maxlen
888 @discussion Retrieves the maximum length of data that may be stored
889 in this mbuf. This value assumes that the data pointer was set
890 to the start of the possible range for that pointer
891 (mbuf_data_start).
892 @param mbuf The mbuf.
893 @result The maximum lenght of data for this mbuf.
894 */
895extern size_t mbuf_maxlen(const mbuf_t mbuf);
896
897/*!
898 @function mbuf_type
899 @discussion Gets the type of mbuf.
900 @param mbuf The mbuf.
901 @result The type.
902 */
903extern mbuf_type_t mbuf_type(const mbuf_t mbuf);
904
905/*!
906 @function mbuf_settype
907 @discussion Sets the type of mbuf.
908 @param mbuf The mbuf.
909 @param new_type The new type.
910 @result 0 upon success otherwise the errno error.
911 */
912extern errno_t mbuf_settype(mbuf_t mbuf, mbuf_type_t new_type);
913
914/*!
915 @function mbuf_flags
916 @discussion Returns the set flags.
917 @param mbuf The mbuf.
918 @result The flags.
919 */
920extern mbuf_flags_t mbuf_flags(const mbuf_t mbuf);
921
922/*!
923 @function mbuf_setflags
924 @discussion Sets the set of set flags.
925 @param mbuf The mbuf.
926 @param flags The flags that should be set, all other flags will be
927 cleared. Certain flags such as MBUF_EXT cannot be altered.
928 @result 0 upon success otherwise the errno error.
929 */
930extern errno_t mbuf_setflags(mbuf_t mbuf, mbuf_flags_t flags);
931
932/*!
933 @function mbuf_setflags_mask
934 @discussion Useful for setting or clearing individual flags. Easier
935 than calling mbuf_setflags(m, mbuf_flags(m) | M_FLAG).
936 @param mbuf The mbuf.
937 @param flags The flags that should be set or cleared. Certain flags
938 such as MBUF_EXT cannot be altered.
939 @param mask The mask controlling which flags will be modified.
940 @result 0 upon success otherwise the errno error.
941 */
942extern errno_t mbuf_setflags_mask(mbuf_t mbuf, mbuf_flags_t flags,
943 mbuf_flags_t mask);
944
945/*!
946 @function mbuf_copy_pkthdr
947 @discussion Copies the packet header from src to dest.
948 @param src The mbuf from which the packet header will be copied.
949 @param dest The mbuf to which the packet header will be copied.
950 @result 0 upon success otherwise the errno error.
951 */
952extern errno_t mbuf_copy_pkthdr(mbuf_t dest, const mbuf_t src);
953
954/*!
955 @function mbuf_pkthdr_len
956 @discussion Returns the length as reported by the packet header.
957 @param mbuf The mbuf containing the packet header
958 @result The length, in bytes, of the packet.
959 */
960extern size_t mbuf_pkthdr_len(const mbuf_t mbuf);
961
962/*!
963 @function mbuf_pkthdr_setlen
964 @discussion Sets the length of the packet in the packet header.
965 @param mbuf The mbuf containing the packet header.
966 @param len The new length of the packet.
967 */
968extern void mbuf_pkthdr_setlen(mbuf_t mbuf, size_t len);
969
970#ifdef XNU_KERNEL_PRIVATE
971/*!
972 @function mbuf_pkthdr_maxlen
973 @discussion Retrieves the maximum length of data that may be stored
974 in this mbuf packet. This value assumes that the data pointer
975 was set to the start of the possible range for that pointer
976 for each mbuf in the packet chain
977 @param mbuf The mbuf.
978 @result The maximum lenght of data for this mbuf.
979 */
980extern size_t mbuf_pkthdr_maxlen(const mbuf_t mbuf);
981#endif /* XNU_KERNEL_PRIVATE */
982
983/*!
984 @function mbuf_pkthdr_adjustlen
985 @discussion Adjusts the length of the packet in the packet header.
986 @param mbuf The mbuf containing the packet header.
987 @param amount The number of bytes to adjust the packet header length
988 field by.
989 */
990extern void mbuf_pkthdr_adjustlen(mbuf_t mbuf, int amount);
991
992/*!
993 @function mbuf_pkthdr_rcvif
994 @discussion Returns the interface the packet was received on. This
995 funciton does not modify the reference count of the interface.
996 The interface is only valid for as long as the mbuf is not freed
997 and the rcvif for the mbuf is not changed. Take a reference on
998 the interface that you will release later before doing any of
999 the following: free the mbuf, change the rcvif, pass the mbuf to
1000 any function that may free the mbuf or change the rcvif.
1001 @param mbuf The mbuf containing the packet header.
1002 @result A reference to the interface.
1003 */
1004extern ifnet_t mbuf_pkthdr_rcvif(const mbuf_t mbuf);
1005
1006/*!
1007 @function mbuf_pkthdr_setrcvif
1008 @discussion Sets the interface the packet was received on.
1009 @param mbuf The mbuf containing the packet header.
1010 @param ifp A reference to an interface.
1011 @result 0 upon success otherwise the errno error.
1012 */
1013extern errno_t mbuf_pkthdr_setrcvif(mbuf_t mbuf, ifnet_t ifp);
1014
1015/*!
1016 @function mbuf_pkthdr_header
1017 @discussion Returns a pointer to the packet header.
1018 @param mbuf The mbuf containing the packet header.
1019 @result A pointer to the packet header.
1020 */
1021extern void *mbuf_pkthdr_header(const mbuf_t mbuf);
1022
1023/*!
1024 @function mbuf_pkthdr_setheader
1025 @discussion Sets the pointer to the packet header.
1026 @param mbuf The mbuf containing the packet header.
1027 @param header A pointer to the header.
1028 */
1029extern void mbuf_pkthdr_setheader(mbuf_t mbuf, void *header);
1030
1031/* Checksums */
1032
1033/*!
1034 @function mbuf_inbound_modified
1035 @discussion This function will clear the checksum flags to indicate
1036 that a hardware checksum should not be used. Any filter
1037 modifying data should call this function on an mbuf before
1038 passing the packet up the stack. If a filter modifies a packet
1039 in a way that affects any checksum, the filter is responsible
1040 for either modifying the checksum to compensate for the changes
1041 or verifying the checksum before making the changes and then
1042 modifying the data and calculating a new checksum only if the
1043 original checksum was valid.
1044 @param mbuf The mbuf that has been modified.
1045 */
1046extern void mbuf_inbound_modified(mbuf_t mbuf);
1047
1048/*!
1049 @function mbuf_outbound_finalize
1050 @discussion This function will "finalize" the packet allowing your
1051 code to inspect the final packet.
1052
1053 There are a number of operations that are performed in hardware,
1054 such as calculating checksums. This function will perform in
1055 software the various opterations that were scheduled to be done
1056 in hardware. Future operations may include IPSec processing or
1057 vlan support. If you are redirecting a packet to a new interface
1058 which may not have the same hardware support or encapsulating
1059 the packet, you should call this function to force the stack to
1060 calculate and fill out the checksums. This will bypass hardware
1061 checksums but give you a complete packet to work with. If you
1062 need to inspect aspects of the packet which may be generated by
1063 hardware, you must call this function to get an aproximate final
1064 packet. If you plan to modify the packet in any way, you should
1065 call this function.
1066
1067 This function should be called before modifying any outbound
1068 packets.
1069
1070 This function may be called at various levels, in some cases
1071 additional headers may have already been prepended, such as the
1072 case of a packet seen by an interface filter. To handle this,
1073 the caller must pass the protocol family of the packet as well
1074 as the offset from the start of the packet to the protocol
1075 header.
1076 @param mbuf The mbuf that should be finalized.
1077 @param protocol_family The protocol family of the packet in the
1078 mbuf.
1079 @param protocol_offset The offset from the start of the mbuf to the
1080 protocol header. For an IP packet with an ethernet header, this
1081 would be the length of an ethernet header.
1082 */
1083extern void mbuf_outbound_finalize(mbuf_t mbuf, u_int32_t protocol_family,
1084 size_t protocol_offset);
1085
1086/*!
1087 @function mbuf_set_vlan_tag
1088 @discussion This function is used by interfaces that support vlan
1089 tagging in hardware. This function will set properties in the
1090 mbuf to indicate which vlan the packet was received for.
1091 @param mbuf The mbuf containing the packet.
1092 @param vlan The protocol family of the aux data to add.
1093 @result 0 upon success otherwise the errno error.
1094 */
1095extern errno_t mbuf_set_vlan_tag(mbuf_t mbuf, u_int16_t vlan);
1096
1097/*!
1098 @function mbuf_get_vlan_tag
1099 @discussion This function is used by drivers that support hardware
1100 vlan tagging to determine which vlan this packet belongs to. To
1101 differentiate between the case where the vlan tag is zero and
1102 the case where there is no vlan tag, this function will return
1103 ENXIO when there is no vlan.
1104 @param mbuf The mbuf containing the packet.
1105 @param vlan The protocol family of the aux data to add.
1106 @result 0 upon success otherwise the errno error. ENXIO indicates
1107 that the vlan tag is not set.
1108 */
1109extern errno_t mbuf_get_vlan_tag(mbuf_t mbuf, u_int16_t *vlan);
1110
1111/*!
1112 @function mbuf_clear_vlan_tag
1113 @discussion This function will clear any vlan tag associated with
1114 the mbuf.
1115 @param mbuf The mbuf containing the packet.
1116 @result 0 upon success otherwise the errno error.
1117 */
1118extern errno_t mbuf_clear_vlan_tag(mbuf_t mbuf);
1119
1120#ifdef KERNEL_PRIVATE
1121/*!
1122 @function mbuf_set_csum_requested
1123 @discussion This function is used by the stack to indicate which
1124 checksums should be calculated in hardware. The stack normally
1125 sets these flags as the packet is processed in the outbound
1126 direction. Just before send the packe to the interface, the
1127 stack will look at these flags and perform any checksums in
1128 software that are not supported by the interface.
1129 @param mbuf The mbuf containing the packet.
1130 @param request Flags indicating which checksums are being requested
1131 for this packet.
1132 @param value This parameter is currently unsupported.
1133 @result 0 upon success otherwise the errno error.
1134 */
1135extern errno_t mbuf_set_csum_requested(mbuf_t mbuf,
1136 mbuf_csum_request_flags_t request, u_int32_t value);
1137#endif /* KERNEL_PRIVATE */
1138
1139/*!
1140 @function mbuf_get_csum_requested
1141 @discussion This function is used by the driver to determine which
1142 checksum operations should be performed in hardware.
1143 @param mbuf The mbuf containing the packet.
1144 @param request Flags indicating which checksums are being requested
1145 for this packet.
1146 @param value This parameter is currently unsupported.
1147 @result 0 upon success otherwise the errno error.
1148 */
1149extern errno_t mbuf_get_csum_requested(mbuf_t mbuf,
1150 mbuf_csum_request_flags_t *request, u_int32_t *value);
1151
1152/*!
1153 @function mbuf_get_tso_requested
1154 @discussion This function is used by the driver to determine which
1155 checksum operations should be performed in hardware.
1156 @param mbuf The mbuf containing the packet.
1157 @param request Flags indicating which values are being requested
1158 for this packet.
1159 @param value The requested value.
1160 @result 0 upon success otherwise the errno error.
1161 */
1162extern errno_t mbuf_get_tso_requested(mbuf_t mbuf,
1163 mbuf_tso_request_flags_t *request, u_int32_t *value);
1164
1165/*!
1166 @function mbuf_clear_csum_requested
1167 @discussion This function clears the checksum request flags.
1168 @param mbuf The mbuf containing the packet.
1169 @result 0 upon success otherwise the errno error.
1170 */
1171extern errno_t mbuf_clear_csum_requested(mbuf_t mbuf);
1172
1173/*!
1174 @function mbuf_set_csum_performed
1175 @discussion This is used by the driver to indicate to the stack which
1176 checksum operations were performed in hardware.
1177 @param mbuf The mbuf containing the packet.
1178 @param flags Flags indicating which hardware checksum operations
1179 were performed.
1180 @param value If the MBUF_CSUM_DID_DATA flag is set, value should be
1181 set to the value of the TCP or UDP header as calculated by the
1182 hardware.
1183 @result 0 upon success otherwise the errno error.
1184 */
1185extern errno_t mbuf_set_csum_performed(mbuf_t mbuf,
1186 mbuf_csum_performed_flags_t flags, u_int32_t value);
1187
1188#ifdef KERNEL_PRIVATE
1189/*
1190 @function mbuf_get_csum_performed
1191 @discussion This is used by the stack to determine which checksums
1192 were calculated in hardware on the inbound path.
1193 @param mbuf The mbuf containing the packet.
1194 @param flags Flags indicating which hardware checksum operations
1195 were performed.
1196 @param value If the MBUF_CSUM_DID_DATA flag is set, value will be
1197 set to the value of the TCP or UDP header as calculated by the
1198 hardware.
1199 @result 0 upon success otherwise the errno error.
1200 */
1201extern errno_t mbuf_get_csum_performed(mbuf_t mbuf,
1202 mbuf_csum_performed_flags_t *flags, u_int32_t *value);
1203#endif /* KERNEL_PRIVATE */
1204
1205/*!
1206 @function mbuf_get_mlen
1207 @discussion This routine returns the number of data bytes in a normal
1208 mbuf, i.e. an mbuf that is not a packet header, nor one with
1209 an external cluster attached to it. This is equivalent to the
1210 legacy MLEN macro.
1211 @result The number of bytes of available data.
1212 */
1213extern u_int32_t mbuf_get_mlen(void);
1214
1215/*!
1216 @function mbuf_get_mhlen
1217 @discussion This routine returns the number of data bytes in a packet
1218 header mbuf. This is equivalent to the legacy MHLEN macro.
1219 @result The number of bytes of available data.
1220 */
1221extern u_int32_t mbuf_get_mhlen(void);
1222
1223/*!
1224 @function mbuf_get_minclsize
1225 @discussion This routine returns the minimum number of data bytes
1226 before an external cluster is used. This is equivalent to the
1227 legacy MINCLSIZE macro.
1228 @result The minimum number of bytes before a cluster will be used.
1229 */
1230extern u_int32_t mbuf_get_minclsize(void);
1231
1232/*!
1233 @function mbuf_clear_csum_performed
1234 @discussion Clears the hardware checksum flags and values.
1235 @param mbuf The mbuf containing the packet.
1236 @result 0 upon success otherwise the errno error.
1237 */
1238extern errno_t mbuf_clear_csum_performed(mbuf_t mbuf);
1239
1240/*!
1241 @function mbuf_inet_cksum
1242 @discussion Calculates 16-bit 1's complement Internet checksum of the
1243 transport segment with or without the pseudo header checksum
1244 of a given IPv4 packet. If the caller specifies a non-zero
1245 transport protocol, the checksum returned will also include
1246 the pseudo header checksum for the corresponding transport
1247 header. Otherwise, no header parsing will be done and the
1248 caller may use this to calculate the Internet checksum of
1249 an arbitrary span of data.
1250
1251 This routine does not modify the contents of the packet. If
1252 the caller specifies a non-zero protocol and/or offset, the
1253 routine expects the complete protocol header to be present
1254 at the beginning of the first mbuf.
1255 @param mbuf The mbuf (or chain of mbufs) containing the packet.
1256 @param protocol A zero or non-zero value. A non-zero value specifies
1257 the transport protocol used for pseudo header checksum.
1258 @param offset A zero or non-zero value; if the latter, it specifies
1259 the offset of the transport header from the beginning of mbuf.
1260 @param length The total (non-zero) length of the transport segment.
1261 @param csum Pointer to the checksum variable; upon success, this
1262 routine will return the calculated Internet checksum through
1263 this variable. The caller must set it to a non-NULL value.
1264 @result 0 upon success otherwise the errno error.
1265 */
1266extern errno_t mbuf_inet_cksum(mbuf_t mbuf, int protocol, u_int32_t offset,
1267 u_int32_t length, u_int16_t *csum);
1268
1269/*!
1270 @function mbuf_inet6_cksum
1271 @discussion Calculates 16-bit 1's complement Internet checksum of the
1272 transport segment with or without the pseudo header checksum
1273 of a given IPv6 packet. If the caller specifies a non-zero
1274 transport protocol, the checksum returned will also include
1275 the pseudo header checksum for the corresponding transport
1276 header. Otherwise, no header parsing will be done and the
1277 caller may use this to calculate the Internet checksum of
1278 an arbitrary span of data.
1279
1280 This routine does not modify the contents of the packet. If
1281 the caller specifies a non-zero protocol and/or offset, the
1282 routine expects the complete protocol header(s) to be present
1283 at the beginning of the first mbuf.
1284 @param mbuf The mbuf (or chain of mbufs) containing the packet.
1285 @param protocol A zero or non-zero value. A non-zero value specifies
1286 the transport protocol used for pseudo header checksum.
1287 @param offset A zero or non-zero value; if the latter, it specifies
1288 the offset of the transport header from the beginning of mbuf.
1289 @param length The total (non-zero) length of the transport segment.
1290 @param csum Pointer to the checksum variable; upon success, this
1291 routine will return the calculated Internet checksum through
1292 this variable. The caller must set it to a non-NULL value.
1293 @result 0 upon success otherwise the errno error.
1294 */
1295extern errno_t mbuf_inet6_cksum(mbuf_t mbuf, int protocol, u_int32_t offset,
1296 u_int32_t length, u_int16_t *csum);
1297
1298/* mbuf tags */
1299
1300/*!
1301 @function mbuf_tag_id_find
1302 @discussion Lookup the module id for a string. If there is no module
1303 id assigned to this string, a new module id will be assigned.
1304 The string should be the bundle id of the kext. In the case of a
1305 tag that will be shared across multiple kexts, a common bundle
1306 id style string should be used.
1307
1308 The lookup operation is not optimized. A module should call this
1309 function once during startup and chache the module id. The
1310 module id will not be resassigned until the machine reboots.
1311 @param module_string A unique string identifying your module.
1312 Example: com.apple.nke.SharedIP.
1313 @param module_id Upon return, a unique identifier for use with
1314 mbuf_tag_* functions. This identifier is valid until the machine
1315 is rebooted.
1316 @result 0 upon success otherwise the errno error.
1317 */
1318extern errno_t mbuf_tag_id_find(const char *module_string,
1319 mbuf_tag_id_t *module_id);
1320
1321/*!
1322 @function mbuf_tag_allocate
1323 @discussion Allocate an mbuf tag. Mbuf tags allow various portions
1324 of the stack to tag mbufs with data that will travel with the
1325 mbuf through the stack.
1326
1327 Tags may only be added to mbufs with packet headers
1328 (MBUF_PKTHDR flag is set). Mbuf tags are freed when the mbuf is
1329 freed or when mbuf_tag_free is called.
1330 @param mbuf The mbuf to attach this tag to.
1331 @param module_id A module identifier returned by mbuf_tag_id_find.
1332 @param type A 16 bit type value. For a given module_id, you can use
1333 a number of different tag types.
1334 @param length The length, in bytes, to allocate for storage that
1335 will be associated with this tag on this mbuf.
1336 @param how Indicate whether you want to block and wait for memory if
1337 memory is not immediately available.
1338 @param data_p Upon successful return, *data_p will point to the
1339 buffer allocated for the mtag.
1340 @result 0 upon success otherwise the errno error.
1341 */
1342extern errno_t mbuf_tag_allocate(mbuf_t mbuf, mbuf_tag_id_t module_id,
1343 mbuf_tag_type_t type, size_t length, mbuf_how_t how, void **data_p);
1344
1345/*!
1346 @function mbuf_tag_find
1347 @discussion Find the data associated with an mbuf tag.
1348 @param mbuf The mbuf the tag is attached to.
1349 @param module_id A module identifier returned by mbuf_tag_id_find.
1350 @param type The 16 bit type of the tag to find.
1351 @param length Upon success, the length of data will be store in
1352 *length.
1353 @param data_p Upon successful return, *data_p will point to the
1354 buffer allocated for the mtag.
1355 @result 0 upon success otherwise the errno error.
1356 */
1357extern errno_t mbuf_tag_find(mbuf_t mbuf, mbuf_tag_id_t module_id,
1358 mbuf_tag_type_t type, size_t *length, void **data_p);
1359
1360/*!
1361 @function mbuf_tag_free
1362 @discussion Frees a previously allocated mbuf tag.
1363 @param mbuf The mbuf the tag was allocated on.
1364 @param module_id The ID of the tag to free.
1365 @param type The type of the tag to free.
1366 */
1367extern void mbuf_tag_free(mbuf_t mbuf, mbuf_tag_id_t module_id,
1368 mbuf_tag_type_t type);
1369
1370#ifdef KERNEL_PRIVATE
1371/*!
1372 @function mbuf_add_drvaux
1373 @discussion Allocate space for driver auxiliary data and attach it
1374 to the packet (MBUF_PKTHDR is required.) This space is freed
1375 when the mbuf is freed or when mbuf_del_drvaux is called.
1376 Only one instance of driver auxiliary data may be attached to
1377 a packet. Any attempt to add it to a packet already associated
1378 with one will yield an error, and the existing one must first
1379 be removed via mbuf_del_drvaux. The format and length of the
1380 data depend largely on the family and sub-family. The system
1381 makes no attempt to define and/or interpret the contents of
1382 the data, and simply acts as a conduit between its producer
1383 and consumer.
1384 @param mbuf The mbuf to attach the auxiliary data to.
1385 @param how Indicate whether you are willing to block and wait for
1386 memory, if memory is not immediately available.
1387 @param family The interface family as defined in net/kpi_interface.h.
1388 @param subfamily The interface sub-family as defined in
1389 net/kpi_interface.h.
1390 @param length The length of the auxiliary data, must be greater than 0.
1391 @param data_p Upon successful return, *data_p will point to the
1392 space allocated for the data. Caller may set this to NULL.
1393 @result 0 upon success otherwise the errno error.
1394 */
1395extern errno_t mbuf_add_drvaux(mbuf_t mbuf, mbuf_how_t how,
1396 u_int32_t family, u_int32_t subfamily, size_t length, void **data_p);
1397
1398/*!
1399 @function mbuf_find_drvaux
1400 @discussion Find the driver auxiliary data associated with a packet.
1401 @param mbuf The mbuf the auxiliary data is attached to.
1402 @param family_p Upon successful return, *family_p will contain
1403 the interface family associated with the data, as defined
1404 in net/kpi_interface.h. Caller may set this to NULL.
1405 @param subfamily_p Upon successful return, *subfamily_p will contain
1406 the interface family associated with the data, as defined
1407 in net/kpi_interface.h. Caller may set this to NULL.
1408 @param length_p Upon successful return, *length_p will contain
1409 the length of the driver auxiliary data. Caller may
1410 set this to NULL.
1411 @param data_p Upon successful return, *data_p will point to the
1412 space allocated for the data.
1413 @result 0 upon success otherwise the errno error.
1414 */
1415extern errno_t mbuf_find_drvaux(mbuf_t mbuf, u_int32_t *family_p,
1416 u_int32_t *subfamily_p, u_int32_t *length_p, void **data_p);
1417
1418/*!
1419 @function mbuf_del_drvaux
1420 @discussion Remove and free any driver auxility data associated
1421 with the packet.
1422 @param mbuf The mbuf the auxiliary data is attached to.
1423 */
1424extern void mbuf_del_drvaux(mbuf_t mbuf);
1425#endif /* KERNEL_PRIVATE */
1426
1427/* mbuf stats */
1428
1429/*!
1430 @function mbuf_stats
1431 @discussion Get the mbuf statistics.
1432 @param stats Storage to copy the stats in to.
1433 */
1434extern void mbuf_stats(struct mbuf_stat *stats);
1435
1436
1437/*!
1438 @enum mbuf_traffic_class_t
1439 @abstract Traffic class of a packet
1440 @discussion Property that represent the category of traffic of a packet.
1441 This information may be used by the driver and at the link level.
1442 @constant MBUF_TC_BE Best effort, normal class.
1443 @constant MBUF_TC_BK Background, low priority or bulk traffic.
1444 @constant MBUF_TC_VI Interactive video, constant bit rate, low latency.
1445 @constant MBUF_TC_VO Interactive voice, constant bit rate, lowest latency.
1446*/
1447typedef enum {
1448#ifdef XNU_KERNEL_PRIVATE
1449 MBUF_TC_UNSPEC = -1, /* Internal: not specified */
1450#endif
1451 MBUF_TC_BE = 0,
1452 MBUF_TC_BK = 1,
1453 MBUF_TC_VI = 2,
1454 MBUF_TC_VO = 3
1455#ifdef XNU_KERNEL_PRIVATE
1456 ,
1457 MBUF_TC_MAX = 4 /* Internal: traffic class count */
1458#endif
1459} mbuf_traffic_class_t;
1460
1461/*!
1462 @function mbuf_get_traffic_class
1463 @discussion Get the traffic class of an mbuf packet
1464 @param mbuf The mbuf to get the traffic class of.
1465 @result The traffic class
1466*/
1467extern mbuf_traffic_class_t mbuf_get_traffic_class(mbuf_t mbuf);
1468
1469/*!
1470 @function mbuf_set_traffic_class
1471 @discussion Set the traffic class of an mbuf packet.
1472 @param mbuf The mbuf to set the traffic class on.
1473 @param tc The traffic class
1474 @result 0 on success, EINVAL if bad parameter is passed
1475*/
1476extern errno_t mbuf_set_traffic_class(mbuf_t mbuf, mbuf_traffic_class_t tc);
1477
1478/*!
1479 @function mbuf_is_traffic_class_privileged
1480 @discussion Returns the privileged status of the traffic class
1481 of the packet specified by the mbuf.
1482 @param mbuf The mbuf to retrieve the status from.
1483 @result Non-zero if privileged, 0 otherwise.
1484 */
1485extern int mbuf_is_traffic_class_privileged(mbuf_t mbuf);
1486
1487#ifdef KERNEL_PRIVATE
1488
1489/*!
1490 @function mbuf_get_traffic_class_max_count
1491 @discussion Returns the maximum number of mbuf traffic class types
1492 @result The total count of mbuf traffic classes
1493 */
1494extern u_int32_t mbuf_get_traffic_class_max_count(void);
1495
1496/*!
1497 @function mbuf_get_traffic_class_index
1498 @discussion Returns the zero-based index of an mbuf traffic class value
1499 @param tc The traffic class
1500 @param index Pointer to the index value
1501 @result 0 on success, EINVAL if bad parameter is passed
1502 */
1503extern errno_t mbuf_get_traffic_class_index(mbuf_traffic_class_t tc,
1504 u_int32_t *index);
1505
1506/*!
1507 @enum mbuf_svc_class_t
1508 @abstract Service class of a packet
1509 @discussion Property that represents the category of service
1510 of a packet. This information may be used by the driver
1511 and at the link level.
1512 @constant MBUF_SC_BK_SYS "Background System-Initiated", high delay
1513 tolerant, high loss tolerant, elastic flow, variable size &
1514 long-lived.
1515 @constant MBUF_SC_BK "Background", user-initiated, high delay tolerant,
1516 high loss tolerant, elastic flow, variable size. This level
1517 corresponds to WMM access class "BG", or MBUF_TC_BK.
1518 @constant MBUF_SC_BE "Best Effort", unclassified/standard. This is
1519 the default service class; pretty much a mix of everything.
1520 This level corresponds to WMM access class "BE" or MBUF_TC_BE.
1521 @constant MBUF_SC_RD
1522 "Responsive Data", a notch higher than "Best Effort", medium
1523 delay tolerant, medium loss tolerant, elastic flow, bursty,
1524 long-lived.
1525 @constant MBUF_SC_OAM "Operations, Administration, and Management",
1526 medium delay tolerant, low-medium loss tolerant, elastic &
1527 inelastic flows, variable size.
1528 @constant MBUF_SC_AV "Multimedia Audio/Video Streaming", medium delay
1529 tolerant, low-medium loss tolerant, elastic flow, constant
1530 packet interval, variable rate & size.
1531 @constant MBUF_SC_RV "Responsive Multimedia Audio/Video", low delay
1532 tolerant, low-medium loss tolerant, elastic flow, variable
1533 packet interval, rate and size.
1534 @constant MBUF_SC_VI "Interactive Video", low delay tolerant, low-
1535 medium loss tolerant, elastic flow, constant packet interval,
1536 variable rate & size. This level corresponds to WMM access
1537 class "VI" or MBUF_TC_VI.
1538 @constant MBUF_SC_SIG "Signaling", low delay tolerant, low loss
1539 tolerant, inelastic flow, jitter tolerant, rate is bursty but
1540 short, variable size. e.g. SIP. This level corresponds to WMM
1541 access class "VI" or MBUF_TC_VI.
1542 @constant MBUF_SC_VO "Interactive Voice", low delay tolerant, low loss
1543 tolerant, inelastic flow, constant packet rate, somewhat fixed
1544 size. This level corresponds to WMM access class "VO" or
1545 MBUF_TC_VO.
1546 @constant MBUF_SC_CTL "Network Control", low delay tolerant, low loss
1547 tolerant, inelastic flow, rate is short & burst, variable size.
1548*/
1549typedef enum {
1550#ifdef XNU_KERNEL_PRIVATE
1551 MBUF_SC_UNSPEC = -1, /* Internal: not specified */
1552#endif
1553 MBUF_SC_BK_SYS = 0x00080090, /* lowest class */
1554 MBUF_SC_BK = 0x00100080,
1555
1556 MBUF_SC_BE = 0x00000000,
1557 MBUF_SC_RD = 0x00180010,
1558 MBUF_SC_OAM = 0x00200020,
1559
1560 MBUF_SC_AV = 0x00280120,
1561 MBUF_SC_RV = 0x00300110,
1562 MBUF_SC_VI = 0x00380100,
1563 MBUF_SC_SIG = 0x00380130,
1564
1565 MBUF_SC_VO = 0x00400180,
1566 MBUF_SC_CTL = 0x00480190, /* highest class */
1567} mbuf_svc_class_t;
1568
1569/*!
1570 @function mbuf_get_service_class_max_count
1571 @discussion Returns the maximum number of mbuf service class types.
1572 @result The total count of mbuf service classes.
1573 */
1574extern u_int32_t mbuf_get_service_class_max_count(void);
1575
1576/*!
1577 @function mbuf_get_service_class_index
1578 @discussion Returns the zero-based index of an mbuf service class value
1579 @param sc The service class
1580 @param index Pointer to the index value
1581 @result 0 on success, EINVAL if bad parameter is passed
1582 */
1583extern errno_t mbuf_get_service_class_index(mbuf_svc_class_t sc,
1584 u_int32_t *index);
1585
1586/*!
1587 @function mbuf_get_service_class
1588 @discussion Get the service class of an mbuf packet
1589 @param mbuf The mbuf to get the service class of.
1590 @result The service class
1591*/
1592extern mbuf_svc_class_t mbuf_get_service_class(mbuf_t mbuf);
1593
1594/*!
1595 @function mbuf_set_servicec_class
1596 @discussion Set the service class of an mbuf packet.
1597 @param mbuf The mbuf to set the service class on.
1598 @param sc The service class
1599 @result 0 on success, EINVAL if bad parameter is passed
1600*/
1601extern errno_t mbuf_set_service_class(mbuf_t mbuf, mbuf_svc_class_t sc);
1602
1603/*!
1604 @function mbuf_is_service_class_privileged
1605 @discussion Returns the privileged status of the service class
1606 of the packet specified by the mbuf.
1607 @param mbuf The mbuf to retrieve the status from.
1608 @result Non-zero if privileged, 0 otherwise.
1609 */
1610extern int mbuf_is_service_class_privileged(mbuf_t mbuf);
1611
1612/*!
1613 @enum mbuf_pkthdr_aux_flags_t
1614 @abstract Constants defining mbuf auxiliary flags. Only the flags
1615 listed below can be retrieved.
1616 @constant MBUF_PKTAUXF_INET_RESOLVE_RTR Indicates this is an ARP
1617 request packet, whose target is the address of the default
1618 IPv4 router.
1619 @constant MBUF_PKTAUXF_INET6_RESOLVE_RTR Indicates this is an ICMPv6
1620 Neighbor Solicitation packet, whose target is the address of
1621 the default IPv6 router.
1622 */
1623enum {
1624 MBUF_PKTAUXF_INET_RESOLVE_RTR = 0x0004,
1625 MBUF_PKTAUXF_INET6_RESOLVE_RTR = 0x0008,
1626};
1627typedef u_int32_t mbuf_pkthdr_aux_flags_t;
1628
1629/*!
1630 @function mbuf_pkthdr_aux_flags
1631 @discussion Returns the auxiliary flags of a packet.
1632 @param mbuf The mbuf containing the packet header.
1633 @param paux_flags Pointer to mbuf_pkthdr_aux_flags_t variable.
1634 @result 0 upon success otherwise the errno error.
1635*/
1636extern errno_t mbuf_pkthdr_aux_flags(mbuf_t mbuf,
1637 mbuf_pkthdr_aux_flags_t *paux_flags);
1638
1639/*!
1640 @function mbuf_get_driver_scratch
1641 @discussion Returns a pointer to a driver specific area in the mbuf
1642 @param m The mbuf whose driver scratch space is to be returned
1643 @param area A pointer to a location to store the address of the
1644 driver scratch space. This value is guaranteed to be 32-bit
1645 aligned.
1646 @param area_ln A pointer to a location to store the total length of
1647 the memory location.
1648*/
1649extern errno_t mbuf_get_driver_scratch(mbuf_t m, u_int8_t **area,
1650 size_t *area_ln);
1651
1652/*!
1653 @function mbuf_get_unsent_data_bytes
1654 @discussion Returns the amount of data that is waiting to be sent
1655 on this interface. This is a private SPI used by cellular
1656 interface as an indication of future activity on that
1657 interface.
1658 @param m The mbuf containing the packet header
1659 @param unsent_data A pointer to an integer where the value of
1660 unsent data will be set.
1661 @result 0 upon success otherwise the errno error. If the mbuf
1662 packet header does not have valid data bytes, the error
1663 code will be EINVAL
1664 */
1665extern errno_t mbuf_get_unsent_data_bytes(const mbuf_t m,
1666 u_int32_t *unsent_data);
1667
1668typedef struct {
1669 int32_t buf_interface; /* data to send at interface */
1670 int32_t buf_sndbuf; /* data to send at socket buffer */
1671} mbuf_buffer_status_t;
1672
1673/*!
1674 @function mbuf_get_buffer_status
1675 @discussion Returns the amount of data that is waiting to be sent
1676 on this interface. This is a private SPI used by cellular
1677 interface as an indication of future activity on that
1678 interface.
1679 @param m The mbuf containing the packet header
1680 @param buf_status A pointer to the structure where the value of
1681 unsent data will be set.
1682 @result 0 upon success. If any of the arguments is NULL or if the
1683 mbuf packet header does not have valid data bytes,
1684 EINVAL will be returned
1685 */
1686extern errno_t mbuf_get_buffer_status(const mbuf_t m,
1687 mbuf_buffer_status_t *buf_status);
1688
1689/*!
1690 @function mbuf_pkt_new_flow
1691 @discussion This function is used to check if the packet is from a
1692 new flow that can be treated with higher priority. This is
1693 a private SPI.
1694 @param m The mbuf containing the packet header
1695 @param retval A pointer to an integer used as an out argument. The
1696 value is set to 1 if the packet is from a new flow,
1697 otherwise it is set to 0.
1698 @result 0 upon success otherwise the errno error. If any of the
1699 arguments is NULL or if the mbuf does not have valid packet
1700 header, the error code will be EINVAL
1701 */
1702extern errno_t mbuf_pkt_new_flow(const mbuf_t m, u_int32_t *retval);
1703
1704/*!
1705 @function mbuf_last_pkt
1706 @discussion This function is used to check if the packet is the
1707 last one sent on a TCP socket. This is an advisory
1708 for the underlying layers.
1709 @param m The mbuf containing the packet header
1710 @param retval A pointer to an integer whose value will be set to
1711 1 if the packet is the last packet, otherwise it will
1712 be set to 0.
1713 @result 0 upon success otherwise the errno error. If any of the
1714 arguments is NULL or if the mbuf does not have valid
1715 packet header, the error code will be EINVAL
1716 */
1717extern errno_t mbuf_last_pkt(const mbuf_t m, u_int32_t *retval);
1718
1719#endif /* KERNEL_PRIVATE */
1720
1721#ifdef XNU_KERNEL_PRIVATE
1722/*!
1723 @function mbuf_pkt_list_len
1724 @discussion Retrieves the length of the list of mbuf packets.
1725 @param mbuf The mbuf.
1726 @result The length of the mbuf packet list.
1727 */
1728extern size_t mbuf_pkt_list_len(const mbuf_t mbuf);
1729
1730/*!
1731 @function mbuf_pkt_list_maxlen
1732 @discussion Retrieves the maximum length of data that may be stored
1733 in the list of mbuf packet. This value assumes that the data pointer
1734 was set to the start of the possible range for that pointer
1735 for each mbuf in the packet chain
1736 @param mbuf The mbuf.
1737 @result The maximum length of data for this mbuf.
1738 */
1739extern size_t mbuf_pkt_list_maxlen(const mbuf_t mbuf);
1740#endif /* XNU_KERNEL_PRIVATE */
1741
1742#ifdef KERNEL_PRIVATE
1743/*!
1744 @function mbuf_get_timestamp
1745 @discussion Retrieves the timestamp of the packet.
1746 @param mbuf The mbuf representing the packet.
1747 @param ts A pointer where the value of the timestamp will be copied
1748 to.
1749 @param valid A pointer to a boolean value that indicate if the
1750 timestamp is valid (i.e. the packet timestamp has been set).
1751 If "false" the value of "ts" is undetermined.
1752 @result 0 upon success otherwise the errno error. If the mbuf
1753 packet header does not have valid data bytes, the error
1754 code will be EINVAL
1755 */
1756extern errno_t mbuf_get_timestamp(mbuf_t mbuf, u_int64_t *ts, boolean_t *valid);
1757
1758/*!
1759 @function mbuf_set_timestamp
1760 @discussion Set the timestamp of the packet.
1761 @param mbuf The mbuf representing the packet.
1762 @param ts The value of the timestamp to be stored in the mbuf packet
1763 header
1764 @param valid A boolean value that indicate if the timestamp is valid.
1765 Passing false clears any previous timestamp value.
1766 @result 0 upon success otherwise the errno error. If the mbuf
1767 packet header does not have valid data bytes, the error
1768 code will be EINVAL
1769 */
1770extern errno_t mbuf_set_timestamp(mbuf_t mbuf, u_int64_t ts, boolean_t valid);
1771
1772/*!
1773 @typedef mbuf_tx_compl_func
1774 @discussion This callback is used to indicate when a driver has
1775 transmitted a packet.
1776 @param pktid The packet indentifier that was returned by
1777 mbuf_set_timestamp_requested()
1778 @param ifp The outgoing interface or NULL if the packet was dropped
1779 before reaching the driver
1780 @param ts The timestamp in nanoseconds when the packet was transmitted
1781 @param tx_compl_arg An argument set by the driver
1782 @param tx_compl_data Additional data set by the driver
1783 @param tx_compl_val The transmission status is expected to be an
1784 IOReturn value -- see <IOKit/IOReturn.h>
1785*/
1786
1787typedef void (*mbuf_tx_compl_func)(uintptr_t pktid, ifnet_t ifp, u_int64_t ts,
1788 uintptr_t tx_compl_arg, uintptr_t tx_compl_data, kern_return_t tx_compl_val);
1789
1790/*!
1791 @function mbuf_register_tx_compl_callback
1792 @discussion Register a transmit completion callback function. The
1793 callback function must be unregistered before the calling
1794 module unloads.
1795 @param callback The completion callback function to register
1796 @result 0 upon success otherwise the errno error. ENOSPC is returned
1797 if too many callbacks are registered. EINVAL is returned when
1798 the function pointer is invalid. EEXIST is returned when
1799 the function pointer is already registered.
1800 */
1801extern errno_t mbuf_register_tx_compl_callback(
1802 mbuf_tx_compl_func callback);
1803
1804/*!
1805 @function mbuf_unregister_tx_compl_callback
1806 @discussion Unregister a transmit completion callback function. The
1807 callback function must be unregistered before the calling
1808 module unloads.
1809 @param callback The completion callback function to unregister
1810 @result 0 upon success otherwise the errno error. EINVAL is returned
1811 when the function pointer is invalid. ENOENT is returned when
1812 the function pointer is not registered.
1813 */
1814extern errno_t mbuf_unregister_tx_compl_callback(
1815 mbuf_tx_compl_func callback);
1816
1817/*!
1818 @function mbuf_get_timestamp_requested
1819 @discussion Tell if the packet timestamp needs to be set. This is meant
1820 to be used by a driver on egress packets.
1821 @param mbuf The mbuf representing the packet.
1822 @param requested A pointer to a boolean value that indicate if the
1823 timestamp was requested to be set.
1824 @result 0 upon success otherwise the errno error. If the mbuf
1825 packet header does not have valid data bytes, the error
1826 code will be EINVAL
1827 */
1828extern errno_t mbuf_get_timestamp_requested(mbuf_t mbuf, boolean_t *requested);
1829
1830/*!
1831 @function mbuf_set_timestamp_requested
1832 @discussion Indicate the callback is expected to be called with the
1833 transmission complete timestamp. This is meant to be used
1834 on egress packet by the driver.
1835 @param mbuf The mbuf representing the packet.
1836 @param callback A previously registered completion callback function.
1837 @param pktid An output parameter with an opaque value that can be used
1838 to identify the packet.
1839 @result 0 upon success otherwise the errno error. EINVAL is retuned
1840 if the mbuf is not a valid packet or if one of the parameter
1841 is NULL. ENOENT if the callback is not registred.
1842 */
1843extern errno_t mbuf_set_timestamp_requested(mbuf_t mbuf,
1844 uintptr_t *pktid, mbuf_tx_compl_func callback);
1845
1846/*!
1847 @function mbuf_get_status
1848 @discussion Retrieves the packet completion status.
1849 @param mbuf The mbuf representing the packet.
1850 @param status A pointer where the value of the completion status will
1851 be copied to.
1852 @result 0 upon success otherwise the errno error. If the mbuf
1853 packet header does not have valid data bytes, the error
1854 code will be EINVAL
1855 */
1856extern errno_t mbuf_get_status(mbuf_t mbuf, kern_return_t *status);
1857
1858/*!
1859 @function mbuf_set_status
1860 @discussion Store the packet completion status in the mbuf packet
1861 header.
1862 @param mbuf The mbuf representing the packet.
1863 @param status The value of the completion status.
1864 @result 0 upon success otherwise the errno error. If the mbuf
1865 packet header does not have valid data bytes, the error
1866 code will be EINVAL
1867 */
1868extern errno_t mbuf_set_status(mbuf_t mbuf, kern_return_t status);
1869
1870/*!
1871 @function mbuf_get_tx_compl_data
1872 @discussion Retrieves the packet completion status.
1873 @param m The mbuf representing the packet.
1874 @result 0 upon success otherwise the errno error. If the mbuf
1875 packet header does not have valid data bytes, the error
1876 code will be EINVAL
1877 */
1878extern errno_t mbuf_get_tx_compl_data(mbuf_t m, uintptr_t *arg,
1879 uintptr_t *data);
1880
1881/*!
1882 @function mbuf_set_tx_compl_data
1883 @discussion Retrieves the packet completion status.
1884 @param m The mbuf representing the packet.
1885 @result 0 upon success otherwise the errno error. If the mbuf
1886 packet header does not have valid data bytes, the error
1887 code will be EINVAL
1888 */
1889extern errno_t mbuf_set_tx_compl_data(mbuf_t m, uintptr_t arg,
1890 uintptr_t data);
1891
1892/*!
1893 @function mbuf_get_flowid
1894 @discussion Retrieve the flow ID of the packet .
1895 @param mbuf The mbuf representing the packet.
1896 @param flowid The flow ID of the packet.
1897 @result 0 upon success otherwise the errno error. If the mbuf
1898 packet header does not have valid data bytes, the error
1899 code will be EINVAL
1900 */
1901extern errno_t mbuf_get_flowid(mbuf_t mbuf, u_int16_t *flowid);
1902
1903/*!
1904 @function mbuf_set_flowid
1905 @discussion Set the flow ID of the packet .
1906 @param mbuf The mbuf representing the packet.
1907 @param flowid The flow ID to be set.
1908 @result 0 upon success otherwise the errno error. If the mbuf
1909 packet header does not have valid data bytes, the error
1910 code will be EINVAL
1911 */
1912extern errno_t mbuf_set_flowid(mbuf_t mbuf, u_int16_t flowid);
1913
1914
1915#endif /* KERNEL_PRIVATE */
1916
1917/* IF_QUEUE interaction */
1918
1919#define IF_ENQUEUE_MBUF(ifq, m) { \
1920 mbuf_setnextpkt((m), 0); \
1921 if ((ifq)->ifq_tail == 0) \
1922 (ifq)->ifq_head = (m); \
1923 else \
1924 mbuf_setnextpkt((mbuf_t)(ifq)->ifq_tail, (m)); \
1925 (ifq)->ifq_tail = (m); \
1926 (ifq)->ifq_len++; \
1927}
1928
1929#define IF_PREPEND_MBUF(ifq, m) { \
1930 mbuf_setnextpkt((m), (ifq)->ifq_head); \
1931 if ((ifq)->ifq_tail == 0) \
1932 (ifq)->ifq_tail = (m); \
1933 (ifq)->ifq_head = (m); \
1934 (ifq)->ifq_len++; \
1935}
1936
1937#define IF_DEQUEUE_MBUF(ifq, m) { \
1938 (m) = (ifq)->ifq_head; \
1939 if (m) { \
1940 if (((ifq)->ifq_head = mbuf_nextpkt((m))) == 0) \
1941 (ifq)->ifq_tail = 0; \
1942 mbuf_setnextpkt((m), 0); \
1943 (ifq)->ifq_len--; \
1944 } \
1945}
1946
1947__END_DECLS
1948#endif /* __KPI_MBUF__ */
1949