Add a prototype mbuf.9 man page. Probably needs work, but it's a good

start.

PR:             docs/22053
Submitted by:   Yar Tikhiy <yar@comp.chem.msu.su>

2 files changed, 408 insertions, 1 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 4f7757b..05eb33e 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -18,7 +18,7 @@ MAN9=	CONDSPLASSERT.9 KASSERT.9 MD5.9 SPLASSERT.9 \
 	posix4.9 psignal.9 random.9 resettodr.9 rtalloc.9 rtentry.9 sleep.9 spl.9 \
 	store.9 style.9 suser.9 time.9 timeout.9 uio.9 \
 	vget.9 vnode.9 vput.9 vref.9 vrele.9 vslock.9 \
-	microtime.9 microuptime.9 tvtohz.9
+	mbuf.9 microtime.9 microuptime.9 tvtohz.9
 
 MAN9+=	device.9 device_add_child.9 device_delete_child.9 device_enable.9 \
 	device_find_child.9 device_get_children.9 \
diff --git a/share/man/man9/mbuf.9 b/share/man/man9/mbuf.9
new file mode 100644
index 0000000..2fdac7f
--- /dev/null
+++ b/share/man/man9/mbuf.9
@@ -0,0 +1,407 @@
+.\" Copyright (c) 2000 FreeBSD Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd October 17, 2000
+.Dt MBUF 9
+.Os
+.\"
+.Sh NAME
+.Nm mbuf
+.Nd "memory management in the kernel IPC subsystem"
+.\"
+.Sh SYNOPSIS
+.Fd #include <sys/param.h>
+.Fd #include <sys/mbuf.h>
+.\"
+.Ss Mbuf manipulation macros
+.Fn mtod "struct mbuf *mbuf" "any type"
+.Fn MGET "struct mbuf *mbuf" "int how" "short type"
+.Fn MGETHDR "struct mbuf *mbuf" "int how" "short type" 
+.Fn MCLGET "struct mbuf *mbuf" "int how"
+.Fn M_PREPEND "struct mbuf *mbuf" "int len" "int how" 
+.\"
+.Ss Mbuf manipulation functions
+.Ft struct mbuf *
+.Fn m_get "int how" "int type"
+.Ft struct mbuf *
+.Fn m_getclr "int how" "int type"
+.Ft struct mbuf *
+.Fn m_gethdr "int how" "int type"
+.Ss Mbuf chain manipulation functions
+.Ft void
+.Fn m_freem "struct mbuf *mbuf"
+.Ft void
+.Fn m_adj "struct mbuf *mbuf" "int len"
+.Ft struct mbuf *
+.Fn m_prepend "struct mbuf *mbuf" "int len" "int how"
+.Ft struct mbuf *
+.Fn m_pullup "struct mbuf *mbuf" "int len"
+.Ft struct mbuf *
+.Fn m_copym "struct mbuf *mbuf" "int offset" "int len" "int how"
+.Ft struct mbuf *
+.Fn m_copypacket "struct mbuf *mbuf" "int how"
+.Ft struct mbuf *
+.Fn m_dup "struct mbuf *mbuf" "int how"
+.Ft void
+.Fn m_copydata "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf"
+.Ft void
+.Fn m_copyback "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf"
+.Ft struct mbuf *
+.Fo m_devget
+.Fa "char *buf"
+.Fa "int len"
+.Fa "int offset"
+.Fa "struct ifnet *ifp"
+.Fa "void (*copy)(char *from, caddr_t to, u_int len)"
+.Fc
+.Ft void
+.Fn m_cat "struct mbuf *m" "struct mbuf *n"
+.Ft struct mbuf *
+.Fn m_split "struct mbuf *mbuf" "int len" "int how"
+.\"
+.Sh DESCRIPTION
+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
+.Pq linked list ,
+which allows adding or trimming
+network headers without overhead.
+.Pp
+While a developer should not bother mbuf internals without serious
+reason in order to avoid incompatibilities with future changes, it
+would be useful to know the mbuf general structure.
+.Pp
+Mbuf consists of a variable-length header and a small internal
+buffer for data. Mbuf total size
+.Dv MSIZE
+is a machine-dependent constant defined in
+.Pa machine/param.h .
+The mbuf header includes:
+.Pp
+.Bl -tag -width "m_nextpkt" -compact -offset indent
+.It Fa m_next
+a pointer to the next buffer in the chain
+.It Fa m_nextpkt
+a pointer to the next chain in the queue
+.It Fa m_data
+a pointer to the data
+.It Fa m_len
+the length of the data
+.It Fa m_type
+the type of the data
+.It Fa m_flags
+the mbuf flags
+.El
+.Pp
+The mbuf flag bits are defined as follows:
+.Bd -literal
+/* mbuf flags */
+#define	M_EXT		0x0001	/* has associated external storage */
+#define	M_PKTHDR	0x0002	/* start of record */
+#define	M_EOR		0x0004	/* end of record */
+#define	M_PROTO1	0x0008	/* protocol-specific */
+#define	M_PROTO2	0x0010	/* protocol-specific */
+#define	M_PROTO3	0x0020	/* protocol-specific */
+#define	M_PROTO4	0x0040	/* protocol-specific */
+#define	M_PROTO5	0x0080	/* protocol-specific */
+
+/* mbuf pkthdr flags, also in m_flags */
+#define	M_BCAST		0x0100	/* send/received as link-level broadcast */
+#define	M_MCAST		0x0200	/* send/received as link-level multicast */
+#define	M_FRAG		0x0400	/* packet is a fragment of a larger packet */
+#define	M_FIRSTFRAG	0x0800	/* packet is first fragment */
+#define	M_LASTFRAG	0x1000	/* packet is last fragment */
+.Ed
+.Pp
+The possible mbuf types are defined as follows:
+.Bd -literal
+/* mbuf types */
+#define	MT_FREE		0	/* should be on free list */
+#define	MT_DATA		1	/* dynamic (data) allocation */
+#define	MT_HEADER	2	/* packet header */
+#define	MT_SONAME	8	/* socket name */
+#define	MT_FTABLE	11	/* fragment reassembly header */
+#define	MT_CONTROL	14	/* extra-data protocol message */
+#define	MT_OOBDATA	15	/* expedited data  */
+.Ed
+.Pp
+If the
+.Dv M_PKTHDR
+flag is set, a
+.Fa struct pkthdr m_pkthdr
+is added to the mbuf header. It contains a pointer to the interface
+the packet has been received from
+.Pq Fa struct ifnet *rcvif ,
+and the total packet length
+.Pq Fa int len .
+.Pp
+Data is placed into the mbuf internal buffer if small enough. If
+it is not, another mbuf may be added to the chain, or external
+storage may be associated with the mbuf.
+.Dv MHLEN
+bytes of data can fit into a mbuf with the
+.Dv M_PKTHDR
+flag set,
+.Dv MLEN
+bytes can otherwise.
+.Pp
+If external storage is being associated with a mbuf, yet another
+header is added at the cost of loosing the internal buffer.  It
+includes a pointer to an external buffer, its size, and two pointers
+to storage-specific management routines: one for freeing the buffer,
+and another for accounting references to it. A mbuf using external
+storage has the
+.Dv M_EXT
+flag set.
+.Pp
+The system supplies a macro for allocating
+the external storage in a system-wide pool of fixed-size
+buffers called
+.Dq mbuf clusters ,
+each
+.Dv MCLBYTES
+long.
+.Dv 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.
+It's equal to the sum of
+.Dv MLEN
+and
+.Dv MHLEN .
+The idea is that one should rather add a mbuf to the chain than
+allocate a mbuf cluster, if possible.
+.\"
+.Ss Macros and Functions
+There is plenty of predefined macros and functions that help a
+developer not to worry about mbuf internals. The macros are:
+.\"
+.Bl -ohang -offset indent
+.It Fn mtod mbuf type
+Convert a mbuf pointer to a data pointer.
+The macro expands to the data pointer cast to the pointer to the specified type.
+.Sy Note :
+You must usually ensure that there is enough contiguous data in the mbuf.
+See
+.Fn m_pullup
+for details.
+.It Fn MGET mbuf how type
+Allocate a mbuf and initialize it to contain internal data.
+.Fa Mbuf
+will point to the allocated mbuf on success, or be
+.Dv NULL
+on failure. The
+.Fa how
+argument is to be set to
+.Dv M_WAIT
+or
+.Dv M_DONTWAIT .
+It specifies if the macro can block. If 
+.Fa how
+is set to M_WAIT, the macro should never fail, but can block
+forever. A number of other mbuf-related
+functions and macros have the same argument because they may
+need to allocate new mbufs.
+.Sy Caution :
+Never use
+.Dv M_WAIT
+if running at the interrupt level.
+.It Fn MGETHDR mbuf how type
+Allocate a mbuf and initialize it to contain a packet header
+and internal data. See
+.Fn MGET
+for details.
+.It Fn MCLGET mbuf how
+Attach a mbuf cluster to a mbuf. If the macro fails, the
+.Dv M_EXT
+flag won't be set in the mbuf.
+.It Fn M_PREPEND mbuf len how
+This macro operates on a mbuf chain.
+It is an optimized wrapper for
+.Fn m_prepend
+that can make use of possible empty space before data
+.Pq "e.g. left after trimming of a link-layer header" .
+The new chain pointer or
+.Dv NULL
+is in 
+.Fa mbuf
+after the call.
+.El
+.Pp
+The functions are:
+.Bl -ohang -offset indent 
+.It Fn m_get how type
+A function version of
+.Fn MGET .
+.It Fn m_gethdr how type
+A function version of
+.Fn MGETHDR .
+.It Fn m_getclr how type
+.Fn MGET how type
+first,
+.Fn bzero
+the internal data buffer then.
+.El
+.Pp
+The functions below operate on mbuf chains.
+.Bl -ohang -offset indent
+.It Fn m_freem mbuf
+Free an entire mbuf chain, including any external
+storage.
+.\"
+.It Fn m_adj mbuf len
+Trim
+.Fa len
+bytes from the head of a 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
+.Dv M_PKTHDR
+properly.
+.Sy Note :
+It doesn't allocate any clusters, so
+.Fa len
+must be less than
+.Dv MLEN
+or
+.Dv MHLEN ,
+depending on the
+.Dv M_PKTHDR flag setting.
+.\"
+.It Fn m_pullup mbuf len
+Arrange that the first
+.Fa len
+bytes of a 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,
+.Dv NULL
+on failure
+.Pq the chain is freed in this case .
+.Sy Note :
+It doesn't allocate any 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 
+.Fa offset
+bytes from the beginning, continuing for 
+.Fa len
+bytes. If
+.Fa len
+is
+.Dv M_COPYALL ,
+copy to the end of the mbuf chain.
+.Sy Note :
+The copy is read-only, because 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.
+.\"
+.It Fn m_dup mbuf how
+Copy a packet header mbuf chain into a completely new chain, including
+copying any mbuf clusters.  Use this instead of
+.Fn m_copypacket
+when you need a writable copy of an mbuf chain.
+.\"
+.It Fn m_copydata mbuf offset len buf
+Copy data from a mbuf chain starting
+.Fa off
+bytes from the beginning, continuing for
+.Fa len
+bytes, into the indicated buffer 
+.Fa buf .
+.\"
+.It Fn m_copyback mbuf offset len buf
+Copy
+.Fa len
+bytes from the buffer
+.Fa buf
+back into the indicated mbuf chain,
+starting at
+.Fa offset
+bytes from the beginning of the chain, extending the mbuf chain if necessary.
+.Sy Note :
+It doesn't allocate any clusters, just adds mbufs to the chain. It's safe
+to set
+.Fa offset
+beyond the current chain end: zeroed mbufs will be allocated to fill the
+space.
+.\"
+.It Fn m_devget buf len offset ifp copy
+Copy data from a device local memory pointed to by
+.Fa buf
+to a mbuf chain. The copy is done using a specified copy routine
+.Fa copy ,
+or
+.Fn bcopy
+if
+.Fa copy
+is
+.Dv NULL .
+.\"
+.It Fn m_cat m n
+Concatenate
+.Fa n
+to
+.Fa m .
+Both chains must be of the same type.
+.Fa N
+is still valid after the function returned.
+.Sy Note :
+It does not handle
+.Dv M_PKTHDR
+and friends.
+.\"
+.It Fn m_split mbuf len how
+Partition an 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.
+.Sh RETURN VALUES
+See above.
+.Sh HISTORY
+.\" Please correct me if I'm wrong
+Mbufs appeared in an early version of BSD. They were used
+to keep various dynamic structures, such as routing table
+entries, interface addresses, protocol control blocks etc
+besides network packets.
+.Sh AUTHORS
+This man page was written by Yar Tikhiy.