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