document the bits of the kstat struct that providers work with.

the kstat api is a small part of implementing a kstat, most of it
depends on how you set up the kstat struct.

1 files changed, 162 insertions, 23 deletions

diff --git a/share/man/man9/kstat_create.9 b/share/man/man9/kstat_create.9
index 3b95bba05be..2c2f335b2ba 100644
--- a/share/man/man9/kstat_create.9
+++ b/share/man/man9/kstat_create.9
@@ -1,4 +1,4 @@
-.\" $OpenBSD: kstat_create.9,v 1.5 2022/04/19 01:39:38 dlg Exp $
+.\" $OpenBSD: kstat_create.9,v 1.6 2022/04/19 03:51:47 dlg Exp $
 .\"
 .\" Copyright (c) 2020 David Gwynne <dlg@openbsd.org>
 .\"
@@ -19,9 +19,10 @@
 .Os
 .Sh NAME
 .Nm kstat_create ,
-.\" .Nm kstat_set_wlock ,
-.\" .Nm kstat_set_rlock ,
-.\" .Nm kstat_set_mutex ,
+.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
@@ -37,12 +38,14 @@
 .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 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
@@ -50,14 +53,9 @@
 .Ft void
 .Fn kstat_destroy "struct kstat *ks"
 .Sh DESCRIPTION
-Kernel subsystems can export statistics to userland using the kernel
+Kernel subsystems can provide statistics to userland using the kernel
 statistics (kstat) API.
 .Pp
-The
-.Fn kstat_create
-function allocates a
-.Vt 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 ,
@@ -65,9 +63,10 @@ A kstat is uniquely identified by a tuple made up of the
 and
 .Fa unit
 arguments.
-The type of information provided by the kstat is identified by the
-.Fa type
-argument.
+.\" 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
@@ -81,11 +80,141 @@ See
 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 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
@@ -107,12 +236,17 @@ from the list of exported statistics and frees it.
 .Fn kstat_create ,
 .Fn kstat_install ,
 .Fn kstat_remove ,
-.\" .Fn kstat_set_wlock ,
-.\" .Fn kstat_set_rlock ,
-.\" .Fn kstat_set_mutex ,
+.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
@@ -121,7 +255,12 @@ structure on success, or
 .Dv NULL
 on failure.
 .Sh SEE ALSO
-.Xr kstat_kv_init 9
+.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 .