From 162361b3d2b94480023f5b3e160e0b6ebe09eb89 Mon Sep 17 00:00:00 2001 From: mpi Date: Wed, 17 Jun 2015 06:24:46 +0000 Subject: [PATCH] Move mbuf_list and mbuf_queue documentation in their own manual. ok jmc@, deraadt@, dlg@ --- share/man/man9/Makefile | 23 ++- share/man/man9/mbuf.9 | 316 +-------------------------------------- share/man/man9/ml_init.9 | 161 ++++++++++++++++++++ share/man/man9/mq_init.9 | 229 ++++++++++++++++++++++++++++ 4 files changed, 403 insertions(+), 326 deletions(-) create mode 100644 share/man/man9/ml_init.9 create mode 100644 share/man/man9/mq_init.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index ca3d8baceaf..2386f36713f 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,4 +1,4 @@ -# $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. @@ -22,7 +22,8 @@ MAN= aml_evalnode.9 atomic_add_int.9 atomic_cas_uint.9 \ 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 \ @@ -253,16 +254,7 @@ MLINKS+=mbuf.9 m_copym2.9 mbuf.9 m_copym.9 mbuf.9 m_free.9 mbuf.9 MFREE.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 \ @@ -274,11 +266,18 @@ MLINKS+=microtime.9 getmicrotime.9 microtime.9 microuptime.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 \ diff --git a/share/man/man9/mbuf.9 b/share/man/man9/mbuf.9 index e47391846c8..87e75f7fdf5 100644 --- a/share/man/man9/mbuf.9 +++ b/share/man/man9/mbuf.9 @@ -1,4 +1,4 @@ -.\" $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 .\" All rights reserved. @@ -25,30 +25,11 @@ .\" (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 @@ -111,54 +92,6 @@ .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 @@ -757,251 +690,6 @@ See 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 diff --git a/share/man/man9/ml_init.9 b/share/man/man9/ml_init.9 new file mode 100644 index 00000000000..89c1ac778bc --- /dev/null +++ b/share/man/man9/ml_init.9 @@ -0,0 +1,161 @@ +.\" $OpenBSD: ml_init.9,v 1.1 2015/06/17 06:24:46 mpi Exp $ +.\" +.\" Copyright (c) 2015 David Gwynne +.\" +.\" 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 diff --git a/share/man/man9/mq_init.9 b/share/man/man9/mq_init.9 new file mode 100644 index 00000000000..18d22fa13d5 --- /dev/null +++ b/share/man/man9/mq_init.9 @@ -0,0 +1,229 @@ +.\" $OpenBSD: mq_init.9,v 1.1 2015/06/17 06:24:46 mpi Exp $ +.\" +.\" Copyright (c) 2015 David Gwynne +.\" +.\" 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 -- 2.20.1