| blob | c2a9f2569e3a9b2b7c6c5ccab8816f65e0b0e5ac |
1 '\" te
2 .\" Copyright (c) 2001 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 7D "Sep 20, 1999"
7 .SH NAME
8 pm \- Power Management driver
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/dev/pm\fR
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 The Power Management ( \fBpm\fR) driver provides an interface for applications
19 to configure devices within the system for Power Management. The interface is
20 provided through \fBioctl\fR(2) commands. The \fBpm\fR driver may be accessed
21 using \fB/dev/pm\fR.
22 .SS "Power Management Framework"
23 .sp
24 .LP
25 The Power Management framework model allows the system to be viewed as a
26 collection of devices. Each device is a collection of components that comprise
27 the smallest power manageable units. The device driver controls the definition
28 of a device's power manageable components.
29 .sp
30 .LP
31 A component can either be \fBbusy\fR or \fBidle\fR at the current power level.
32 Normally, the Power Management framework takes an \fBidle\fR component to the
33 next lower power level. The Power Management framework uses two factors to
34 determine this transition: the component must have been idle for at least the
35 threshold time, and the device to which the component belongs must satisfy any
36 dependency requirements. A dependency occurs when a device requires another
37 device to be power managed before it can be power managed. Dependencies occur
38 on a per device basis: when a dependency exists, no components of a device may
39 be managed unless all the devices it depends upon are first power managed.
40 .sp
41 .LP
42 Using the commands below, an application may take control of the Power
43 Management of a device from the Power Management framework driver and manage
44 the transition of device power levels directly.
45 .sp
46 .LP
47 For this set of ioctl commands, \fIarg\fR (see \fBioctl\fR(2)) points to a
48 structure of type \fBpm_req\fR defined in <\fBsys/pm.h\fR>:
49 .sp
50 .in +2
51 .nf
52 typedef struct pm_req {
53 char *physpath; /* physical path of device */
54 /* to configure. See libdevinfo(3LIB) */
55 int component; /* device component */
56 int value; /* power level, threshold value, or count */
57 void *data; /* command-dependent variable-sized data */
58 size_t datasize; /* size of data buffer */
59 } pm_req_t;
60 .fi
61 .in -2
63 .sp
64 .LP
65 The fields should contain the following data:
66 .sp
67 .ne 2
68 .na
69 \fB\fIphyspath\fR\fR
70 .ad
71 .RS 13n
72 Pointer to the physical path of a device. See \fBlibdevinfo\fR(3LIB). For
73 example, for the device \fB/devices/pseudo/pm@0:pm\fR the \fIphyspath\fR value
74 would be \fB/pseudo/pm@0\fR.
75 .RE
77 .sp
78 .ne 2
79 .na
80 \fB\fIcomponent\fR\fR
81 .ad
82 .RS 13n
83 Non-negative integer specifying which component is being configured. The
84 numbering starts at zero.
85 .RE
87 .sp
88 .ne 2
89 .na
90 \fB\fIvalue\fR\fR
91 .ad
92 .RS 13n
93 Non-negative integer specifying the threshold value in seconds or the desired
94 power level, or the number of levels being specified.
95 .RE
97 .sp
98 .ne 2
99 .na
100 \fB\fIdata\fR\fR
101 .ad
102 .RS 13n
103 Pointer to a buffer which contains or receives variable-sized data, such as the
104 name of a device upon which this device has a dependency.
105 .RE
107 .sp
108 .ne 2
109 .na
110 \fB\fIsize\fR\fR
111 .ad
112 .RS 13n
113 Size of the data buffer.
114 .RE
116 .sp
117 .LP
118 Not all fields are used in each command.
119 .sp
120 .ne 2
121 .na
122 \fB\fBPM_DIRECT_PM\fR\fR
123 .ad
124 .sp .6
125 .RS 4n
126 The device named by \fIphyspath\fR is disabled from being power managed by the
127 framework. The caller will power manage the device directly using the
128 \fBPM_DIRECT_NOTIFY\fR, \fBPM_GET_TIME_IDLE\fR and \fBPM_GET_CURRENT_POWER\fR,
129 \fBPM_GET_FULL_POWER\fR and \fBPM_SET_CURRENT_POWER\fR commands. If the device
130 needs to have its power level changed either because its driver calls
131 \fBpm_raise_power\fR(9F), \fBpm_lower_power\fR(9F), or
132 \fBpm_power_has_changed\fR(9F) or because the device is the parent of another
133 device that is changing power level or a device that this device depends on is
134 changing power level, then the power level change of the device will be blocked
135 and the caller will be notified as described below for the
136 \fBPM_DIRECT_NOTIFY\fR command.
137 .sp
138 Error codes:
139 .sp
140 .ne 2
141 .na
142 \fB\fBEBUSY\fR\fR
143 .ad
144 .RS 9n
145 Device already disabled for Power Management by framework.
146 .RE
148 .sp
149 .ne 2
150 .na
151 \fB\fBEPERM\fR\fR
152 .ad
153 .RS 9n
154 Caller is neither superuser nor effective group ID of 0.
155 .RE
157 .RE
159 .sp
160 .ne 2
161 .na
162 \fB\fBPM_RELEASE_DIRECT_PM\fR\fR
163 .ad
164 .sp .6
165 .RS 4n
166 The device named by \fIphyspath\fR (which must have been the target of a
167 \fBPM_DIRECT_PM\fR command) is re-enabled for Power Management by the
168 framework.
169 .sp
170 Error codes:
171 .sp
172 .ne 2
173 .na
174 \fB\fBEINVAL\fR\fR
175 .ad
176 .RS 10n
177 Device component out of range.
178 .RE
180 .RE
182 .sp
183 .ne 2
184 .na
185 \fB\fBPM_DIRECT_NOTIFY \fR\fBPM_DIRECT_NOTIFY_WAIT\fR\fR
186 .ad
187 .sp .6
188 .RS 4n
189 These commands allow the process that is directly power managing a device to be
190 notified of events that could change the power level of the device. When such
191 an event occurs, this command returns information about the event.
192 .sp
193 \fIarg\fR (see \fBioctl\fR(2)) points to a structure of type
194 \fBpm_state_change\fR defined in \fB<sys/pm.h>\fR:
195 .sp
196 .in +2
197 .nf
198 typedef struct pm_state_change {
199 char *physpath; /* device which has changed state */
200 int component; /* which component changed state */
201 #if defined(_BIG_ENDIAN)
202 ushort_t flags; /* PSC_EVENT_LOST, PSC_ALL_LOWEST */
203 ushort_t event; /* type of event */
204 #else
205 ushort_t event; /* type of event *
206 ushort_t flags; /* PSC_EVENT_LOST, PSC_ALL_LOWEST */
207 #endif
208 time_t timestamp; /* time of state change */+
209 int old_level; /* power level changing from */
210 int new_level; /* power level changing to */
211 size_t size; /* size of buffer physpath points to */
212 } pm_state_change_t;
213 .fi
214 .in -2
216 When an event occurs, the struct pointed to by \fIarg\fR is filled in. If the
217 event type is \fBPSC_PENDING_CHANGE\fR, then the information in the rest of the
218 struct describes an action that the framework would have taken if the device
219 were not directly power managed by the caller. The caller is responsible for
220 completing the indicated level changes using \fBPM_SET_CURRENT_POWER\fR below.
221 .sp
222 An event type of \fBPSC_HAS_CHANGED\fR indicates that the driver for the
223 directly power managed device has called \fBpm_power_has_changed\fR(9F) due to
224 the device changing power on its own. It is provided to allow the caller to
225 track the power state of the device.
226 .sp
227 The system keeps events in a circular buffer. If the buffer overflow, the
228 oldest events are lost and when the event that next follows a lost event is
229 retrieved it will have PSC_EVENT_LOST set in flags.
230 .sp
231 \fBPM_DIRECT_NOTIFY\fR returns \fBEWOULDBLOCK\fR if no event is pending, and
232 \fBPM_DIRECT_NOTIFY_WAIT\fR blocks until an event is available.
233 .sp
234 \fBpm\fR also supports the \fBpoll\fR(2) interface. When an event is pending a
235 \fBpoll\fR(2) call that includes a file descriptor for \fB/dev/pm\fR and that
236 has \fBPOLLIN \fR or \fBPOLLRDNORM \fR set in its event mask will return.
237 .RE
239 .sp
240 .ne 2
241 .na
242 \fB\fBPM_SET_CURRENT_POWER\fR\fR
243 .ad
244 .sp .6
245 .RS 4n
246 Component \fIcomponent\fR of the device named by \fIphyspath\fR (which must
247 contain the physical path of a device against which the process has issued a
248 \fBPM_DIRECT_PM\fR command) is set to power level \fIvalue. \fRIf all
249 components of the device named by \fIphyspath\fR were at level 0, \fIvalue\fR
250 is non-zero and some device has a dependency on this device, then all
251 components of that device will be brought to full power before this command
252 returns. Similarly, if the parent of the target device is powered off, then it
253 will be brought up as needed before this command returns. When
254 PM_SET_CURRENT_POWER is issued against a device, the resulting power change is
255 included in the event list for PM_DIRECT_NOTIFY.
256 .sp
257 Error codes:
258 .sp
259 .ne 2
260 .na
261 \fB\fBEINVAL\fR\fR
262 .ad
263 .RS 10n
264 Device component out of range, or power level < 0.
265 .RE
267 .sp
268 .ne 2
269 .na
270 \fB\fBEIO\fR\fR
271 .ad
272 .RS 10n
273 Failed to power device or its ancestors or the devices on which this device has
274 dependency or their ancestors. Note that this may not indicate a failure, the
275 device driver may have rejected the command as inappropriate because the
276 component has become busy.
277 .RE
279 .sp
280 .ne 2
281 .na
282 \fB\fBEPERM\fR\fR
283 .ad
284 .RS 10n
285 Caller has not previously issued a successful \fBPM_DIRECT_PM\fR command
286 against this device.
287 .RE
289 .RE
291 .sp
292 .ne 2
293 .na
294 \fB\fBPM_GET_FULL_POWER\fR\fR
295 .ad
296 .sp .6
297 .RS 4n
298 The highest supported power level of component \fIcomponent\fR of the device
299 named by \fIphyspath\fR is returned.
300 .RE
302 .sp
303 .ne 2
304 .na
305 \fB\fBPM_GET_CURRENT_POWER\fR\fR
306 .ad
307 .sp .6
308 .RS 4n
309 The current power level of component \fIcomponent\fR of the device named by
310 \fIphyspath\fR is returned.
311 .sp
312 Error codes:
313 .sp
314 .ne 2
315 .na
316 \fB\fBEAGAIN\fR\fR
317 .ad
318 .RS 10n
319 Device component power level is not currently known.
320 .RE
322 .RE
324 .sp
325 .ne 2
326 .na
327 \fB\fBPM_GET_TIME_IDLE\fR\fR
328 .ad
329 .sp .6
330 .RS 4n
331 \fBPM_GET_TIME_IDLE\fR returns the number of seconds that component
332 \fIcomponent\fR of the device named by \fIphyspath\fR has been idle. If the
333 device is not idle, then \fB0\fR is returned.
334 .sp
335 Note that because the state of the device may change between the time the
336 process issues the \fBPM_GET_TIME_IDLE\fR command and the time the process
337 issues a \fBPM_SET_CURRENT_POWER\fR command to reduce the power level of an
338 idle component, the process must be prepared to deal with a
339 \fBPM_SET_CURRENT_POWER\fR command returning failure because the driver has
340 rejected the command as inappropriate because the device component has become
341 busy. This can be differentiated from other types of failures by issuing the
342 \fBPM_GET_TIME_IDLE\fR command again to see if the component has become busy.
343 .RE
345 .SH ERRORS
346 .sp
347 .LP
348 Upon error, the commands will return \fB\(mi1\fR, and set \fIerrno\fR. In
349 addition to the error codes listed above by command, the following error codes
350 are common to all commands:
351 .sp
352 .ne 2
353 .na
354 \fB\fBEFAULT\fR\fR
355 .ad
356 .RS 10n
357 Bad address passed in as argument.
358 .RE
360 .sp
361 .ne 2
362 .na
363 \fB\fBENODEV\fR\fR
364 .ad
365 .RS 10n
366 Device is not power manageable, or device is not configured.
367 .RE
369 .sp
370 .ne 2
371 .na
372 \fB\fBENXIO\fR\fR
373 .ad
374 .RS 10n
375 Too many opens attempted.
376 .RE
378 .SH ATTRIBUTES
379 .sp
380 .LP
381 See \fBattributes\fR(5) for descriptions of the following attributes:
382 .sp
384 .sp
385 .TS
386 box;
387 c | c
388 l | l .
389 ATTRIBUTE TYPE ATTRIBUTE VALUE
390 _
391 Interface stability Unstable
392 .TE
394 .SH SEE ALSO
395 .sp
396 .LP
397 \fBpmconfig\fR(8), \fBIntro\fR(2), \fBioctl\fR(2), \fBlibdevinfo\fR(3LIB),
398 \fBpower.conf\fR(4), \fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E),
399 \fBpower\fR(9E), \fBpm_busy_component\fR(9F), \fBpm_idle_component\fR(9F),
400 \fBpm_lower_power\fR(9F), \fBpm_power_has_changed\fR(9F),
401 \fBpm_raise_power\fR(9F)
402 .sp
403 .LP
404 \fIWriting Device Drivers\fR