kstat2_named - man pages section 9: DDI and DKI Properties and Data Structures

Language:

kstat2_named (9S)

Name

kstat2_named - structure for named kstats

Synopsis

#include <sys/types.h>
#include <sys/kstat2.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>

Interface Level

Solaris DDI specific (Solaris DDI)

Description

Named kstats are an array of name-value pairs. These pairs are kept in the kstat2_named structure. When a kstat is created by kstat2_create(9F) function, the driver specifies how many of these structures will be allocated. The structures are returned as an array pointed to by the ks_data field.

Structure Members

kstat2_named_str_t  name;    /* Name of this kstat value (kval) */
uint8_t  type;               /* Type of this kval */
uint16_t flags;              /* per-instance flags */
union {
        uint64_t integer;
        struct {
               uint64_t           *array;
               uint32_t           length;
               } integers;
             kstat2_named_str_t string;
             struct {
                  kstat2_named_str_t *array;
                  uint32_t           length;
                } strings;
} value;     /* value of counter */

The name and type members must not be changed once initialized.

The only members exposed to drivers for update are the flags and value fields. The flags field only has one value which can be used by the driver: KSTAT2_NVF_INVAL, which is used to mark the value field as, "containing invalid data". This might be the case if values have not yet been initialized by the driver or if a counter becomes unavailable (for example, device offline). The value field is a union of several data types. The driver must specify which type it will use when initializing the data. v2 kstats support the following types:

typedef enum kstat2_nv_type {
KSTAT2_NVVT_INT    /* Unsigned 64-bit integer value */
KSTAT2_NVVT_INTS   /* Array of unsigned 64-bit integer
                               values */
KSTAT2_NVVT_STR    /* Character string */
KSTAT2_NVVT_STRS   /* Array of character strings */
} kstat2_nv_type_t;

The kstat2_named_str structure has two members:

char     *ptr;       /* Pointer to null-terminated
                                character string */
uint_t   len;        /* Length of the character string
                                including trailing NULL */

Members of the data-structures should only be changed when the driver has locked the kstat.

Values of a kstat2_named_t structure might be accessed using macros:

kstat2_named_t *knp = KSTAT2_NV_PTR(my_kstatp);

int i = KSTAT2_NV_INT(knp);

char *s = KSTAT2_NV_STR(knp);
int s_len = KSTAT2_NV_STR_LEN(knp);

kstat2_named_str_t *strs = KSTAT2_NV_STRS(knp);
int strs_len = KSTAT2_NV_STRS_LEN(knp);

uint64_t *ints = KSTAT2_NV_INTS(knp);
int ints_len = KSTAT2_NV_INTS_LEN(knp);

With the exception of the integer value, setting values on the kstat2_named_t structure should use the setter functions that are provided and called under the kstat's lock:

kstat2_named_t *knp = KSTAT2_NV_PTR(my_kstatp);
(void) mutex_enter(my_kstatp->ks2_lock);

KSTAT2_NV_INT(knp) = 42;

kstat2_nv_setstr(knp, "wibble");

kstat2_named_str_t strs[4];
...
kstat2_nv_setstrs(knp, strs, 4);

uint64_t ints[6];
...
kstat2_nv_setints(knp, ints, 6);

(void) mutex_exit(my_kstatp->ks2_lock);

man pages section 9: DDI and DKI Properties and Data Structures