1.\" $OpenBSD: mq_init.9,v 1.2 2015/08/14 05:25:29 dlg Exp $ 2.\" 3.\" Copyright (c) 2015 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: August 14 2015 $ 18.Dt MQ_INIT 9 19.Os 20.Sh NAME 21.Nm mq_init , 22.Nm mq_enqueue , 23.Nm mq_dequeue , 24.Nm mq_requeue , 25.Nm mq_enlist , 26.Nm mq_delist , 27.Nm mq_dechain , 28.Nm mq_len , 29.Nm mq_empty , 30.Nm mq_drops , 31.Nm mq_set_maxlen , 32.Nm MBUF_QUEUE_INITIALIZER 33.Nd mbuf queue API 34.Sh SYNOPSIS 35.In sys/mbuf.h 36.Fn "mq_init" "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl" 37.Ft int 38.Fn "mq_enqueue" "struct mbuf_queue *mq" "struct mbuf *m" 39.Ft struct mbuf * 40.Fn "mq_dequeue" "struct mbuf_queue *mq" 41.Ft int 42.Fn "mq_requeue" "struct mbuf_queue *mq" "struct mbuf *m" 43.Ft int 44.Fn "mq_enlist" "struct mbuf_queue *mq" "struct mbuf_list *ml" 45.Ft void 46.Fn "mq_delist" "struct mbuf_queue *mq" "struct mbuf_list *ml" 47.Ft struct mbuf * 48.Fn "mq_dechain" "struct mbuf_queue *mq" 49.Ft struct mbuf * 50.Fo mq_filter 51.Fa "struct mbuf_queue *mq" 52.Fa "int (*filter)(void *, struct mbuf *)" 53.Fa "void *context" 54.Fc 55.Ft unsigned int 56.Fn "mq_len" "struct mbuf_queue *mq" 57.Ft int 58.Fn "mq_empty" "struct mbuf_queue *mq" 59.Ft unsigned int 60.Fn "mq_drops" "struct mbuf_queue *mq" 61.Ft void 62.Fn "mq_set_maxlen" "struct mbuf_queue *mq" "unsigned int" 63.Ft struct mbuf_queue 64.Fn "MBUF_QUEUE_INITIALIZER" "unsigned int maxlen" "int ipl" 65.Sh DESCRIPTION 66The mbuf queue API provides implementions of data structures and operations 67for queueing mbufs and lists of mbufs between contexts. 68.Pp 69mbuf_queue data structures provide a superset of the functionality 70available in mbuf_lists, and protect themselves internally with a 71.Xr mutex 9 , 72making them useful for moving mbufs between contexts or subsystems. 73Additionally, mbuf_queues provide a limit on the number of mbufs that 74may be queued. 75.Pp 76mbuf_queue structures support the following functionality: 77.Pp 78.Bl -enum -compact -offset indent 79.It 80Insertion of a new mbuf at the end of the queue. 81.It 82Removal of an mbuf from the head of the queue. 83.It 84Reinsertion of an mbuf at the head of the queue. 85.It 86Removal of the entire chain of mbufs on the queue. 87.It 88Insertion of the mbufs in an mbuf_list at the end of the queue. 89.It 90Removal of all the mbufs on the queue as an mbuf_list. 91.El 92.Bl -tag -width Ds 93.It Fn "mq_init" "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl" 94Initialises the mbuf queue structure 95.Fa mq . 96The maximum number of mbufs that should be queued is specified with 97.Fa maxlen . 98The highest interrupt priority level the queue will be operated at is 99specified via 100.Fa ipl . 101.It Fn "MBUF_QUEUE_INITIALIZER" "unsigned int maxlen" "int ipl" 102Initialises an mbuf queue structure declaration. 103The maximum number of mbufs that should be queued is specified with 104.Fa maxlen . 105The highest interrupt priority level the queue will be operated at is 106specified via 107.Fa ipl . 108.It Fn "mq_enqueue" "struct mbuf_queue *mq" "struct mbuf *m" 109Enqueue mbuf 110.Fa m 111on the end of the 112.Fa mq 113mbuf queue. 114.It Fn "mq_dequeue" "struct mbuf_queue *mq" 115Dequeue an mbuf from the front of the 116.Fa mq 117mbuf queue. 118.It Fn "mq_requeue" "struct mbuf_queue *mq" "struct mbuf *m" 119Enqueue mbuf 120.Fa m 121at the head of the 122.Fa mq 123mbuf queue. 124Note, this operation will succeed even if it will cause the queue to exceed its 125maximum length. 126.It Fn "mq_enlist" "struct mbuf_queue *mq" "struct mbuf_list *ml" 127Enqueue all the mbufs on the 128.Fa ml 129mbuf list on to the end of the 130.Fa mq 131mbuf queue. 132Note, the number of mbufs placed on the queue may exceed its maximum length. 133.It Fn "mq_delist" "struct mbuf_queue *mq" "struct mbuf_list *ml" 134Dequeue all the mbufs on the 135.Fa mq 136mbuf queue on to the 137.Fa ml 138mbuf list. 139.It Fn "mq_dechain" "struct mbuf_queue *mq" 140Dequeue all mbufs from the 141.Fa mq 142mbuf queue. 143.It Fo mq_filter 144.Fa "struct mbuf_queue *mq" 145.Fa "int (*filter)(void *, struct mbuf *)" 146.Fa "void *context" 147.Fc 148Iterates over the mbufs on the 149.Fa mq 150mbuf queue, passing each of them to the 151.Fa filter 152function. 153If the 154.Fa filter 155returns non-zero, the packet is removed from the 156.Fa mq 157mbuf queue to be returned as part of an mbuf chain by 158.Fn mq_filter . 159.Fa context 160is passed as the first argument to each call of 161.Fa filter . 162.It Fn "mq_len" "struct mbuf_queue *mq" 163Return the number of mbufs on the 164.Fa mq 165mbuf queue. 166.It Fn "mq_empty" "struct mbuf_queue *mq" 167Return if the 168.Fa mq 169mbuf queue is empty. 170.It Fn "mq_drops" "struct mbuf_queue *mq" 171Return how many mbufs were dropped and freed by 172.Xr m_freem 9 173if the 174.Fa mq 175mbuf queue was too full. 176.It Fn "mq_set_maxlen" "struct mbuf_queue *mq" "unsigned int" 177Alter the maximum number of mbufs that should be queued on the 178.Fa mq 179mbuf queue. 180Note, 181.Fn mq_set_maxlen 182will only set a new limit, it will not free any excess mbufs that may 183already exist on the queue. 184.El 185.Sh CONTEXT 186.Fn mq_init , 187.Fn mq_enqueue , 188.Fn mq_dequeue , 189.Fn mq_requeue , 190.Fn mq_enlist , 191.Fn mq_delist , 192.Fn mq_dechain , 193.Fn mq_len , 194.Fn mq_empty , 195.Fn mq_drops , 196.Fn mq_set_maxlen , 197and 198.Fn MBUF_QUEUE_INITIALIZER 199can be called during autoconf, from process context, or from interrupt context. 200.Sh RETURN VALUES 201.Fn mq_dequeue 202returns the mbuf that was at the head of its queue. 203If the queue was empty, 204.Dv NULL 205is returned. 206.Pp 207.Fn mq_dechain 208returns all the mbufs that were on its queues via a pointer to an mbuf 209with the chain accessible via m_nextpkt members. 210If the queue was empty, 211.Dv NULL 212is returned. 213.Pp 214.Fn mq_filter 215returns the mbufs that were successfully matched by the filter 216function on the queue via a pointer to a chain of mbufs. 217If no packets matched the filter, 218.Dv NULL 219is returned. 220.Pp 221.Fn mq_len 222returns the number of mbufs on the queue. 223.Pp 224.Fn mq_empty 225returns a non-zero value if the queue is empty, otherwise 0. 226.Pp 227.Fn mq_enqueue 228returns 0 if the mbuf was successfully queued, or non-zero if the 229mbuf was freed because it would cause the queue to exceed its maximum 230length. 231.Pp 232.Fn mq_requeue 233returns non-zero if the mbuf queue is now full, otherwise 0. 234length. 235.Pp 236.Fn mq_enlist 237returns the number of mbufs that were dropped from the list if the 238length of the queue exceeded its maximum length. 239.Pp 240.Fn mq_drops 241returns the number of mbufs that were freed during 242.Fn mq_enqueue 243operations that would have caused the queue to exceed its maximum length. 244.Sh SEE ALSO 245.Xr mbuf 9 , 246.Xr ml_init 9 , 247.Xr mutex 9 248