make a very quick and dirty pass on a manpage for the kstat api.

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