KSTAT_CREATE(9F) Kernel Functions for Drivers KSTAT_CREATE(9F)


NAME


kstat_create - create and initialize a new kstat

SYNOPSIS


#include <sys/types.h>
#include <sys/kstat.h>


kstat_t *kstat_create(const char *ks_module, int ks_instance,
const char *ks_name, const char *ks_class, uchar_t ks_type,
ulong_t ks_ndata, uchar_t ks_flag);


INTERFACE LEVEL


Solaris DDI specific (Solaris DDI)

PARAMETERS


ks_module
The name of the provider's module (such as "sd", "esp",
...). The "core" kernel uses the name "unix".


ks_instance
The provider's instance number, as from
ddi_get_instance(9F). Modules which do not have a
meaningful instance number should use 0.


ks_name
A pointer to a string that uniquely identifies this
structure. Only KSTAT_STRLEN - 1 characters are
significant.


ks_class
The general class that this kstat belongs to. The
following classes are currently in use: disk, tape, net,
controller, vm, kvm, hat, streams, kstat, and misc.


ks_type
The type of kstat to allocate. Valid types are:

KSTAT_TYPE_RAW
Raw data; allows more than one data
record per kstat.


KSTAT_TYPE_NAMED
Name=value pairs; allows more than one
data record per kstat.


KSTAT_TYPE_INTR
Interrupt; only one data record per
kstat.


KSTAT_TYPE_IO
I/O; only one data record per kstat.


KSTAT_TYPE_TIMER
Event timer statistics; allows more
than one data record per kstat.


ks_ndata
The number of type-specific data records to allocate.


ks_flag
A bit-field of various flags for this kstat. ks_flag is
some combination of:

KSTAT_FLAG_VIRTUAL
Tells kstat_create() not to
allocate memory for the kstat
data section; instead, the driver
will set the ks_data field to
point to the data it wishes to
export. This provides a
convenient way to export existing
data structures.


KSTAT_FLAG_WRITABLE
Makes the kstat data section
writable by root.


KSTAT_FLAG_PERSISTENT
Indicates that this kstat is to
be persistent over time. For
persistent kstats,
kstat_delete(9F) simply marks the
kstat as dormant; a subsequent
kstat_create() reactivates the
kstat. This feature is provided
so that statistics are not lost
across driver close/open (such as
raw disk I/O on a disk with no
mounted partitions.) Note:
Persistent kstats cannot be
virtual, since ks_data points to
garbage as soon as the driver
goes away.


DESCRIPTION


kstat_create() is used in conjunction with kstat_install(9F) to allocate
and initialize a kstat(9S) structure. The method is generally as follows:


kstat_create() allocates and performs necessary system initialization of
a kstat(9S) structure. kstat_create() allocates memory for the entire
kstat (header plus data), initializes all header fields, initializes the
data section to all zeroes, assigns a unique kstat ID (KID), and puts the
kstat onto the system's kstat chain. The returned kstat is marked invalid
because the provider (caller) has not yet had a chance to initialize the
data section.


After a successful call to kstat_create() the driver must perform any
necessary initialization of the data section (such as setting the name
fields in a kstat of type KSTAT_TYPE_NAMED). Virtual kstats must have the
ks_data field set at this time. The provider may also set the ks_update,
ks_private, and ks_lock fields if necessary.


Once the kstat is completely initialized, kstat_install(9F) is used to
make the kstat accessible to the outside world.

RETURN VALUES


If successful, kstat_create() returns a pointer to the allocated kstat.
NULL is returned upon failure.

CONTEXT


kstat_create() can be called from user or kernel context.

EXAMPLES


Example 1: Allocating and Initializing a kstat Structure



pkstat_t *ksp;
ksp = kstat_create(module, instance, name, class, type, ndata, flags);
if (ksp) {
/* ... provider initialization, if necessary */
kstat_install(ksp);
}


SEE ALSO


kstat(3KSTAT), ddi_get_instance(9F), kstat_delete(9F), kstat_install(9F),
kstat_named_init(9F), kstat(9S), kstat_named(9S)


Writing Device Drivers


September 7, 2015 KSTAT_CREATE(9F)