OpenBSD manual page server

Manual Page Search Parameters
KSTAT_CREATE(9) Kernel Developer's Manual KSTAT_CREATE(9)

kstat_create, kstat_read_nop, kstat_set_wlock, kstat_set_rlock, kstat_set_mutex, kstat_install, kstat_remove, kstat_destroy — kernel statistics provider API

#include <sys/kstat.h>

struct kstat *
kstat_create(const char *provider, unsigned int instance, const char *name, unsigned int unit, unsigned int type, unsigned int flags);

int
kstat_read_nop(struct kstat *ks);

void
kstat_set_wlock(struct kstat *ks, struct rwlock *rwl);

void
kstat_set_rlock(struct kstat *ks, struct rwlock *rwl);

void
kstat_set_mutex(struct kstat *ks, struct mutex *mtx);

void
kstat_install(struct kstat *ks);

void
kstat_remove(struct kstat *ks);

void
kstat_destroy(struct kstat *ks);

Kernel subsystems can provide statistics to userland using the kernel statistics (kstat) API.

A kstat is uniquely identified by a tuple made up of the provider, instances, name, and unit arguments.

The information exported by a kstat is typed. The supported kstat types are

The kstat provides raw bytes.
The kstat provides a series of struct kstat_kv structures that represent key/value information. See kstat_kv_init(9) for more detail.

Below is a simplified version of the kstat structure that shows the fields that a subsystem operates on:

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;
};

The ks_softc and 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 ks_softc can be initialised with a reference to the softc structure allocated for that device driver. 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.

The ks_datalen field specifies how much data is exported by the kstat to userland.

ks_updated is set by the provider to the system uptime when the kstat data was updated.

ks_data may be set to a data buffer used to store the kstat data payload.

The 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 ks_updated when the interrupt is processed, and ignore the request to update from userland. The default ks_read handler sets ks_updated using getnanouptime(9).

The ks_copy handler is used by the kstat API to copy the current kstat data into the dst buffer. The default ks_copy handler uses memcpy(3) to copy ks_datalen bytes from ks_data to dst.

Accesses to the above kstat structure fields and calls to the ks_read and ks_copy handlers by the kstat subsystem are serialised by the locking primitive referenced by ks_lock. By default ks_lock references a global write lock provided by the kstat API, but should be set to a provider specific lock with the kstat_set_rlock, kstat_set_wlock, or kstat_set_mutex functions.

The () function allocates a kstat structure and adds it to the list of statistics that userland can query. Once a kstat structure has been created, the caller is responsible for initialising the structure.

() can be used as a ks_read handler to ignore the request to update the kstat data and ks_updated timestamp.

The () and () functions specifies that the rwl read/write lock should be used as an exclusive or shared lock respectively by the kstat API when interacting with the provider.

The () function specifies that the mtx mutex should be acquired by the kstat API when interacting with the provider.

After the structure has been initialised, () notifies the kstat subsystem that ks can be used to export information to userland.

() 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 kstat_destroy().

() removes ks from the list of exported statistics and frees it.

kstat_create(), kstat_install(), kstat_remove(), kstat_set_wlock(), kstat_set_rlock(), kstat_set_mutex(), and kstat_destroy() can be called during autoconf, or from process context. They cannot be called by a ks_read or ks_copy handler.

kstat_create() returns a pointer to a kstat structure on success, or NULL on failure.

kstat(1), memcpy(3), kstat(4), kstat_kv_init(9), mtx_enter(9), rw_enter(9)

These functions first appeared in OpenBSD 6.8.

David Gwynne <dlg@openbsd.org>

September 10, 2022 OpenBSD-current