diff options
Diffstat (limited to 'share')
| -rw-r--r-- | share/man/man9/Makefile | 5 | ||||
| -rw-r--r-- | share/man/man9/kstat_create.9 | 107 | ||||
| -rw-r--r-- | share/man/man9/kstat_kv_init.9 | 108 |
3 files changed, 218 insertions, 2 deletions
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 56f29251b7b..7b494dc20de 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.304 2020/06/26 21:08:29 sthen Exp $ +# $OpenBSD: Makefile,v 1.305 2020/07/06 11:48:03 dlg Exp $ # $NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $ # Makefile for section 9 (kernel function and variable) manual pages. @@ -22,7 +22,8 @@ MAN= aml_evalnode.9 atomic_add_int.9 atomic_cas_uint.9 \ ifiq_input.9 ifq_enqueue.9 \ ifq_deq_begin.9 imax.9 iic.9 intro.9 inittodr.9 \ intr_barrier.9 intrmap_create.9 \ - KASSERT.9 km_alloc.9 knote.9 kthread.9 ktrace.9 \ + KASSERT.9 km_alloc.9 knote.9 kstat_create.9 kstat_kv_init.9 \ + kthread.9 ktrace.9 \ lim_cur.9 loadfirmware.9 log.9 \ malloc.9 membar_sync.9 memcmp.9 mbuf.9 mbuf_tags.9 md5.9 mi_switch.9 \ microtime.9 ml_init.9 mq_init.9 mutex.9 \ diff --git a/share/man/man9/kstat_create.9 b/share/man/man9/kstat_create.9 new file mode 100644 index 00000000000..b879aa9dedc --- /dev/null +++ b/share/man/man9/kstat_create.9 @@ -0,0 +1,107 @@ +.\" $OpenBSD: kstat_create.9,v 1.1 2020/07/06 11:48:03 dlg 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: July 6 2020 $ +.Dt KSTAT_CREATE 9 +.Os +.Sh NAME +.Nm kstat_create , +.\" .Nm kstat_set_wlock , +.\" .Nm kstat_set_rlock , +.\" .Nm kstat_set_mutex , +.Nm kstat_install , +.Nm kstat_destroy +.Nd kernel statistics provider API +.Sh SYNOPSIS +.In sys/kstat.h +.Ft struct kstat * +.Fo kstatap_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 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_destroy "struct kstat *ks" +.Sh DESCRIPTION +Kernel subsystems can export statistics to userland using the kernel +statistics (kstat) API. +.Pp +The +.Fn kstat_create +function allocates a kstat structure and adds it to the list of statistics that userland can query. +A kstat is uniquely identified by a tuple made up of the +.Fa provider , +.Fa instances , +.Fa name , +and +.Fa unit +arguments. +The type of information provided by the kstat is identified by the +.Fa type +argument. +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 +Once a kstat structure has been created, the caller is responsible for initialising the structure. +.Pp +After the structure has been initialised, +.Fn kstat_install +notifies the kstat subsystem that the kstat structure +.Fa ks +can be used to export information to userland. +.Pp +.Fn kstat_destroy +removes the +.Fa ks + kstat structure from the list of exported statistics and frees it. +.\" might want a kstat_remove... +.Sh CONTEXT +.Fn kstat_create , +.Fn kstat_install , +.\" .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. +.Sh RETURN VALUES +.Fn kstat_create +returns a pointer to an kstat structure on success, of +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr kstat_kv_init 9 diff --git a/share/man/man9/kstat_kv_init.9 b/share/man/man9/kstat_kv_init.9 new file mode 100644 index 00000000000..94fd78bca46 --- /dev/null +++ b/share/man/man9/kstat_kv_init.9 @@ -0,0 +1,108 @@ +.\" $OpenBSD: kstat_kv_init.9,v 1.1 2020/07/06 11:48:03 dlg 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: July 6 2020 $ +.Dt KSTAT_KV_INIT 9 +.Os +.Sh NAME +.Nm kstat_kv_init , +.Nm kstat_kv_unit_init , +.Nm KSTAT_KV_INITIALIZER , +.Nm KSTAT_KV_UNIT_INITIALIZER +.Nd kernel statistic key/value data API +.Sh SYNOPSIS +.In sys/kstat.h +.Ft void +.Fo kstat_kv_init +.Fa "struct kstat_kv *kv" +.Fa "const char *key" +.Fa "enum kstat_kv_type type" +.Fc +.Ft void +.Fo kstat_kv_unit_init +.Fa "struct kstat_kv *kv" +.Fa "const char *key" +.Fa "enum kstat_kv_type type" +.Fa "enum kstat_kv_unit unit" +.Fc +.Fo KSTAT_KV_INITIALIZER +.Fa "const char *name" +.Fa "enum kstat_kv_type type" +.Fc +.Fo KSTAT_KV_UNIT_INITIALIZER +.Fa "const char *name" +.Fa "enum kstat_kv_type type" +.Fa "enum kstat_kv_unit unit" +.Fc +.Sh DESCRIPTION +The kstat key/value data API supports the creation and maintenance +of kstat_kv structures that can be exported to userland using the +kstat API. +.Pp +A kstat key/value data payload for a kstat structure +.Po +created using +.Xr kstat_create 9 +with +.Dv KSTAT_T_KV +as the +.Fa type +argument +.Pc +is a series of kstat_kv structures in memory. +kstat_kv values are typed, and the memory used to store values of +different types is either inline as part of the structure, or is +extra bytes following a structure of a specified length. +.\" .Pp +.\" kstat_kv structures contain the following fields: +.Pp +.Fn kstat_kv_init +initialises the kstat_kv structure +.Fa kv +with a name specified as +.Fa key . +The type of the value is specified as +.Fa type . +.Pp +.Fn kstat_kv_unit_init +initialises the kstat_kv structure +.Fa kv +with a name specified as +.Fa key . +The integer or counter type of the value is specified as +.Fa type , +and specifies the units for the values in +.Fa unit . +.Pp +A kstat_kv structure can be initialised at compile time with the +.Fn KSTAT_KV_INITIALIZER +macro. +The kstat_kv structure will be declared with the name +.Fa key +with the type of the values as +.Fa type . +.Pp +A kstat_kv structure can be initialised at compile time with the +.Fn KSTAT_KV_UNIT_INITIALIZER +macro. +The kstat_kv structure will be declared with the name +.Fa key +with the integer or counter type of the values as +.Fa type , +and specifies the units for the values in +.Fa unit . +.Sh SEE ALSO +.Xr kstat_create 9 |