xref: /dragonfly/share/man/man9/mbuf.9 (revision 2038fb68)
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: src/share/man/man9/mbuf.9,v 1.27.2.1 2003/05/28 13:53:18 yar Exp $
26.\" $DragonFly: src/share/man/man9/mbuf.9,v 1.8 2007/08/18 18:58:20 swildner Exp $
27.\"
28.Dd August 18, 2007
29.Dt MBUF 9
30.Os
31.\"
32.Sh NAME
33.Nm mbuf
34.Nd "memory management in the kernel IPC subsystem"
35.\"
36.Sh SYNOPSIS
37.In sys/param.h
38.In sys/systm.h
39.In sys/mbuf.h
40.\"
41.Ss Mbuf allocation macros
42.Fn MGET "struct mbuf *mbuf" "int how" "short type"
43.Fn MGETHDR "struct mbuf *mbuf" "int how" "short type"
44.Fn MCLGET "struct mbuf *mbuf" "int how"
45.Fn MFREE "struct mbuf *mbuf" "struct mbuf *successor"
46.\"
47.Ss Mbuf utility macros
48.Ft void *
49.Fn mtod "struct mbuf *mbuf" "type"
50.Ft int
51.Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from"
52.Fn M_ALIGN "struct mbuf *mbuf" "u_int len"
53.Fn MH_ALIGN "struct mbuf *mbuf" "u_int len"
54.Ft int
55.Fn M_LEADINGSPACE "struct mbuf *mbuf"
56.Ft int
57.Fn M_TRAILINGSPACE "struct mbuf *mbuf"
58.Fn M_PREPEND "struct mbuf *mbuf" "int len" "int how"
59.\"
60.Ss Mbuf allocation functions
61.Ft struct mbuf *
62.Fn m_get "int how" "int type"
63.Ft struct mbuf *
64.Fn m_getm "struct mbuf *orig" "int len" "int how" "int type"
65.Ft struct mbuf *
66.Fn m_getclr "int how" "int type"
67.Ft struct mbuf *
68.Fn m_gethdr "int how" "int type"
69.Ft struct mbuf *
70.Fn m_free "struct mbuf *mbuf"
71.Ft void
72.Fn m_freem "struct mbuf *mbuf"
73.\"
74.Ss Mbuf utility functions
75.Ft void
76.Fn m_adj "struct mbuf *mbuf" "int len"
77.Ft struct mbuf *
78.Fn m_prepend "struct mbuf *mbuf" "int len" "int how"
79.Ft struct mbuf *
80.Fn m_pullup "struct mbuf *mbuf" "int len"
81.Ft struct mbuf *
82.Fn m_copym "struct mbuf *mbuf" "int offset" "int len" "int how"
83.Ft struct mbuf *
84.Fn m_copypacket "struct mbuf *mbuf" "int how"
85.Ft struct mbuf *
86.Fn m_dup "struct mbuf *mbuf" "int how"
87.Ft void
88.Fn m_copydata "const struct mbuf *mbuf" "int offset" "int len" "caddr_t buf"
89.Ft void
90.Fn m_copyback "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf"
91.Ft struct mbuf *
92.Fo m_devget
93.Fa "char *buf"
94.Fa "int len"
95.Fa "int offset"
96.Fa "struct ifnet *ifp"
97.Fa "void (*copy)(char *from, caddr_t to, u_int len)"
98.Fc
99.Ft void
100.Fn m_cat "struct mbuf *m" "struct mbuf *n"
101.Ft struct mbuf *
102.Fn m_split "struct mbuf *mbuf" "int len" "int how"
103.\"
104.Sh DESCRIPTION
105An mbuf is a basic unit of memory management in the kernel IPC subsystem.
106Network packets and socket buffers are stored in mbufs.
107A network packet may span multiple mbufs arranged into a chain
108(linked list),
109which allows adding or trimming
110network headers with little overhead.
111.Pp
112While a developer should not bother with mbuf internals without serious
113reason in order to avoid incompatibilities with future changes, it
114is useful to understand the mbuf's general structure.
115.Pp
116An mbuf consists of a variable-sized header and a small internal
117buffer for data.
118The mbuf's total size,
119.Dv MSIZE ,
120is a machine-dependent constant defined in
121.In machine/param.h .
122The mbuf header includes:
123.Pp
124.Bl -tag -width "m_nextpkt" -compact -offset indent
125.It Fa m_next
126a pointer to the next buffer in the chain
127.It Fa m_nextpkt
128a pointer to the next chain in the queue
129.It Fa m_data
130a pointer to the data
131.It Fa m_len
132the length of the data
133.It Fa m_type
134the type of data
135.It Fa m_flags
136the mbuf flags
137.El
138.Pp
139The mbuf flag bits are defined as follows:
140.Bd -literal
141/* mbuf flags */
142#define	M_EXT		0x0001	/* has associated external storage */
143#define	M_PKTHDR	0x0002	/* start of record */
144#define	M_EOR		0x0004	/* end of record */
145#define	M_PROTO1	0x0010	/* protocol-specific */
146#define	M_PROTO2	0x0020 	/* protocol-specific */
147#define	M_PROTO3	0x0040	/* protocol-specific */
148#define	M_PROTO4	0x0080	/* protocol-specific */
149#define	M_PROTO5	0x0100	/* protocol-specific */
150
151/* mbuf pkthdr flags, also in m_flags */
152#define	M_BCAST		0x0200	/* send/received as link-level broadcast */
153#define	M_MCAST		0x0400	/* send/received as link-level multicast */
154#define	M_FRAG		0x0800	/* packet is fragment of larger packet */
155#define	M_FIRSTFRAG	0x1000	/* packet is first fragment */
156#define	M_LASTFRAG	0x2000	/* packet is last fragment */
157.Ed
158.Pp
159The available mbuf types are defined as follows:
160.Bd -literal
161/* mbuf types */
162#define	MT_FREE		0	/* should be on free list */
163#define	MT_DATA		1	/* dynamic (data) allocation */
164#define	MT_HEADER	2	/* packet header */
165#define	MT_SONAME	8	/* socket name */
166#define	MT_FTABLE	11	/* fragment reassembly header */
167#define	MT_CONTROL	14	/* extra-data protocol message */
168#define	MT_OOBDATA	15	/* expedited data  */
169.Ed
170.Pp
171If the
172.Dv M_PKTHDR
173flag is set, a
174.Li struct pkthdr m_pkthdr
175is added to the mbuf header.
176It contains a pointer to the interface
177the packet has been received from
178.Pq Fa struct ifnet *rcvif ,
179and the total packet length
180.Pq Fa int len .
181.Pp
182If small enough, data is stored in the mbuf's internal data buffer.
183If the data is sufficiently large, another mbuf may be added to the chain,
184or external storage may be associated with the mbuf.
185.Dv MHLEN
186bytes of data can fit into an mbuf with the
187.Dv M_PKTHDR
188flag set,
189.Dv MLEN
190bytes can otherwise.
191.Pp
192If external storage is being associated with an mbuf, the
193.Dv m_ext
194header is added at the cost of losing the internal data buffer.
195It includes a pointer to external storage, the size of the storage,
196a pointer to a function used for freeing the storage,
197a pointer to an optional argument that can be passed to the function,
198and a pointer to a reference counter.
199An mbuf using external storage has the
200.Dv M_EXT
201flag set.
202.Pp
203The system supplies a default type of external storage buffer called an
204.Dq mbuf cluster .
205Mbuf clusters can be allocated and configured with the use of the
206.Dv MCLGET
207macro.
208Each cluster is
209.Dv MCLBYTES
210in size, where
211.Dv MCLBYTES
212is a machine-dependent constant.
213The system defines an advisory macro
214.Dv MINCLSIZE ,
215which is the smallest amount of data to put into a cluster.
216It's equal to the sum of
217.Dv MLEN
218and
219.Dv MHLEN .
220It is typically preferable to store data into an mbuf's data region, if size
221permits, as opposed to allocating a separate mbuf cluster to hold the same
222data.
223.\"
224.Ss Macros and Functions
225There are numerous predefined macros and functions that provide the
226developer with common utilities.
227.\"
228.Bl -ohang -offset indent
229.It Fn mtod mbuf type
230Convert an mbuf pointer to a data pointer.
231The macro expands to the data pointer cast to the pointer of the specified type.
232.Sy Note :
233It is advisable to ensure that there is enough contiguous data in the mbuf.
234See
235.Fn m_pullup
236for details.
237.It Fn MGET mbuf how type
238Allocate an mbuf and initialize it to contain internal data.
239.Fa mbuf
240will point to the allocated mbuf on success, or be set to
241.Dv NULL
242on failure.
243The
244.Fa how
245argument is to be set to
246.Dv MB_WAIT
247or
248.Dv MB_DONTWAIT .
249It specifies whether the caller is willing to block if necessary.
250If
251.Fa how
252is set to
253.Dv MB_WAIT ,
254a failed allocation will result in the caller being put
255to sleep for a designated
256.Va kern.ipc.mbuf_wait
257.Xr ( sysctl 8
258tunable)
259number of ticks.
260A number of other mbuf-related
261functions and macros have the same argument because they may
262at some point need to allocate new mbufs.
263.Pp
264Programmers should be careful not to confuse the mbuf allocation flag
265.Dv MB_DONTWAIT
266with the
267.Xr kmalloc 9
268allocation flag,
269.Dv M_NOWAIT .
270They are not the same.
271.It Fn MGETHDR mbuf how type
272Allocate an mbuf and initialize it to contain a packet header
273and internal data.
274See
275.Fn MGET
276for details.
277.It Fn MCLGET mbuf how
278Allocate and attach an mbuf cluster to an mbuf.
279If the macro fails, the
280.Dv M_EXT
281flag won't be set in the mbuf.
282.It Fn M_PREPEND mbuf len how
283This macro operates on an mbuf chain.
284It is an optimized wrapper for
285.Fn m_prepend
286that can make use of possible empty space before data
287(e.g. left after trimming of a link-layer header).
288The new chain pointer or
289.Dv NULL
290is in
291.Fa mbuf
292after the call.
293.El
294.Pp
295The functions are:
296.Bl -ohang -offset indent
297.It Fn m_get how type
298A function version of
299.Fn MGET
300for non-critical paths.
301.It Fn m_getm orig len how type
302Allocate
303.Fa len
304bytes worth of mbufs and mbuf clusters if necessary and append the resulting
305allocated chain to the
306.Fa orig
307mbuf chain, if it is
308.No non- Ns Dv NULL .
309If the allocation fails at any point,
310free whatever was allocated and return
311.Dv NULL .
312If
313.Fa orig
314is
315.No non- Ns Dv NULL ,
316it will not be freed.
317It is possible to use
318.Fn m_getm
319to either append
320.Fa len
321bytes to an existing mbuf or mbuf chain
322(for example, one which may be sitting in a pre-allocated ring)
323or to simply perform an all-or-nothing mbuf and mbuf cluster allocation.
324.It Fn m_gethdr how type
325A function version of
326.Fn MGETHDR
327for non-critical paths.
328.It Fn m_getclr how type
329Allocate an mbuf and zero out the data region.
330.El
331.Pp
332The functions below operate on mbuf chains.
333.Bl -ohang -offset indent
334.It Fn m_freem mbuf
335Free an entire mbuf chain, including any external
336storage.
337.\"
338.It Fn m_adj mbuf len
339Trim
340.Fa len
341bytes from the head of an mbuf chain if
342.Fa len
343is positive, from the tail otherwise.
344.\"
345.It Fn m_prepend mbuf len how
346Allocate a new mbuf and prepend it to the chain, handle
347.Dv M_PKTHDR
348properly.
349.Sy Note :
350It doesn't allocate any clusters, so
351.Fa len
352must be less than
353.Dv MLEN
354or
355.Dv MHLEN ,
356depending on the
357.Dv M_PKTHDR
358flag setting.
359.\"
360.It Fn m_pullup mbuf len
361Arrange that the first
362.Fa len
363bytes of an mbuf chain are contiguous and lay in the data area of
364.Fa mbuf ,
365so they are accessible with
366.Fn mtod mbuf type .
367Return the new chain on success,
368.Dv NULL
369on failure
370(the chain is freed in this case).
371.Sy Note :
372It doesn't allocate any clusters, so
373.Fa len
374must be less than
375.Dv MHLEN .
376.\"
377.It Fn m_copym mbuf offset len how
378Make a copy of an mbuf chain starting
379.Fa offset
380bytes from the beginning, continuing for
381.Fa len
382bytes.
383If
384.Fa len
385is
386.Dv M_COPYALL ,
387copy to the end of the mbuf chain.
388.Sy Note :
389The copy is read-only, because clusters are not
390copied, only their reference counts are incremented.
391.\"
392.It Fn m_copypacket mbuf how
393Copy an entire packet including header, which must be present.
394This is an optimized version of the common case
395.Fn m_copym mbuf 0 M_COPYALL how .
396.Sy Note :
397the copy is read-only, because clusters are not
398copied, only their reference counts are incremented.
399.\"
400.It Fn m_dup mbuf how
401Copy a packet header mbuf chain into a completely new chain, including
402copying any mbuf clusters.
403Use this instead of
404.Fn m_copypacket
405when you need a writable copy of an mbuf chain.
406.\"
407.It Fn m_copydata mbuf offset len buf
408Copy data from an mbuf chain starting
409.Fa off
410bytes from the beginning, continuing for
411.Fa len
412bytes, into the indicated buffer
413.Fa buf .
414.\"
415.It Fn m_copyback mbuf offset len buf
416Copy
417.Fa len
418bytes from the buffer
419.Fa buf
420back into the indicated mbuf chain,
421starting at
422.Fa offset
423bytes from the beginning of the chain, extending the mbuf chain if necessary.
424.Sy Note :
425It doesn't allocate any clusters, just adds mbufs to the chain.
426It's safe to set
427.Fa offset
428beyond the current chain end: zeroed mbufs will be allocated to fill the
429space.
430.\"
431.It Fn m_devget buf len offset ifp copy
432Copy data from a device local memory pointed to by
433.Fa buf
434to an mbuf chain.
435The copy is done using a specified copy routine
436.Fa copy ,
437or
438.Fn bcopy
439if
440.Fa copy
441is
442.Dv NULL .
443.\"
444.It Fn m_cat m n
445Concatenate
446.Fa n
447to
448.Fa m .
449Both chains must be of the same type.
450.Fa N
451is still valid after the function returned.
452.Sy Note :
453It does not handle
454.Dv M_PKTHDR
455and friends.
456.\"
457.It Fn m_split mbuf len how
458Partition an mbuf chain in two pieces, returning the tail:
459all but the first
460.Fa len
461bytes.
462In case of failure, it returns
463.Dv NULL
464and attempts to restore the chain to its original state.
465.El
466.Sh STRESS TESTING
467When running a kernel compiled with the option
468.Dv MBUF_STRESS_TEST ,
469the following
470.Xr sysctl 8 Ns
471-controlled options may be used to create
472various failure/extreme cases for testing of network drivers
473and other parts of the kernel that rely on
474.Vt mbufs .
475.Bl -tag -width ident
476.It Va net.inet.ip.mbuf_frag_size
477Causes
478.Fn ip_output
479to fragment outgoing
480.Vt mbuf chains
481into fragments of the specified size.
482Setting this variable to 1 is an excellent way to
483test the long
484.Vt mbuf chain
485handling ability of network drivers.
486.It Va kern.ipc.m_defragrandomfailures
487Causes the function
488.Fn m_defrag
489to randomly fail, returning
490.Dv NULL .
491Any piece of code which uses
492.Fn m_defrag
493should be tested with this feature.
494.El
495.Sh RETURN VALUES
496See above.
497.Sh HISTORY
498.\" Please correct me if I'm wrong
499Mbufs appeared in an early version of
500.Bx .
501Besides for being used for network packets, they were used
502to store various dynamic structures, such as routing table
503entries, interface addresses, protocol control blocks, etc.
504.Sh AUTHORS
505The original
506.Nm
507man page was written by Yar Tikhiy.
508