1.\" $OpenBSD: mq_init.9,v 1.11 2020/01/23 07:12:42 jmc 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: January 23 2020 $ 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_enlist , 25.Nm mq_delist , 26.Nm mq_dechain , 27.Nm mq_len , 28.Nm mq_empty , 29.Nm mq_full , 30.Nm mq_hdatalen , 31.Nm mq_purge , 32.Nm mq_drops , 33.Nm mq_set_maxlen , 34.Nm MBUF_QUEUE_INITIALIZER 35.Nd mbuf queue API 36.Sh SYNOPSIS 37.In sys/mbuf.h 38.Ft void 39.Fn mq_init "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl" 40.Ft int 41.Fn mq_enqueue "struct mbuf_queue *mq" "struct mbuf *m" 42.Ft struct mbuf * 43.Fn mq_dequeue "struct mbuf_queue *mq" 44.Ft int 45.Fn mq_enlist "struct mbuf_queue *mq" "struct mbuf_list *ml" 46.Ft void 47.Fn mq_delist "struct mbuf_queue *mq" "struct mbuf_list *ml" 48.Ft struct mbuf * 49.Fn mq_dechain "struct mbuf_queue *mq" 50.Ft unsigned int 51.Fn mq_len "struct mbuf_queue *mq" 52.Ft int 53.Fn mq_empty "struct mbuf_queue *mq" 54.Ft int 55.Fn mq_full "struct mbuf_queue *mq" 56.Ft unsigned int 57.Fn mq_hdatalen "struct mbuf_queue *mq" 58.Ft unsigned int 59.Fn mq_purge "struct mbuf_queue *mq" 60.Ft unsigned int 61.Fn mq_drops "struct mbuf_queue *mq" 62.Ft void 63.Fn mq_set_maxlen "struct mbuf_queue *mq" "unsigned int" 64.Ft struct mbuf_queue 65.Fn MBUF_QUEUE_INITIALIZER "unsigned int maxlen" "int ipl" 66.Sh DESCRIPTION 67The mbuf queue API provides implementions of data structures and operations 68for queueing mbufs and lists of mbufs between contexts. 69.Pp 70mbuf_queue data structures provide a superset of the functionality 71available in mbuf_lists, and protect themselves internally with a 72.Xr mutex 9 , 73making them useful for moving mbufs between contexts or subsystems. 74Additionally, mbuf_queues provide a limit on the number of mbufs that 75may be queued. 76.Pp 77mbuf_queue structures support the following functionality: 78.Pp 79.Bl -enum -compact -offset indent 80.It 81Insertion of a new mbuf at the end of the queue. 82.It 83Removal of an mbuf from the head of the queue. 84.It 85Reinsertion of an mbuf at the head of the queue. 86.It 87Removal of the entire chain of mbufs on the queue. 88.It 89Insertion of the mbufs in an mbuf_list at the end of the queue. 90.It 91Removal of all the mbufs on the queue as an mbuf_list. 92.El 93.Bl -tag -width Ds 94.It Fn mq_init "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl" 95Initialises the mbuf queue structure 96.Fa mq . 97The maximum number of mbufs that should be queued is specified with 98.Fa maxlen . 99The highest interrupt priority level the queue will be operated at is 100specified via 101.Fa ipl . 102.It Fn MBUF_QUEUE_INITIALIZER "unsigned int maxlen" "int ipl" 103Initialises an mbuf queue structure declaration. 104The maximum number of mbufs that should be queued is specified with 105.Fa maxlen . 106The highest interrupt priority level the queue will be operated at is 107specified via 108.Fa ipl . 109.It Fn mq_enqueue "struct mbuf_queue *mq" "struct mbuf *m" 110Enqueue mbuf 111.Fa m 112on the end of the 113.Fa mq 114mbuf queue. 115.It Fn mq_dequeue "struct mbuf_queue *mq" 116Dequeue an mbuf from the front of the 117.Fa mq 118mbuf queue. 119.It Fn mq_enlist "struct mbuf_queue *mq" "struct mbuf_list *ml" 120Enqueue all the mbufs on the 121.Fa ml 122mbuf list on to the end of the 123.Fa mq 124mbuf queue. 125Note, the number of mbufs placed on the queue may exceed its maximum length. 126.It Fn mq_delist "struct mbuf_queue *mq" "struct mbuf_list *ml" 127Dequeue all the mbufs on the 128.Fa mq 129mbuf queue on to the 130.Fa ml 131mbuf list. 132.It Fn mq_dechain "struct mbuf_queue *mq" 133Dequeue all mbufs from the 134.Fa mq 135mbuf queue. 136.It Fn mq_len "struct mbuf_queue *mq" 137Return the number of mbufs on the 138.Fa mq 139mbuf queue. 140.It Fn mq_empty "struct mbuf_queue *mq" 141Return if the 142.Fa mq 143mbuf queue is empty. 144.It Fn mq_full "struct mbuf_queue *mq" 145Return if the 146.Fa mq 147mbuf queue is full. 148.It Fn mq_hdatalen "struct mbuf_queue *mq" 149Return the number of bytes in the packet at the head of the 150.Fa mq 151mbuf queue. 152.It Fn mq_purge "struct mbuf_queue *mq" 153Free all the mbufs on the 154.Fa mq 155mbuf queue. 156.It Fn mq_drops "struct mbuf_queue *mq" 157Return how many mbufs were dropped and freed by 158.Xr m_freem 9 159if the 160.Fa mq 161mbuf queue was too full. 162.It Fn mq_set_maxlen "struct mbuf_queue *mq" "unsigned int" 163Alter the maximum number of mbufs that should be queued on the 164.Fa mq 165mbuf queue. 166Note, 167.Fn mq_set_maxlen 168will only set a new limit, it will not free any excess mbufs that may 169already exist on the queue. 170.El 171.Sh CONTEXT 172.Fn mq_init , 173.Fn mq_enqueue , 174.Fn mq_dequeue , 175.Fn mq_enlist , 176.Fn mq_delist , 177.Fn mq_dechain , 178.Fn mq_len , 179.Fn mq_empty , 180.Fn mq_full , 181.Fn mq_purge , 182.Fn mq_drops , 183.Fn mq_set_maxlen , 184and 185.Fn MBUF_QUEUE_INITIALIZER 186can be called during autoconf, from process context, or from interrupt context. 187.Sh RETURN VALUES 188.Fn mq_dequeue 189returns the mbuf that was at the head of its queue. 190If the queue was empty, 191.Dv NULL 192is returned. 193.Pp 194.Fn mq_dechain 195returns all the mbufs that were on its queues via a pointer to an mbuf 196with the chain accessible via m_nextpkt members. 197If the queue was empty, 198.Dv NULL 199is returned. 200.Pp 201.Fn mq_len 202returns the number of mbufs on the queue. 203.Pp 204.Fn mq_empty 205returns a non-zero value if the queue is empty, otherwise 0. 206.Pp 207.Fn mq_full 208returns a non-zero value if the queue is full, otherwise 0. 209.Pp 210.Fn mq_enqueue 211returns 0 if the mbuf was successfully queued, or non-zero if the 212mbuf was freed because it would cause the queue to exceed its maximum 213length. 214.Pp 215.Fn mq_enlist 216returns the number of mbufs that were dropped from the list if the 217length of the queue exceeded its maximum length. 218.Pp 219.Fn mq_hdatalen 220returns the size of a packet on the queue, or 0 if the queue is empty. 221.Pp 222.Fn mq_purge 223returns the number of mbufs that were freed. 224.Pp 225.Fn mq_drops 226returns the number of mbufs that were freed during 227.Fn mq_enqueue 228operations that would have caused the queue to exceed its maximum length. 229.Sh SEE ALSO 230.Xr mbuf 9 , 231.Xr ml_init 9 , 232.Xr mutex 9 233