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