share/man/man9e/ks_update.9e

   1 '\" te
   2 .\" Copyright (c) 1994, 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 KS_UPDATE 9E "May 27, 1994"
   7 .SH NAME
   8 ks_update \- dynamically update kstats
   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
  17
  18
  19 \fBint prefix\fR\fB_ks_update\fR(\fBkstat_t *\fR\fIksp\fR, \fBint\fR \fIrw\fR);
  20 .fi
  21
  22 .SH INTERFACE LEVEL
  23 .sp
  24 .LP
  25 Solaris DDI specific (Solaris DDI)
  26 .SH PARAMETERS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fIksp\fR \fR
  31 .ad
  32 .RS 8n
  33 Pointer to a \fBkstat\fR(9S) structure.
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIrw\fR \fR
  40 .ad
  41 .RS 8n
  42 Read/Write flag. Possible values are
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fBKSTAT_READ\fR \fR
  47 .ad
  48 .RS 16n
  49 Update \fBkstat\fR structure statistics from the driver.
  50 .RE
  51
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fBKSTAT_WRITE\fR \fR
  56 .ad
  57 .RS 16n
  58 Update driver statistics from the kstat structure.
  59 .RE
  60
  61 .RE
  62
  63 .SH DESCRIPTION
  64 .sp
  65 .LP
  66 The kstat mechanism allows for an optional \fBks_update()\fR function to update
  67 kstat data.  This is useful for drivers where the underlying device keeps cheap
  68 hardware statistics, but extraction is expensive.  Instead of constantly
  69 keeping the kstat data section up to date, the driver can supply a
  70 \fBks_update()\fR function which updates the kstat's data section on demand. To
  71 take advantage of this feature, set the  \fBks_update\fR field before calling
  72 \fBkstat_install\fR(9F).
  73 .sp
  74 .LP
  75 The \fBks_update()\fR function must have the following structure:
  76 .sp
  77 .in +2
  78 .nf
  79 static int
  80 xx_kstat_update(kstat_t *ksp, int rw)
  81 {
  82         if (rw == KSTAT_WRITE) {
  83                 /* update the native stats from ksp->ks_data */
  84                 /* return EACCES if you don't support this */
  85         } else {
  86                 /* update ksp->ks_data from the native stats */
  87         }
  88         return (0);
  89 }
  90 .fi
  91 .in -2
  92
  93 .sp
  94 .LP
  95 In general, the \fBks_update()\fR routine may need to refer to provider-private
  96 data; for example, it may need a pointer to the provider's raw statistics.  The
  97 \fBks_private\fR field is available for this purpose.   Its use is entirely at
  98 the provider's discretion.
  99 .sp
 100 .LP
 101 No \fBkstat\fR locking should be done inside the \fBks_update()\fR routine.
 102 The caller will already be holding the \fBkstat's\fR  \fBks_lock\fR (to ensure
 103 consistent data) and will prevent the \fBkstat\fR from being removed.
 104 .SH RETURN VALUES
 105 .sp
 106 .LP
 107 \fBks_update()\fR should return
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fB0\fR \fR
 112 .ad
 113 .RS 11n
 114 For success.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBEACCES\fR \fR
 121 .ad
 122 .RS 11n
 123 If \fBKSTAT_WRITE\fR is not allowed.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBEIO\fR \fR
 130 .ad
 131 .RS 11n
 132 For any other error.
 133 .RE
 134
 135 .SH SEE ALSO
 136 .sp
 137 .LP
 138 \fBkstat_create\fR(9F), \fBkstat_install\fR(9F), \fBkstat\fR(9S)
 139 .sp
 140 .LP
 141 \fIWriting Device Drivers\fR