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