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