KSTAT_CREATE(9) FreeBSD Kernel Developer's Manual KSTAT_CREATE(9)
NAME
kstat_create, kstat_read_nop, kstat_set_wlock, kstat_set_rlock,
kstat_set_mutex, kstat_install, kstat_remove, kstat_destroy - kernel
statistics provider API
SYNOPSIS
#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);
DESCRIPTION
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
KSTAT_T_RAW
The kstat provides raw bytes.
KSTAT_T_KV
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 kstat_create() 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.
kstat_read_nop() can be used as a ks_read handler to ignore the request
to update the kstat data and ks_updated timestamp.
The kstat_set_wlock() and kstat_set_rlock() 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 kstat_set_mutex() function specifies that the mtx mutex should be
acquired by the kstat API when interacting with the provider.
After the structure has been initialised, kstat_install() notifies the
kstat subsystem that ks can be used to export information to userland.
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 kstat_destroy().
kstat_destroy() removes ks from the list of exported statistics and frees
it.
CONTEXT
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.
RETURN VALUES
kstat_create() returns a pointer to a kstat structure on success, or NULL
on failure.
SEE ALSO
kstat(1), memcpy(3), kstat(4), kstat_kv_init(9), mtx_enter(9),
rw_enter(9)
HISTORY
These functions first appeared in OpenBSD 6.8.
AUTHORS
David Gwynne <
[email protected]>
FreeBSD 14.1-RELEASE-p8 September 10, 2022 FreeBSD 14.1-RELEASE-p8