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