kstat_create(9f)

1kstat_create(9F)         Kernel Functions for Drivers         kstat_create(9F)
2
3
4

NAME

6       kstat_create - create and initialize a new kstat
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/kstat.h>
11
12
13
14       kstat_t *kstat_create(const char *ks_module, int ks_instance,
15            const char *ks_name, const char *ks_class, uchar_t ks_type,
16            ulong_t ks_ndata, uchar_t ks_flag);
17
18

INTERFACE LEVEL

20       Solaris DDI specific (Solaris DDI)
21

PARAMETERS

23       ks_module      The  name of the provider's module (such as "sd", "esp",
24                      ...). The "core" kernel uses the name "unix".
25
26
27       ks_instance    The    provider's    instance    number,     as     from
28                      ddi_get_instance(9F).  Modules which do not have a mean‐
29                      ingful instance number should use 0.
30
31
32       ks_name        A pointer to a  string  that  uniquely  identifies  this
33                      structure. Only KSTAT_STRLEN − 1 characters are signifi‐
34                      cant.
35
36
37       ks_class       The general class that this kstat belongs to.  The  fol‐
38                      lowing  classes  are  currently in use: disk, tape, net,
39                      controller, vm, kvm, hat, streams, kstat, and misc.
40
41
42       ks_type        The type of kstat to allocate. Valid types are:
43
44                      KSTAT_TYPE_NAMED    Allows more than one data record per
45                                          kstat.
46
47
48                      KSTAT_TYPE_INTR     Interrupt;  only one data record per
49                                          kstat.
50
51
52                      KSTAT_TYPE_IO       I/O; only one data record per kstat
53
54
55
56       ks_ndata       The number of type-specific data records to allocate.
57
58
59       ks_flag        A bit-field of various flags for this kstat. ks_flag  is
60                      some combination of:
61
62                      KSTAT_FLAG_VIRTUAL       Tells   kstat_create()  not  to
63                                               allocate memory for  the  kstat
64                                               data   section;   instead,  the
65                                               driver  will  set  the  ks_data
66                                               field  to  point to the data it
67                                               wishes to export. This provides
68                                               a   convenient  way  to  export
69                                               existing data structures.
70
71
72                      KSTAT_FLAG_WRITABLE      Makes the  kstat  data  section
73                                               writable by root.
74
75
76                      KSTAT_FLAG_PERSISTENT    Indicates that this kstat is to
77                                               be persistent  over  time.  For
78                                               persistent              kstats,
79                                               kstat_delete(9F)  simply  marks
80                                               the  kstat as dormant; a subse‐
81                                               quent  kstat_create()   reacti‐
82                                               vates  the  kstat. This feature
83                                               is provided so that  statistics
84                                               are   not  lost  across  driver
85                                               close/open (such  as  raw  disk
86                                               I/O  on  a disk with no mounted
87                                               partitions.)  Note:  Persistent
88                                               kstats cannot be virtual, since
89                                               ks_data points  to  garbage  as
90                                               soon as the driver goes away.
91
92
93

DESCRIPTION

95       kstat_create()  is  used in conjunction with kstat_install(9F) to allo‐
96       cate and initialize a kstat(9S) structure. The method is  generally  as
97       follows:
98
99
100       kstat_create()  allocates  and performs necessary system initialization
101       of a kstat(9S)  structure.  kstat_create()  allocates  memory  for  the
102       entire  kstat  (header  plus data), initializes all header fields, ini‐
103       tializes the data section to all zeroes,  assigns  a  unique  kstat  ID
104       (KID),  and  puts the kstat onto the system's kstat chain. The returned
105       kstat is marked invalid because the provider (caller) has not yet had a
106       chance to initialize the data section.
107
108
109       After  a  successful call to kstat_create() the driver must perform any
110       necessary initialization of the data section (such as setting the  name
111       fields  in  a kstat of type KSTAT_TYPE_NAMED). Virtual kstats must have
112       the ks_data field set at this time.  The  provider  may  also  set  the
113       ks_update, ks_private, and ks_lock fields if necessary.
114
115
116       Once  the kstat is completely initialized, kstat_install(9F) is used to
117       make the kstat accessible to the outside world.
118

RETURN VALUES

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

CONTEXT

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

EXAMPLES

127       Example 1 Allocating and Initializing a kstat Structure
128
129         pkstat_t   *ksp;
130            ksp = kstat_create(module, instance, name, class, type, ndata, flags);
131            if (ksp) {
132               /* ... provider initialization, if necessary */
133               kstat_install(ksp);
134            }
135
136