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