share/man/man9f/pm_trans_check.9f

   1 '\" te
   2 .\" Copyright (c) 2009, 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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. 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
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PM_TRANS_CHECK 9F "Jul 16, 2009"
   7 .SH NAME
   8 pm_trans_check \- Device power cycle advisory check
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/sunddi.h>
  13
  14 \fBint\fR \fBpm_trans_check\fR(\fBstruct pm_trans_data *\fR\fIdatap,\fR time_t *\fIintervalp\fR);
  15 .fi
  16
  17 .SH INTERFACE LEVEL
  18 .sp
  19 .LP
  20 Solaris DDI specific (Solaris DDI)
  21 .SH PARAMETERS
  22 .sp
  23 .ne 2
  24 .na
  25 \fB\fIdatap\fR\fR
  26 .ad
  27 .RS 9n
  28 Pointer to a \fBpm_trans_data\fR structure
  29 .RE
  30
  31 .sp
  32 .ne 2
  33 .na
  34 \fB\fIintervalp\fR\fR
  35 .ad
  36 .RS 13n
  37 Pointer to time difference when next power cycle will be advised
  38 .RE
  39
  40 .SH DESCRIPTION
  41 .sp
  42 .LP
  43 The \fBpm_trans_check()\fR function checks if a power-cycle is currently
  44 advised based on data in the \fBpm_trans_data\fR  structure. This function is
  45 provided to prevent damage to devices from excess power cycles; drivers for
  46 devices that are sensitive to the number of power cycles should call
  47 \fBpm_trans_check()\fR from their \fBpower\fR(9E) function before powering-off
  48 a device. If \fBpm_trans_check()\fR indicates that the device should not be
  49 power cycled, the driver should not attempt to power cycle the device and
  50 should fail the call to \fBpower\fR(9E) entry point.
  51 .sp
  52 .LP
  53 If \fBpm_trans_check()\fR returns that it is not advised to power cycle the
  54 device, it attempts to calculate when the  next power cycle is advised, based
  55 on the supplied parameters. In such case, \fIintervalp\fR returns the time
  56 difference (in seconds) from the current time to when the next power cycle is
  57 advised. If the time for the next power cycle cannot be determined,
  58 \fIintervalp\fR indicates \fB0\fR.
  59 .sp
  60 .LP
  61 To avoid excessive calls to the \fBpower\fR(9E) entry point during a period
  62 when power cycling is not advised, the driver should mark the corresponding
  63 device component busy for the  \fIintervalp\fR time period (if interval is not
  64 0). Conveniently, the driver can utilize the fact that calls to
  65 \fBpm_busy_component\fR(9F) are stacked. If power cycling is not advised, the
  66 driver can call \fBpm_busy_component\fR(9F)  and issue a \fBtimeout\fR(9F) for
  67 the \fIintervalp\fR time. The \fBtimeout()\fR handler can issue the
  68 corresponding \fBpm_idle_component\fR(9F) call.
  69 .sp
  70 .LP
  71 The format field of \fBpm_trans_data\fR accepts either \fBDC_SCSI_FORMAT\fR or
  72 \fBDC_SMART_FORMAT\fR. If the caller provides information from a SCSI Log Page,
  73 it should set the format field to \fBDC_SCSI_FORMAT\fR, and provide  valid data
  74 in \fIsvc_date\fR[], \fIlifemax\fR, \fIncycles\fR and \fIflag\fR in the
  75 \fBpm_scsi_cycles\fR structure. If the caller provides information from a SMART
  76 feature attribute, it should set the format field to \fBDC_SMART_FORMAT\fR and
  77 provide valid data in \fIallowed\fR, \fIusedup\fR and \fIflag\fR in the
  78 \fBpm_smart_count\fR structure, where \fIallowed\fR indicates the normalized
  79 cycle count before reaching the borderline threshold cycle count, and
  80 \fIusedup\fR indicates the normalized consumed cycle count.
  81 .sp
  82 .LP
  83 The \fIflag\fR field in both \fBpm_scsi_cycles\fR and \fBpm_smart_count\fR
  84 structures is reserved for future use and must be set to 0.
  85 .sp
  86 .in +2
  87 .nf
  88 struct pm_trans_data {
  89        int format;            /* data format */
  90        union {
  91              struct pm_scsi_cycles scsi_cycles;
  92              struct pm_smart_count smart_count;
  93        } un;
  94 };
  95 .fi
  96 .in -2
  97
  98 .SH RETURN VALUES
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fB1\fR\fR
 103 .ad
 104 .RS 6n
 105 Power cycle is advised.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fB0\fR\fR
 112 .ad
 113 .RS 6n
 114 Power cycle is not advised.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fB-1\fR\fR
 121 .ad
 122 .RS 6n
 123 Error due to invalid argument.
 124 .RE
 125
 126 .SH ATTRIBUTES
 127 .sp
 128 .LP
 129 See \fBattributes\fR(5) for descriptions of the following attributes:
 130 .sp
 131
 132 .sp
 133 .TS
 134 box;
 135 c | c
 136 l | l .
 137 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 138 _
 139 Interface Stability     Committed
 140 .TE
 141
 142 .SH SEE ALSO
 143 .sp
 144 .LP
 145 \fBpower.conf\fR(4), \fBattributes\fR(5), \fBpower\fR(9E)
 146 .sp
 147 .LP
 148 \fIWriting Device Drivers\fR
 149 .sp
 150 .LP
 151 \fIUsing Power Management\fR