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.\" $FreeBSD$ 27.\" 28.Dd September 27, 2012 29.Dt DRBR 9 30.Os 31.Sh NAME 32.Nm drbr , 33.Nm drbr_free , 34.Nm drbr_enqueue , 35.Nm drbr_dequeue , 36.Nm drbr_dequeue_cond , 37.Nm drbr_flush , 38.Nm drbr_empty , 39.Nm drbr_inuse 40.Nd network driver interface to buf_ring 41.Sh SYNOPSIS 42.In sys/param.h 43.In net/if.h 44.In net/if_var.h 45.Ft void 46.Fn drbr_free "struct buf_ring *br" "struct malloc_type *type" 47.Ft int 48.Fn drbr_enqueue "struct ifnet *ifp" "struct buf_ring *br" "struct mbuf *m" 49.Ft struct mbuf * 50.Fn drbr_dequeue "struct ifnet *ifp" "struct buf_ring *br" 51.Ft struct mbuf * 52.Fn drbr_dequeue_cond "struct ifnet *ifp" "struct buf_ring *br" "int (*func) (struct mbuf *, void *)" "void *arg" 53.Ft void 54.Fn drbr_flush "struct ifnet *ifp" "struct buf_ring *br" 55.Ft int 56.Fn drbr_empty "struct ifnet *ifp" "struct buf_ring *br" 57.Ft int 58.Fn drbr_inuse "struct ifnet *ifp" "struct buf_ring *br" 59.Sh DESCRIPTION 60The 61.Nm 62functions provide an API to network drivers for using 63.Xr buf_ring 9 64for enqueueing and dequeueing packets. 65This is meant as a replacement for the IFQ interface for packet queuing. 66It allows a packet to be enqueued with a single atomic and packet 67dequeue to be done without any per-packet atomics as it is protected 68by the driver's tx queue lock. 69If 70.Dv INVARIANTS 71is enabled, 72.Fn drbr_dequeue 73will assert that the tx queue lock is held when it is called. 74.Pp 75The 76.Fn drbr_free 77function frees all the enqueued mbufs and then frees the buf_ring. 78.Pp 79The 80.Fn drbr_enqueue 81function is used to enqueue an mbuf to a buf_ring, falling back to the 82ifnet's IFQ if 83.Xr ALTQ 4 84is enabled. 85.Pp 86The 87.Fn drbr_dequeue 88function is used to dequeue an mbuf from a buf_ring or, if 89.Xr ALTQ 4 90is enabled, from the ifnet's IFQ. 91.Pp 92The 93.Fn drbr_dequeue_cond 94function is used to conditionally dequeue an mbuf from a buf_ring based 95on whether 96.Fa func 97returns 98.Dv TRUE 99or 100.Dv FALSE . 101.Pp 102The 103.Fn drbr_flush 104function frees all mbufs enqueued in the buf_ring and the ifnet's IFQ. 105.Pp 106The 107.Fn drbr_empty 108function returns 109.Dv TRUE 110if there are no mbufs enqueued, 111.Dv FALSE 112otherwise. 113.Pp 114The 115.Fn drbr_inuse 116function returns the number of mbufs enqueued. 117Note to users that this is intrinsically racy as there is no guarantee that 118there will not be more mbufs when 119.Fn drbr_dequeue 120is actually called. 121Provided the tx queue lock is held there will not be less. 122.Sh RETURN VALUES 123The 124.Fn drbr_enqueue 125function returns 126.Er ENOBUFS 127if there are no slots available in the buf_ring and 128.Dv 0 129on success. 130.Pp 131The 132.Fn drbr_dequeue 133and 134.Fn drbr_dequeue_cond 135functions return an mbuf on success and 136.Dv NULL 137if the buf_ring is empty. 138.Sh HISTORY 139These functions were introduced in 140.Fx 8.0 . 141