diff options
Diffstat (limited to 'static/openbsd/man9/kstat_create.9')
| -rw-r--r-- | static/openbsd/man9/kstat_create.9 | 268 |
1 files changed, 268 insertions, 0 deletions
diff --git a/static/openbsd/man9/kstat_create.9 b/static/openbsd/man9/kstat_create.9 new file mode 100644 index 00000000..f17112ee --- /dev/null +++ b/static/openbsd/man9/kstat_create.9 @@ -0,0 +1,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 |