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