1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
.\" $OpenBSD: kstat_create.9,v 1.7 2022/09/10 08:50:53 jsg Exp $
.\"
.\" Copyright (c) 2020 David Gwynne <dlg@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 10 2022 $
.Dt KSTAT_CREATE 9
.Os
.Sh NAME
.Nm kstat_create ,
.Nm kstat_read_nop ,
.Nm kstat_set_wlock ,
.Nm kstat_set_rlock ,
.Nm kstat_set_mutex ,
.Nm kstat_install ,
.Nm kstat_remove ,
.Nm kstat_destroy
.Nd kernel statistics provider API
.Sh SYNOPSIS
.In sys/kstat.h
.Ft struct kstat *
.Fo kstat_create
.Fa "const char *provider"
.Fa "unsigned int instance"
.Fa "const char *name"
.Fa "unsigned int unit"
.Fa "unsigned int type"
.Fa "unsigned int flags"
.Fc
.Ft int
.Fn kstat_read_nop "struct kstat *ks"
.Ft void
.Fn kstat_set_wlock "struct kstat *ks" "struct rwlock *rwl"
.Ft void
.Fn kstat_set_rlock "struct kstat *ks" "struct rwlock *rwl"
.Ft void
.Fn kstat_set_mutex "struct kstat *ks" "struct mutex *mtx"
.Ft void
.Fn kstat_install "struct kstat *ks"
.Ft void
.Fn kstat_remove "struct kstat *ks"
.Ft void
.Fn kstat_destroy "struct kstat *ks"
.Sh DESCRIPTION
Kernel subsystems can provide statistics to userland using the kernel
statistics (kstat) API.
.Pp
A kstat is uniquely identified by a tuple made up of the
.Fa provider ,
.Fa instances ,
.Fa name ,
and
.Fa unit
arguments.
.\" Once created, the kstat API allocates a unique 64bit identifier for
.\" the kstat.
.Pp
The information exported by a kstat is typed.
The supported kstat types are
.Bl -tag -width xxx -offset indent
.It Dv KSTAT_T_RAW
The kstat provides raw bytes.
.It Dv KSTAT_T_KV
The kstat provides a series of
.Vt struct kstat_kv
structures that represent key/value information.
See
.Xr kstat_kv_init 9
for more detail.
.El
.Pp
Below is a simplified version of the
.Vt kstat
structure that shows the fields that a subsystem operates on:
.Bd -literal
struct kstat {
void *ks_softc;
void *ks_ptr;
void *ks_data;
size_t ks_datalen;
struct timespec ks_updated;
int (*ks_read)(struct kstat *ks);
int (*ks_copy)(struct kstat *ks, void *dst);
const struct kstat_lock_ops *
ks_lock_ops;
void *ks_lock;
};
.Ed
.Pp
The
.Fa ks_softc
and
.Fa ks_ptr
fields are available for the subsystem providing the kstat to use.
For example, if a hardware device driver is providing a kstat then
.Fa ks_softc
can be initialised with a reference to the softc structure allocated
for that device driver.
.Fa ks_ptr
is intended for use by a subsystem to refer to data or state that
is only needed when providing the kstat which would not otherwise
be referenced by the provider.
.Pp
The
.Fa ks_datalen
field specifies how much data is exported by the kstat to userland.
.Pp
.Fa ks_updated
is set by the provider to the system uptime when the kstat data was
updated.
.Pp
.Fa ks_data
may be set to a data buffer used to store the kstat data payload.
.Pp
The
.Fa ks_read
handler is called by the kstat API when userland requests the current
kstat data.
A kstat provider may ignore the request via and update the data by
another process.
For example, a device may periodically update a set of statistics
and notify the kernel when the new statistics are available with
an interrupt.
Such a driver would update the kstat data and
.Fa ks_updated
when the interrupt is processed, and ignore the request to update
from userland.
The default
.Fa ks_read
handler sets
.Fa ks_updated
using
.Xr getnanouptime 9 .
.Pp
The
.Fa ks_copy
handler is used by the kstat API to copy the current kstat data into the
.Fa dst
buffer.
The default
.Fa ks_copy
handler uses
.Xr memcpy 3
to copy
.Fa ks_datalen
bytes from
.Fa ks_data
to
.Fa dst .
.Pp
Accesses to the above
.Vt kstat
structure fields and calls to the
.Fa ks_read
and
.Fa ks_copy
handlers by the kstat subsystem are serialised by the locking primitive
referenced by
.Fa ks_lock .
By default
.Fa ks_lock
references a global write lock provided by the kstat API,
but should be set to a provider specific lock with the
.Fa kstat_set_rlock ,
.Fa kstat_set_wlock ,
or
.Fa kstat_set_mutex
functions.
.Pp
The
.Fn kstat_create
function allocates a
.Vt kstat
structure and adds it to the list of statistics that userland can
query.
Once a
.Vt kstat
structure has been created,
the caller is responsible for initialising the structure.
.Pp
.Fn kstat_read_nop
can be used as a
.Fa ks_read
handler to ignore the request to update the kstat data and
.Fa ks_updated
timestamp.
.Pp
The
.Fn kstat_set_wlock
and
.Fn kstat_set_rlock
functions specifies that the
.Fa rwl
read/write lock should be used as an exclusive or shared lock
respectively by the kstat API when interacting with the provider.
.Pp
The
.Fn kstat_set_mutex
function specifies that the
.Fa mtx
mutex should be acquired by the kstat API when interacting with the
provider.
.Pp
After the structure has been initialised,
.Fn kstat_install
notifies the kstat subsystem that
.Fa ks
can be used to export information to userland.
.Pp
.Fn kstat_remove
disables the kstat, preventing it from being used to export information
to userland.
This allows allocations referenced by the kstat struct to be released
and configuration torn down before the kstat itself is freed with
.Fn kstat_destroy .
.Pp
.Fn kstat_destroy
removes
.Fa ks
from the list of exported statistics and frees it.
.Sh CONTEXT
.Fn kstat_create ,
.Fn kstat_install ,
.Fn kstat_remove ,
.Fn kstat_set_wlock ,
.Fn kstat_set_rlock ,
.Fn kstat_set_mutex ,
and
.Fn kstat_destroy
can be called during autoconf, or from process context.
They cannot be called by a
.Fa ks_read
or
.Fa ks_copy
handler.
.Sh RETURN VALUES
.Fn kstat_create
returns a pointer to a
.Vt kstat
structure on success, or
.Dv NULL
on failure.
.Sh SEE ALSO
.Xr kstat 1 ,
.Xr memcpy 3 ,
.Xr kstat 4 ,
.Xr kstat_kv_init 9 ,
.Xr mtx_enter 9 ,
.Xr rw_enter 9
.Sh HISTORY
These functions first appeared in
.Ox 6.8 .
.Sh AUTHORS
.An David Gwynne Aq Mt dlg@openbsd.org
|
