share/man/man9/drbr.9

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