share/man/man9/mbuf.9

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