usr/src/man/man9f/pm_power_has_changed.9f

   1 '\" te
   2 .\"  Copyright (c) 2004, 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 PM_POWER_HAS_CHANGED 9F "Jul 22, 2004"
   7 .SH NAME
   8 pm_power_has_changed \- Notify Power Management framework of autonomous power
   9 level change
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ddi.h>
  14 #include <sys/sunddi.h>
  15
  16 \fBint\fR \fBpm_power_has_changed\fR(\fBdev_info_t *\fR\fIdip,\fR int \fIcomponent\fR, int \fIlevel\fR);
  17 .fi
  18
  19 .SH INTERFACE LEVEL
  20 .sp
  21 .LP
  22 Solaris DDI specific (Solaris DDI)
  23 .SH PARAMETERS
  24 .sp
  25 .ne 2
  26 .na
  27 \fB\fIdip\fR\fR
  28 .ad
  29 .RS 7n
  30 Pointer to the device \fBdev_info\fR structure
  31 .RE
  32
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fIcomponent\fR\fR
  37 .ad
  38 .RS 13n
  39 Number of the component that has changed power level
  40 .RE
  41
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fIlevel\fR\fR
  46 .ad
  47 .RS 9n
  48 Power level to which the indicated component has changed
  49 .RE
  50
  51 .SH DESCRIPTION
  52 .sp
  53 .LP
  54 The \fBpm_power_has_changed\fR(9) function notifies the Power Management
  55 framework that the power level of component of \fIdip \fR has changed to
  56 \fIlevel\fR.
  57 .sp
  58 .LP
  59 Normally power level changes are initiated by the Power Management framework
  60 due to device idleness, or through a request to the framework from the driver
  61 via \fBpm_raise_power\fR(9F) or \fBpm_lower_power\fR(9F), but some devices may
  62 change power levels on their own. For the framework to track the power level of
  63 the device under these circumstances, the framework must be notified of
  64 autonomous power level changes by a call to \fBpm_power_has_changed()\fR.
  65 .sp
  66 .LP
  67 Because of the asynchronous nature of these events, the Power Management
  68 framework might have called \fBpower\fR(9E) between the device's autonomous
  69 power level change and the driver calling \fBpm_power_has_changed()\fR, or the
  70 framework may be in the process of changing the power level when
  71 \fBpm_power_has_changed()\fR is called. To handle these situations correctly,
  72 the driver should verify that the device is indeed at the level or set the
  73 device to the level if it doesn't support inquirying of power levels, before
  74 calling \fBpm_power_has_changed()\fR. In addition, the driver should prevent a
  75 \fBpower\fR(9E) entry point from running in parallel with
  76 \fBpm_power_has_changed()\fR.
  77 .LP
  78 Note -
  79 .sp
  80 .RS 2
  81 If this function is called as a result of entry into the driver's
  82 \fBattach\fR(9E), \fBdetach\fR(9E) or \fBpower\fR(9E) entry point, this
  83 function must be called from the same thread which entered \fBattach\fR(9E),
  84 \fBdetach\fR(9E) or \fBpower\fR(9E).
  85 .RE
  86 .SH RETURN VALUES
  87 .sp
  88 .LP
  89 The \fBpm_power_has_changed()\fR function returns:
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fBDDI_SUCCESS\fR\fR
  94 .ad
  95 .RS 15n
  96 The power level of component was successfully updated to \fIlevel\fR.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBDDI_FAILURE\fR\fR
 103 .ad
 104 .RS 15n
 105 Invalid component \fIcomponent\fR or power level \fIlevel\fR.
 106 .RE
 107
 108 .SH CONTEXT
 109 .sp
 110 .LP
 111 This function can be called from user or kernel context. This function can also
 112 be called from interrupt context, providing that it is not the first Power
 113 Management function called by the driver.
 114 .SH EXAMPLES
 115 .sp
 116 .LP
 117 A hypothetical driver might include this code to handle
 118 \fBpm_power_has_changed\fR(9):
 119 .sp
 120 .in +2
 121 .nf
 122 static int
 123 xxusb_intr(struct buf *bp)
 124 {
 125
 126         ...
 127
 128
 129         /*
 130          * At this point the device has informed us that it has
 131          * changed power level on its own. Inform this to framework.
 132          * We need to take care of the case when framework has
 133          * already called power() entry point and changed power level
 134          * before we were able to inform framework of this change.
 135          * Handle this by comparing the informed power level with
 136          * the actual power level and only doing the call if they
 137          * are same. In addition, make sure that power() doesn't get
 138          * run in parallel with this code by holding the mutex.
 139          */
 140         ASSERT(mutex_owned(&xsp->lock));
 141         if (level_informed == *(xsp->level_reg_addr)) {
 142                 if (pm_power_has_changed(xsp->dip, XXUSB_COMPONENT,
 143                     level_informed) != DDI_SUCCESS) {
 144                         mutex_exit( &xsp->lock);
 145                         return(DDI_INTR_UNCLAIMED);
 146                 }
 147         }
 148
 149         ....
 150
 151 }
 152
 153
 154 xxdisk_power(dev_info *dip, int comp, int level)
 155 {
 156         mutex_enter( xsp->lock);
 157
 158         ...
 159
 160         ...
 161
 162 }
 163 .fi
 164 .in -2
 165
 166 .SH ATTRIBUTES
 167 .sp
 168 .LP
 169 See \fBattributes\fR(5) for a description of the following attributes:
 170 .sp
 171
 172 .sp
 173 .TS
 174 box;
 175 c | c
 176 l | l .
 177 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 178 _
 179 Interface Stability     Committed
 180 .TE
 181
 182 .SH SEE ALSO
 183 .sp
 184 .LP
 185 \fBpower.conf\fR(4), \fBpm\fR(7D), \fBattach\fR(9E), \fBdetach\fR(9E),
 186 \fBpower\fR(9E), \fBpm_busy_component\fR(9F), \fBpm_idle_component\fR(9F),
 187 \fBpm_raise_power\fR(9F), \fBpm_lower_power\fR(9F), \fBpm\fR(9P),
 188 \fBpm-components\fR(9P)
 189 .sp
 190 .LP
 191 \fIWriting Device Drivers\fR