Add documentation for mchain API.

Reviewed by:	asmodai, ru (mbchain.9)

3 files changed, 464 insertions, 1 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 9245e6a..d03f67e 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -20,7 +20,8 @@ MAN9=	CONDSPLASSERT.9 DECLARE_MODULE.9 DELAY.9 KASSERT.9 MD5.9 SPLASSERT.9 \
 	get_cyclecounter.9 \
 	ifnet.9 inittodr.9 intro.9 ithread.9 \
 	kernacc.9 kthread.9 \
-	malloc.9 make_dev.9 mbuf.9 microseq.9 microtime.9 microuptime.9 \
+	malloc.9 make_dev.9 mbuf.9 mbchain.9 mdchain.9 \
+	microseq.9 microtime.9 microuptime.9 \
 	mi_switch.9 module.9 mutex.9 \
 	namei.9 \
 	panic.9 pfil.9 physio.9 posix4.9 psignal.9 \
@@ -167,6 +168,41 @@ MLINKS+=BUS_SETUP_INTR.9 BUS_TEARDOWN_INTR.9
 MLINKS+=BUS_SETUP_INTR.9 bus_teardown_intr.9
 MLINKS+=bus_generic_read_ivar.9 bus_generic_write_ivar.9
 
+MLINKS+=mbchain.9 mb_init.9
+MLINKS+=mbchain.9 mb_initm.9
+MLINKS+=mbchain.9 mb_done.9
+MLINKS+=mbchain.9 mb_detach.9
+MLINKS+=mbchain.9 mb_fixhdr.9
+MLINKS+=mbchain.9 mb_reserve.9
+MLINKS+=mbchain.9 mb_put_uint8.9
+MLINKS+=mbchain.9 mb_put_uint16be.9
+MLINKS+=mbchain.9 mb_put_uint16le.9
+MLINKS+=mbchain.9 mb_put_uint32be.9
+MLINKS+=mbchain.9 mb_put_uint32le.9
+MLINKS+=mbchain.9 mb_put_int64be.9
+MLINKS+=mbchain.9 mb_put_int64le.9
+MLINKS+=mbchain.9 mb_put_mem.9
+MLINKS+=mbchain.9 mb_put_mbuf.9
+MLINKS+=mbchain.9 mb_put_uio.9
+
+MLINKS+=mdchain.9 md_initm.9
+MLINKS+=mdchain.9 md_done.9
+MLINKS+=mdchain.9 md_append_record.9
+MLINKS+=mdchain.9 md_next_record.9
+MLINKS+=mdchain.9 md_get_uint8.9
+MLINKS+=mdchain.9 md_get_uint16.9
+MLINKS+=mdchain.9 md_get_uint16be.9
+MLINKS+=mdchain.9 md_get_uint16le.9
+MLINKS+=mdchain.9 md_get_uint32.9
+MLINKS+=mdchain.9 md_get_uint32be.9
+MLINKS+=mdchain.9 md_get_uint32le.9
+MLINKS+=mdchain.9 md_get_int64.9
+MLINKS+=mdchain.9 md_get_int64be.9
+MLINKS+=mdchain.9 md_get_int64le.9
+MLINKS+=mdchain.9 md_get_mem.9
+MLINKS+=mdchain.9 md_get_mbuf.9
+MLINKS+=mdchain.9 md_get_uio.9
+
 MLINKS+=microtime.9 getmicrotime.9 microtime.9 nanotime.9
 MLINKS+=microtime.9 getnanotime.9
 MLINKS+=microuptime.9 getmicrouptime.9 microuptime.9 nanouptime.9
diff --git a/share/man/man9/mbchain.9 b/share/man/man9/mbchain.9
new file mode 100644
index 0000000..a62580d
--- /dev/null
+++ b/share/man/man9/mbchain.9
@@ -0,0 +1,219 @@
+.\" -*- nroff -*-
+.\"
+.\" Copyright (c) 2001 Boris Popov
+.\"
+.\" 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 DEVELOPERS ``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 THE DEVELOPERS 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 February 20, 2001
+.Dt MBCHAIN 9
+.Os
+.Sh NAME
+.Nm mbchain ,
+.Nm mb_init ,
+.Nm mb_initm ,
+.Nm mb_done ,
+.Nm mb_detach ,
+.Nm mb_fixhdr ,
+.Nm mb_reserve ,
+.Nm mb_put_uint8 ,
+.Nm mb_put_uint16be ,
+.Nm mb_put_uint16le ,
+.Nm mb_put_uint32be ,
+.Nm mb_put_uint32le ,
+.Nm mb_put_int64be ,
+.Nm mb_put_int64le ,
+.Nm mb_put_mem ,
+.Nm mb_put_mbuf ,
+.Nm mb_put_uio
+.Nd "set of functions to build an mbuf chain from various data types"
+.Sh SYNOPSIS
+.Cd options LIBMCHAIN
+.Li kldload libmchain
+.Pp
+.Fd #include <sys/param.h>
+.Fd #include <sys/mchain.h>
+.Ft int
+.Fn mb_init "struct mbchain *mbp"
+.Ft void
+.Fn mb_initm "struct mbchain *mbp" "struct mbuf *m"
+.Ft void
+.Fn mb_done "struct mbchain *mbp"
+.Ft struct mbuf *
+.Fn mb_detach "struct mbchain *mbp"
+.Ft int
+.Fn mb_fixhdr "struct mbchain *mbp"
+.Ft caddr_t
+.Fn mb_reserve "struct mbchain *mbp" "int size"
+.Ft int
+.Fn mb_put_uint8 "struct mbchain *mbp" "u_int8_t x"
+.Ft int
+.Fn mb_put_uint16be "struct mbchain *mbp" "u_int16_t x"
+.Ft int
+.Fn mb_put_uint16le "struct mbchain *mbp" "u_int16_t x"
+.Ft int
+.Fn mb_put_uint32be "struct mbchain *mbp" "u_int32_t x"
+.Ft int
+.Fn mb_put_uint32le "struct mbchain *mbp" "u_int32_t x"
+.Ft int
+.Fn mb_put_int64be "struct mbchain *mbp" "int64_t x"
+.Ft int
+.Fn mb_put_int64le "struct mbchain *mbp" "int64_t x"
+.Ft int
+.Fn mb_put_mem "struct mbchain *mbp" "c_caddr_t source" "int size" "int type"
+.Ft int
+.Fn mb_put_mbuf "struct mbchain *mbp" "struct mbuf *m"
+.Ft int
+.Fn mb_put_uio "struct mbchain *mbp" "struct uio *uiop" "int size"
+.Sh DESCRIPTION
+These functions are used to compose mbuf chains from various data types.
+The
+.Vt mbchain
+structure is used as a working context and should be initialized with a call
+to either
+.Fn mb_init
+or
+.Fn mb_initm .
+It has the following fields:
+.Bl -tag -width "mb_count"
+.It Va "mb_top"
+.Vt ( "struct mbuf *" )
+a pointer to the top of constructed mbuf chain
+.It Va mb_cur
+.Vt ( "struct mbuf *" )
+a pointer to the currently filled mbuf
+.It Va mb_mleft
+.Vt ( int )
+number of bytes left in the current mbuf
+.It Va mb_count
+.Vt ( int )
+total number of bytes placed in the mbuf chain
+.It Va mb_copy
+.Vt ( "mb_copy_t *" )
+user-defined function to perform a copy into mbuf;
+useful if any unusual
+data conversion is necessesary
+.It Va mb_udata
+.Vt ( "void *" )
+user-supplied data which can be used in the
+.Va mb_copy
+function
+.El
+.Pp
+.Fn mb_done
+function disposes an mbuf chain pointed to by
+.Fa mbp->mb_top
+field and sets
+the field to
+.Dv NULL .
+.Pp
+.Fn mb_detach
+function returns the value of
+.Fa mbp->mb_top
+field and sets its value to
+.Dv NULL .
+.Pp
+.Fn mb_fixhdr
+recalculates the length of an mbuf chain and updates the
+.Va m_pkthdr.len
+field of the first mbuf in the chain.
+.Pp
+.Fn mb_reserve
+ensures that the object of the length specified by the
+.Fa size
+argument will fit in the current mbuf (mbuf allocation is performed if
+necessary), and advances all pointers as if the real data was placed.
+Returned
+value will point to the beginning of the reserved space.
+Note that the size
+of the object should not exceed
+.Dv MLEN
+bytes.
+.Pp
+All
+.Fn mb_put_*
+functions perform an actual copy of the data into mbuf chain.
+Functions which have
+.Cm le
+or
+.Cm be
+suffixes will perform conversion to the little\- or big\-endian data formats.
+.Pp
+.Fn mb_put_mem
+function copies
+.Fa size
+bytes of data specified by the
+.Fa source
+argument to an mbuf chain.
+The
+.Fa type
+argument specifies the method used to perform a copy,
+and can be one of the following:
+.Bl -tag -width "MB_MINLINE"
+.It Dv MB_MSYSTEM
+use
+.Fn bcopy
+function
+.It Dv MB_MUSER
+use
+.Xr copyin 9
+function
+.It Dv MB_MINLINE
+use an
+.Dq inline
+loop which does not call any function
+.It Dv MB_MZERO
+do not copy any data, but just fill the destination with zero bytes
+.It Dv MB_MCUSTOM
+call function specified by the
+.Fa mbp->mb_copy
+field
+.El
+.Sh RETURN VALUES
+All
+.Ft int
+functions return zero if successful,
+otherwise error code is returned.
+.Pp
+.Em Note :
+after failure of any function, an mbuf chain is left in the broken state,
+and only
+.Fn mb_done
+function can safely be called to destroy it.
+.Sh EXAMPLES
+.Bd -literal
+struct mbchain *mbp;
+struct mbuf *m;
+
+mb_init(mbp);
+mb_put_uint8(mbp, 33);
+mb_put_uint16le(mbp, length);
+m = m_copym(mbp->mb_top, 0, M_COPYALL, M_TRYWAIT);
+send(m);
+mb_done(mbp);
+.Ed
+.Sh SEE ALSO
+.Xr mbuf 9 ,
+.Xr mdchain 9
+.Sh AUTHORS
+This manual page was written by
+.An Boris Popov Aq bp@FreeBSD.org .
diff --git a/share/man/man9/mdchain.9 b/share/man/man9/mdchain.9
new file mode 100644
index 0000000..f1a2763
--- /dev/null
+++ b/share/man/man9/mdchain.9
@@ -0,0 +1,208 @@
+.\" -*- nroff -*-
+.\"
+.\" Copyright (c) 2001 Boris Popov
+.\"
+.\" 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 DEVELOPERS ``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 THE DEVELOPERS 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 February 28, 2001
+.Dt MDCHAIN 9
+.Os
+.Sh NAME
+.Nm mdchain ,
+.Nm md_initm ,
+.Nm md_done ,
+.Nm md_append_record ,
+.Nm md_next_record ,
+.Nm md_get_uint8 ,
+.Nm md_get_uint16 ,
+.Nm md_get_uint16be ,
+.Nm md_get_uint16le ,
+.Nm md_get_uint32 ,
+.Nm md_get_uint32be ,
+.Nm md_get_uint32le ,
+.Nm md_get_int64 ,
+.Nm md_get_int64be ,
+.Nm md_get_int64le ,
+.Nm md_get_mem ,
+.Nm md_get_mbuf ,
+.Nm md_get_uio
+.Nd "set of functions to dissect an mbuf chain to various data types"
+.Sh SYNOPSIS
+.Cd options LIBMCHAIN
+.Li kldload libmchain
+.Pp
+.Fd #include <sys/param.h>
+.Fd #include <sys/mchain.h>
+.Ft void
+.Fn md_initm "struct mdchain *mdp" "struct mbuf *m"
+.Ft void
+.Fn md_done "struct mdchain *mdp"
+.Ft void
+.Fn md_append_record "struct mdchain *mdp" "struct mbuf *top"
+.Ft int
+.Fn md_next_record "struct mdchain *mdp"
+.Ft int
+.Fn md_get_uint8 "struct mdchain *mdp" "u_int8_t x"
+.Ft int
+.Fn md_get_uint16 "struct mdchain *mdp" "u_int16_t x"
+.Ft int
+.Fn md_get_uint16be "struct mdchain *mdp" "u_int16_t x"
+.Ft int
+.Fn md_get_uint16le "struct mdchain *mdp" "u_int16_t x"
+.Ft int
+.Fn md_get_uint32 "struct mdchain *mdp" "u_int32_t x"
+.Ft int
+.Fn md_get_uint32be "struct mdchain *mdp" "u_int32_t x"
+.Ft int
+.Fn md_get_uint32le "struct mdchain *mdp" "u_int32_t x"
+.Ft int
+.Fn md_get_int64 "struct mdchain *mdp" "int64_t x"
+.Ft int
+.Fn md_get_int64be "struct mdchain *mdp" "int64_t x"
+.Ft int
+.Fn md_get_int64le "struct mdchain *mdp" "int64_t x"
+.Ft int
+.Fn md_get_mem "struct mdchain *mdp" "caddr_t target" "int size" "int type"
+.Ft int
+.Fn md_get_mbuf "struct mdchain *mdp" "struct mbuf *m"
+.Ft int
+.Fn md_get_uio "struct mdchain *mdp" "struct uio *uiop" "int size"
+.Sh DESCRIPTION
+These functions are used to decompose mbuf chains to various data types.
+The
+.Vt mdchain
+structure is used as a working context
+and should be initialized via call of
+.Fn mb_initm
+function.
+It has the following fields:
+.Bl -tag -width "md_top"
+.It Va "md_top"
+.Vt ( "struct mbuf *" )
+a pointer to the top of the parsed mbuf chain
+.It Va md_cur
+.Vt ( "struct mbuf *" )
+a pointer to the currently parsed mbuf
+.It Va md_pas
+.Vt ( int )
+offset in the current mbuf
+.El
+.Pp
+The
+.Fn md_done
+function disposes of an mbuf chain pointed to by the
+.Fa mdp->md_top
+field and sets the field to
+.Dv NULL .
+.Pp
+The
+.Fn md_append_record
+appends a new mbuf chain using
+.Va m_nextpkt
+field to form a signle linked list of mbuf chains.
+If
+.Va mdp->md_top
+field is
+.Dv NULL ,
+then this function behaves exactly as
+.Fn md_initm
+function.
+.Pp
+The
+.Fn md_next_record
+extracts next mbuf chain and disposes current if any.
+For new mbuf chain it calls
+.Fn md_initm
+function.
+If there is no data left function returns
+.Dv ENOENT .
+.Pp
+All
+.Fn md_get_*
+functions perform an actual copy of the data from an mbuf chain.
+Functions which have
+.Cm le
+or
+.Cm be
+suffixes will perform conversion to the little- or big-endian data formats.
+.Pp
+.Fn md_get_mem
+function copies
+.Fa size
+bytes of data specified by the
+.Fa source
+argument from an mbuf chain.
+The
+.Fa type
+argument specifies the method used to perform a copy,
+and can be one of the following:
+.Bl -tag -width "MB_MINLINE"
+.It Dv MB_MSYSTEM
+use
+.Fn bcopy
+function
+.It Dv MB_MUSER
+use
+.Xr copyin 9
+function
+.It Dv MB_MINLINE
+use an
+.Dq inline
+loop which does not call any function
+.El
+.Pp
+If
+.Ar target is
+.Dv NULL ,
+an actual copy is not performed and function just skips given number of bytes.
+.Sh RETURN VALUES
+All
+.Ft int
+functions return zero if successful,
+otherwise an error code is returned.
+.Pp
+.Em Note :
+after failure of any function,
+a mbuf chain is left in the broken state and only the
+.Fn md_done
+function can safely be called to destroy it.
+.Sh EXAMPLES
+.Bd -literal
+struct mdchain *mdp;
+struct mbuf *m;
+u_int16_t length;
+u_int8_t byte;
+.Pp
+receive(so, &m);
+md_initm(mdp, m);
+if (md_get_uint8(mdp, &byte) != 0 ||
+    md_get_uint16le(mdp, &length) != 0)
+	error = EBADRPC;
+mb_done(mdp);
+.Ed
+.Sh SEE ALSO
+.Xr mbuf 9 ,
+.Xr mbchain 9
+.Sh AUTHORS
+This manual page was written by
+.An Boris Popov Aq bp@FreeBSD.org .