share/man/man9/counter.9

   1 .\"-
   2 .\" Copyright (c) 2013 Gleb Smirnoff <glebius@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 March 14, 2016
  29 .Dt COUNTER 9
  30 .Os
  31 .Sh NAME
  32 .Nm counter
  33 .Nd "SMP-friendly kernel counter implementation"
  34 .Sh SYNOPSIS
  35 .In sys/types.h
  36 .In sys/systm.h
  37 .In sys/counter.h
  38 .Ft counter_u64_t
  39 .Fn counter_u64_alloc "int wait"
  40 .Ft void
  41 .Fn counter_u64_free "counter_u64_t c"
  42 .Ft void
  43 .Fn counter_u64_add "counter_u64_t c" "int64_t v"
  44 .Ft void
  45 .Fn counter_enter
  46 .Ft void
  47 .Fn counter_exit
  48 .Ft void
  49 .Fn counter_u64_add_protected "counter_u64_t c" "int64_t v"
  50 .Ft uint64_t
  51 .Fn counter_u64_fetch "counter_u64_t c"
  52 .Ft void
  53 .Fn counter_u64_zero "counter_u64_t c"
  54 .In sys/sysctl.h
  55 .Fn SYSCTL_COUNTER_U64 parent nbr name access ptr descr
  56 .Fn SYSCTL_ADD_COUNTER_U64 ctx parent nbr name access ptr descr
  57 .Fn SYSCTL_COUNTER_U64_ARRAY parent nbr name access ptr len descr
  58 .Fn SYSCTL_ADD_COUNTER_U64_ARRAY ctx parent nbr name access ptr len descr
  59 .Sh DESCRIPTION
  60 .Nm
  61 is a generic facility to create counters
  62 that can be utilized for any purpose (such as collecting statistical
  63 data).
  64 A
  65 .Nm
  66 is guaranteed to be lossless when several kernel threads do simultaneous
  67 updates.
  68 However,
  69 .Nm
  70 does not block the calling thread,
  71 also no
  72 .Xr atomic 9
  73 operations are used for the update, therefore the counters
  74 can be used in any non-interrupt context.
  75 Moreover,
  76 .Nm
  77 has special optimisations for SMP environments, making
  78 .Nm
  79 update faster than simple arithmetic on the global variable.
  80 Thus
  81 .Nm
  82 is considered suitable for accounting in the performance-critical
  83 code paths.
  84 .Bl -tag -width indent
  85 .It Fn counter_u64_alloc wait
  86 Allocate a new 64-bit unsigned counter.
  87 The
  88 .Fa wait
  89 argument is the
  90 .Xr malloc 9
  91 wait flag, should be either
  92 .Va M_NOWAIT
  93 or
  94 .Va M_WAITOK .
  95 If
  96 .Va M_NOWAIT
  97 is specified the operation may fail.
  98 .It Fn counter_u64_free c
  99 Free the previously allocated counter
 100 .Fa c .
 101 .It Fn counter_u64_add c v
 102 Add
 103 .Fa v
 104 to
 105 .Fa c .
 106 The KPI does not guarantee any protection from wraparound.
 107 .It Fn counter_enter
 108 Enter mode that would allow to safely update several counters via
 109 .Fn counter_u64_add_protected .
 110 On some machines this expands to
 111 .Xr critical 9
 112 section, while on other is a nop.
 113 See
 114 .Sx IMPLEMENTATION DETAILS .
 115 .It Fn counter_exit
 116 Exit mode for updating several counters.
 117 .It Fn counter_u64_add_protected c v
 118 Same as
 119 .Fn counter_u64_add ,
 120 but should be preceded by
 121 .Fn counter_enter .
 122 .It Fn counter_u64_fetch c
 123 Take a snapshot of counter
 124 .Fa c .
 125 The data obtained is not guaranteed to reflect the real cumulative
 126 value for any moment.
 127 .It Fn counter_u64_zero c
 128 Clear the counter
 129 .Fa c
 130 and set it to zero.
 131 .It Fn SYSCTL_COUNTER_U64 parent nbr name access ptr descr
 132 Declare a static
 133 .Xr sysctl
 134 oid that would represent a
 135 .Nm .
 136 The
 137 .Fa ptr
 138 argument should be a pointer to allocated
 139 .Vt counter_u64_t .
 140 A read of the oid returns value obtained through
 141 .Fn counter_u64_fetch .
 142 Any write to the oid zeroes it.
 143 .It Fn SYSCTL_ADD_COUNTER_U64 ctx parent nbr name access ptr descr
 144 Create a
 145 .Xr sysctl
 146 oid that would represent a
 147 .Nm .
 148 The
 149 .Fa ptr
 150 argument should be a pointer to allocated
 151 .Vt counter_u64_t .
 152 A read of the oid returns value obtained through
 153 .Fn counter_u64_fetch .
 154 Any write to the oid zeroes it.
 155 .It Fn SYSCTL_COUNTER_U64_ARRAY parent nbr name access ptr len descr
 156 Declare a static
 157 .Xr sysctl
 158 oid that would represent an array of
 159 .Nm .
 160 The
 161 .Fa ptr
 162 argument should be a pointer to allocated array of
 163 .Vt counter_u64_t's .
 164 The
 165 .Fa len
 166 argument should specify number of elements in the array.
 167 A read of the oid returns len-sized array of
 168 .Vt uint64_t
 169 values  obtained through
 170 .Fn counter_u64_fetch .
 171 Any write to the oid zeroes all array elements.
 172 .It Fn SYSCTL_ADD_COUNTER_U64_ARRAY ctx parent nbr name access ptr len descr
 173 Create a
 174 .Xr sysctl
 175 oid that would represent an array of
 176 .Nm .
 177 The
 178 .Fa ptr
 179 argument should be a pointer to allocated array of
 180 .Vt counter_u64_t's .
 181 The
 182 .Fa len
 183 argument should specify number of elements in the array.
 184 A read of the oid returns len-sized array of
 185 .Vt uint64_t
 186 values obtained through
 187 .Fn counter_u64_fetch .
 188 Any write to the oid zeroes all array elements.
 189 .El
 190 .Sh IMPLEMENTATION DETAILS
 191 On all architectures
 192 .Nm
 193 is implemented using per-CPU data fields that are specially aligned
 194 in memory, to avoid inter-CPU bus traffic due to shared use
 195 of the variables between CPUs.
 196 These are allocated using
 197 .Va UMA_ZONE_PCPU
 198 .Xr uma 9
 199 zone.
 200 The update operation only touches the field that is private to current CPU.
 201 Fetch operation loops through all per-CPU fields and obtains a snapshot
 202 sum of all fields.
 203 .Pp
 204 On amd64 a
 205 .Nm counter
 206 update is implemented as a single instruction without lock semantics,
 207 operating on the private data for the current CPU,
 208 which is safe against preemption and interrupts.
 209 .Pp
 210 On i386 architecture, when machine supports the cmpxchg8 instruction,
 211 this instruction is used.
 212 The multi-instruction sequence provides the same guarantees as the
 213 amd64 single-instruction implementation.
 214 .Pp
 215 On some architectures updating a counter require a
 216 .Xr critical 9
 217 section.
 218 .Sh EXAMPLES
 219 The following example creates a static counter array exported to
 220 userspace through a sysctl:
 221 .Bd -literal -offset indent
 222 #define MY_SIZE 8
 223 static counter_u64_t array[MY_SIZE];
 224 SYSCTL_COUNTER_U64_ARRAY(_debug, OID_AUTO, counter_array, CTLFLAG_RW,
 225     &array[0], MY_SIZE, "Test counter array");
 226 .Ed
 227 .Pp
 228 .Sh SEE ALSO
 229 .Xr atomic 9 ,
 230 .Xr critical 9 ,
 231 .Xr locking 9 ,
 232 .Xr malloc 9 ,
 233 .Xr sysctl 9 ,
 234 .Xr uma 9
 235 .Sh HISTORY
 236 The
 237 .Nm
 238 facility first appeared in
 239 .Fx 10.0 .
 240 .Sh AUTHORS
 241 .An -nosplit
 242 The
 243 .Nm
 244 facility was written by
 245 .An Gleb Smirnoff
 246 and
 247 .An Konstantin Belousov .