share/man/man9s/kstat.9s

   1 '\" te
   2 .\" Copyright (c) 2000, Sun Microsystems, Inc., All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH KSTAT 9S "Apr 4, 1994"
   7 .SH NAME
   8 kstat \- kernel statistics structure
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/types.h>
  13 #include <sys/kstat.h>
  14 #include <sys/ddi.h>
  15 #include <sys/sunddi.h>
  16 .fi
  17
  18 .SH INTERFACE LEVEL
  19 .sp
  20 .LP
  21 Solaris DDI specific (Solaris DDI)
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 Each kernel statistic (\fBkstat\fR) exported by device drivers consists of a
  26 header section and a data section. The \fBkstat\fR structure is the header
  27 portion of the statistic.
  28 .sp
  29 .LP
  30 A driver receives a pointer to a \fBkstat\fR structure from a successful call
  31 to \fBkstat_create\fR(9F). Drivers should never allocate a \fBkstat\fR
  32 structure in any other manner.
  33 .sp
  34 .LP
  35 After allocation, the driver should perform any further initialization needed
  36 before calling \fBkstat_install\fR(9F) to actually export the \fBkstat\fR.
  37 .SH STRUCTURE MEMBERS
  38 .sp
  39 .in +2
  40 .nf
  41 void      *ks_data;             /* kstat type-specif. data */
  42 ulong_t   ks_ndata;             /* # of type-specif. data
  43                                      records */
  44 ulong_t   ks_data_size;         /* total size of kstat data
  45                                    section */
  46 int       (*ks_update)(struct kstat *, int);
  47 void      *ks_private;          /* arbitrary provider-private
  48                                    data */
  49 void      *ks_lock;             /* protects kstat's data */
  50 .fi
  51 .in -2
  52
  53 .sp
  54 .LP
  55 The members of the \fBkstat\fR structure available to examine or set by a
  56 driver are as follows:
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fBks_data\fR \fR
  61 .ad
  62 .RS 17n
  63 Points to the data portion of the \fBkstat\fR. Either allocated by
  64 \fBkstat_create\fR(9F) for the drivers use, or by the driver if it is using
  65 virtual \fBkstat\fRs.
  66 .RE
  67
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fBks_ndata\fR \fR
  72 .ad
  73 .RS 17n
  74 The number of data records in this \fBkstat\fR. Set by the \fBks_update\fR(9E)
  75 routine.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBks_data_size\fR \fR
  82 .ad
  83 .RS 17n
  84 The amount of data pointed to by \fBks_data\fR. Set by the \fBks_update\fR(9E)
  85 routine.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBks_update\fR \fR
  92 .ad
  93 .RS 17n
  94 Pointer to a routine that dynamically updates \fBkstat\fR. This is useful for
  95 drivers where the underlying device keeps cheap hardware statistics, but where
  96 extraction is expensive. Instead of constantly keeping the \fBkstat\fR data
  97 section up to date, the driver can supply a \fBks_update\fR(9E) function that
  98 updates the \fBkstat\fR data section on demand. To take advantage of this
  99 feature, set the \fBks_update\fR field before calling \fBkstat_install\fR(9F).
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBks_private\fR \fR
 106 .ad
 107 .RS 17n
 108 Is a private field for the driver's use. Often used in \fBks_update\fR(9E).
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBks_lock\fR \fR
 115 .ad
 116 .RS 17n
 117 Is a pointer to a mutex that protects this \fBkstat\fR. \fBkstat\fR data
 118 sections are optionally protected by the per-\fBkstat\fR \fBks_lock\fR. If
 119 \fBks_lock\fR is non-\fINULL\fR, \fBkstat\fR clients (such as \fB/dev/kstat\fR)
 120 will acquire this lock for all of their operations on that \fBkstat\fR. It is
 121 up to the \fBkstat\fR provider to decide whether guaranteeing consistent data
 122 to \fBkstat\fR clients is sufficiently important to justify the locking cost.
 123 Note, however, that most statistic updates already occur under one of the
 124 provider's mutexes. If the provider sets \fBks_lock\fR to point to that mutex,
 125 then \fBkstat\fR data locking is free. \fBks_lock\fR is really of type
 126 \fB(kmutex_t*)\fR and is declared as \fB(void*)\fR in the \fBkstat\fR header.
 127 That way, users do not have to be exposed to all of the kernel's lock-related
 128 data structures.
 129 .RE
 130
 131 .SH SEE ALSO
 132 .sp
 133 .LP
 134 \fBkstat_create\fR(9F)
 135 .sp
 136 .LP
 137 \fIWriting Device Drivers\fR