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