Kernel Functions for Drivers kstatcreate(9F)
NAME
kstatcreate - create and initialize a new kstat
SYNOPSIS
#include
#include
kstatt *kstatcreate(const char *ksmodule, int ksinstance,
const char *ksname, const char *ksclass, uchart kstype,
ulongt ksndata, uchart ksflag);
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
PARAMETERS
ksmodule The name of the provider's module (such as
"sd", "esp", ...). The "core" kernel uses the
name "unix".
ksinstance The provider's instance number, as from
ddigetinstance(9F). Modules which do not
have a meaningful instance number should use
0.
ksname A pointer to a string that uniquely identi-
fies this structure. Only KSTATSTRLEN - 1
characters are significant.
ksclass 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.
kstype The type of kstat to allocate. Valid types
are:
KSTATYPENAMED Allows more than one data
record per kstat.
KSTATYPEINTR Interrupt; only one data
record per kstat.
SunOS 5.11 Last change: 13 Nov 2006 1
Kernel Functions for Drivers kstatcreate(9F)
KSTATYPEIO I/O; only one data record
per kstat
ksndata The number of type-specific data records to
allocate.
ksflag A bit-field of various flags for this kstat.
ksflag is some combination of:
KSTATFLAGVIRTUAL Tells kstatcreate()
not to allocate
memory for the kstat
data section;
instead, the driver
will set the ksdata
field to point to
the data it wishes
to export. This pro-
vides a convenient
way to export exist-
ing data structures.
KSTATFLAGWRITABLE Makes the kstat data
section writable by
root.
KSTATFLAGPERSISTENT Indicates that this
kstat is to be per-
sistent over time.
For persistent
kstats,
kstatdelete(9F)
simply marks the
kstat as dormant; a
subsequent
kstatcreate() reac-
tivates the kstat.
This feature is pro-
vided 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,
SunOS 5.11 Last change: 13 Nov 2006 2
Kernel Functions for Drivers kstatcreate(9F)
since ksdata points
to garbage as soon
as the driver goes
away.
DESCRIPTION
kstatcreate() is used in conjunction with kstatinstall(9F)
to allocate and initialize a kstat(9S) structure. The method
is generally as follows:
kstatcreate() allocates and performs necessary system ini-
tialization of a kstat(9S) structure. kstatcreate() allo-
cates memory for the entire kstat (header plus data), ini-
tializes 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 kstatcreate() the driver must
perform any necessary initialization of the data section
(such as setting the name fields in a kstat of type
KSTATYPENAMED). Virtual kstats must have the ksdata
field set at this time. The provider may also set the
ksupdate, ksprivate, and kslock fields if necessary.
Once the kstat is completely initialized, kstatinstall(9F)
is used to make the kstat accessible to the outside world.
RETURN VALUES
If successful, kstatcreate() returns a pointer to the allo-
cated kstat. NUL is returned upon failure.
CONTEXT
kstatcreate() can be called from user or kernel context.
EXAMPLES
Example 1 Allocating and Initializing a kstat Structure
pkstatt *ksp;
ksp = kstatcreate(module, instance, name, class, type, ndata, flags);
if (ksp) {
/* ... provider initialization, if necessary */
kstatinstall(ksp);
}
SunOS 5.11 Last change: 13 Nov 2006 3
Kernel Functions for Drivers kstatcreate(9F)
SEE ALSO
kstat(3KSTAT), ddigetinstance(9F), kstatdelete(9F),
kstatinstall(9F), kstatnamedinit(9F), kstat(9S),
kstatnamed(9S)
Writing Device Drivers
SunOS 5.11 Last change: 13 Nov 2006 4
|
