svn commit: r231081 - stable/9/share/man/man9
Christian Brueffer
brueffer at FreeBSD.org
Mon Feb 6 13:12:31 UTC 2012
Author: brueffer
Date: Mon Feb 6 13:12:30 2012
New Revision: 231081
URL: http://svn.freebsd.org/changeset/base/231081
Log:
MFC: r230787
Manpages for the buf_ring and drbr interfaces.
Added:
stable/9/share/man/man9/buf_ring.9
- copied unchanged from r230787, head/share/man/man9/buf_ring.9
stable/9/share/man/man9/drbr.9
- copied unchanged from r230787, head/share/man/man9/drbr.9
Modified:
stable/9/share/man/man9/Makefile
Directory Properties:
stable/9/share/man/man9/ (props changed)
Modified: stable/9/share/man/man9/Makefile
==============================================================================
--- stable/9/share/man/man9/Makefile Mon Feb 6 12:08:41 2012 (r231080)
+++ stable/9/share/man/man9/Makefile Mon Feb 6 13:12:30 2012 (r231081)
@@ -12,6 +12,7 @@ MAN= accept_filter.9 \
boot.9 \
bpf.9 \
buf.9 \
+ buf_ring.9 \
BUF_ISLOCKED.9 \
BUF_LOCK.9 \
BUF_LOCKFREE.9 \
@@ -99,6 +100,7 @@ MAN= accept_filter.9 \
devtoname.9 \
disk.9 \
domain.9 \
+ drbr.9 \
driver.9 \
DRIVER_MODULE.9 \
EVENTHANDLER.9 \
@@ -408,6 +410,16 @@ MLINKS+=bpf.9 bpfattach.9 \
bpf.9 bpf_tap.9 \
bpf.9 bpf_validate.9
MLINKS+=buf.9 bp.9
+MLINKS+=buf_ring.9 buf_ring_alloc.9 \
+ buf_ring.9 buf_ring_free.9 \
+ buf_ring.9 buf_ring_enqueue.9 \
+ buf_ring.9 buf_ring_enqueue_bytes.9 \
+ buf_ring.9 buf_ring_dequeue_mc.9 \
+ buf_ring.9 buf_ring_dequeue_sc.9 \
+ buf_ring.9 buf_ring_count.9 \
+ buf_ring.9 buf_ring_empty.9 \
+ buf_ring.9 buf_ring_full.9 \
+ buf_ring.9 buf_ring_peek.9
MLINKS+=bus_activate_resource.9 bus_deactivate_resource.9
MLINKS+=bus_alloc_resource.9 bus_alloc_resource_any.9
MLINKS+=BUS_BIND_INTR.9 bus_bind_intr.9
@@ -606,6 +618,14 @@ MLINKS+=domain.9 DOMAIN_SET.9 \
domain.9 pfctlinput2.9 \
domain.9 pffindproto.9 \
domain.9 pffindtype.9
+MLINKS+=drbr.9 drbr_free.9 \
+ drbr.9 drbr_enqueue.9 \
+ drbr.9 drbr_dequeue.9 \
+ drbr.9 drbr_dequeue_cond.9 \
+ drbr.9 drbr_flush.9 \
+ drbr.9 drbr_empty.9 \
+ drbr.9 drbr_inuse.9 \
+ drbr.9 drbr_stats_update.9
MLINKS+=EVENTHANDLER.9 EVENTHANDLER_DECLARE.9 \
EVENTHANDLER.9 EVENTHANDLER_DEREGISTER.9 \
EVENTHANDLER.9 eventhandler_deregister.9 \
Copied: stable/9/share/man/man9/buf_ring.9 (from r230787, head/share/man/man9/buf_ring.9)
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ stable/9/share/man/man9/buf_ring.9 Mon Feb 6 13:12:30 2012 (r231081, copy of r230787, head/share/man/man9/buf_ring.9)
@@ -0,0 +1,144 @@
+.\" Copyright (c) 2009 Bitgravity Inc
+.\" Written by: Kip Macy <kmacy at FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd January 30, 2012
+.Dt BUF_RING 9
+.Os
+.Sh NAME
+.Nm buf_ring ,
+.Nm buf_ring_alloc ,
+.Nm buf_ring_free ,
+.Nm buf_ring_enqueue ,
+.Nm buf_ring_enqueue_bytes ,
+.Nm buf_ring_dequeue_mc ,
+.Nm buf_ring_dequeue_sc ,
+.Nm buf_ring_count ,
+.Nm buf_ring_empty ,
+.Nm buf_ring_full ,
+.Nm buf_ring_peek ,
+.Nd multi-producer, {single, multi}-consumer lock-less ring buffer
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/buf_ring.h
+.Ft struct buf_ring *
+.Fn buf_ring_alloc "int count" "struct malloc_type *type" "int flags" "struct mtx *sc_lock"
+.Ft void
+.Fn buf_ring_free "struct buf_ring *br" "struct malloc_type *type"
+.Ft int
+.Fn buf_ring_enqueue "struct buf_ring *br" "void *buf"
+.Ft int
+.Fn buf_ring_enqueue_bytes "struct buf_ring *br" "void *buf" "int bytes"
+.Ft void *
+.Fn buf_ring_dequeue_mc "struct buf_ring *br"
+.Ft void *
+.Fn buf_ring_dequeue_sc "struct buf_ring *br"
+.Ft int
+.Fn buf_ring_count "struct buf_ring *br"
+.Ft int
+.Fn buf_ring_empty "struct buf_ring *br"
+.Ft int
+.Fn buf_ring_full "struct buf_ring *br"
+.Ft void *
+.Fn buf_ring_peek "struct buf_ring *br"
+.Sh DESCRIPTION
+The
+.Nm
+functions provide a lock-less multi-producer and lock-less multi-consumer as
+well as single-consumer ring buffer.
+.Pp
+The
+.Fn buf_ring_alloc
+function is used to allocate a buf_ring ring buffer with
+.Fa count
+slots using malloc_type
+.Fa type
+and memory flags
+.Fa flags .
+The single consumer interface is protected by
+.Fa sc_lock .
+.Pp
+The
+.Fn buf_ring_free
+function is used to free a buf_ring.
+The user is responsible for freeing any enqueued items.
+.Pp
+The
+.Fn buf_ring_enqueue
+function is used to enqueue a buffer to a buf_ring.
+.Pp
+The
+.Fn buf_ring_enqueue_bytes
+function is used to enqueue a buffer to a buf_ring and increment the
+number of bytes enqueued by
+.Fa bytes .
+.Pp
+The
+.Fn buf_ring_dequeue_mc
+function is a multi-consumer safe way of dequeueing elements from a buf_ring.
+.Pp
+The
+.Fn buf_ring_dequeue_sc
+function is a single-consumer interface to dequeue elements - requiring
+the user to serialize accesses with a lock.
+.Pp
+The
+.Fn buf_ring_count
+function returns the number of elements in a buf_ring.
+.Pp
+The
+.Fn buf_ring_empty
+function returns
+.Dv TRUE
+if the buf_ring is empty,
+.Dv FALSE
+otherwise.
+.Pp
+The
+.Fn buf_ring_full
+function returns
+.Dv TRUE
+if no more items can be enqueued,
+.Dv FALSE
+otherwise.
+.Pp
+The
+.Fn buf_ring_peek
+function returns a pointer to the last element in the buf_ring if the
+buf_ring is not empty,
+.Dv NULL
+otherwise.
+.Sh RETURN VALUES
+The
+.Fn buf_ring_enqueue
+and
+.Fn buf_ring_enqueue_bytes
+functions return
+.Er ENOBUFS
+if there are no available slots in the buf_ring.
+.Sh HISTORY
+These functions were introduced in
+.Fx 8.0 .
Copied: stable/9/share/man/man9/drbr.9 (from r230787, head/share/man/man9/drbr.9)
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ stable/9/share/man/man9/drbr.9 Mon Feb 6 13:12:30 2012 (r231081, copy of r230787, head/share/man/man9/drbr.9)
@@ -0,0 +1,147 @@
+.\" Copyright (c) 2009 Bitgravity Inc
+.\" Written by: Kip Macy <kmacy@@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd January 30, 2012
+.Dt DRBR 9
+.Os
+.Sh NAME
+.Nm drbr ,
+.Nm drbr_free ,
+.Nm drbr_enqueue ,
+.Nm drbr_dequeue ,
+.Nm drbr_dequeue_cond ,
+.Nm drbr_flush ,
+.Nm drbr_empty ,
+.Nm drbr_inuse ,
+.Nm drbr_stats_update ,
+.Nd network driver interface to buf_ring
+.Sh SYNOPSIS
+.In sys/param.h
+.In net/if.h
+.In net/if_var.h
+.Ft void
+.Fn drbr_free "struct buf_ring *br" "struct malloc_type *type"
+.Ft int
+.Fn drbr_enqueue "struct ifnet *ifp" "struct buf_ring *br" "struct mbuf *m"
+.Ft struct mbuf *
+.Fn drbr_dequeue "struct ifnet *ifp" "struct buf_ring *br"
+.Ft struct mbuf *
+.Fn drbr_dequeue_cond "struct ifnet *ifp" "struct buf_ring *br" "int (*func) (struct mbuf *, void *)" "void *arg"
+.Ft void
+.Fn drbr_flush "struct ifnet *ifp" "struct buf_ring *br"
+.Ft int
+.Fn drbr_empty "struct ifnet *ifp" "struct buf_ring *br"
+.Ft int
+.Fn drbr_inuse "struct ifnet *ifp" "struct buf_ring *br"
+.Ft void
+.Fn drbr_stats_update "struct ifnet *ifp" "int len" "int mflags"
+.Sh DESCRIPTION
+The
+.Nm
+functions provide an API to network drivers for using
+.Xr buf_ring 9
+for enqueueing and dequeueing packets.
+This is meant as a replacement for the IFQ interface for packet queuing.
+It allows a packet to be enqueued with a single atomic and packet
+dequeue to be done without any per-packet atomics as it is protected
+by the driver's tx queue lock.
+If
+.Dv INVARIANTS
+is enabled,
+.Fn drbr_dequeue
+will assert that the tx queue lock is held when it is called.
+.Pp
+The
+.Fn drbr_free
+function frees all the enqueued mbufs and then frees the buf_ring.
+.Pp
+The
+.Fn drbr_enqueue
+function is used to enqueue an mbuf to a buf_ring, falling back to the
+ifnet's IFQ if
+.Xr ALTQ 4
+is enabled.
+.Pp
+The
+.Fn drbr_dequeue
+function is used to dequeue an mbuf from a buf_ring or, if
+.Xr ALTQ 4
+is enabled, from the ifnet's IFQ.
+.Pp
+The
+.Fn drbr_dequeue_cond
+function is used to conditionally dequeue an mbuf from a buf_ring based
+on whether
+.Fa func
+returns
+.Dv TRUE
+or
+.Dv FALSE .
+.Pp
+The
+.Fn drbr_flush
+function frees all mbufs enqueued in the buf_ring and the ifnet's IFQ.
+.Pp
+The
+.Fn drbr_empty
+function returns
+.Dv TRUE
+if there are no mbufs enqueued,
+.Dv FALSE
+otherwise.
+.Pp
+The
+.Fn drbr_inuse
+function returns the number of mbufs enqueued.
+Note to users that this is intrinsically racy as there is no guarantee that
+there will not be more mbufs when
+.Fn drbr_dequeue
+is actually called.
+Provided the tx queue lock is held there will not be less.
+.Pp
+The
+.Fn drbr_stats_update
+function updates the number of bytes and the number of multicast packets sent.
+.Sh RETURN VALUES
+The
+.Fn drbr_enqueue
+function returns
+.Er ENOBUFS
+if there are no slots available in the buf_ring and
+.Dv 0
+on success.
+.Pp
+The
+.Fn drbr_dequeue
+and
+.Fn drbr_dequeue_cond
+functions return an mbuf on success and
+.Dv NULL
+if the buf_ring is empty.
+.Sh HISTORY
+These functions were introduced in
+.Fx 8.0 .
More information about the svn-src-stable-9
mailing list