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