1pm_power_has_changed(9F) Kernel Functions for Drivers pm_power_has_changed(9F)
2
3
4

NAME

6       pm_power_has_changed  - Notify Power Management framework of autonomous
7       power level change
8

SYNOPSIS

10       #include <sys/ddi.h>
11       #include <sys/sunddi.h>
12
13       int pm_power_has_changed(dev_info_t *dip, int component, int level);
14
15

INTERFACE LEVEL

17       Solaris DDI specific (Solaris DDI)
18

PARAMETERS

20       dip    Pointer to the device dev_info structure
21
22
23       component    Number of the component that has changed power level
24
25
26       level    Power level to which the indicated component has changed
27
28

DESCRIPTION

30       The pm_power_has_changed(9)  function  notifies  the  Power  Management
31       framework  that  the  power  level  of component of dip  has changed to
32       level.
33
34
35       Normally power level changes are  initiated  by  the  Power  Management
36       framework due to device idleness, or through a request to the framework
37       from the driver via pm_raise_power(9F) or pm_lower_power(9F), but  some
38       devices  may  change  power  levels  on their own. For the framework to
39       track the power level of the  device  under  these  circumstances,  the
40       framework  must be notified of autonomous power level changes by a call
41       to pm_power_has_changed().
42
43
44       Because of the asynchronous nature of these events, the  Power  Manage‐
45       ment framework might have called power(9E) between the device's autono‐
46       mous power level change and the driver calling  pm_power_has_changed(),
47       or the framework may be in the process of changing the power level when
48       pm_power_has_changed() is called. To handle these situations correctly,
49       the  driver should verify that the device is indeed at the level or set
50       the device to the level if it doesn't support inquirying of power  lev‐
51       els,  before  calling  pm_power_has_changed().  In addition, the driver
52       should prevent a power(9E) entry point from running  in  parallel  with
53       pm_power_has_changed().
54
55       Note -
56
57         If  this  function  is  called as a result of entry into the driver's
58         attach(9E), detach(9E) or power(9E) entry point, this  function  must
59         be  called  from the same thread which entered attach(9E), detach(9E)
60         or power(9E).
61

RETURN VALUES

63       The pm_power_has_changed() function returns:
64
65       DDI_SUCCESS    The power level of component was successfully updated to
66                      level.
67
68
69       DDI_FAILURE    Invalid component component or power level level.
70
71

CONTEXT

73       This  function can be called from user or kernel context. This function
74       can also be called from interrupt context, providing that it is not the
75       first Power Management function called by the driver.
76

EXAMPLES

78       A   hypothetical   driver   might   include   this   code   to   handle
79       pm_power_has_changed(9):
80
81         static int
82         xxusb_intr(struct buf *bp)
83         {
84
85              ...
86
87
88              /*
89               * At this point the device has informed us that it has
90               * changed power level on its own. Inform this to framework.
91               * We need to take care of the case when framework has
92               * already called power() entry point and changed power level
93               * before we were able to inform framework of this change.
94                  * Handle this by comparing the informed power level with
95               * the actual power level and only doing the call if they
96               * are same. In addition, make sure that power() doesn't get
97               * run in parallel with this code by holding the mutex.
98               */
99                 ASSERT(mutex_owned(&xsp->lock));
100              if (level_informed == *(xsp->level_reg_addr)) {
101                   if (pm_power_has_changed(xsp->dip, XXUSB_COMPONENT,
102                       level_informed) != DDI_SUCCESS) {
103                        mutex_exit( &xsp->lock);
104                        return(DDI_INTR_UNCLAIMED);
105                   }
106                 }
107
108              ....
109
110         }
111
112
113         xxdisk_power(dev_info *dip, int comp, int level)
114         {
115              mutex_enter( xsp->lock);
116
117              ...
118
119              ...
120
121         }
122
123

ATTRIBUTES

125       See attributes(5) for a description of the following attributes:
126
127
128
129
130       ┌─────────────────────────────┬─────────────────────────────┐
131       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
132       ├─────────────────────────────┼─────────────────────────────┤
133       │Interface Stability          │Committed                    │
134       └─────────────────────────────┴─────────────────────────────┘
135

SEE ALSO

137       power.conf(4), pm(7D), attach(9E), detach(9E), power(9E),  pm_busy_com‐
138       ponent(9F),          pm_idle_component(9F),         pm_raise_power(9F),
139       pm_lower_power(9F), pm(9P), pm-components(9P)
140
141
142       Writing Device Drivers
143
144
145
146SunOS 5.11                       22 July 2004         pm_power_has_changed(9F)
Impressum