Go to main content

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

Exit Print View

Updated: Thursday, June 13, 2019
 
 

kstat2_md (9S)

Name

kstat2_md - structure for kstats metadata

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

To facilitate automated processing and/or display of v2 kstats, the creators of such kstats are expected to provide metadata for each value in the kstat data.

Structure Members

uint16_t   type;         /* kval semantic type */
uint16_t   flags;        /* per-value flags */
uint64_t   scale         /* Units scale */
const char *descr;       /* Brief description of kval */
int8_t     v1_data_type; /* Data type of the original
                            v1 kval */

type is the semantic type of the kstat which is set to one of the enumerated type values:

typedef enum kstat2_nv_metatype {
KSTAT2_NVMT_UNK      /* Unknown type */
KSTAT2_NVMT_ID       /* Arbitrary numeric or string identifier */
KSTAT2_NVMT_CNT      /* Counter, example network packets */
KSTAT2_NVMT_T_EPOCH  /* Time since UNIX epoch */
KSTAT2_NVMT_T_REL    /* Time relative to boot time */
KSTAT2_NVMT_T_ACC    /* Accumulated time */
KSTAT2_NVMT_PCT      /* Percentage */
KSTAT2_NVMT_ADDR     /* Memory address */
KSTAT2_NVMT_TEMP_C   /* Temperature in centigrade */
KSTAT2_NVMT_RPM      /* Revolutions per minute, example fan speed */
KSTAT2_NVMT_VOLT     /* Voltage */
KSTAT2_NVMT_WATT     /* Power usage */
KSTAT2_NVMT_CURR     /* Current */
KSTAT2_NVMT_BYTES    /* Bytes */
KSTAT2_NVMT_BITS     /* Bits */
KSTAT2_NVMT_STATE    /* Numeric or string representation of a state */
KSTAT2_NVMT_FREQ     /* Frequency */
KSTAT2_NVMT_FLAGS    /* Bitwise flags */
KSTAT2_NVMF_LIMIT    /* Kstat's value represents limit(s) */
} kstat2_nv_metatype_t;

flags provide some additional metadata about the kval and are constructed by combining values from the enum:

typedef enum kstat2_nv_metaflag {
   KSTAT2_NVMF_NONE     /* No flags set */
   KSTAT2_NVMF_FRACT    /* Value of kval is fractional
                           and should be divided by scale */

   KSTAT2_NVMF_IMMUT    /* Value of kval will not change */

   KSTAT2_NVMF_STABLE   /* Kval's name and type will not
                           change between minor Oracle Solaris
                           releases */
} kstat2_nv_metaflag_t;

For example:

flags = KSTAT2_NVMF_IMMUT | KSTAT2_NVMF_STABLE;

scale is used to provide scaling information for a kval. When combined with the KSTAT2_NVMF_FRACT flag, it can be used to display or report a floating-point value whereas the actual value held in the kstat is an integer.

scale is most useful where a kval of a particular type has a large potential range. For instance, a timer might record in nanoseconds but is based in seconds. We can indicate that a timer is recording in nanoseconds by setting scale to 1x10^9 and setting the KSTAT2_NVMF_FRACT flag. Clients then know that the timer value needs to be divided by setting the scale to get the value in seconds.

v1_data_type is used to ensure that the correct data type is used for each kval when a kstat is read by a v1 client. This is for backward compatibility with existing clients. The value of this field is one of the following:

KSTAT_DATA_NONE
KSTAT_DATA_CHAR
KSTAT_DATA_INT32
KSTAT_DATA_UINT32
KSTAT_DATA_INT64
KSTAT_DATA_UINT64
KSTAT_DATA_LONG
KSTAT_DATA_ULONG
KSTAT_DATA_STRING

KSTAT1_DATA_NONE is used when the kstat or kval was not previously delivered as a v1 value. Kvals which are new in a v2 kstat converted from a v1 kstat will not be published to v1 clients.

descr is a null-terminated character string which briefly describes the kval.

See Also

kstat2_create(9F), kstat2_nv_init(9F), kstat_named(9S)