1.\" Copyright (c) 2009 Bitgravity Inc 2.\" Written by: Kip Macy <kmacy@@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd September 27, 2012 27.Dt DRBR 9 28.Os 29.Sh NAME 30.Nm drbr , 31.Nm drbr_free , 32.Nm drbr_enqueue , 33.Nm drbr_dequeue , 34.Nm drbr_dequeue_cond , 35.Nm drbr_flush , 36.Nm drbr_empty , 37.Nm drbr_inuse 38.Nd network driver interface to buf_ring 39.Sh SYNOPSIS 40.In sys/param.h 41.In net/if.h 42.In net/if_var.h 43.Ft void 44.Fn drbr_free "struct buf_ring *br" "struct malloc_type *type" 45.Ft int 46.Fn drbr_enqueue "struct ifnet *ifp" "struct buf_ring *br" "struct mbuf *m" 47.Ft struct mbuf * 48.Fn drbr_dequeue "struct ifnet *ifp" "struct buf_ring *br" 49.Ft struct mbuf * 50.Fn drbr_dequeue_cond "struct ifnet *ifp" "struct buf_ring *br" "int (*func) (struct mbuf *, void *)" "void *arg" 51.Ft void 52.Fn drbr_flush "struct ifnet *ifp" "struct buf_ring *br" 53.Ft int 54.Fn drbr_empty "struct ifnet *ifp" "struct buf_ring *br" 55.Ft int 56.Fn drbr_inuse "struct ifnet *ifp" "struct buf_ring *br" 57.Sh DESCRIPTION 58The 59.Nm 60functions provide an API to network drivers for using 61.Xr buf_ring 9 62for enqueueing and dequeueing packets. 63This is meant as a replacement for the IFQ interface for packet queuing. 64It allows a packet to be enqueued with a single atomic and packet 65dequeue to be done without any per-packet atomics as it is protected 66by the driver's tx queue lock. 67If 68.Dv INVARIANTS 69is enabled, 70.Fn drbr_dequeue 71will assert that the tx queue lock is held when it is called. 72.Pp 73The 74.Fn drbr_free 75function frees all the enqueued mbufs and then frees the buf_ring. 76.Pp 77The 78.Fn drbr_enqueue 79function is used to enqueue an mbuf to a buf_ring, falling back to the 80ifnet's IFQ if 81.Xr ALTQ 4 82is enabled. 83.Pp 84The 85.Fn drbr_dequeue 86function is used to dequeue an mbuf from a buf_ring or, if 87.Xr ALTQ 4 88is enabled, from the ifnet's IFQ. 89.Pp 90The 91.Fn drbr_dequeue_cond 92function is used to conditionally dequeue an mbuf from a buf_ring based 93on whether 94.Fa func 95returns 96.Dv TRUE 97or 98.Dv FALSE . 99.Pp 100The 101.Fn drbr_flush 102function frees all mbufs enqueued in the buf_ring and the ifnet's IFQ. 103.Pp 104The 105.Fn drbr_empty 106function returns 107.Dv TRUE 108if there are no mbufs enqueued, 109.Dv FALSE 110otherwise. 111.Pp 112The 113.Fn drbr_inuse 114function returns the number of mbufs enqueued. 115Note to users that this is intrinsically racy as there is no guarantee that 116there will not be more mbufs when 117.Fn drbr_dequeue 118is actually called. 119Provided the tx queue lock is held there will not be less. 120.Sh RETURN VALUES 121The 122.Fn drbr_enqueue 123function returns 124.Er ENOBUFS 125if there are no slots available in the buf_ring and 126.Dv 0 127on success. 128.Pp 129The 130.Fn drbr_dequeue 131and 132.Fn drbr_dequeue_cond 133functions return an mbuf on success and 134.Dv NULL 135if the buf_ring is empty. 136.Sh HISTORY 137These functions were introduced in 138.Fx 8.0 . 139