xref: /freebsd/share/man/man9/mbuf.9 (revision 2f513db72b034fd5ef7f080b11be5c711c15186a)
1.\" Copyright (c) 2000 FreeBSD Inc.
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd June 28, 2019
28.Dt MBUF 9
29.Os
30.\"
31.Sh NAME
32.Nm mbuf
33.Nd "memory management in the kernel IPC subsystem"
34.\"
35.Sh SYNOPSIS
36.In sys/param.h
37.In sys/systm.h
38.In sys/mbuf.h
39.\"
40.Ss Mbuf allocation macros
41.Fn MGET "struct mbuf *mbuf" "int how" "short type"
42.Fn MGETHDR "struct mbuf *mbuf" "int how" "short type"
43.Ft int
44.Fn MCLGET "struct mbuf *mbuf" "int how"
45.Fo MEXTADD
46.Fa "struct mbuf *mbuf"
47.Fa "char *buf"
48.Fa "u_int size"
49.Fa "void (*free)(struct mbuf *)"
50.Fa "void *opt_arg1"
51.Fa "void *opt_arg2"
52.Fa "int flags"
53.Fa "int type"
54.Fc
55.\"
56.Ss Mbuf utility macros
57.Fn mtod "struct mbuf *mbuf" "type"
58.Fn M_ALIGN "struct mbuf *mbuf" "u_int len"
59.Fn MH_ALIGN "struct mbuf *mbuf" "u_int len"
60.Ft int
61.Fn M_LEADINGSPACE "struct mbuf *mbuf"
62.Ft int
63.Fn M_TRAILINGSPACE "struct mbuf *mbuf"
64.Fn M_MOVE_PKTHDR "struct mbuf *to" "struct mbuf *from"
65.Fn M_PREPEND "struct mbuf *mbuf" "int len" "int how"
66.Fn MCHTYPE "struct mbuf *mbuf" "short type"
67.Ft int
68.Fn M_WRITABLE "struct mbuf *mbuf"
69.\"
70.Ss Mbuf allocation functions
71.Ft struct mbuf *
72.Fn m_get "int how" "short type"
73.Ft struct mbuf *
74.Fn m_get2 "int size" "int how" "short type" "int flags"
75.Ft struct mbuf *
76.Fn m_getm "struct mbuf *orig" "int len" "int how" "short type"
77.Ft struct mbuf *
78.Fn m_getjcl "int how" "short type" "int flags" "int size"
79.Ft struct mbuf *
80.Fn m_getcl "int how" "short type" "int flags"
81.Ft struct mbuf *
82.Fn m_gethdr "int how" "short type"
83.Ft struct mbuf *
84.Fn m_free "struct mbuf *mbuf"
85.Ft void
86.Fn m_freem "struct mbuf *mbuf"
87.\"
88.Ss Mbuf utility functions
89.Ft void
90.Fn m_adj "struct mbuf *mbuf" "int len"
91.Ft void
92.Fn m_align "struct mbuf *mbuf" "int len"
93.Ft int
94.Fn m_append "struct mbuf *mbuf" "int len" "c_caddr_t cp"
95.Ft struct mbuf *
96.Fn m_prepend "struct mbuf *mbuf" "int len" "int how"
97.Ft struct mbuf *
98.Fn m_copyup "struct mbuf *mbuf" "int len" "int dstoff"
99.Ft struct mbuf *
100.Fn m_pullup "struct mbuf *mbuf" "int len"
101.Ft struct mbuf *
102.Fn m_pulldown "struct mbuf *mbuf" "int offset" "int len" "int *offsetp"
103.Ft struct mbuf *
104.Fn m_copym "struct mbuf *mbuf" "int offset" "int len" "int how"
105.Ft struct mbuf *
106.Fn m_copypacket "struct mbuf *mbuf" "int how"
107.Ft struct mbuf *
108.Fn m_dup "const struct mbuf *mbuf" "int how"
109.Ft void
110.Fn m_copydata "const struct mbuf *mbuf" "int offset" "int len" "caddr_t buf"
111.Ft void
112.Fn m_copyback "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf"
113.Ft struct mbuf *
114.Fo m_devget
115.Fa "char *buf"
116.Fa "int len"
117.Fa "int offset"
118.Fa "struct ifnet *ifp"
119.Fa "void (*copy)(char *from, caddr_t to, u_int len)"
120.Fc
121.Ft void
122.Fn m_cat "struct mbuf *m" "struct mbuf *n"
123.Ft void
124.Fn m_catpkt "struct mbuf *m" "struct mbuf *n"
125.Ft u_int
126.Fn m_fixhdr "struct mbuf *mbuf"
127.Ft int
128.Fn m_dup_pkthdr "struct mbuf *to" "const struct mbuf *from" "int how"
129.Ft void
130.Fn m_move_pkthdr "struct mbuf *to" "struct mbuf *from"
131.Ft u_int
132.Fn m_length "struct mbuf *mbuf" "struct mbuf **last"
133.Ft struct mbuf *
134.Fn m_split "struct mbuf *mbuf" "int len" "int how"
135.Ft int
136.Fn m_apply "struct mbuf *mbuf" "int off" "int len" "int (*f)(void *arg, void *data, u_int len)" "void *arg"
137.Ft struct mbuf *
138.Fn m_getptr "struct mbuf *mbuf" "int loc" "int *off"
139.Ft struct mbuf *
140.Fn m_defrag "struct mbuf *m0" "int how"
141.Ft struct mbuf *
142.Fn m_collapse "struct mbuf *m0" "int how" "int maxfrags"
143.Ft struct mbuf *
144.Fn m_unshare "struct mbuf *m0" "int how"
145.\"
146.Sh DESCRIPTION
147An
148.Vt mbuf
149is a basic unit of memory management in the kernel IPC subsystem.
150Network packets and socket buffers are stored in
151.Vt mbufs .
152A network packet may span multiple
153.Vt mbufs
154arranged into a
155.Vt mbuf chain
156(linked list),
157which allows adding or trimming
158network headers with little overhead.
159.Pp
160While a developer should not bother with
161.Vt mbuf
162internals without serious
163reason in order to avoid incompatibilities with future changes, it
164is useful to understand the general structure of an
165.Vt mbuf .
166.Pp
167An
168.Vt mbuf
169consists of a variable-sized header and a small internal
170buffer for data.
171The total size of an
172.Vt mbuf ,
173.Dv MSIZE ,
174is a constant defined in
175.In sys/param.h .
176The
177.Vt mbuf
178header includes:
179.Bl -tag -width "m_nextpkt" -offset indent
180.It Va m_next
181.Pq Vt struct mbuf *
182A pointer to the next
183.Vt mbuf
184in the
185.Vt mbuf chain .
186.It Va m_nextpkt
187.Pq Vt struct mbuf *
188A pointer to the next
189.Vt mbuf chain
190in the queue.
191.It Va m_data
192.Pq Vt caddr_t
193A pointer to data attached to this
194.Vt mbuf .
195.It Va m_len
196.Pq Vt int
197The length of the data.
198.It Va m_type
199.Pq Vt short
200The type of the data.
201.It Va m_flags
202.Pq Vt int
203The
204.Vt mbuf
205flags.
206.El
207.Pp
208The
209.Vt mbuf
210flag bits are defined as follows:
211.Bd -literal
212#define	M_EXT		0x00000001 /* has associated external storage */
213#define	M_PKTHDR	0x00000002 /* start of record */
214#define	M_EOR		0x00000004 /* end of record */
215#define	M_RDONLY	0x00000008 /* associated data marked read-only */
216#define	M_NOMAP		0x00000100 /* mbuf data is unmapped */
217#define	M_NOFREE	0x00000200 /* do not free mbuf, embedded in cluster */
218#define	M_BCAST		0x00000010 /* send/received as link-level broadcast */
219#define	M_MCAST		0x00000020 /* send/received as link-level multicast */
220#define	M_PROMISC	0x00000040 /* packet was not for us */
221#define	M_VLANTAG	0x00000080 /* ether_vtag is valid */
222#define	M_TSTMP		0x00000400 /* rcv_tstmp field is valid */
223#define	M_TSTMP_HPREC	0x00000800 /* rcv_tstmp is high-prec, typically
224				      hw-stamped on port (useful for IEEE 1588
225				      and 802.1AS) */
226
227#define	M_PROTO1	0x00001000 /* protocol-specific */
228#define	M_PROTO2	0x00002000 /* protocol-specific */
229#define	M_PROTO3	0x00004000 /* protocol-specific */
230#define	M_PROTO4	0x00008000 /* protocol-specific */
231#define	M_PROTO5	0x00010000 /* protocol-specific */
232#define	M_PROTO6	0x00020000 /* protocol-specific */
233#define	M_PROTO7	0x00040000 /* protocol-specific */
234#define	M_PROTO8	0x00080000 /* protocol-specific */
235#define	M_PROTO9	0x00100000 /* protocol-specific */
236#define	M_PROTO10	0x00200000 /* protocol-specific */
237#define	M_PROTO11	0x00400000 /* protocol-specific */
238#define	M_PROTO12	0x00800000 /* protocol-specific */
239.Ed
240.Pp
241The available
242.Vt mbuf
243types are defined as follows:
244.Bd -literal
245#define	MT_DATA		1	/* dynamic (data) allocation */
246#define	MT_HEADER	MT_DATA	/* packet header */
247
248#define	MT_VENDOR1	4	/* for vendor-internal use */
249#define	MT_VENDOR2	5	/* for vendor-internal use */
250#define	MT_VENDOR3	6	/* for vendor-internal use */
251#define	MT_VENDOR4	7	/* for vendor-internal use */
252
253#define	MT_SONAME	8	/* socket name */
254
255#define	MT_EXP1		9	/* for experimental use */
256#define	MT_EXP2		10	/* for experimental use */
257#define	MT_EXP3		11	/* for experimental use */
258#define	MT_EXP4		12	/* for experimental use */
259
260#define	MT_CONTROL	14	/* extra-data protocol message */
261#define	MT_EXTCONTROL	15	/* control message with externalized contents */
262#define	MT_OOBDATA	16	/* expedited data  */
263.Ed
264.Pp
265The available external buffer types are defined as follows:
266.Bd -literal
267#define	EXT_CLUSTER	1	/* mbuf cluster */
268#define	EXT_SFBUF	2	/* sendfile(2)'s sf_bufs */
269#define	EXT_JUMBOP	3	/* jumbo cluster 4096 bytes */
270#define	EXT_JUMBO9	4	/* jumbo cluster 9216 bytes */
271#define	EXT_JUMBO16	5	/* jumbo cluster 16184 bytes */
272#define	EXT_PACKET	6	/* mbuf+cluster from packet zone */
273#define	EXT_MBUF	7	/* external mbuf reference */
274#define	EXT_RXRING	8	/* data in NIC receive ring */
275#define	EXT_PGS		9	/* array of unmapped pages */
276
277#define	EXT_VENDOR1	224	/* for vendor-internal use */
278#define	EXT_VENDOR2	225	/* for vendor-internal use */
279#define	EXT_VENDOR3	226	/* for vendor-internal use */
280#define	EXT_VENDOR4	227	/* for vendor-internal use */
281
282#define	EXT_EXP1	244	/* for experimental use */
283#define	EXT_EXP2	245	/* for experimental use */
284#define	EXT_EXP3	246	/* for experimental use */
285#define	EXT_EXP4	247	/* for experimental use */
286
287#define	EXT_NET_DRV	252	/* custom ext_buf provided by net driver(s) */
288#define	EXT_MOD_TYPE	253	/* custom module's ext_buf type */
289#define	EXT_DISPOSABLE	254	/* can throw this buffer away w/page flipping */
290#define	EXT_EXTREF	255	/* has externally maintained ref_cnt ptr */
291.Ed
292.Pp
293If the
294.Dv M_PKTHDR
295flag is set, a
296.Vt struct pkthdr Va m_pkthdr
297is added to the
298.Vt mbuf
299header.
300It contains a pointer to the interface
301the packet has been received from
302.Pq Vt struct ifnet Va *rcvif ,
303and the total packet length
304.Pq Vt int Va len .
305Optionally, it may also contain an attached list of packet tags
306.Pq Vt "struct m_tag" .
307See
308.Xr mbuf_tags 9
309for details.
310Fields used in offloading checksum calculation to the hardware are kept in
311.Va m_pkthdr
312as well.
313See
314.Sx HARDWARE-ASSISTED CHECKSUM CALCULATION
315for details.
316.Pp
317If small enough, data is stored in the internal data buffer of an
318.Vt mbuf .
319If the data is sufficiently large, another
320.Vt mbuf
321may be added to the
322.Vt mbuf chain ,
323or external storage may be associated with the
324.Vt mbuf .
325.Dv MHLEN
326bytes of data can fit into an
327.Vt mbuf
328with the
329.Dv M_PKTHDR
330flag set,
331.Dv MLEN
332bytes can otherwise.
333.Pp
334If external storage is being associated with an
335.Vt mbuf ,
336the
337.Va m_ext
338header is added at the cost of losing the internal data buffer.
339It includes a pointer to external storage, the size of the storage,
340a pointer to a function used for freeing the storage,
341a pointer to an optional argument that can be passed to the function,
342and a pointer to a reference counter.
343An
344.Vt mbuf
345using external storage has the
346.Dv M_EXT
347flag set.
348.Pp
349The system supplies a macro for allocating the desired external storage
350buffer,
351.Dv MEXTADD .
352.Pp
353The allocation and management of the reference counter is handled by the
354subsystem.
355.Pp
356The system also supplies a default type of external storage buffer called an
357.Vt mbuf cluster .
358.Vt Mbuf clusters
359can be allocated and configured with the use of the
360.Dv MCLGET
361macro.
362Each
363.Vt mbuf cluster
364is
365.Dv MCLBYTES
366in size, where MCLBYTES is a machine-dependent constant.
367The system defines an advisory macro
368.Dv MINCLSIZE ,
369which is the smallest amount of data to put into an
370.Vt mbuf cluster .
371It is equal to
372.Dv MHLEN
373plus one.
374It is typically preferable to store data into the data region of an
375.Vt mbuf ,
376if size permits, as opposed to allocating a separate
377.Vt mbuf cluster
378to hold the same data.
379.\"
380.Ss Macros and Functions
381There are numerous predefined macros and functions that provide the
382developer with common utilities.
383.\"
384.Bl -ohang -offset indent
385.It Fn mtod mbuf type
386Convert an
387.Fa mbuf
388pointer to a data pointer.
389The macro expands to the data pointer cast to the specified
390.Fa type .
391.Sy Note :
392It is advisable to ensure that there is enough contiguous data in
393.Fa mbuf .
394See
395.Fn m_pullup
396for details.
397.It Fn MGET mbuf how type
398Allocate an
399.Vt mbuf
400and initialize it to contain internal data.
401.Fa mbuf
402will point to the allocated
403.Vt mbuf
404on success, or be set to
405.Dv NULL
406on failure.
407The
408.Fa how
409argument is to be set to
410.Dv M_WAITOK
411or
412.Dv M_NOWAIT .
413It specifies whether the caller is willing to block if necessary.
414A number of other functions and macros related to
415.Vt mbufs
416have the same argument because they may
417at some point need to allocate new
418.Vt mbufs .
419.It Fn MGETHDR mbuf how type
420Allocate an
421.Vt mbuf
422and initialize it to contain a packet header
423and internal data.
424See
425.Fn MGET
426for details.
427.It Fn MEXTADD mbuf buf size free opt_arg1 opt_arg2 flags type
428Associate externally managed data with
429.Fa mbuf .
430Any internal data contained in the mbuf will be discarded, and the
431.Dv M_EXT
432flag will be set.
433The
434.Fa buf
435and
436.Fa size
437arguments are the address and length, respectively, of the data.
438The
439.Fa free
440argument points to a function which will be called to free the data
441when the mbuf is freed; it is only used if
442.Fa type
443is
444.Dv EXT_EXTREF .
445The
446.Fa opt_arg1
447and
448.Fa opt_arg2
449arguments will be saved in
450.Va ext_arg1
451and
452.Va ext_arg2
453fields of the
454.Va struct m_ext
455of the mbuf.
456The
457.Fa flags
458argument specifies additional
459.Vt mbuf
460flags; it is not necessary to specify
461.Dv M_EXT .
462Finally, the
463.Fa type
464argument specifies the type of external data, which controls how it
465will be disposed of when the
466.Vt mbuf
467is freed.
468In most cases, the correct value is
469.Dv EXT_EXTREF .
470.It Fn MCLGET mbuf how
471Allocate and attach an
472.Vt mbuf cluster
473to
474.Fa mbuf .
475On success, a non-zero value returned; otherwise, 0.
476Historically, consumers would check for success by testing the
477.Dv M_EXT
478flag on the mbuf, but this is now discouraged to avoid unnecessary awareness
479of the implementation of external storage in protocol stacks and device
480drivers.
481.It Fn M_ALIGN mbuf len
482Set the pointer
483.Fa mbuf->m_data
484to place an object of the size
485.Fa len
486at the end of the internal data area of
487.Fa mbuf ,
488long word aligned.
489Applicable only if
490.Fa mbuf
491is newly allocated with
492.Fn MGET
493or
494.Fn m_get .
495.It Fn MH_ALIGN mbuf len
496Serves the same purpose as
497.Fn M_ALIGN
498does, but only for
499.Fa mbuf
500newly allocated with
501.Fn MGETHDR
502or
503.Fn m_gethdr ,
504or initialized by
505.Fn m_dup_pkthdr
506or
507.Fn m_move_pkthdr .
508.It Fn m_align mbuf len
509Services the same purpose as
510.Fn M_ALIGN
511but handles any type of mbuf.
512.It Fn M_LEADINGSPACE mbuf
513Returns the number of bytes available before the beginning
514of data in
515.Fa mbuf .
516.It Fn M_TRAILINGSPACE mbuf
517Returns the number of bytes available after the end of data in
518.Fa mbuf .
519.It Fn M_PREPEND mbuf len how
520This macro operates on an
521.Vt mbuf chain .
522It is an optimized wrapper for
523.Fn m_prepend
524that can make use of possible empty space before data
525(e.g.\& left after trimming of a link-layer header).
526The new
527.Vt mbuf chain
528pointer or
529.Dv NULL
530is in
531.Fa mbuf
532after the call.
533.It Fn M_MOVE_PKTHDR to from
534Using this macro is equivalent to calling
535.Fn m_move_pkthdr to from .
536.It Fn M_WRITABLE mbuf
537This macro will evaluate true if
538.Fa mbuf
539is not marked
540.Dv M_RDONLY
541and if either
542.Fa mbuf
543does not contain external storage or,
544if it does,
545then if the reference count of the storage is not greater than 1.
546The
547.Dv M_RDONLY
548flag can be set in
549.Fa mbuf->m_flags .
550This can be achieved during setup of the external storage,
551by passing the
552.Dv M_RDONLY
553bit as a
554.Fa flags
555argument to the
556.Fn MEXTADD
557macro, or can be directly set in individual
558.Vt mbufs .
559.It Fn MCHTYPE mbuf type
560Change the type of
561.Fa mbuf
562to
563.Fa type .
564This is a relatively expensive operation and should be avoided.
565.El
566.Pp
567The functions are:
568.Bl -ohang -offset indent
569.It Fn m_get how type
570A function version of
571.Fn MGET
572for non-critical paths.
573.It Fn m_get2 size how type flags
574Allocate an
575.Vt mbuf
576with enough space to hold specified amount of data.
577.It Fn m_getm orig len how type
578Allocate
579.Fa len
580bytes worth of
581.Vt mbufs
582and
583.Vt mbuf clusters
584if necessary and append the resulting allocated
585.Vt mbuf chain
586to the
587.Vt mbuf chain
588.Fa orig ,
589if it is
590.No non- Ns Dv NULL .
591If the allocation fails at any point,
592free whatever was allocated and return
593.Dv NULL .
594If
595.Fa orig
596is
597.No non- Ns Dv NULL ,
598it will not be freed.
599It is possible to use
600.Fn m_getm
601to either append
602.Fa len
603bytes to an existing
604.Vt mbuf
605or
606.Vt mbuf chain
607(for example, one which may be sitting in a pre-allocated ring)
608or to simply perform an all-or-nothing
609.Vt mbuf
610and
611.Vt mbuf cluster
612allocation.
613.It Fn m_gethdr how type
614A function version of
615.Fn MGETHDR
616for non-critical paths.
617.It Fn m_getcl how type flags
618Fetch an
619.Vt mbuf
620with a
621.Vt mbuf cluster
622attached to it.
623If one of the allocations fails, the entire allocation fails.
624This routine is the preferred way of fetching both the
625.Vt mbuf
626and
627.Vt mbuf cluster
628together, as it avoids having to unlock/relock between allocations.
629Returns
630.Dv NULL
631on failure.
632.It Fn m_getjcl how type flags size
633This is like
634.Fn m_getcl
635but it the size of the cluster allocated will be large enough for
636.Fa size
637bytes.
638.It Fn m_free mbuf
639Frees
640.Vt mbuf .
641Returns
642.Va m_next
643of the freed
644.Vt mbuf .
645.El
646.Pp
647The functions below operate on
648.Vt mbuf chains .
649.Bl -ohang -offset indent
650.It Fn m_freem mbuf
651Free an entire
652.Vt mbuf chain ,
653including any external storage.
654.\"
655.It Fn m_adj mbuf len
656Trim
657.Fa len
658bytes from the head of an
659.Vt mbuf chain
660if
661.Fa len
662is positive, from the tail otherwise.
663.\"
664.It Fn m_append mbuf len cp
665Append
666.Vt len
667bytes of data
668.Vt cp
669to the
670.Vt mbuf chain .
671Extend the mbuf chain if the new data does not fit in
672existing space.
673.\"
674.It Fn m_prepend mbuf len how
675Allocate a new
676.Vt mbuf
677and prepend it to the
678.Vt mbuf chain ,
679handle
680.Dv M_PKTHDR
681properly.
682.Sy Note :
683It does not allocate any
684.Vt mbuf clusters ,
685so
686.Fa len
687must be less than
688.Dv MLEN
689or
690.Dv MHLEN ,
691depending on the
692.Dv M_PKTHDR
693flag setting.
694.\"
695.It Fn m_copyup mbuf len dstoff
696Similar to
697.Fn m_pullup
698but copies
699.Fa len
700bytes of data into a new mbuf at
701.Fa dstoff
702bytes into the mbuf.
703The
704.Fa dstoff
705argument aligns the data and leaves room for a link layer header.
706Returns the new
707.Vt mbuf chain
708on success,
709and frees the
710.Vt mbuf chain
711and returns
712.Dv NULL
713on failure.
714.Sy Note :
715The function does not allocate
716.Vt mbuf clusters ,
717so
718.Fa len + dstoff
719must be less than
720.Dv MHLEN .
721.\"
722.It Fn m_pullup mbuf len
723Arrange that the first
724.Fa len
725bytes of an
726.Vt mbuf chain
727are contiguous and lay in the data area of
728.Fa mbuf ,
729so they are accessible with
730.Fn mtod mbuf type .
731It is important to remember that this may involve
732reallocating some mbufs and moving data so all pointers
733referencing data within the old mbuf chain
734must be recalculated or made invalid.
735Return the new
736.Vt mbuf chain
737on success,
738.Dv NULL
739on failure
740(the
741.Vt mbuf chain
742is freed in this case).
743.Sy Note :
744It does not allocate any
745.Vt mbuf clusters ,
746so
747.Fa len
748must be less than or equal to
749.Dv MHLEN .
750.\"
751.It Fn m_pulldown mbuf offset len offsetp
752Arrange that
753.Fa len
754bytes between
755.Fa offset
756and
757.Fa offset + len
758in the
759.Vt mbuf chain
760are contiguous and lay in the data area of
761.Fa mbuf ,
762so they are accessible with
763.Fn mtod mbuf type .
764.Fa len
765must be smaller than, or equal to, the size of an
766.Vt mbuf cluster .
767Return a pointer to an intermediate
768.Vt mbuf
769in the chain containing the requested region;
770the offset in the data region of the
771.Vt mbuf chain
772to the data contained in the returned mbuf is stored in
773.Fa *offsetp .
774If
775.Fa offsetp
776is NULL, the region may be accessed using
777.Fn mtod mbuf type .
778If
779.Fa offsetp
780is non-NULL, the region may be accessed using
781.Fn mtod mbuf uint8_t
782+ *offsetp.
783The region of the mbuf chain between its beginning and
784.Fa offset
785is not modified, therefore it is safe to hold pointers to data within
786this region before calling
787.Fn m_pulldown .
788.\"
789.It Fn m_copym mbuf offset len how
790Make a copy of an
791.Vt mbuf chain
792starting
793.Fa offset
794bytes from the beginning, continuing for
795.Fa len
796bytes.
797If
798.Fa len
799is
800.Dv M_COPYALL ,
801copy to the end of the
802.Vt mbuf chain .
803.Sy Note :
804The copy is read-only, because the
805.Vt mbuf clusters
806are not copied, only their reference counts are incremented.
807.\"
808.It Fn m_copypacket mbuf how
809Copy an entire packet including header, which must be present.
810This is an optimized version of the common case
811.Fn m_copym mbuf 0 M_COPYALL how .
812.Sy Note :
813the copy is read-only, because the
814.Vt mbuf clusters
815are not copied, only their reference counts are incremented.
816.\"
817.It Fn m_dup mbuf how
818Copy a packet header
819.Vt mbuf chain
820into a completely new
821.Vt mbuf chain ,
822including copying any
823.Vt mbuf clusters .
824Use this instead of
825.Fn m_copypacket
826when you need a writable copy of an
827.Vt mbuf chain .
828.\"
829.It Fn m_copydata mbuf offset len buf
830Copy data from an
831.Vt mbuf chain
832starting
833.Fa off
834bytes from the beginning, continuing for
835.Fa len
836bytes, into the indicated buffer
837.Fa buf .
838.\"
839.It Fn m_copyback mbuf offset len buf
840Copy
841.Fa len
842bytes from the buffer
843.Fa buf
844back into the indicated
845.Vt mbuf chain ,
846starting at
847.Fa offset
848bytes from the beginning of the
849.Vt mbuf chain ,
850extending the
851.Vt mbuf chain
852if necessary.
853.Sy Note :
854It does not allocate any
855.Vt mbuf clusters ,
856just adds
857.Vt mbufs
858to the
859.Vt mbuf chain .
860It is safe to set
861.Fa offset
862beyond the current
863.Vt mbuf chain
864end: zeroed
865.Vt mbufs
866will be allocated to fill the space.
867.\"
868.It Fn m_length mbuf last
869Return the length of the
870.Vt mbuf chain ,
871and optionally a pointer to the last
872.Vt mbuf .
873.\"
874.It Fn m_dup_pkthdr to from how
875Upon the function's completion, the
876.Vt mbuf
877.Fa to
878will contain an identical copy of
879.Fa from->m_pkthdr
880and the per-packet attributes found in the
881.Vt mbuf chain
882.Fa from .
883The
884.Vt mbuf
885.Fa from
886must have the flag
887.Dv M_PKTHDR
888initially set, and
889.Fa to
890must be empty on entry.
891.\"
892.It Fn m_move_pkthdr to from
893Move
894.Va m_pkthdr
895and the per-packet attributes from the
896.Vt mbuf chain
897.Fa from
898to the
899.Vt mbuf
900.Fa to .
901The
902.Vt mbuf
903.Fa from
904must have the flag
905.Dv M_PKTHDR
906initially set, and
907.Fa to
908must be empty on entry.
909Upon the function's completion,
910.Fa from
911will have the flag
912.Dv M_PKTHDR
913and the per-packet attributes cleared.
914.\"
915.It Fn m_fixhdr mbuf
916Set the packet-header length to the length of the
917.Vt mbuf chain .
918.\"
919.It Fn m_devget buf len offset ifp copy
920Copy data from a device local memory pointed to by
921.Fa buf
922to an
923.Vt mbuf chain .
924The copy is done using a specified copy routine
925.Fa copy ,
926or
927.Fn bcopy
928if
929.Fa copy
930is
931.Dv NULL .
932.\"
933.It Fn m_cat m n
934Concatenate
935.Fa n
936to
937.Fa m .
938Both
939.Vt mbuf chains
940must be of the same type.
941.Fa n
942is not guaranteed to be valid after
943.Fn m_cat
944returns.
945.Fn m_cat
946does not update any packet header fields or free mbuf tags.
947.\"
948.It Fn m_catpkt m n
949A variant of
950.Fn m_cat
951that operates on packets.
952Both
953.Fa m
954and
955.Fa n
956must contain packet headers.
957.Fa n
958is not guaranteed to be valid after
959.Fn m_catpkt
960returns.
961.\"
962.It Fn m_split mbuf len how
963Partition an
964.Vt mbuf chain
965in two pieces, returning the tail:
966all but the first
967.Fa len
968bytes.
969In case of failure, it returns
970.Dv NULL
971and attempts to restore the
972.Vt mbuf chain
973to its original state.
974.\"
975.It Fn m_apply mbuf off len f arg
976Apply a function to an
977.Vt mbuf chain ,
978at offset
979.Fa off ,
980for length
981.Fa len
982bytes.
983Typically used to avoid calls to
984.Fn m_pullup
985which would otherwise be unnecessary or undesirable.
986.Fa arg
987is a convenience argument which is passed to the callback function
988.Fa f .
989.Pp
990Each time
991.Fn f
992is called, it will be passed
993.Fa arg ,
994a pointer to the
995.Fa data
996in the current mbuf, and the length
997.Fa len
998of the data in this mbuf to which the function should be applied.
999.Pp
1000The function should return zero to indicate success;
1001otherwise, if an error is indicated, then
1002.Fn m_apply
1003will return the error and stop iterating through the
1004.Vt mbuf chain .
1005.\"
1006.It Fn m_getptr mbuf loc off
1007Return a pointer to the mbuf containing the data located at
1008.Fa loc
1009bytes from the beginning of the
1010.Vt mbuf chain .
1011The corresponding offset into the mbuf will be stored in
1012.Fa *off .
1013.It Fn m_defrag m0 how
1014Defragment an mbuf chain, returning the shortest possible
1015chain of mbufs and clusters.
1016If allocation fails and this can not be completed,
1017.Dv NULL
1018will be returned and the original chain will be unchanged.
1019Upon success, the original chain will be freed and the new
1020chain will be returned.
1021.Fa how
1022should be either
1023.Dv M_WAITOK
1024or
1025.Dv M_NOWAIT ,
1026depending on the caller's preference.
1027.Pp
1028This function is especially useful in network drivers, where
1029certain long mbuf chains must be shortened before being added
1030to TX descriptor lists.
1031.It Fn m_collapse m0 how maxfrags
1032Defragment an mbuf chain, returning a chain of at most
1033.Fa maxfrags
1034mbufs and clusters.
1035If allocation fails or the chain cannot be collapsed as requested,
1036.Dv NULL
1037will be returned, with the original chain possibly modified.
1038As with
1039.Fn m_defrag ,
1040.Fa how
1041should be one of
1042.Dv M_WAITOK
1043or
1044.Dv M_NOWAIT .
1045.It Fn m_unshare m0 how
1046Create a version of the specified mbuf chain whose
1047contents can be safely modified without affecting other users.
1048If allocation fails and this operation can not be completed,
1049.Dv NULL
1050will be returned.
1051The original mbuf chain is always reclaimed and the reference
1052count of any shared mbuf clusters is decremented.
1053.Fa how
1054should be either
1055.Dv M_WAITOK
1056or
1057.Dv M_NOWAIT ,
1058depending on the caller's preference.
1059As a side-effect of this process the returned
1060mbuf chain may be compacted.
1061.Pp
1062This function is especially useful in the transmit path of
1063network code, when data must be encrypted or otherwise
1064altered prior to transmission.
1065.El
1066.Sh HARDWARE-ASSISTED CHECKSUM CALCULATION
1067This section currently applies to TCP/IP only.
1068In order to save the host CPU resources, computing checksums is
1069offloaded to the network interface hardware if possible.
1070The
1071.Va m_pkthdr
1072member of the leading
1073.Vt mbuf
1074of a packet contains two fields used for that purpose,
1075.Vt int Va csum_flags
1076and
1077.Vt int Va csum_data .
1078The meaning of those fields depends on the direction a packet flows in,
1079and on whether the packet is fragmented.
1080Henceforth,
1081.Va csum_flags
1082or
1083.Va csum_data
1084of a packet
1085will denote the corresponding field of the
1086.Va m_pkthdr
1087member of the leading
1088.Vt mbuf
1089in the
1090.Vt mbuf chain
1091containing the packet.
1092.Pp
1093On output, checksum offloading is attempted after the outgoing
1094interface has been determined for a packet.
1095The interface-specific field
1096.Va ifnet.if_data.ifi_hwassist
1097(see
1098.Xr ifnet 9 )
1099is consulted for the capabilities of the interface to assist in
1100computing checksums.
1101The
1102.Va csum_flags
1103field of the packet header is set to indicate which actions the interface
1104is supposed to perform on it.
1105The actions unsupported by the network interface are done in the
1106software prior to passing the packet down to the interface driver;
1107such actions will never be requested through
1108.Va csum_flags .
1109.Pp
1110The flags demanding a particular action from an interface are as follows:
1111.Bl -tag -width ".Dv CSUM_TCP" -offset indent
1112.It Dv CSUM_IP
1113The IP header checksum is to be computed and stored in the
1114corresponding field of the packet.
1115The hardware is expected to know the format of an IP header
1116to determine the offset of the IP checksum field.
1117.It Dv CSUM_TCP
1118The TCP checksum is to be computed.
1119(See below.)
1120.It Dv CSUM_UDP
1121The UDP checksum is to be computed.
1122(See below.)
1123.El
1124.Pp
1125Should a TCP or UDP checksum be offloaded to the hardware,
1126the field
1127.Va csum_data
1128will contain the byte offset of the checksum field relative to the
1129end of the IP header.
1130In this case, the checksum field will be initially
1131set by the TCP/IP module to the checksum of the pseudo header
1132defined by the TCP and UDP specifications.
1133.Pp
1134On input, an interface indicates the actions it has performed
1135on a packet by setting one or more of the following flags in
1136.Va csum_flags
1137associated with the packet:
1138.Bl -tag -width ".Dv CSUM_IP_CHECKED" -offset indent
1139.It Dv CSUM_IP_CHECKED
1140The IP header checksum has been computed.
1141.It Dv CSUM_IP_VALID
1142The IP header has a valid checksum.
1143This flag can appear only in combination with
1144.Dv CSUM_IP_CHECKED .
1145.It Dv CSUM_DATA_VALID
1146The checksum of the data portion of the IP packet has been computed
1147and stored in the field
1148.Va csum_data
1149in network byte order.
1150.It Dv CSUM_PSEUDO_HDR
1151Can be set only along with
1152.Dv CSUM_DATA_VALID
1153to indicate that the IP data checksum found in
1154.Va csum_data
1155allows for the pseudo header defined by the TCP and UDP specifications.
1156Otherwise the checksum of the pseudo header must be calculated by
1157the host CPU and added to
1158.Va csum_data
1159to obtain the final checksum to be used for TCP or UDP validation purposes.
1160.El
1161.Pp
1162If a particular network interface just indicates success or
1163failure of TCP or UDP checksum validation without returning
1164the exact value of the checksum to the host CPU, its driver can mark
1165.Dv CSUM_DATA_VALID
1166and
1167.Dv CSUM_PSEUDO_HDR
1168in
1169.Va csum_flags ,
1170and set
1171.Va csum_data
1172to
1173.Li 0xFFFF
1174hexadecimal to indicate a valid checksum.
1175It is a peculiarity of the algorithm used that the Internet checksum
1176calculated over any valid packet will be
1177.Li 0xFFFF
1178as long as the original checksum field is included.
1179.Sh STRESS TESTING
1180When running a kernel compiled with the option
1181.Dv MBUF_STRESS_TEST ,
1182the following
1183.Xr sysctl 8 Ns
1184-controlled options may be used to create
1185various failure/extreme cases for testing of network drivers
1186and other parts of the kernel that rely on
1187.Vt mbufs .
1188.Bl -tag -width ident
1189.It Va net.inet.ip.mbuf_frag_size
1190Causes
1191.Fn ip_output
1192to fragment outgoing
1193.Vt mbuf chains
1194into fragments of the specified size.
1195Setting this variable to 1 is an excellent way to
1196test the long
1197.Vt mbuf chain
1198handling ability of network drivers.
1199.It Va kern.ipc.m_defragrandomfailures
1200Causes the function
1201.Fn m_defrag
1202to randomly fail, returning
1203.Dv NULL .
1204Any piece of code which uses
1205.Fn m_defrag
1206should be tested with this feature.
1207.El
1208.Sh RETURN VALUES
1209See above.
1210.Sh SEE ALSO
1211.Xr ifnet 9 ,
1212.Xr mbuf_tags 9
1213.Sh HISTORY
1214.\" Please correct me if I'm wrong
1215.Vt Mbufs
1216appeared in an early version of
1217.Bx .
1218Besides being used for network packets, they were used
1219to store various dynamic structures, such as routing table
1220entries, interface addresses, protocol control blocks, etc.
1221In more recent
1222.Fx
1223use of
1224.Vt mbufs
1225is almost entirely limited to packet storage, with
1226.Xr uma 9
1227zones being used directly to store other network-related memory.
1228.Pp
1229Historically, the
1230.Vt mbuf
1231allocator has been a special-purpose memory allocator able to run in
1232interrupt contexts and allocating from a special kernel address space map.
1233As of
1234.Fx 5.3 ,
1235the
1236.Vt mbuf
1237allocator is a wrapper around
1238.Xr uma 9 ,
1239allowing caching of
1240.Vt mbufs ,
1241clusters, and
1242.Vt mbuf
1243+ cluster pairs in per-CPU caches, as well as bringing other benefits of
1244slab allocation.
1245.Sh AUTHORS
1246The original
1247.Nm
1248manual page was written by
1249.An Yar Tikhiy .
1250The
1251.Xr uma 9
1252.Vt mbuf
1253allocator was written by
1254.An Bosko Milekic .
1255