From owner-svn-src-projects@FreeBSD.ORG Sun Mar 17 19:13:14 2013 Return-Path: Delivered-To: svn-src-projects@freebsd.org Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id A313BA35; Sun, 17 Mar 2013 19:13:14 +0000 (UTC) (envelope-from glebius@FreeBSD.org) Received: from cell.glebius.int.ru (glebius.int.ru [81.19.69.10]) by mx1.freebsd.org (Postfix) with ESMTP id 0744DE59; Sun, 17 Mar 2013 19:13:12 +0000 (UTC) Received: from cell.glebius.int.ru (localhost [127.0.0.1]) by cell.glebius.int.ru (8.14.6/8.14.6) with ESMTP id r2HJDB1o063829; Sun, 17 Mar 2013 23:13:11 +0400 (MSK) (envelope-from glebius@FreeBSD.org) Received: (from glebius@localhost) by cell.glebius.int.ru (8.14.6/8.14.6/Submit) id r2HJDBvU063828; Sun, 17 Mar 2013 23:13:11 +0400 (MSK) (envelope-from glebius@FreeBSD.org) X-Authentication-Warning: cell.glebius.int.ru: glebius set sender to glebius@FreeBSD.org using -f Date: Sun, 17 Mar 2013 23:13:11 +0400 From: Gleb Smirnoff To: src-committers@freebsd.org, svn-src-projects@freebsd.org Subject: Re: svn commit: r248438 - projects/counters/share/man/man9 Message-ID: <20130317191311.GW48089@FreeBSD.org> References: <201303171912.r2HJC1nF016954@svn.freebsd.org> MIME-Version: 1.0 Content-Type: text/plain; charset=koi8-r Content-Disposition: inline In-Reply-To: <201303171912.r2HJC1nF016954@svn.freebsd.org> User-Agent: Mutt/1.5.21 (2010-09-15) X-BeenThere: svn-src-projects@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the src " projects" tree" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 17 Mar 2013 19:13:14 -0000 On Sun, Mar 17, 2013 at 07:12:01PM +0000, Gleb Smirnoff wrote: T> Author: glebius T> Date: Sun Mar 17 19:12:01 2013 T> New Revision: 248438 T> URL: http://svnweb.freebsd.org/changeset/base/248438 T> T> Log: T> Document counter(9). Native speakers review requested. Feel free to commit any wording fixes without my approvement. T> Added: T> projects/counters/share/man/man9/counter.9 (contents, props changed) T> Modified: T> projects/counters/share/man/man9/Makefile T> T> Modified: projects/counters/share/man/man9/Makefile T> ============================================================================== T> --- projects/counters/share/man/man9/Makefile Sun Mar 17 18:49:11 2013 (r248437) T> +++ projects/counters/share/man/man9/Makefile Sun Mar 17 19:12:01 2013 (r248438) T> @@ -51,6 +51,7 @@ MAN= accept_filter.9 \ T> config_intrhook.9 \ T> contigmalloc.9 \ T> copy.9 \ T> + counter.9 \ T> cr_cansee.9 \ T> critical_enter.9 \ T> cr_seeothergids.9 \ T> @@ -569,6 +570,12 @@ MLINKS+=copy.9 copyin.9 \ T> copy.9 copyout.9 \ T> copy.9 copyout_nofault.9 \ T> copy.9 copystr.9 T> +MLINKS+=counter.9 counter_u64_alloc.9 \ T> + counter.9 counter_u64_free.9 \ T> + counter.9 counter_u64_inc.9 \ T> + counter.9 counter_u64_dec.9 \ T> + counter.9 counter_u64_fetch.9 \ T> + counter.9 counter_u64_zero.9 T> MLINKS+=critical_enter.9 critical.9 \ T> critical_enter.9 critical_exit.9 T> MLINKS+=crypto.9 crypto_dispatch.9 \ T> T> Added: projects/counters/share/man/man9/counter.9 T> ============================================================================== T> --- /dev/null 00:00:00 1970 (empty, because file is newly added) T> +++ projects/counters/share/man/man9/counter.9 Sun Mar 17 19:12:01 2013 (r248438) T> @@ -0,0 +1,179 @@ T> +.\" Copyright (c) 2013 Gleb Smirnoff T> +.\" All rights reserved. T> +.\" T> +.\" Redistribution and use in source and binary forms, with or without T> +.\" modification, are permitted provided that the following conditions T> +.\" are met: T> +.\" 1. Redistributions of source code must retain the above copyright T> +.\" notice, this list of conditions and the following disclaimer. T> +.\" 2. Redistributions in binary form must reproduce the above copyright T> +.\" notice, this list of conditions and the following disclaimer in the T> +.\" documentation and/or other materials provided with the distribution. T> +.\" T> +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND T> +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE T> +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE T> +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE T> +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL T> +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS T> +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) T> +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT T> +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY T> +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF T> +.\" SUCH DAMAGE. T> +.\" T> +.\" $FreeBSD$ T> +.\" T> +.Dd March 17, 2013 T> +.Dt COUNTER 9 T> +.Os T> +.Sh NAME T> +.Nm counter T> +.Nd "generic kernel counter implementation" T> +.Sh SYNOPSIS T> +.In sys/types.h T> +.In sys/counter.h T> +.Ft counter_u64_t T> +.Fn counter_u64_alloc "int wait" T> +.Ft void T> +.Fn counter_u64_free "counter_u64_t cnt" T> +.Ft void T> +.Fn counter_u64_inc "counter_u64_t cnt" "uint64_t inc" T> +.Ft void T> +.Fn counter_u64_dec "counter_u64_t cnt "uint64_t dec" T> +.Ft uint64_t T> +.Fn counter_u64_fetch "counter_u64_t cnt" T> +.Ft void T> +.Fn counter_u64_zero "counter_u64_t cnt" T> +.In sys/sysctl.h T> +.Fn SYSCTL_COUNTER_U64 parent nbr name access ptr val descr T> +.Fn SYSCTL_ADD_COUNTER_U64 ctx parent nbr name access ptr descr T> +.Sh DESCRIPTION T> +The T> +.Nm T> +is a generic facility, which allows to create counters, T> +that can be utilized to collect statistical data or for other purposes. T> +A T> +.Nm T> +is guaranteed to be lossless when several kernel threads do simultaneous T> +update. T> +However, T> +.Nm T> +does not imply any T> +.Xr locking 9 , T> +neither any T> +.Xr atomic 9 T> +operations, thus are expected to be fast. T> +Moreover, T> +.Nm T> +has special optimisations for SMP environment making T> +.Nm T> +update faster than simple "+=" or "++" operation. T> +.Bl -tag -width indent T> +.It Fn counter_u64_alloc how T> +Allocate a new 64-bit unsigned counter. T> +The T> +.Fa wait T> +argument is T> +.Xr malloc 9 T> +wait flag, should be either T> +.Va M_NOWAIT T> +or T> +.Va M_WAITOK . T> +With no-wait semantics operation may fail. T> +.It Fn counter_u64_free cnt T> +Free previously allocated T> +.Nm T> +.Fa cnt . T> +.It Fn counter_u64_inc cnt inc T> +Add value of T> +.Fa inc T> +to T> +.Nm T> +.Fa cnt . T> +.It Fn counter_u64_dec cnt dec T> +Subtract value of T> +.Fa dec T> +from T> +.Nm T> +.Fa cnt . T> +API doesn't guarantee any protection from underflow. T> +See T> +.Sx IMPLEMENTATION DETAILS . T> +.It Fn counter_u64_fetch cnt T> +Obtain current snapshot of the data collected in T> +.Nm T> +.Fa cnt . T> +The data obtained isn't guaranteed to be precise. T> +.It Fn counter_u64_zero cnt T> +Clear data collected in T> +.Nm T> +.Fa cnt T> +and set its value to zero. T> +.It Fn SYSCTL_COUNTER_U64 parent nbr name access ptr val descr T> +Declare a static T> +.Xr sysctl T> +oid that would represent a T> +.Nm . T> +The T> +.Fa ptr T> +argument should be a pointer to allocated T> +.Vt counter_u64_t . T> +Any read of oid returns value obtained through T> +.Fn counter_u64_fetch . T> +Any write to oid zeroes it. T> +.It Fn SYSCTL_ADD_COUNTER_U64 ctx parent nbr name access ptr descr T> +Create a T> +.Xr sysctl T> +oid that would represent a T> +.Nm . T> +The T> +.Fa ptr T> +argument should be a pointer to allocated T> +.Vt counter_u64_t . T> +Any read of oid returns value obtained through T> +.Fn counter_u64_fetch . T> +Any write to oid zeroes it. T> +.El T> +.Sh IMPLEMENTATION DETAILS T> +On all architectures T> +.Nm T> +is implemented using per-CPU data fields, that are specially aligned in T> +memory, to avoid excessive CPU cache invalidation during updates. T> +These are allocated using T> +.Va UMA_ZONE_PCPU T> +.Xr uma 9 T> +zone. T> +Update operation touches only the field that is private to current CPU. T> +Fetch operation loops through all per-CPU fields and obtains a snapshot T> +sum of all fields. T> +.Pp T> +On amd64 a T> +.Nm counter T> +update is implemented as a single instruction without lock semantics. T> +.Pp T> +On i386 with cmpxchg8 instruction available, this instruction is used. T> +.Pp T> +On some architectures updating a counter require a T> +.Xr critical 9 T> +section. T> +.Sh SEE ALSO T> +.Xr atomic 9 , T> +.Xr critical 9 , T> +.Xr locking 9 , T> +.Xr malloc 9 , T> +.Xr sysctl , T> +.Xr uma 9 T> +.Sh HISTORY T> +The T> +.Nm T> +facility first appeared in T> +.Fx 10.0 . T> +.Sh AUTHORS T> +.An -nosplit T> +The T> +.Nm T> +facility was written by T> +.An Gleb Smirnoff T> +and T> +.An Konstantin Belousov . -- Totus tuus, Glebius.