1pm(7D) Devices pm(7D)
2
6 pm - Power Management driver
7
9 /dev/pm
10
13 The Power Management ( pm) driver provides an interface for applica‐
14 tions to configure devices within the system for Power Management. The
15 interface is provided through ioctl(2) commands. The pm driver may be
16 accessed using /dev/pm.
17 Power Management Framework
19 The Power Management framework model allows the system to be viewed as
20 a collection of devices. Each device is a collection of components that
21 comprise the smallest power manageable units. The device driver con‐
22 trols the definition of a device's power manageable components.
23 A component can either be busy or idle at the current power level. Nor‐
26 mally, the Power Management framework takes an idle component to the
27 next lower power level. The Power Management framework uses two factors
28 to determine this transition: the component must have been idle for at
29 least the threshold time, and the device to which the component belongs
30 must satisfy any dependency requirements. A dependency occurs when a
31 device requires another device to be power managed before it can be
32 power managed. Dependencies occur on a per device basis: when a depen‐
33 dency exists, no components of a device may be managed unless all the
34 devices it depends upon are first power managed.
35 Using the commands below, an application may take control of the Power
38 Management of a device from the Power Management framework driver and
39 manage the transition of device power levels directly.
40 For this set of ioctl commands, arg (see ioctl(2)) points to a struc‐
43 ture of type pm_req defined in <sys/pm.h>:
44 typedef struct pm_req {
46 char *physpath; /* physical path of device */
47 /* to configure. See libdevinfo(3LIB) */
48 int component; /* device component */
49 int value; /* power level, threshold value, or count */
50 void *data; /* command-dependent variable-sized data */
51 size_t datasize; /* size of data buffer */
52 } pm_req_t;
53 The fields should contain the following data:
57 physpath Pointer to the physical path of a device. See libdev‐
59 info(3LIB). For example, for the device
60 /devices/pseudo/pm@0:pm the physpath value would be
61 /pseudo/pm@0.
62 component Non-negative integer specifying which component is being
65 configured. The numbering starts at zero.
66 value Non-negative integer specifying the threshold value in
69 seconds or the desired power level, or the number of lev‐
70 els being specified.
71 data Pointer to a buffer which contains or receives variable-
74 sized data, such as the name of a device upon which this
75 device has a dependency.
76 size Size of the data buffer.
79 Not all fields are used in each command.
83 PM_DIRECT_PM
85 The device named by physpath is disabled from being power managed
87 by the framework. The caller will power manage the device directly
88 using the PM_DIRECT_NOTIFY, PM_GET_TIME_IDLE and PM_GET_CUR‐
89 RENT_POWER, PM_GET_FULL_POWER and PM_SET_CURRENT_POWER commands. If
90 the device needs to have its power level changed either because its
91 driver calls pm_raise_power(9F), pm_lower_power(9F), or
92 pm_power_has_changed(9F) or because the device is the parent of
93 another device that is changing power level or a device that this
94 device depends on is changing power level, then the power level
95 change of the device will be blocked and the caller will be noti‐
96 fied as described below for the PM_DIRECT_NOTIFY command.
97 Error codes:
99 EBUSY Device already disabled for Power Management by framework.
101 EPERM Caller is neither superuser nor effective group ID of 0.
104 PM_RELEASE_DIRECT_PM
108 The device named by physpath (which must have been the target of a
110 PM_DIRECT_PM command) is re-enabled for Power Management by the
111 framework.
112 Error codes:
114 EINVAL Device component out of range.
116 PM_DIRECT_NOTIFY PM_DIRECT_NOTIFY_WAIT
120 These commands allow the process that is directly power managing a
122 device to be notified of events that could change the power level
123 of the device. When such an event occurs, this command returns
124 information about the event.
125 arg (see ioctl(2)) points to a structure of type pm_state_change
127 defined in <sys/pm.h>:
128 typedef struct pm_state_change {
130 char *physpath; /* device which has changed state */
131 int component; /* which component changed state */
132 #if defined(_BIG_ENDIAN)
133 ushort_t flags; /* PSC_EVENT_LOST, PSC_ALL_LOWEST */
134 ushort_t event; /* type of event */
135 #else
136 ushort_t event; /* type of event *
137 ushort_t flags; /* PSC_EVENT_LOST, PSC_ALL_LOWEST */
138 #endif
139 time_t timestamp; /* time of state change */+
140 int old_level; /* power level changing from */
141 int new_level; /* power level changing to */
142 size_t size; /* size of buffer physpath points to */
143 } pm_state_change_t;
144 When an event occurs, the struct pointed to by arg is filled in. If
146 the event type is PSC_PENDING_CHANGE, then the information in the
147 rest of the struct describes an action that the framework would
148 have taken if the device were not directly power managed by the
149 caller. The caller is responsible for completing the indicated
150 level changes using PM_SET_CURRENT_POWER below.
151 An event type of PSC_HAS_CHANGED indicates that the driver for the
153 directly power managed device has called pm_power_has_changed(9F)
154 due to the device changing power on its own. It is provided to
155 allow the caller to track the power state of the device.
156 The system keeps events in a circular buffer. If the buffer over‐
158 flow, the oldest events are lost and when the event that next fol‐
159 lows a lost event is retrieved it will have PSC_EVENT_LOST set in
160 flags.
161 PM_DIRECT_NOTIFY returns EWOULDBLOCK if no event is pending, and
163 PM_DIRECT_NOTIFY_WAIT blocks until an event is available.
164 pm also supports the poll(2) interface. When an event is pending a
166 poll(2) call that includes a file descriptor for /dev/pm and that
167 has POLLIN or POLLRDNORM set in its event mask will return.
168 PM_SET_CURRENT_POWER
171 Component component of the device named by physpath (which must
173 contain the physical path of a device against which the process has
174 issued a PM_DIRECT_PM command) is set to power level value. If all
175 components of the device named by physpath were at level 0, value
176 is non-zero and some device has a dependency on this device, then
177 all components of that device will be brought to full power before
178 this command returns. Similarly, if the parent of the target device
179 is powered off, then it will be brought up as needed before this
180 command returns. When PM_SET_CURRENT_POWER is issued against a
181 device, the resulting power change is included in the event list
182 for PM_DIRECT_NOTIFY.
183 Error codes:
185 EINVAL Device component out of range, or power level < 0.
187 EIO Failed to power device or its ancestors or the devices on
190 which this device has dependency or their ancestors. Note
191 that this may not indicate a failure, the device driver
192 may have rejected the command as inappropriate because
193 the component has become busy.
194 EPERM Caller has not previously issued a successful
197 PM_DIRECT_PM command against this device.
198 PM_GET_FULL_POWER
202 The highest supported power level of component component of the
204 device named by physpath is returned.
205 PM_GET_CURRENT_POWER
208 The current power level of component component of the device named
210 by physpath is returned.
211 Error codes:
213 EAGAIN Device component power level is not currently known.
215 PM_GET_TIME_IDLE
219 PM_GET_TIME_IDLE returns the number of seconds that component com‐
221 ponent of the device named by physpath has been idle. If the device
222 is not idle, then 0 is returned.
223 Note that because the state of the device may change between the
225 time the process issues the PM_GET_TIME_IDLE command and the time
226 the process issues a PM_SET_CURRENT_POWER command to reduce the
227 power level of an idle component, the process must be prepared to
228 deal with a PM_SET_CURRENT_POWER command returning failure because
229 the driver has rejected the command as inappropriate because the
230 device component has become busy. This can be differentiated from
231 other types of failures by issuing the PM_GET_TIME_IDLE command
232 again to see if the component has become busy.
233
236 Upon error, the commands will return −1, and set errno. In addition to
237 the error codes listed above by command, the following error codes are
238 common to all commands:
239 EFAULT Bad address passed in as argument.
241 ENODEV Device is not power manageable, or device is not configured.
244 ENXIO Too many opens attempted.
247
250 See attributes(5) for descriptions of the following attributes:
251 ┌─────────────────────────────┬─────────────────────────────┐
256 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
257 ├─────────────────────────────┼─────────────────────────────┤
258 │Interface stability │Unstable │
259 └─────────────────────────────┴─────────────────────────────┘
260
262 pmconfig(1M), Intro(2), ioctl(2), libdevinfo(3LIB), power.conf(4),
263 attributes(5), attach(9E), detach(9E), power(9E), pm_busy_compo‐
264 nent(9F), pm_idle_component(9F), pm_lower_power(9F),
265 pm_power_has_changed(9F), pm_raise_power(9F)
266 Writing Device Drivers
269SunOS 5.11 20 Sep 1999 pm(7D)