1.\" $OpenBSD: ifq_enqueue.9,v 1.13 2022/03/31 17:27:23 naddy 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: March 31 2022 $ 18.Dt IFQ_ENQUEUE 9 19.Os 20.Sh NAME 21.Nm ifq_enqueue , 22.Nm ifq_dequeue , 23.Nm ifq_purge , 24.Nm ifq_len , 25.Nm ifq_empty , 26.Nm ifq_hdatalen , 27.Nm ifq_set_oactive , 28.Nm ifq_clr_oactive , 29.Nm ifq_is_oactive , 30.Nm ifq_restart , 31.Nm ifq_barrier 32.Nd interface send queue API 33.Sh SYNOPSIS 34.In net/if_var.h 35.Ft int 36.Fn ifq_enqueue "struct ifqueue *ifq" "struct mbuf *m" 37.Ft struct mbuf * 38.Fn ifq_dequeue "struct ifqueue *ifq" 39.Ft unsigned int 40.Fn ifq_purge "struct ifqueue *ifq" 41.Ft unsigned int 42.Fn ifq_len "struct ifqueue *ifq" 43.Ft unsigned int 44.Fn ifq_empty "struct ifqueue *ifq" 45.Ft int 46.Fn ifq_hdatalen "struct ifqueue *ifq" 47.Ft void 48.Fn ifq_set_oactive "struct ifqueue *ifq" 49.Ft void 50.Fn ifq_clr_oactive "struct ifqueue *ifq" 51.Ft unsigned int 52.Fn ifq_is_oactive "struct ifqueue *ifq" 53.Ft void 54.Fn ifq_restart "struct ifqueue *ifq" 55.Ft void 56.Fn ifq_barrier "struct ifqueue *ifq" 57.Sh DESCRIPTION 58The ifqueue API provides implementations of data structures and 59operations for the network stack to queue mbufs for a network driver 60to dequeue from its start routine for transmission. 61.Bl -tag -width Ds 62.It Fn ifq_enqueue "struct ifqueue *ifq" "struct mbuf *m" 63Enqueue mbuf 64.Fa m 65on the 66.Fa ifq 67interface send queue. 68If the queue rejects the packet, it will be freed with 69.Xr m_freem 9 70and counted as a drop. 71.It Fn ifq_dequeue "struct ifqueue *ifq" 72Dequeue the next mbuf to be transmitted from the 73.Fa ifq 74interface send queue. 75.It Fn ifq_purge "struct ifqueue *ifq" 76Free all the mbufs on the interface send queue 77.Fa ifq . 78Freed mbufs will be accounted as drops. 79.It Fn ifq_len "struct ifqueue *ifq" 80Return the number of mbufs on the interface send queue 81.Fa ifq . 82Note that while 83.Fn ifq_len 84may report that mbufs are on the queue, the current queue 85discipline may not make them available for dequeueing with 86.Fn ifq_dequeue 87or 88.Fn ifq_deq_begin . 89.It Fn ifq_empty "struct ifqueue *ifq" 90Return if the interface send queue 91.Fa ifq 92is empty. 93.It Fn ifq_hdatalen "struct ifqueue *ifq" 94Return the number of bytes in the mbuf at the head of the interface 95send queue 96.Fa ifq . 97.It Fn ifq_set_oactive "struct ifqueue *ifq" 98.Fn ifq_set_oactive 99is called by the relevant driver to mark the hardware associated 100with the interface send queue 101.Fa ifq 102as unable to transmit more packets. 103.It Fn ifq_clr_oactive "struct ifqueue *ifq" 104.Fn ifq_clr_oactive 105is called by the relevant driver to clear the "active" mark on the 106hardware associated with the interface send queue 107.Fa ifq , 108meaning it is now able to transmit packets. 109.It Fn ifq_is_oactive "struct ifqueue *ifq" 110Return if the hardware associated with the interface send queue 111.Fa ifq 112is unable to transmit more packets. 113.It Fn ifq_restart "struct ifqueue *ifq" 114Dispatch a call to 115.Fn ifq_clr_oactive 116and the interface's start routine. 117This call is serialised with other calls to the start routine via 118.Fn if_start 119and therefore provides race free modification of the "active" mark. 120.It Fn ifq_barrier "struct ifqueue *ifq" 121.Fn ifq_barrier 122guarantees that any work currently running in the interface queue 123serialiser (e.g. work dispatched by 124.Fn ifq_restart 125or the interface's start routine) has finished before 126.Fn ifq_barrier 127returns. 128.El 129.Sh CONTEXT 130.Fn ifq_enqueue , 131.Fn ifq_dequeue , 132.Fn ifq_purge , 133.Fn ifq_len , 134.Fn ifq_empty , 135.Fn ifq_hdatalen , 136.Fn ifq_set_oactive , 137.Fn ifq_clr_oactive , 138.Fn ifq_is_oactive , 139and 140.Fn ifq_restart 141can be called during autoconf, from process context, or from interrupt context. 142.Pp 143.Fn ifq_barrier 144can be called from process context. 145.Sh RETURN VALUES 146.Fn ifq_enqueue 147returns 0 if the mbuf was successfully queued, or non-zero if mbuf was freed. 148.Pp 149.Fn ifq_dequeue 150returns the next mbuf to be transmitted by the interface. 151If no packet is available for transmission, 152.Dv NULL 153is returned. 154.Pp 155.Fn ifq_purge 156returns the number of mbufs that were removed from the queue and freed. 157.Pp 158.Fn ifq_len 159returns the number of mbufs on the queue. 160.Pp 161.Fn ifq_empty 162returns a non-zero value if the queue is empty, otherwise 0. 163.Pp 164.Fn ifq_hdatalen 165returns the size of a packet on the queue, or 0 if the queue is empty; 166.Pp 167.Fn ifq_is_oactive 168returns a non-zero value if the hardware associated with the interface 169send queue is unable to transmit more packets, otherwise 0. 170.Sh SEE ALSO 171.Xr ifq_deq_begin 9 , 172.Xr m_freem 9 173