Go to main content

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

Exit Print View

Updated: Thursday, June 13, 2019
 
 

kstat2_template (9S)

Name

kstat2_template - structure for creating templated kstats

Synopsis

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

Interface Level

Solaris DDI specific (Solaris DDI)

Description

Templates enable simplified creation of v2 kstats by providing much of the information needed to create the kstat in a static structure rather than as individual arguments to a function.

A number of templates are defined by the kstats framework which support the creation of common kstats such as those whose v1 kstat types were KSTAT_TYPE_IO and KSTAT_TYPE_INTR. Kstats using these templates are created using kstat2_lookup_template(9F) function with the appropriate kstat2_metatype_t value followed by a call to kstat2_create_with_template(9F) function.

Driver developers can also create their own templates. This would typically be useful in cases where modules/drivers share kstat layouts or where a driver creates and deletes a kstat regularly. Such kstats can be created by passing a pointer to a kstat2_template structure to kstat2_create_with_template(9F).

Structure Members

The public members of a kstat template are:

kstat2_named_t *template;    /* Templated kstat data */
uchar_t ndata;               /* # of kvals in template */
kstat2_md_t *metadata;       /* Pointer to metadata for each of the named kvals */

template is an array of kstat2_named structures of length ndata. For kstats whose storage is managed by the framework, this templated data is copied into the kstat's ks2_data buffer when the kstat is created. Otherwise, the templated data is copied into the user's private data structure if its address is passed as the last parameter to kstat2_create_with_template(9F).

ndata is the number of kvals in template.

metadata is a pointer to the metadata for the kstats. This array must have the same number of elements as the kvals array and must be in the same order as the kvals array.

Examples

Example 1 Creating a kstat using a template
     /*
      * Assume the template has been created elsewhere and 
      * contains the definitions for two name-value pairs.
      */
     kstat2_template_t cmn_drv_tmpl = {
        /* Kval definitions */
        { { { "bytes_in" },  KSTAT2_NVVT_INT, KSTAT2_NVF_NONE },
          { { 'bytes_out" }, KSTAT2_NVVT_INT, KSTAT2_NVF_NONE } },

        /* # of kvals */
        2,

        /* Metadata for kvals */
        { { KSTAT2_NVMT_BYTES, KSTAT2_NVMF_NONE, 1UL,
                "bytes read", KSTAT1_DATA_NONE },
          { KSTAT2_NVMT_BYTES, KSTAT2_NVMF_NONE, 1UL,
                "bytes written", KSTAT1_DATA_NONE } }
     };

     /*
      * Structure containing name-value pairs.
      * This is used as an array of name-value pairs by the
      * kstats framework, but is declared as a structure to
      * make it easier to access individual kvals by a
      * field name instead of index into an array.
      */
     static struct my_drv_kvals_s {
            kstat2_named_t bytes_in;
            kstat2_named_t bytes_out;
     } my_drv_kvals;

     void
     init_my_drv_kstat()
     {
            const char *pseg =
                { "misc", "my_drv", "usage", "0" };

             /*
              * Create the kstat from template.
              * The kval data from the template is copied
              * into my_drv_kvals and kstat2(9S)->ks2_data
              * is set to point to this private data-
              * structure.
              */
             my_drv_kstat =
                 kstat2_create_with_template(pseg, 4,
                     ALL_ZONES, cmn_drv_tmpl,
                     0, &my_drv_kvals,
                     "My drv IO usage", KSTAT2_MF_NONE);

             if (my_drv_kstat != NULL)
                     kstat2_install(my_drv_kstat);
     }

See Also

kstat2_create(9F), kstat2_create_with_template(9F), kstat2_lookup_template(9F), kstat2(9S), kstat2_named(9S)