xref: /openbsd-src/share/man/man9/kstat_create.9 (revision 139410fb3e68569c0361f09ac28029baf78c1fe9)

.\" $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