From owner-svn-src-stable@FreeBSD.ORG Mon Feb 6 13:26:13 2012 Return-Path: Delivered-To: svn-src-stable@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 7B406106575F; Mon, 6 Feb 2012 13:26:13 +0000 (UTC) (envelope-from brueffer@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 5F7D78FC18; Mon, 6 Feb 2012 13:26:13 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q16DQD9f037725; Mon, 6 Feb 2012 13:26:13 GMT (envelope-from brueffer@svn.freebsd.org) Received: (from brueffer@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id q16DQDZv037721; Mon, 6 Feb 2012 13:26:13 GMT (envelope-from brueffer@svn.freebsd.org) Message-Id: <201202061326.q16DQDZv037721@svn.freebsd.org> From: Christian Brueffer Date: Mon, 6 Feb 2012 13:26:13 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-8@freebsd.org X-SVN-Group: stable-8 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r231084 - stable/8/share/man/man9 X-BeenThere: svn-src-stable@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for all the -stable branches of the src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 06 Feb 2012 13:26:13 -0000 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 +.\" 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 +.\" 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 .