Skip site navigation (1)Skip section navigation (2)
Date:      Mon, 6 Feb 2012 13:26:13 +0000 (UTC)
From:      Christian Brueffer <brueffer@FreeBSD.org>
To:        src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-8@freebsd.org
Subject:   svn commit: r231084 - stable/8/share/man/man9
Message-ID:  <201202061326.q16DQDZv037721@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: brueffer
Date: Mon Feb  6 13:26:12 2012
New Revision: 231084
URL: http://svn.freebsd.org/changeset/base/231084

Log:
  MFC: r230787
  
  Manpages for the buf_ring and drbr interfaces.

Added:
  stable/8/share/man/man9/buf_ring.9
     - copied unchanged from r230787, head/share/man/man9/buf_ring.9
  stable/8/share/man/man9/drbr.9
     - copied unchanged from r230787, head/share/man/man9/drbr.9
Modified:
  stable/8/share/man/man9/Makefile
Directory Properties:
  stable/8/share/man/man9/   (props changed)

Modified: stable/8/share/man/man9/Makefile
==============================================================================
--- stable/8/share/man/man9/Makefile	Mon Feb  6 13:17:57 2012	(r231083)
+++ stable/8/share/man/man9/Makefile	Mon Feb  6 13:26:12 2012	(r231084)
@@ -13,6 +13,7 @@ MAN=	accept_filter.9 \
 	boot.9 \
 	bpf.9 \
 	buf.9 \
+	buf_ring.9 \
 	BUF_ISLOCKED.9 \
 	BUF_LOCK.9 \
 	BUF_LOCKFREE.9 \
@@ -100,6 +101,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 bpf_filter.9 \
 	bpf.9 bpfattach2.9 \
 	bpf.9 bpfdetach.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
@@ -605,6 +617,14 @@ MLINKS+=domain.9 DOMAIN_SET.9 \
 	domain.9 pffindproto.9 \
 	domain.9 pffindtype.9
 MLINKS+=DRIVER_MODULE.9 MULTI_DRIVER_MODULE.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/8/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/8/share/man/man9/buf_ring.9	Mon Feb  6 13:26:12 2012	(r231084, copy of r230787, head/share/man/man9/buf_ring.9)
@@ -0,0 +1,144 @@
+.\" 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 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/8/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/8/share/man/man9/drbr.9	Mon Feb  6 13:26:12 2012	(r231084, 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 .



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201202061326.q16DQDZv037721>