-# $OpenBSD: Makefile,v 1.233 2015/06/11 16:04:55 mikeb Exp $
+# $OpenBSD: Makefile,v 1.234 2015/06/17 06:24:46 mpi Exp $
# $NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
kern.9 km_alloc.9 knote.9 kthread.9 ktrace.9 \
loadfirmware.9 lock.9 log.9 \
malloc.9 membar_sync.9 mbuf.9 mbuf_tags.9 md5.9 mi_switch.9 \
- microtime.9 mountroothook_establish.9 mutex.9 namei.9 \
+ microtime.9 ml_init.9 mountroothook_establish.9 mq_init.9 mutex.9 \
+ namei.9 \
panic.9 pci_conf_read.9 pci_intr_map.9 pfind.9 physio.9 pmap.9 \
pool.9 powerhook_establish.9 ppsratecheck.9 printf.9 psignal.9 \
radio.9 arc4random.9 rasops.9 ratecheck.9 resettodr.9 rssadapt.9 \
mbuf.9 MEXTADD.9 mbuf.9 M_ALIGN.9 mbuf.9 MH_ALIGN.9 \
mbuf.9 M_READONLY.9 mbuf.9 M_LEADINGSPACE.9 \
mbuf.9 M_TRAILINGSPACE.9 mbuf.9 mtod.9 \
- mbuf.9 m_dup_pkthdr.9 \
- mbuf.9 ml_init.9 mbuf.9 ml_enqueue.9 mbuf.9 ml_dequeue.9 \
- mbuf.9 ml_dechain.9 mbuf.9 ml_filter.9 mbuf.9 ml_len.9 \
- mbuf.9 ml_empty.9 \
- mbuf.9 MBUF_LIST_INITIALIZER.9 mbuf.9 MBUF_LIST_FOREACH.9 \
- mbuf.9 mq_init.9 mbuf.9 mq_enqueue.9 mbuf.9 mq_dequeue.9 \
- mbuf.9 mq_enlist.9 mbuf.9 mq_delist.9 mbuf.9 mq_dechain.9 \
- mbuf.9 mq_filter.9 mbuf.9 mq_len.9 mbuf.9 mq_empty.9 \
- mbuf.9 mq_drops.9 mbuf.9 mq_set_maxlen.9 \
- mbuf.9 MBUF_QUEUE_INITIALIZER.9
+ mbuf.9 m_dup_pkthdr.9
MLINKS+=mbuf_tags.9 m_tag_get.9 mbuf_tags.9 m_tag_find.9 \
mbuf_tags.9 m_tag_prepend.9 mbuf_tags.9 m_tag_delete.9 \
mbuf_tags.9 m_tag_copy.9 mbuf_tags.9 m_tag_delete_chain.9 \
microtime.9 getnanotime.9 microtime.9 nanouptime.9 \
microtime.9 getnanouptime.9 microtime.9 bintime.9 \
microtime.9 binuptime.9
+MLINKS+=ml_init.9 ml_enqueue.9 ml_init.9 ml_dequeue.9 ml_init.9 ml_dechain.9 \
+ ml_init.9 ml_filter.9 ml_init.9 ml_len.9 ml_init.9 ml_empty.9 \
+ ml_init.9 MBUF_LIST_INITIALIZER.9 ml_init.9 MBUF_LIST_FOREACH.9
MLINKS+=mountroothook_establish.9 mountroothook_disestablish.9
MLINKS+=mutex.9 mtx_init.9 mutex.9 mtx_enter.9 mutex.9 mtx_leave.9 \
mutex.9 MUTEX_ASSERT_LOCKED.9 mutex.9 MUTEX_ASSERT_UNLOCKED.9 \
mutex.9 MUTEX_INITIALIZER.9
MLINKS+=mutex.9 mtx_enter_try.9
+MLINKS+=mq_init.9 mq_enqueue.9 mq_init.9 mq_dequeue.9 mq_init.9 mq_enlist.9 \
+ mq_init.9 mq_delist.9 mq_init.9 mq_dechain.9 mq_init.9 mq_filter.9 \
+ mq_init.9 mq_len.9 mq_init.9 mq_empty.9 mq_init.9 mq_drops.9 \
+ mq_init.9 mq_set_maxlen.9 mq_init.9 MBUF_QUEUE_INITIALIZER.9
MLINKS+=namei.9 vfs_lookup.9 namei.9 vfs_relookup.9 namei.9 NDINIT.9
MLINKS+=namei.9 NDINITAT.9
MLINKS+=pci_conf_read.9 pci_conf_write.9 pci_conf_read.9 pci_make_tag.9 \
-.\" $OpenBSD: mbuf.9,v 1.86 2015/06/16 11:17:02 mpi Exp $
+.\" $OpenBSD: mbuf.9,v 1.87 2015/06/17 06:24:46 mpi Exp $
.\"
.\" Copyright (c) 2001 Jean-Jacques Bernard-Gundol <jjbg@openbsd.org>
.\" All rights reserved.
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd $Mdocdate: June 16 2015 $
+.Dd $Mdocdate: June 17 2015 $
.Dt MBUF 9
.Os
.Sh NAME
.Nm mbuf
-.\" .Nm ml_init ,
-.\" .Nm ml_enqueue ,
-.\" .Nm ml_dequeue ,
-.\" .Nm ml_dechain ,
-.\" .Nm ml_len ,
-.\" .Nm ml_empty ,
-.\" .Nm MBUF_LIST_INITIALIZER ,
-.\" .Nm MBUF_LIST_FOREACH ,
-.\" .Nm mq_init ,
-.\" .Nm mq_enqueue ,
-.\" .Nm mq_dequeue ,
-.\" .Nm mq_enlist ,
-.\" .Nm mq_delist ,
-.\" .Nm mq_dechain ,
-.\" .Nm mq_len ,
-.\" .Nm mq_empty ,
-.\" .Nm mq_drops ,
-.\" .Nm mq_set_maxlen ,
-.\" .Nm MBUF_QUEUE_INITIALIZER
.Nd kernel memory management for networking protocols
.Sh SYNOPSIS
.In sys/mbuf.h
.Fn M_TRAILINGSPACE "struct mbuf *m"
.Ft int
.Fn m_dup_pkthdr "struct mbuf *to" "struct mbuf *from" "int how"
-.Ft void
-.Fn "ml_init" "struct mbuf_list *ml"
-.Ft void
-.Fn "ml_enqueue" "struct mbuf_list *ml" "struct mbuf *m"
-.Ft struct mbuf *
-.Fn "ml_dequeue" "struct mbuf_list *ml"
-.Ft struct mbuf *
-.Fn "ml_dechain" "struct mbuf_list *ml"
-.Ft struct mbuf *
-.Fo ml_filter
-.Fa "struct mbuf_list *ml"
-.Fa "int (*filter)(void *, struct mbuf *)"
-.Fa "void *context"
-.Fc
-.Ft unsigned int
-.Fn "ml_len" "struct mbuf_list *ml"
-.Ft int
-.Fn "ml_empty" "struct mbuf_list *ml"
-.Ft struct mbuf_list
-.Fn "MBUF_LIST_INITIALIZER"
-.Fn "MBUF_LIST_FOREACH" "struct mbuf_list *ml" "VARNAME"
-.Fn "mq_init" "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl"
-.Ft int
-.Fn "mq_enqueue" "struct mbuf_queue *mq" "struct mbuf *m"
-.Ft struct mbuf *
-.Fn "mq_dequeue" "struct mbuf_queue *mq"
-.Ft int
-.Fn "mq_enlist" "struct mbuf_queue *mq" "struct mbuf_list *ml"
-.Ft void
-.Fn "mq_delist" "struct mbuf_queue *mq" "struct mbuf_list *ml"
-.Ft struct mbuf *
-.Fn "mq_dechain" "struct mbuf_queue *mq"
-.Ft struct mbuf *
-.Fo mq_filter
-.Fa "struct mbuf_queue *mq"
-.Fa "int (*filter)(void *, struct mbuf *)"
-.Fa "void *context"
-.Fc
-.Ft unsigned int
-.Fn "mq_len" "struct mbuf_queue *mq"
-.Ft int
-.Fn "mq_empty" "struct mbuf_queue *mq"
-.Ft unsigned int
-.Fn "mq_drops" "struct mbuf_queue *mq"
-.Ft void
-.Fn "mq_set_maxlen" "struct mbuf_queue *mq" "unsigned int"
-.Ft struct mbuf_queue
-.Fn "MBUF_QUEUE_INITIALIZER" "unsigned int maxlen" "int ipl"
.Bd -literal
#define MSIZE 256
for a description of
.Fa how .
.El
-.Pp
-The mbuf list and mbuf queue API provides implementions of data
-structures and operations for managing lists of mbufs or for queueing
-mbufs and lists of mbufs between contexts.
-.Pp
-mbuf_list structures support the following functionality:
-.Pp
-.Bl -enum -compact -offset indent
-.It
-Insertion of a new mbuf at the end of the list.
-.It
-Removal of an mbuf from the head of the list.
-.It
-Removal of the entire chain of mbufs on the list.
-.El
-.Bl -tag -width Ds
-.It Fn "ml_init" "struct mbuf_list *ml"
-Initialise the
-.Fa ml
-mbuf_list structure.
-.It Fn "MBUF_LIST_INITIALIZER"
-An initialiser for an mbuf_list structure declaration.
-.It Fn "ml_enqueue" "struct mbuf_list *ml" "struct mbuf *m"
-Enqueue mbuf
-.Fa m
-on the end of the
-.Fa ml
-mbuf list.
-.It Fn "ml_dequeue" "struct mbuf_list *ml"
-Dequeue an mbuf from the front of the
-.Fa ml
-mbuf list.
-.It Fn "ml_dechain" "struct mbuf_list *ml"
-Dequeues all mbufs from the
-.Fa ml
-mbuf list.
-.It Fo ml_filter
-.Fa "struct mbuf_list *ml"
-.Fa "int (*filter)(void *, struct mbuf *)"
-.Fa "void *context"
-.Fc
-Iterates over the mbufs on the
-.Fa ml
-mbuf list, passing each of them to the
-.Fa filter
-function.
-If the
-.Fa filter
-returns non-zero, the packet is removed from the
-.Fa ml
-mbuf list to be returned as part of an mbuf chain by
-.Fn ml_filter .
-.Fa context
-is passed as the first argument to each call of
-.Fa filter .
-.It Fn "ml_len" "struct mbuf_list *ml"
-Return the number of mbufs on the
-.Fa ml
-mbuf list.
-.It Fn "ml_empty" "struct mbuf_list *ml"
-Return if the
-.Fa ml
-mbuf list is empty.
-.It Fn "MBUF_LIST_FOREACH" "struct mbuf_list *ml" "VARNAME"
-A convenience macro that can be used to iterate over the contents of the
-.Fa ml
-mbuf list.
-.Fa VARNAME
-identifies the name (not the address) of an mbuf pointer that will
-be set to each entry on the list.
-Note that it is unsafe to modify the list while iterating over it.
-.El
-.Pp
-mbuf_queue data structures provide a superset of the functionality
-available in mbuf_lists, and protect themselves internally with a
-.Xr mutex 9 ,
-making them useful for moving mbufs between contexts or subsystems.
-Additionally, mbuf_queues provide a limit on the number of mbufs that
-may be queued.
-The additional functionality mbuf_queues provides is:
-.Pp
-.Bl -enum -compact -offset indent
-.It
-Insertion of the mbufs in an mbuf_list at the end of the queue.
-.It
-Removal of all the mbufs on the queue as an mbuf_list.
-.El
-.Bl -tag -width Ds
-.It Fn "mq_init" "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl"
-Initialises the mbuf queue structure
-.Fa mq .
-The maximum number of mbufs that can be queued is specified with
-.Fa maxlen .
-The highest interrupt priority level the queue will be operated at is
-specified via
-.Fa ipl .
-.It Fn "MBUF_QUEUE_INITIALIZER" "unsigned int maxlen" "int ipl"
-Initialises an mbuf queue structure declaration.
-The maximum number of mbufs that can be queued is specified with
-.Fa maxlen .
-The highest interrupt priority level the queue will be operated at is
-specified via
-.Fa ipl .
-.It Fn "mq_enqueue" "struct mbuf_queue *mq" "struct mbuf *m"
-Enqueue mbuf
-.Fa m
-on the end of the
-.Fa mq
-mbuf queue.
-.It Fn "mq_dequeue" "struct mbuf_queue *mq"
-Dequeue an mbuf from the front of the
-.Fa mq
-mbuf queue.
-.It Fn "mq_enlist" "struct mbuf_queue *mq" "struct mbuf_list *ml"
-Enqueue all the mbufs on the
-.Fa ml
-mbuf list on to the end of the
-.Fa mq
-mbuf queue.
-Note, the number of mbufs placed on the queue may exceed its maximum length.
-.It Fn "mq_delist" "struct mbuf_queue *mq" "struct mbuf_list *ml"
-Dequeue all the mbufs on the
-.Fa mq
-mbuf queue on to the
-.Fa ml
-mbuf list.
-.It Fn "mq_dechain" "struct mbuf_queue *mq"
-Dequeue all mbufs from the
-.Fa mq
-mbuf queue.
-.It Fo mq_filter
-.Fa "struct mbuf_queue *mq"
-.Fa "int (*filter)(void *, struct mbuf *)"
-.Fa "void *context"
-.Fc
-Iterates over the mbufs on the
-.Fa mq
-mbuf queue, passing each of them to the
-.Fa filter
-function.
-If the
-.Fa filter
-returns non-zero, the packet is removed from the
-.Fa mq
-mbuf queue to be returned as part of an mbuf chain by
-.Fn mq_filter .
-.Fa context
-is passed as the first argument to each call of
-.Fa filter .
-.It Fn "mq_len" "struct mbuf_queue *mq"
-Return the number of mbufs on the
-.Fa ml
-mbuf queue.
-.It Fn "mq_empty" "struct mbuf_queue *mq"
-Return if the
-.Fa mq
-mbuf queue is empty.
-.It Fn "mq_drops" "struct mbuf_queue *mq"
-Return how many mbufs were dropped and freed by
-.Xr m_freem 9
-if the
-.Fa mq
-mbuf queue was too full.
-.It Fn "mq_set_maxlen" "struct mbuf_queue *mq" "unsigned int"
-Alter the maximum number of mbufs that can be queued on the
-.Fa mq
-mbuf queue.
-Note,
-.Fn mq_set_maxlen
-will only set a new limit, it will not free any excess mbufs that may
-already exist on the queue.
-.El
-.Sh CONTEXT
-.Fn ml_init ,
-.Fn ml_enqueue ,
-.Fn ml_dequeue ,
-.Fn ml_dechain ,
-.Fn ml_len ,
-.Fn ml_empty ,
-.Fn MBUF_LIST_INITIALIZER ,
-.Fn MBUF_LIST_FOREACH ,
-.Fn mq_init ,
-.Fn mq_enqueue ,
-.Fn mq_dequeue ,
-.Fn mq_enlist ,
-.Fn mq_delist ,
-.Fn mq_dechain ,
-.Fn mq_len ,
-.Fn mq_empty ,
-.Fn mq_drops ,
-.Fn mq_set_maxlen ,
-.Fn MBUF_QUEUE_INITIALIZER
-can be called during autoconf, from process context, or from interrupt context.
-.Sh RETURN VALUES
-.Fn ml_dequeue
-and
-.Fn mq_dequeue
-return the mbuf that was at the head of their respective list or queue.
-If the list or queue was empty,
-.Dv NULL
-is returned.
-.Pp
-.Fn ml_dechain
-and
-.Fn mq_dechain
-return all the mbufs that were on the respective list or queues via
-a pointer to an mbuf with the chain accessible via m_nextpkt members.
-If the list or queue was empty,
-.Dv NULL
-is returned.
-.Pp
-.Fn ml_filter
-and
-.Fn mq_filter
-return the mbufs that were successfully matched by the filter
-function on the respective list or queue via a pointer to a chain
-of mbufs.
-If no packets matched the filter,
-.Dv NULL
-is returned.
-.Pp
-.Fn ml_len
-and
-.Fn mq_len
-return the number of mbufs on the list or queue respectively.
-.Pp
-.Fn ml_empty
-and
-.Fn mq_empty
-return a non-zero value if the list or queue is empty,
-otherwise 0.
-.Pp
-.Fn mq_enqueue
-returns 0 if the mbuf was successfully queued, or non-zero if the
-mbuf was freed because it would cause the queue to exceed its maximum
-length.
-.Pp
-.Fn mq_enlist
-returns the number of mbufs that were dropped from the list if the
-length of the queue exceeded its maximum length.
-.Pp
-.Fn mq_drops
-returns the number of mbufs that were freed during
-.Fn mq_enqueue
-operations that would have caused the queue to exceed its maximum length.
.Sh CODE REFERENCES
The mbuf management functions are implemented in the files
.Pa sys/kern/uipc_mbuf.c
--- /dev/null
+.\" $OpenBSD: ml_init.9,v 1.1 2015/06/17 06:24:46 mpi Exp $
+.\"
+.\" Copyright (c) 2015 David Gwynne <dlg@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: June 17 2015 $
+.Dt ML_INIT 9
+.Os
+.Sh NAME
+.Nm ml_init ,
+.Nm ml_enqueue ,
+.Nm ml_dequeue ,
+.Nm ml_dechain ,
+.Nm ml_len ,
+.Nm ml_empty ,
+.Nm MBUF_LIST_INITIALIZER ,
+.Nm MBUF_LIST_FOREACH ,
+.Nd mbuf list API
+.Sh SYNOPSIS
+.In sys/mbuf.h
+.Fn "ml_init" "struct mbuf_list *ml"
+.Ft void
+.Fn "ml_enqueue" "struct mbuf_list *ml" "struct mbuf *m"
+.Ft struct mbuf *
+.Fn "ml_dequeue" "struct mbuf_list *ml"
+.Ft struct mbuf *
+.Fn "ml_dechain" "struct mbuf_list *ml"
+.Ft struct mbuf *
+.Fo ml_filter
+.Fa "struct mbuf_list *ml"
+.Fa "int (*filter)(void *, struct mbuf *)"
+.Fa "void *context"
+.Fc
+.Ft unsigned int
+.Fn "ml_len" "struct mbuf_list *ml"
+.Ft int
+.Fn "ml_empty" "struct mbuf_list *ml"
+.Ft struct mbuf_list
+.Fn "MBUF_LIST_INITIALIZER"
+.Fn "MBUF_LIST_FOREACH" "struct mbuf_list *ml" "VARNAME"
+.Sh DESCRIPTION
+The mbuf list API provides implementions of data structures and operations
+for managing lists of mbufs between contexts.
+.Pp
+mbuf_list structures support the following functionality:
+.Pp
+.Bl -enum -compact -offset indent
+.It
+Insertion of a new mbuf at the end of the list.
+.It
+Removal of an mbuf from the head of the list.
+.It
+Removal of the entire chain of mbufs on the list.
+.El
+.Bl -tag -width Ds
+.It Fn "ml_init" "struct mbuf_list *ml"
+Initialise the
+.Fa ml
+mbuf_list structure.
+.It Fn "MBUF_LIST_INITIALIZER"
+An initialiser for an mbuf_list structure declaration.
+.It Fn "ml_enqueue" "struct mbuf_list *ml" "struct mbuf *m"
+Enqueue mbuf
+.Fa m
+on the end of the
+.Fa ml
+mbuf list.
+.It Fn "ml_dequeue" "struct mbuf_list *ml"
+Dequeue an mbuf from the front of the
+.Fa ml
+mbuf list.
+.It Fn "ml_dechain" "struct mbuf_list *ml"
+Dequeues all mbufs from the
+.Fa ml
+mbuf list.
+.It Fo ml_filter
+.Fa "struct mbuf_list *ml"
+.Fa "int (*filter)(void *, struct mbuf *)"
+.Fa "void *context"
+.Fc
+Iterates over the mbufs on the
+.Fa ml
+mbuf list, passing each of them to the
+.Fa filter
+function.
+If the
+.Fa filter
+returns non-zero, the packet is removed from the
+.Fa ml
+mbuf list to be returned as part of an mbuf chain by
+.Fn ml_filter .
+.Fa context
+is passed as the first argument to each call of
+.Fa filter .
+.It Fn "ml_len" "struct mbuf_list *ml"
+Return the number of mbufs on the
+.Fa ml
+mbuf list.
+.It Fn "ml_empty" "struct mbuf_list *ml"
+Return if the
+.Fa ml
+mbuf list is empty.
+.It Fn "MBUF_LIST_FOREACH" "struct mbuf_list *ml" "VARNAME"
+A convenience macro that can be used to iterate over the contents of the
+.Fa ml
+mbuf list.
+.Fa VARNAME
+identifies the name (not the address) of an mbuf pointer that will
+be set to each entry on the list.
+Note that it is unsafe to modify the list while iterating over it.
+.El
+.Sh CONTEXT
+.Fn ml_init ,
+.Fn ml_enqueue ,
+.Fn ml_dequeue ,
+.Fn ml_dechain ,
+.Fn ml_len ,
+.Fn ml_empty ,
+.Fn MBUF_LIST_INITIALIZER ,
+and
+.Fn MBUF_LIST_FOREACH
+can be called during autoconf, from process context, or from interrupt context.
+.Sh RETURN VALUES
+.Fn ml_dequeue
+returns the mbuf that was at the head of its list.
+If the list was empty,
+.Dv NULL
+is returned.
+.Pp
+.Fn ml_dechain
+returns all the mbufs that were on the list via
+a pointer to an mbuf with the chain accessible via m_nextpkt members.
+If the list was empty,
+.Dv NULL
+is returned.
+.Pp
+.Fn ml_filter
+returns the mbufs that were successfully matched by the filter
+function on the list via a pointer to a chain of mbufs.
+If no packets matched the filter,
+.Dv NULL
+is returned.
+.Pp
+.Fn ml_len
+returns the number of mbufs on the list.
+.Pp
+.Fn ml_empty
+return a non-zero value if the list is empty, otherwise 0.
+.Sh SEE ALSO
+.Xr mbuf 9
--- /dev/null
+.\" $OpenBSD: mq_init.9,v 1.1 2015/06/17 06:24:46 mpi Exp $
+.\"
+.\" Copyright (c) 2015 David Gwynne <dlg@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: June 17 2015 $
+.Dt MQ_INIT 9
+.Os
+.Sh NAME
+.Nm mq_init ,
+.Nm mq_enqueue ,
+.Nm mq_dequeue ,
+.Nm mq_enlist ,
+.Nm mq_delist ,
+.Nm mq_dechain ,
+.Nm mq_len ,
+.Nm mq_empty ,
+.Nm mq_drops ,
+.Nm mq_set_maxlen ,
+.Nm MBUF_QUEUE_INITIALIZER
+.Nd mbuf queue API
+.Sh SYNOPSIS
+.In sys/mbuf.h
+.Fn "mq_init" "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl"
+.Ft int
+.Fn "mq_enqueue" "struct mbuf_queue *mq" "struct mbuf *m"
+.Ft struct mbuf *
+.Fn "mq_dequeue" "struct mbuf_queue *mq"
+.Ft int
+.Fn "mq_enlist" "struct mbuf_queue *mq" "struct mbuf_list *ml"
+.Ft void
+.Fn "mq_delist" "struct mbuf_queue *mq" "struct mbuf_list *ml"
+.Ft struct mbuf *
+.Fn "mq_dechain" "struct mbuf_queue *mq"
+.Ft struct mbuf *
+.Fo mq_filter
+.Fa "struct mbuf_queue *mq"
+.Fa "int (*filter)(void *, struct mbuf *)"
+.Fa "void *context"
+.Fc
+.Ft unsigned int
+.Fn "mq_len" "struct mbuf_queue *mq"
+.Ft int
+.Fn "mq_empty" "struct mbuf_queue *mq"
+.Ft unsigned int
+.Fn "mq_drops" "struct mbuf_queue *mq"
+.Ft void
+.Fn "mq_set_maxlen" "struct mbuf_queue *mq" "unsigned int"
+.Ft struct mbuf_queue
+.Fn "MBUF_QUEUE_INITIALIZER" "unsigned int maxlen" "int ipl"
+.Sh DESCRIPTION
+The mbuf queue API provides implementions of data structures and operations
+for queueing mbufs and lists of mbufs between contexts.
+.Pp
+mbuf_queue data structures provide a superset of the functionality
+available in mbuf_lists, and protect themselves internally with a
+.Xr mutex 9 ,
+making them useful for moving mbufs between contexts or subsystems.
+Additionally, mbuf_queues provide a limit on the number of mbufs that
+may be queued.
+.Pp
+mbuf_queue structures support the following functionality:
+.Pp
+.Bl -enum -compact -offset indent
+.It
+Insertion of a new mbuf at the end of the queue.
+.It
+Removal of an mbuf from the head of the queue.
+.It
+Removal of the entire chain of mbufs on the queue.
+.It
+Insertion of the mbufs in an mbuf_list at the end of the queue.
+.It
+Removal of all the mbufs on the queue as an mbuf_list.
+.El
+.Bl -tag -width Ds
+.It Fn "mq_init" "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl"
+Initialises the mbuf queue structure
+.Fa mq .
+The maximum number of mbufs that can be queued is specified with
+.Fa maxlen .
+The highest interrupt priority level the queue will be operated at is
+specified via
+.Fa ipl .
+.It Fn "MBUF_QUEUE_INITIALIZER" "unsigned int maxlen" "int ipl"
+Initialises an mbuf queue structure declaration.
+The maximum number of mbufs that can be queued is specified with
+.Fa maxlen .
+The highest interrupt priority level the queue will be operated at is
+specified via
+.Fa ipl .
+.It Fn "mq_enqueue" "struct mbuf_queue *mq" "struct mbuf *m"
+Enqueue mbuf
+.Fa m
+on the end of the
+.Fa mq
+mbuf queue.
+.It Fn "mq_dequeue" "struct mbuf_queue *mq"
+Dequeue an mbuf from the front of the
+.Fa mq
+mbuf queue.
+.It Fn "mq_enlist" "struct mbuf_queue *mq" "struct mbuf_list *ml"
+Enqueue all the mbufs on the
+.Fa ml
+mbuf list on to the end of the
+.Fa mq
+mbuf queue.
+Note, the number of mbufs placed on the queue may exceed its maximum length.
+.It Fn "mq_delist" "struct mbuf_queue *mq" "struct mbuf_list *ml"
+Dequeue all the mbufs on the
+.Fa mq
+mbuf queue on to the
+.Fa ml
+mbuf list.
+.It Fn "mq_dechain" "struct mbuf_queue *mq"
+Dequeue all mbufs from the
+.Fa mq
+mbuf queue.
+.It Fo mq_filter
+.Fa "struct mbuf_queue *mq"
+.Fa "int (*filter)(void *, struct mbuf *)"
+.Fa "void *context"
+.Fc
+Iterates over the mbufs on the
+.Fa mq
+mbuf queue, passing each of them to the
+.Fa filter
+function.
+If the
+.Fa filter
+returns non-zero, the packet is removed from the
+.Fa mq
+mbuf queue to be returned as part of an mbuf chain by
+.Fn mq_filter .
+.Fa context
+is passed as the first argument to each call of
+.Fa filter .
+.It Fn "mq_len" "struct mbuf_queue *mq"
+Return the number of mbufs on the
+.Fa mq
+mbuf queue.
+.It Fn "mq_empty" "struct mbuf_queue *mq"
+Return if the
+.Fa mq
+mbuf queue is empty.
+.It Fn "mq_drops" "struct mbuf_queue *mq"
+Return how many mbufs were dropped and freed by
+.Xr m_freem 9
+if the
+.Fa mq
+mbuf queue was too full.
+.It Fn "mq_set_maxlen" "struct mbuf_queue *mq" "unsigned int"
+Alter the maximum number of mbufs that can be queued on the
+.Fa mq
+mbuf queue.
+Note,
+.Fn mq_set_maxlen
+will only set a new limit, it will not free any excess mbufs that may
+already exist on the queue.
+.El
+.Sh CONTEXT
+.Fn mq_init ,
+.Fn mq_enqueue ,
+.Fn mq_dequeue ,
+.Fn mq_enlist ,
+.Fn mq_delist ,
+.Fn mq_dechain ,
+.Fn mq_len ,
+.Fn mq_empty ,
+.Fn mq_drops ,
+.Fn mq_set_maxlen ,
+and
+.Fn MBUF_QUEUE_INITIALIZER
+can be called during autoconf, from process context, or from interrupt context.
+.Sh RETURN VALUES
+.Fn mq_dequeue
+returns the mbuf that was at the head of its queue.
+If the queue was empty,
+.Dv NULL
+is returned.
+.Pp
+.Fn mq_dechain
+returns all the mbufs that were on its queues via a pointer to an mbuf
+with the chain accessible via m_nextpkt members.
+If the queue was empty,
+.Dv NULL
+is returned.
+.Pp
+.Fn mq_filter
+returns the mbufs that were successfully matched by the filter
+function on the queue via a pointer to a chain of mbufs.
+If no packets matched the filter,
+.Dv NULL
+is returned.
+.Pp
+.Fn mq_len
+returns the number of mbufs on the queue.
+.Pp
+.Fn mq_empty
+returns a non-zero value if the queue is empty, otherwise 0.
+.Pp
+.Fn mq_enqueue
+returns 0 if the mbuf was successfully queued, or non-zero if the
+mbuf was freed because it would cause the queue to exceed its maximum
+length.
+.Pp
+.Fn mq_enlist
+returns the number of mbufs that were dropped from the list if the
+length of the queue exceeded its maximum length.
+.Pp
+.Fn mq_drops
+returns the number of mbufs that were freed during
+.Fn mq_enqueue
+operations that would have caused the queue to exceed its maximum length.
+.Sh SEE ALSO
+.Xr mbuf 9 ,
+.Xr ml_init 9 ,
+.Xr mutex 9
projects / openbsd / commitdiff