Add more markup to the mbuf(9) manpage. This includes:
- tagging plaintext "mbuf", "mbuf cluster", and "mbuf chain" with .Vt (variable type) since all of them are ways of managing data, i.e., they can be seen as data types; - using .Vt/.Va instead of .Li (literal) where appropriate; - tagging plaintext words that actually refer to function arguments with .Fa. Suggested by: ru
This commit is contained in:
Yaroslav Tykhiy
parent
1dd991a05b
commit
7b2fd1831f
@ -121,30 +121,49 @@
|
||||
.Fn m_split "struct mbuf *mbuf" "int len" "int how"
|
||||
.\"
|
||||
.Sh DESCRIPTION
|
||||
An mbuf is a basic unit of memory management in the kernel IPC subsystem.
|
||||
Network packets and socket buffers are stored in mbufs.
|
||||
A network packet may span multiple mbufs arranged into a chain
|
||||
An
|
||||
.Vt mbuf
|
||||
is a basic unit of memory management in the kernel IPC subsystem.
|
||||
Network packets and socket buffers are stored in
|
||||
.Vt mbufs .
|
||||
A network packet may span multiple
|
||||
.Vt mbufs
|
||||
arranged into a
|
||||
.Vt mbuf chain
|
||||
(linked list),
|
||||
which allows adding or trimming
|
||||
network headers with little overhead.
|
||||
.Pp
|
||||
While a developer should not bother with mbuf internals without serious
|
||||
While a developer should not bother with
|
||||
.Vt mbuf
|
||||
internals without serious
|
||||
reason in order to avoid incompatibilities with future changes, it
|
||||
is useful to understand the mbuf's general structure.
|
||||
is useful to understand the general structure of an
|
||||
.Vt mbuf .
|
||||
.Pp
|
||||
An mbuf consists of a variable-sized header and a small internal
|
||||
An
|
||||
.Vt mbuf
|
||||
consists of a variable-sized header and a small internal
|
||||
buffer for data.
|
||||
The mbuf's total size,
|
||||
The total size of an
|
||||
.Vt mbuf ,
|
||||
.Dv MSIZE ,
|
||||
is a machine-dependent constant defined in
|
||||
.Pa machine/param.h .
|
||||
The mbuf header includes:
|
||||
The
|
||||
.Vt mbuf
|
||||
header includes:
|
||||
.Pp
|
||||
.Bl -tag -width "m_nextpkt" -compact -offset indent
|
||||
.It Va m_next
|
||||
a pointer to the next buffer in the chain
|
||||
a pointer to the next
|
||||
.Vt mbuf
|
||||
in the
|
||||
.Vt mbuf chain
|
||||
.It Va m_nextpkt
|
||||
a pointer to the next chain in the queue
|
||||
a pointer to the next
|
||||
.Vt mbuf chain
|
||||
in the queue
|
||||
.It Va m_data
|
||||
a pointer to the data
|
||||
.It Va m_len
|
||||
@ -152,10 +171,14 @@ the length of the data
|
||||
.It Va m_type
|
||||
the type of data
|
||||
.It Va m_flags
|
||||
the mbuf flags
|
||||
the
|
||||
.Vt mbuf
|
||||
flags
|
||||
.El
|
||||
.Pp
|
||||
The mbuf flag bits are defined as follows:
|
||||
The
|
||||
.Vt mbuf
|
||||
flag bits are defined as follows:
|
||||
.Bd -literal
|
||||
/* mbuf flags */
|
||||
#define M_EXT 0x0001 /* has associated external storage */
|
||||
@ -176,7 +199,9 @@ The mbuf flag bits are defined as follows:
|
||||
#define M_LASTFRAG 0x2000 /* packet is last fragment */
|
||||
.Ed
|
||||
.Pp
|
||||
The available mbuf types are defined as follows:
|
||||
The available
|
||||
.Vt mbuf
|
||||
types are defined as follows:
|
||||
.Bd -literal
|
||||
/* mbuf types */
|
||||
#define MT_FREE 0 /* should be on free list */
|
||||
@ -191,32 +216,45 @@ The available mbuf types are defined as follows:
|
||||
If the
|
||||
.Dv M_PKTHDR
|
||||
flag is set, a
|
||||
.Li struct pkthdr m_pkthdr
|
||||
is added to the mbuf header.
|
||||
.Vt struct pkthdr Va m_pkthdr
|
||||
is added to the
|
||||
.Vt mbuf
|
||||
header.
|
||||
It contains a pointer to the interface
|
||||
the packet has been received from
|
||||
.Pq Fa struct ifnet *rcvif ,
|
||||
.Pq Vt struct ifnet Va *rcvif ,
|
||||
and the total packet length
|
||||
.Pq Fa int len .
|
||||
.Pq Vt int Va len .
|
||||
.Pp
|
||||
If small enough, data is stored in the mbuf's internal data buffer.
|
||||
If the data is sufficiently large, another mbuf may be added to the chain,
|
||||
or external storage may be associated with the mbuf.
|
||||
If small enough, data is stored in the internal data buffer of an
|
||||
.Vt mbuf .
|
||||
If the data is sufficiently large, another
|
||||
.Vt mbuf
|
||||
may be added to the
|
||||
.Vt mbuf chain ,
|
||||
or external storage may be associated with the
|
||||
.Vt mbuf .
|
||||
.Dv MHLEN
|
||||
bytes of data can fit into an mbuf with the
|
||||
bytes of data can fit into an
|
||||
.Vt mbuf
|
||||
with the
|
||||
.Dv M_PKTHDR
|
||||
flag set,
|
||||
.Dv MLEN
|
||||
bytes can otherwise.
|
||||
.Pp
|
||||
If external storage is being associated with an mbuf, the
|
||||
If external storage is being associated with an
|
||||
.Vt mbuf ,
|
||||
the
|
||||
.Va m_ext
|
||||
header is added at the cost of losing the internal data buffer.
|
||||
It includes a pointer to external storage, the size of the storage,
|
||||
a pointer to a function used for freeing the storage,
|
||||
a pointer to an optional argument that can be passed to the function,
|
||||
and a pointer to a reference counter.
|
||||
An mbuf using external storage has the
|
||||
An
|
||||
.Vt mbuf
|
||||
using external storage has the
|
||||
.Dv M_EXT
|
||||
flag set.
|
||||
.Pp
|
||||
@ -227,7 +265,9 @@ buffer,
|
||||
The allocation and management of the reference counter is handled by the
|
||||
subsystem.
|
||||
The developer can check whether the reference count for the
|
||||
given mbuf's external storage is greater than 1 with the
|
||||
external storage of a given
|
||||
.Vt mbuf
|
||||
is greater than 1 with the
|
||||
.Dv MEXT_IS_REF
|
||||
macro.
|
||||
Similarly, the developer can directly add and remove references,
|
||||
@ -238,23 +278,29 @@ and
|
||||
macros.
|
||||
.Pp
|
||||
The system also supplies a default type of external storage buffer called an
|
||||
.Dq mbuf cluster .
|
||||
Mbuf clusters can be allocated and configured with the use of the
|
||||
.Vt mbuf cluster .
|
||||
.Vt Mbuf clusters
|
||||
can be allocated and configured with the use of the
|
||||
.Dv MCLGET
|
||||
macro.
|
||||
Each cluster is
|
||||
Each
|
||||
.Vt mbuf cluster
|
||||
is
|
||||
.Dv MCLBYTES
|
||||
in size, where MCLBYTES is a machine-dependent constant.
|
||||
The system defines an advisory macro
|
||||
.Dv MINCLSIZE ,
|
||||
which is the smallest amount of data to put into a cluster.
|
||||
which is the smallest amount of data to put into an
|
||||
.Vt mbuf cluster .
|
||||
It's equal to the sum of
|
||||
.Dv MLEN
|
||||
and
|
||||
.Dv MHLEN .
|
||||
It is typically preferable to store data into an mbuf's data region, if size
|
||||
permits, as opposed to allocating a separate mbuf cluster to hold the same
|
||||
data.
|
||||
It is typically preferable to store data into the data region of an
|
||||
.Vt mbuf ,
|
||||
if size permits, as opposed to allocating a separate
|
||||
.Vt mbuf cluster
|
||||
to hold the same data.
|
||||
.\"
|
||||
.Ss Macros and Functions
|
||||
There are numerous predefined macros and functions that provide the
|
||||
@ -262,17 +308,25 @@ developer with common utilities.
|
||||
.\"
|
||||
.Bl -ohang -offset indent
|
||||
.It Fn mtod mbuf type
|
||||
Convert an mbuf pointer to a data pointer.
|
||||
The macro expands to the data pointer cast to the pointer of the specified type.
|
||||
Convert an
|
||||
.Fa mbuf
|
||||
pointer to a data pointer.
|
||||
The macro expands to the data pointer cast to the pointer of the specified
|
||||
.Fa type .
|
||||
.Sy Note :
|
||||
It is advisable to ensure that there is enough contiguous data in the mbuf.
|
||||
It is advisable to ensure that there is enough contiguous data in
|
||||
.Fa mbuf .
|
||||
See
|
||||
.Fn m_pullup
|
||||
for details.
|
||||
.It Fn MGET mbuf how type
|
||||
Allocate an mbuf and initialize it to contain internal data.
|
||||
Allocate an
|
||||
.Vt mbuf
|
||||
and initialize it to contain internal data.
|
||||
.Fa mbuf
|
||||
will point to the allocated mbuf on success, or be set to
|
||||
will point to the allocated
|
||||
.Vt mbuf
|
||||
on success, or be set to
|
||||
.Dv NULL
|
||||
on failure.
|
||||
The
|
||||
@ -292,11 +346,15 @@ kern.ipc.mbuf_wait
|
||||
.Xr ( sysctl 8
|
||||
tunable)
|
||||
number of ticks.
|
||||
A number of other mbuf-related
|
||||
functions and macros have the same argument because they may
|
||||
at some point need to allocate new mbufs.
|
||||
A number of other functions and macros related to
|
||||
.Vt mbufs
|
||||
have the same argument because they may
|
||||
at some point need to allocate new
|
||||
.Vt mbufs .
|
||||
.Pp
|
||||
Programmers should be careful not to confuse the mbuf allocation flag
|
||||
Programmers should be careful not to confuse the
|
||||
.Vt mbuf
|
||||
allocation flag
|
||||
.Dv M_DONTWAIT
|
||||
with the
|
||||
.Xr malloc 9
|
||||
@ -304,37 +362,50 @@ allocation flag,
|
||||
.Dv M_NOWAIT .
|
||||
They are not the same.
|
||||
.It Fn MGETHDR mbuf how type
|
||||
Allocate an mbuf and initialize it to contain a packet header
|
||||
Allocate an
|
||||
.Vt mbuf
|
||||
and initialize it to contain a packet header
|
||||
and internal data.
|
||||
See
|
||||
.Fn MGET
|
||||
for details.
|
||||
.It Fn MCLGET mbuf how
|
||||
Allocate and attach an mbuf cluster to an mbuf.
|
||||
Allocate and attach an
|
||||
.Vt mbuf cluster
|
||||
to
|
||||
.Fa mbuf .
|
||||
If the macro fails, the
|
||||
.Dv M_EXT
|
||||
flag won't be set in the mbuf.
|
||||
flag won't be set in
|
||||
.Fa mbuf .
|
||||
.It Fn M_PREPEND mbuf len how
|
||||
This macro operates on an mbuf chain.
|
||||
This macro operates on an
|
||||
.Vt mbuf chain .
|
||||
It is an optimized wrapper for
|
||||
.Fn m_prepend
|
||||
that can make use of possible empty space before data
|
||||
(e.g. left after trimming of a link-layer header).
|
||||
The new chain pointer or
|
||||
The new
|
||||
.Vt mbuf chain
|
||||
pointer or
|
||||
.Dv NULL
|
||||
is in
|
||||
.Fa mbuf
|
||||
after the call.
|
||||
.It Fn M_WRITABLE mbuf
|
||||
This macro will evaluate true if the mbuf is not marked
|
||||
This macro will evaluate true if
|
||||
.Fa mbuf
|
||||
is not marked
|
||||
.Dv M_RDONLY
|
||||
and if either the mbuf does not contain external storage or,
|
||||
and if either
|
||||
.Fa mbuf
|
||||
does not contain external storage or,
|
||||
if it does,
|
||||
then if the reference count of the storage is not greater than 1.
|
||||
The
|
||||
.Dv M_RDONLY
|
||||
flag can be set in the mbuf's
|
||||
.Va m_flags .
|
||||
flag can be set in
|
||||
.Fa mbuf->m_flags .
|
||||
This can be achieved during setup of the external storage,
|
||||
by passing the
|
||||
.Dv M_RDONLY
|
||||
@ -342,7 +413,8 @@ bit as a
|
||||
.Fa flags
|
||||
argument to the
|
||||
.Fn MEXTADD
|
||||
macro, or can be directly set in individual mbufs.
|
||||
macro, or can be directly set in individual
|
||||
.Vt mbufs .
|
||||
.El
|
||||
.Pp
|
||||
The functions are:
|
||||
@ -354,10 +426,16 @@ for non-critical paths.
|
||||
.It Fn m_getm orig len how type
|
||||
Allocate
|
||||
.Fa len
|
||||
bytes worth of mbufs and mbuf clusters if necessary and append the resulting
|
||||
allocated chain to the
|
||||
.Fa orig
|
||||
mbuf chain, if it is
|
||||
bytes worth of
|
||||
.Vt mbufs
|
||||
and
|
||||
.Vt mbuf clusters
|
||||
if necessary and append the resulting allocated
|
||||
.Vt mbuf chain
|
||||
to the
|
||||
.Vt mbuf chain
|
||||
.Fa orig ,
|
||||
if it is
|
||||
.No non- Ns Dv NULL .
|
||||
If the allocation fails at any point,
|
||||
free whatever was allocated and return
|
||||
@ -371,36 +449,55 @@ It is possible to use
|
||||
.Fn m_getm
|
||||
to either append
|
||||
.Fa len
|
||||
bytes to an existing mbuf or mbuf chain
|
||||
bytes to an existing
|
||||
.Vt mbuf
|
||||
or
|
||||
.Vt mbuf chain
|
||||
(for example, one which may be sitting in a pre-allocated ring)
|
||||
or to simply perform an all-or-nothing mbuf and mbuf cluster allocation.
|
||||
or to simply perform an all-or-nothing
|
||||
.Vt mbuf
|
||||
and
|
||||
.Vt mbuf cluster
|
||||
allocation.
|
||||
.It Fn m_gethdr how type
|
||||
A function version of
|
||||
.Fn MGETHDR
|
||||
for non-critical paths.
|
||||
.It Fn m_getclr how type
|
||||
Allocate an mbuf and zero out the data region.
|
||||
Allocate an
|
||||
.Vt mbuf
|
||||
and zero out the data region.
|
||||
.El
|
||||
.Pp
|
||||
The functions below operate on mbuf chains.
|
||||
The functions below operate on
|
||||
.Vt mbuf chains .
|
||||
.Bl -ohang -offset indent
|
||||
.It Fn m_freem mbuf
|
||||
Free an entire mbuf chain, including any external
|
||||
storage.
|
||||
Free an entire
|
||||
.Vt mbuf chain ,
|
||||
including any external storage.
|
||||
.\"
|
||||
.It Fn m_adj mbuf len
|
||||
Trim
|
||||
.Fa len
|
||||
bytes from the head of an mbuf chain if
|
||||
bytes from the head of an
|
||||
.Vt mbuf chain
|
||||
if
|
||||
.Fa len
|
||||
is positive, from the tail otherwise.
|
||||
.\"
|
||||
.It Fn m_prepend mbuf len how
|
||||
Allocate a new mbuf and prepend it to the chain, handle
|
||||
Allocate a new
|
||||
.Vt mbuf
|
||||
and prepend it to the
|
||||
.Vt mbuf chain ,
|
||||
handle
|
||||
.Dv M_PKTHDR
|
||||
properly.
|
||||
.Sy Note :
|
||||
It doesn't allocate any clusters, so
|
||||
It doesn't allocate any
|
||||
.Vt mbuf clusters ,
|
||||
so
|
||||
.Fa len
|
||||
must be less than
|
||||
.Dv MLEN
|
||||
@ -413,22 +510,32 @@ flag setting.
|
||||
.It Fn m_pullup mbuf len
|
||||
Arrange that the first
|
||||
.Fa len
|
||||
bytes of an mbuf chain are contiguous and lay in the data area of
|
||||
bytes of an
|
||||
.Vt mbuf chain
|
||||
are contiguous and lay in the data area of
|
||||
.Fa mbuf ,
|
||||
so they are accessible with
|
||||
.Fn mtod mbuf type .
|
||||
Return the new chain on success,
|
||||
Return the new
|
||||
.Vt mbuf chain
|
||||
on success,
|
||||
.Dv NULL
|
||||
on failure
|
||||
(the chain is freed in this case).
|
||||
(the
|
||||
.Vt mbuf chain
|
||||
is freed in this case).
|
||||
.Sy Note :
|
||||
It doesn't allocate any clusters, so
|
||||
It doesn't allocate any
|
||||
.Vt mbuf clusters ,
|
||||
so
|
||||
.Fa len
|
||||
must be less than
|
||||
.Dv MHLEN .
|
||||
.\"
|
||||
.It Fn m_copym mbuf offset len how
|
||||
Make a copy of an mbuf chain starting
|
||||
Make a copy of an
|
||||
.Vt mbuf chain
|
||||
starting
|
||||
.Fa offset
|
||||
bytes from the beginning, continuing for
|
||||
.Fa len
|
||||
@ -437,28 +544,38 @@ If
|
||||
.Fa len
|
||||
is
|
||||
.Dv M_COPYALL ,
|
||||
copy to the end of the mbuf chain.
|
||||
copy to the end of the
|
||||
.Vt mbuf chain .
|
||||
.Sy Note :
|
||||
The copy is read-only, because clusters are not
|
||||
copied, only their reference counts are incremented.
|
||||
The copy is read-only, because the
|
||||
.Vt mbuf clusters
|
||||
are not copied, only their reference counts are incremented.
|
||||
.\"
|
||||
.It Fn m_copypacket mbuf how
|
||||
Copy an entire packet including header, which must be present.
|
||||
This is an optimized version of the common case
|
||||
.Fn m_copym mbuf 0 M_COPYALL how .
|
||||
.Sy Note :
|
||||
the copy is read-only, because clusters are not
|
||||
copied, only their reference counts are incremented.
|
||||
the copy is read-only, because the
|
||||
.Vt mbuf clusters
|
||||
are not copied, only their reference counts are incremented.
|
||||
.\"
|
||||
.It Fn m_dup mbuf how
|
||||
Copy a packet header mbuf chain into a completely new chain, including
|
||||
copying any mbuf clusters.
|
||||
Copy a packet header
|
||||
.Vt mbuf chain
|
||||
into a completely new
|
||||
.Vt mbuf chain ,
|
||||
including copying any
|
||||
.Vt mbuf clusters .
|
||||
Use this instead of
|
||||
.Fn m_copypacket
|
||||
when you need a writable copy of an mbuf chain.
|
||||
when you need a writable copy of an
|
||||
.Vt mbuf chain .
|
||||
.\"
|
||||
.It Fn m_copydata mbuf offset len buf
|
||||
Copy data from an mbuf chain starting
|
||||
Copy data from an
|
||||
.Vt mbuf chain
|
||||
starting
|
||||
.Fa off
|
||||
bytes from the beginning, continuing for
|
||||
.Fa len
|
||||
@ -470,27 +587,45 @@ Copy
|
||||
.Fa len
|
||||
bytes from the buffer
|
||||
.Fa buf
|
||||
back into the indicated mbuf chain,
|
||||
back into the indicated
|
||||
.Vt mbuf chain ,
|
||||
starting at
|
||||
.Fa offset
|
||||
bytes from the beginning of the chain, extending the mbuf chain if necessary.
|
||||
bytes from the beginning of the
|
||||
.Vt mbuf chain ,
|
||||
extending the
|
||||
.Vt mbuf chain
|
||||
if necessary.
|
||||
.Sy Note :
|
||||
It doesn't allocate any clusters, just adds mbufs to the chain.
|
||||
It doesn't allocate any
|
||||
.Vt mbuf clusters ,
|
||||
just adds
|
||||
.Vt mbufs
|
||||
to the
|
||||
.Vt mbuf chain .
|
||||
It's safe to set
|
||||
.Fa offset
|
||||
beyond the current chain end: zeroed mbufs will be allocated to fill the
|
||||
space.
|
||||
beyond the current
|
||||
.Vt mbuf chain
|
||||
end: zeroed
|
||||
.Vt mbufs
|
||||
will be allocated to fill the space.
|
||||
.\"
|
||||
.It Fn m_length buf last
|
||||
Return the length of the mbuf chain, and optionally a pointer to the last mbuf.
|
||||
Return the length of the
|
||||
.Vt mbuf chain ,
|
||||
and optionally a pointer to the last
|
||||
.Vt mbuf .
|
||||
.\"
|
||||
.It Fn m_fixhdr buf
|
||||
Set the packet-header length to the length of the mbuf chain.
|
||||
Set the packet-header length to the length of the
|
||||
.Vt mbuf chain .
|
||||
.\"
|
||||
.It Fn m_devget buf len offset ifp copy
|
||||
Copy data from a device local memory pointed to by
|
||||
.Fa buf
|
||||
to an mbuf chain.
|
||||
to an
|
||||
.Vt mbuf chain .
|
||||
The copy is done using a specified copy routine
|
||||
.Fa copy ,
|
||||
or
|
||||
@ -505,7 +640,9 @@ Concatenate
|
||||
.Fa n
|
||||
to
|
||||
.Fa m .
|
||||
Both chains must be of the same type.
|
||||
Both
|
||||
.Vt mbuf chains
|
||||
must be of the same type.
|
||||
.Fa N
|
||||
is still valid after the function returned.
|
||||
.Sy Note :
|
||||
@ -514,13 +651,17 @@ It does not handle
|
||||
and friends.
|
||||
.\"
|
||||
.It Fn m_split mbuf len how
|
||||
Partition an mbuf chain in two pieces, returning the tail:
|
||||
Partition an
|
||||
.Vt mbuf chain
|
||||
in two pieces, returning the tail:
|
||||
all but the first
|
||||
.Fa len
|
||||
bytes.
|
||||
In case of failure, it returns
|
||||
.Dv NULL
|
||||
and attempts to restore the chain to its original state.
|
||||
and attempts to restore the
|
||||
.Vt mbuf chain
|
||||
to its original state.
|
||||
.El
|
||||
.Sh STRESS TESTING
|
||||
When running a kernel compiled with the option
|
||||
@ -529,14 +670,19 @@ the following
|
||||
.Xr sysctl 8 Ns
|
||||
-controlled options may be used to create
|
||||
various failure/extreme cases for testing of network drivers
|
||||
and other mbuf-reliant parts of the kernel.
|
||||
and other parts of the kernel that rely on
|
||||
.Vt mbufs .
|
||||
.Bl -tag -width ident
|
||||
.It Va net.inet.ip.mbuf_frag_size
|
||||
Causes
|
||||
.Fn ip_output
|
||||
to fragment outgoing mbuf chains into fragments of the specified size.
|
||||
to fragment outgoing
|
||||
.Vt mbuf chains
|
||||
into fragments of the specified size.
|
||||
Setting this variable to 1 is an excellent way to
|
||||
test the long mbuf chain handling ability of network drivers.
|
||||
test the long
|
||||
.Vt mbuf chain
|
||||
handling ability of network drivers.
|
||||
.It Va kern.ipc.m_defragrandomfailures
|
||||
Causes the function
|
||||
.Fn m_defrag
|
||||
@ -550,7 +696,8 @@ should be tested with this feature.
|
||||
See above.
|
||||
.Sh HISTORY
|
||||
.\" Please correct me if I'm wrong
|
||||
Mbufs appeared in an early version of
|
||||
.Vt Mbufs
|
||||
appeared in an early version of
|
||||
.Bx .
|
||||
Besides for being used for network packets, they were used
|
||||
to store various dynamic structures, such as routing table
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user