1 |
3 |
xianfeng |
Power Management for USB
|
2 |
|
|
|
3 |
|
|
Alan Stern
|
4 |
|
|
|
5 |
|
|
October 5, 2007
|
6 |
|
|
|
7 |
|
|
|
8 |
|
|
|
9 |
|
|
What is Power Management?
|
10 |
|
|
-------------------------
|
11 |
|
|
|
12 |
|
|
Power Management (PM) is the practice of saving energy by suspending
|
13 |
|
|
parts of a computer system when they aren't being used. While a
|
14 |
|
|
component is "suspended" it is in a nonfunctional low-power state; it
|
15 |
|
|
might even be turned off completely. A suspended component can be
|
16 |
|
|
"resumed" (returned to a functional full-power state) when the kernel
|
17 |
|
|
needs to use it. (There also are forms of PM in which components are
|
18 |
|
|
placed in a less functional but still usable state instead of being
|
19 |
|
|
suspended; an example would be reducing the CPU's clock rate. This
|
20 |
|
|
document will not discuss those other forms.)
|
21 |
|
|
|
22 |
|
|
When the parts being suspended include the CPU and most of the rest of
|
23 |
|
|
the system, we speak of it as a "system suspend". When a particular
|
24 |
|
|
device is turned off while the system as a whole remains running, we
|
25 |
|
|
call it a "dynamic suspend" (also known as a "runtime suspend" or
|
26 |
|
|
"selective suspend"). This document concentrates mostly on how
|
27 |
|
|
dynamic PM is implemented in the USB subsystem, although system PM is
|
28 |
|
|
covered to some extent (see Documentation/power/*.txt for more
|
29 |
|
|
information about system PM).
|
30 |
|
|
|
31 |
|
|
Note: Dynamic PM support for USB is present only if the kernel was
|
32 |
|
|
built with CONFIG_USB_SUSPEND enabled. System PM support is present
|
33 |
|
|
only if the kernel was built with CONFIG_SUSPEND or CONFIG_HIBERNATION
|
34 |
|
|
enabled.
|
35 |
|
|
|
36 |
|
|
|
37 |
|
|
What is Remote Wakeup?
|
38 |
|
|
----------------------
|
39 |
|
|
|
40 |
|
|
When a device has been suspended, it generally doesn't resume until
|
41 |
|
|
the computer tells it to. Likewise, if the entire computer has been
|
42 |
|
|
suspended, it generally doesn't resume until the user tells it to, say
|
43 |
|
|
by pressing a power button or opening the cover.
|
44 |
|
|
|
45 |
|
|
However some devices have the capability of resuming by themselves, or
|
46 |
|
|
asking the kernel to resume them, or even telling the entire computer
|
47 |
|
|
to resume. This capability goes by several names such as "Wake On
|
48 |
|
|
LAN"; we will refer to it generically as "remote wakeup". When a
|
49 |
|
|
device is enabled for remote wakeup and it is suspended, it may resume
|
50 |
|
|
itself (or send a request to be resumed) in response to some external
|
51 |
|
|
event. Examples include a suspended keyboard resuming when a key is
|
52 |
|
|
pressed, or a suspended USB hub resuming when a device is plugged in.
|
53 |
|
|
|
54 |
|
|
|
55 |
|
|
When is a USB device idle?
|
56 |
|
|
--------------------------
|
57 |
|
|
|
58 |
|
|
A device is idle whenever the kernel thinks it's not busy doing
|
59 |
|
|
anything important and thus is a candidate for being suspended. The
|
60 |
|
|
exact definition depends on the device's driver; drivers are allowed
|
61 |
|
|
to declare that a device isn't idle even when there's no actual
|
62 |
|
|
communication taking place. (For example, a hub isn't considered idle
|
63 |
|
|
unless all the devices plugged into that hub are already suspended.)
|
64 |
|
|
In addition, a device isn't considered idle so long as a program keeps
|
65 |
|
|
its usbfs file open, whether or not any I/O is going on.
|
66 |
|
|
|
67 |
|
|
If a USB device has no driver, its usbfs file isn't open, and it isn't
|
68 |
|
|
being accessed through sysfs, then it definitely is idle.
|
69 |
|
|
|
70 |
|
|
|
71 |
|
|
Forms of dynamic PM
|
72 |
|
|
-------------------
|
73 |
|
|
|
74 |
|
|
Dynamic suspends can occur in two ways: manual and automatic.
|
75 |
|
|
"Manual" means that the user has told the kernel to suspend a device,
|
76 |
|
|
whereas "automatic" means that the kernel has decided all by itself to
|
77 |
|
|
suspend a device. Automatic suspend is called "autosuspend" for
|
78 |
|
|
short. In general, a device won't be autosuspended unless it has been
|
79 |
|
|
idle for some minimum period of time, the so-called idle-delay time.
|
80 |
|
|
|
81 |
|
|
Of course, nothing the kernel does on its own initiative should
|
82 |
|
|
prevent the computer or its devices from working properly. If a
|
83 |
|
|
device has been autosuspended and a program tries to use it, the
|
84 |
|
|
kernel will automatically resume the device (autoresume). For the
|
85 |
|
|
same reason, an autosuspended device will usually have remote wakeup
|
86 |
|
|
enabled, if the device supports remote wakeup.
|
87 |
|
|
|
88 |
|
|
It is worth mentioning that many USB drivers don't support
|
89 |
|
|
autosuspend. In fact, at the time of this writing (Linux 2.6.23) the
|
90 |
|
|
only drivers which do support it are the hub driver, kaweth, asix,
|
91 |
|
|
usblp, usblcd, and usb-skeleton (which doesn't count). If a
|
92 |
|
|
non-supporting driver is bound to a device, the device won't be
|
93 |
|
|
autosuspended. In effect, the kernel pretends the device is never
|
94 |
|
|
idle.
|
95 |
|
|
|
96 |
|
|
We can categorize power management events in two broad classes:
|
97 |
|
|
external and internal. External events are those triggered by some
|
98 |
|
|
agent outside the USB stack: system suspend/resume (triggered by
|
99 |
|
|
userspace), manual dynamic suspend/resume (also triggered by
|
100 |
|
|
userspace), and remote wakeup (triggered by the device). Internal
|
101 |
|
|
events are those triggered within the USB stack: autosuspend and
|
102 |
|
|
autoresume.
|
103 |
|
|
|
104 |
|
|
|
105 |
|
|
The user interface for dynamic PM
|
106 |
|
|
---------------------------------
|
107 |
|
|
|
108 |
|
|
The user interface for controlling dynamic PM is located in the power/
|
109 |
|
|
subdirectory of each USB device's sysfs directory, that is, in
|
110 |
|
|
/sys/bus/usb/devices/.../power/ where "..." is the device's ID. The
|
111 |
|
|
relevant attribute files are: wakeup, level, and autosuspend.
|
112 |
|
|
|
113 |
|
|
power/wakeup
|
114 |
|
|
|
115 |
|
|
This file is empty if the device does not support
|
116 |
|
|
remote wakeup. Otherwise the file contains either the
|
117 |
|
|
word "enabled" or the word "disabled", and you can
|
118 |
|
|
write those words to the file. The setting determines
|
119 |
|
|
whether or not remote wakeup will be enabled when the
|
120 |
|
|
device is next suspended. (If the setting is changed
|
121 |
|
|
while the device is suspended, the change won't take
|
122 |
|
|
effect until the following suspend.)
|
123 |
|
|
|
124 |
|
|
power/level
|
125 |
|
|
|
126 |
|
|
This file contains one of three words: "on", "auto",
|
127 |
|
|
or "suspend". You can write those words to the file
|
128 |
|
|
to change the device's setting.
|
129 |
|
|
|
130 |
|
|
"on" means that the device should be resumed and
|
131 |
|
|
autosuspend is not allowed. (Of course, system
|
132 |
|
|
suspends are still allowed.)
|
133 |
|
|
|
134 |
|
|
"auto" is the normal state in which the kernel is
|
135 |
|
|
allowed to autosuspend and autoresume the device.
|
136 |
|
|
|
137 |
|
|
"suspend" means that the device should remain
|
138 |
|
|
suspended, and autoresume is not allowed. (But remote
|
139 |
|
|
wakeup may still be allowed, since it is controlled
|
140 |
|
|
separately by the power/wakeup attribute.)
|
141 |
|
|
|
142 |
|
|
power/autosuspend
|
143 |
|
|
|
144 |
|
|
This file contains an integer value, which is the
|
145 |
|
|
number of seconds the device should remain idle before
|
146 |
|
|
the kernel will autosuspend it (the idle-delay time).
|
147 |
|
|
The default is 2. 0 means to autosuspend as soon as
|
148 |
|
|
the device becomes idle, and -1 means never to
|
149 |
|
|
autosuspend. You can write a number to the file to
|
150 |
|
|
change the autosuspend idle-delay time.
|
151 |
|
|
|
152 |
|
|
Writing "-1" to power/autosuspend and writing "on" to power/level do
|
153 |
|
|
essentially the same thing -- they both prevent the device from being
|
154 |
|
|
autosuspended. Yes, this is a redundancy in the API.
|
155 |
|
|
|
156 |
|
|
(In 2.6.21 writing "0" to power/autosuspend would prevent the device
|
157 |
|
|
from being autosuspended; the behavior was changed in 2.6.22. The
|
158 |
|
|
power/autosuspend attribute did not exist prior to 2.6.21, and the
|
159 |
|
|
power/level attribute did not exist prior to 2.6.22.)
|
160 |
|
|
|
161 |
|
|
|
162 |
|
|
Changing the default idle-delay time
|
163 |
|
|
------------------------------------
|
164 |
|
|
|
165 |
|
|
The default autosuspend idle-delay time is controlled by a module
|
166 |
|
|
parameter in usbcore. You can specify the value when usbcore is
|
167 |
|
|
loaded. For example, to set it to 5 seconds instead of 2 you would
|
168 |
|
|
do:
|
169 |
|
|
|
170 |
|
|
modprobe usbcore autosuspend=5
|
171 |
|
|
|
172 |
|
|
Equivalently, you could add to /etc/modprobe.conf a line saying:
|
173 |
|
|
|
174 |
|
|
options usbcore autosuspend=5
|
175 |
|
|
|
176 |
|
|
Some distributions load the usbcore module very early during the boot
|
177 |
|
|
process, by means of a program or script running from an initramfs
|
178 |
|
|
image. To alter the parameter value you would have to rebuild that
|
179 |
|
|
image.
|
180 |
|
|
|
181 |
|
|
If usbcore is compiled into the kernel rather than built as a loadable
|
182 |
|
|
module, you can add
|
183 |
|
|
|
184 |
|
|
usbcore.autosuspend=5
|
185 |
|
|
|
186 |
|
|
to the kernel's boot command line.
|
187 |
|
|
|
188 |
|
|
Finally, the parameter value can be changed while the system is
|
189 |
|
|
running. If you do:
|
190 |
|
|
|
191 |
|
|
echo 5 >/sys/module/usbcore/parameters/autosuspend
|
192 |
|
|
|
193 |
|
|
then each new USB device will have its autosuspend idle-delay
|
194 |
|
|
initialized to 5. (The idle-delay values for already existing devices
|
195 |
|
|
will not be affected.)
|
196 |
|
|
|
197 |
|
|
Setting the initial default idle-delay to -1 will prevent any
|
198 |
|
|
autosuspend of any USB device. This is a simple alternative to
|
199 |
|
|
disabling CONFIG_USB_SUSPEND and rebuilding the kernel, and it has the
|
200 |
|
|
added benefit of allowing you to enable autosuspend for selected
|
201 |
|
|
devices.
|
202 |
|
|
|
203 |
|
|
|
204 |
|
|
Warnings
|
205 |
|
|
--------
|
206 |
|
|
|
207 |
|
|
The USB specification states that all USB devices must support power
|
208 |
|
|
management. Nevertheless, the sad fact is that many devices do not
|
209 |
|
|
support it very well. You can suspend them all right, but when you
|
210 |
|
|
try to resume them they disconnect themselves from the USB bus or
|
211 |
|
|
they stop working entirely. This seems to be especially prevalent
|
212 |
|
|
among printers and scanners, but plenty of other types of device have
|
213 |
|
|
the same deficiency.
|
214 |
|
|
|
215 |
|
|
For this reason, by default the kernel disables autosuspend (the
|
216 |
|
|
power/level attribute is initialized to "on") for all devices other
|
217 |
|
|
than hubs. Hubs, at least, appear to be reasonably well-behaved in
|
218 |
|
|
this regard.
|
219 |
|
|
|
220 |
|
|
(In 2.6.21 and 2.6.22 this wasn't the case. Autosuspend was enabled
|
221 |
|
|
by default for almost all USB devices. A number of people experienced
|
222 |
|
|
problems as a result.)
|
223 |
|
|
|
224 |
|
|
This means that non-hub devices won't be autosuspended unless the user
|
225 |
|
|
or a program explicitly enables it. As of this writing there aren't
|
226 |
|
|
any widespread programs which will do this; we hope that in the near
|
227 |
|
|
future device managers such as HAL will take on this added
|
228 |
|
|
responsibility. In the meantime you can always carry out the
|
229 |
|
|
necessary operations by hand or add them to a udev script. You can
|
230 |
|
|
also change the idle-delay time; 2 seconds is not the best choice for
|
231 |
|
|
every device.
|
232 |
|
|
|
233 |
|
|
Sometimes it turns out that even when a device does work okay with
|
234 |
|
|
autosuspend there are still problems. For example, there are
|
235 |
|
|
experimental patches adding autosuspend support to the usbhid driver,
|
236 |
|
|
which manages keyboards and mice, among other things. Tests with a
|
237 |
|
|
number of keyboards showed that typing on a suspended keyboard, while
|
238 |
|
|
causing the keyboard to do a remote wakeup all right, would
|
239 |
|
|
nonetheless frequently result in lost keystrokes. Tests with mice
|
240 |
|
|
showed that some of them would issue a remote-wakeup request in
|
241 |
|
|
response to button presses but not to motion, and some in response to
|
242 |
|
|
neither.
|
243 |
|
|
|
244 |
|
|
The kernel will not prevent you from enabling autosuspend on devices
|
245 |
|
|
that can't handle it. It is even possible in theory to damage a
|
246 |
|
|
device by suspending it at the wrong time -- for example, suspending a
|
247 |
|
|
USB hard disk might cause it to spin down without parking the heads.
|
248 |
|
|
(Highly unlikely, but possible.) Take care.
|
249 |
|
|
|
250 |
|
|
|
251 |
|
|
The driver interface for Power Management
|
252 |
|
|
-----------------------------------------
|
253 |
|
|
|
254 |
|
|
The requirements for a USB driver to support external power management
|
255 |
|
|
are pretty modest; the driver need only define
|
256 |
|
|
|
257 |
|
|
.suspend
|
258 |
|
|
.resume
|
259 |
|
|
.reset_resume
|
260 |
|
|
|
261 |
|
|
methods in its usb_driver structure, and the reset_resume method is
|
262 |
|
|
optional. The methods' jobs are quite simple:
|
263 |
|
|
|
264 |
|
|
The suspend method is called to warn the driver that the
|
265 |
|
|
device is going to be suspended. If the driver returns a
|
266 |
|
|
negative error code, the suspend will be aborted. Normally
|
267 |
|
|
the driver will return 0, in which case it must cancel all
|
268 |
|
|
outstanding URBs (usb_kill_urb()) and not submit any more.
|
269 |
|
|
|
270 |
|
|
The resume method is called to tell the driver that the
|
271 |
|
|
device has been resumed and the driver can return to normal
|
272 |
|
|
operation. URBs may once more be submitted.
|
273 |
|
|
|
274 |
|
|
The reset_resume method is called to tell the driver that
|
275 |
|
|
the device has been resumed and it also has been reset.
|
276 |
|
|
The driver should redo any necessary device initialization,
|
277 |
|
|
since the device has probably lost most or all of its state
|
278 |
|
|
(although the interfaces will be in the same altsettings as
|
279 |
|
|
before the suspend).
|
280 |
|
|
|
281 |
|
|
If the device is disconnected or powered down while it is suspended,
|
282 |
|
|
the disconnect method will be called instead of the resume or
|
283 |
|
|
reset_resume method. This is also quite likely to happen when
|
284 |
|
|
waking up from hibernation, as many systems do not maintain suspend
|
285 |
|
|
current to the USB host controllers during hibernation. (It's
|
286 |
|
|
possible to work around the hibernation-forces-disconnect problem by
|
287 |
|
|
using the USB Persist facility.)
|
288 |
|
|
|
289 |
|
|
The reset_resume method is used by the USB Persist facility (see
|
290 |
|
|
Documentation/usb/persist.txt) and it can also be used under certain
|
291 |
|
|
circumstances when CONFIG_USB_PERSIST is not enabled. Currently, if a
|
292 |
|
|
device is reset during a resume and the driver does not have a
|
293 |
|
|
reset_resume method, the driver won't receive any notification about
|
294 |
|
|
the resume. Later kernels will call the driver's disconnect method;
|
295 |
|
|
2.6.23 doesn't do this.
|
296 |
|
|
|
297 |
|
|
USB drivers are bound to interfaces, so their suspend and resume
|
298 |
|
|
methods get called when the interfaces are suspended or resumed. In
|
299 |
|
|
principle one might want to suspend some interfaces on a device (i.e.,
|
300 |
|
|
force the drivers for those interface to stop all activity) without
|
301 |
|
|
suspending the other interfaces. The USB core doesn't allow this; all
|
302 |
|
|
interfaces are suspended when the device itself is suspended and all
|
303 |
|
|
interfaces are resumed when the device is resumed. It isn't possible
|
304 |
|
|
to suspend or resume some but not all of a device's interfaces. The
|
305 |
|
|
closest you can come is to unbind the interfaces' drivers.
|
306 |
|
|
|
307 |
|
|
|
308 |
|
|
The driver interface for autosuspend and autoresume
|
309 |
|
|
---------------------------------------------------
|
310 |
|
|
|
311 |
|
|
To support autosuspend and autoresume, a driver should implement all
|
312 |
|
|
three of the methods listed above. In addition, a driver indicates
|
313 |
|
|
that it supports autosuspend by setting the .supports_autosuspend flag
|
314 |
|
|
in its usb_driver structure. It is then responsible for informing the
|
315 |
|
|
USB core whenever one of its interfaces becomes busy or idle. The
|
316 |
|
|
driver does so by calling these three functions:
|
317 |
|
|
|
318 |
|
|
int usb_autopm_get_interface(struct usb_interface *intf);
|
319 |
|
|
void usb_autopm_put_interface(struct usb_interface *intf);
|
320 |
|
|
int usb_autopm_set_interface(struct usb_interface *intf);
|
321 |
|
|
|
322 |
|
|
The functions work by maintaining a counter in the usb_interface
|
323 |
|
|
structure. When intf->pm_usage_count is > 0 then the interface is
|
324 |
|
|
deemed to be busy, and the kernel will not autosuspend the interface's
|
325 |
|
|
device. When intf->pm_usage_count is <= 0 then the interface is
|
326 |
|
|
considered to be idle, and the kernel may autosuspend the device.
|
327 |
|
|
|
328 |
|
|
(There is a similar pm_usage_count field in struct usb_device,
|
329 |
|
|
associated with the device itself rather than any of its interfaces.
|
330 |
|
|
This field is used only by the USB core.)
|
331 |
|
|
|
332 |
|
|
The driver owns intf->pm_usage_count; it can modify the value however
|
333 |
|
|
and whenever it likes. A nice aspect of the usb_autopm_* routines is
|
334 |
|
|
that the changes they make are protected by the usb_device structure's
|
335 |
|
|
PM mutex (udev->pm_mutex); however drivers may change pm_usage_count
|
336 |
|
|
without holding the mutex.
|
337 |
|
|
|
338 |
|
|
usb_autopm_get_interface() increments pm_usage_count and
|
339 |
|
|
attempts an autoresume if the new value is > 0 and the
|
340 |
|
|
device is suspended.
|
341 |
|
|
|
342 |
|
|
usb_autopm_put_interface() decrements pm_usage_count and
|
343 |
|
|
attempts an autosuspend if the new value is <= 0 and the
|
344 |
|
|
device isn't suspended.
|
345 |
|
|
|
346 |
|
|
usb_autopm_set_interface() leaves pm_usage_count alone.
|
347 |
|
|
It attempts an autoresume if the value is > 0 and the device
|
348 |
|
|
is suspended, and it attempts an autosuspend if the value is
|
349 |
|
|
<= 0 and the device isn't suspended.
|
350 |
|
|
|
351 |
|
|
There also are a couple of utility routines drivers can use:
|
352 |
|
|
|
353 |
|
|
usb_autopm_enable() sets pm_usage_cnt to 1 and then calls
|
354 |
|
|
usb_autopm_set_interface(), which will attempt an autoresume.
|
355 |
|
|
|
356 |
|
|
usb_autopm_disable() sets pm_usage_cnt to 0 and then calls
|
357 |
|
|
usb_autopm_set_interface(), which will attempt an autosuspend.
|
358 |
|
|
|
359 |
|
|
The conventional usage pattern is that a driver calls
|
360 |
|
|
usb_autopm_get_interface() in its open routine and
|
361 |
|
|
usb_autopm_put_interface() in its close or release routine. But
|
362 |
|
|
other patterns are possible.
|
363 |
|
|
|
364 |
|
|
The autosuspend attempts mentioned above will often fail for one
|
365 |
|
|
reason or another. For example, the power/level attribute might be
|
366 |
|
|
set to "on", or another interface in the same device might not be
|
367 |
|
|
idle. This is perfectly normal. If the reason for failure was that
|
368 |
|
|
the device hasn't been idle for long enough, a delayed workqueue
|
369 |
|
|
routine is automatically set up to carry out the operation when the
|
370 |
|
|
autosuspend idle-delay has expired.
|
371 |
|
|
|
372 |
|
|
Autoresume attempts also can fail. This will happen if power/level is
|
373 |
|
|
set to "suspend" or if the device doesn't manage to resume properly.
|
374 |
|
|
Unlike autosuspend, there's no delay for an autoresume.
|
375 |
|
|
|
376 |
|
|
|
377 |
|
|
Other parts of the driver interface
|
378 |
|
|
-----------------------------------
|
379 |
|
|
|
380 |
|
|
Sometimes a driver needs to make sure that remote wakeup is enabled
|
381 |
|
|
during autosuspend. For example, there's not much point
|
382 |
|
|
autosuspending a keyboard if the user can't cause the keyboard to do a
|
383 |
|
|
remote wakeup by typing on it. If the driver sets
|
384 |
|
|
intf->needs_remote_wakeup to 1, the kernel won't autosuspend the
|
385 |
|
|
device if remote wakeup isn't available or has been disabled through
|
386 |
|
|
the power/wakeup attribute. (If the device is already autosuspended,
|
387 |
|
|
though, setting this flag won't cause the kernel to autoresume it.
|
388 |
|
|
Normally a driver would set this flag in its probe method, at which
|
389 |
|
|
time the device is guaranteed not to be autosuspended.)
|
390 |
|
|
|
391 |
|
|
The usb_autopm_* routines have to run in a sleepable process context;
|
392 |
|
|
they must not be called from an interrupt handler or while holding a
|
393 |
|
|
spinlock. In fact, the entire autosuspend mechanism is not well geared
|
394 |
|
|
toward interrupt-driven operation. However there is one thing a
|
395 |
|
|
driver can do in an interrupt handler:
|
396 |
|
|
|
397 |
|
|
usb_mark_last_busy(struct usb_device *udev);
|
398 |
|
|
|
399 |
|
|
This sets udev->last_busy to the current time. udev->last_busy is the
|
400 |
|
|
field used for idle-delay calculations; updating it will cause any
|
401 |
|
|
pending autosuspend to be moved back. The usb_autopm_* routines will
|
402 |
|
|
also set the last_busy field to the current time.
|
403 |
|
|
|
404 |
|
|
Calling urb_mark_last_busy() from within an URB completion handler is
|
405 |
|
|
subject to races: The kernel may have just finished deciding the
|
406 |
|
|
device has been idle for long enough but not yet gotten around to
|
407 |
|
|
calling the driver's suspend method. The driver would have to be
|
408 |
|
|
responsible for synchronizing its suspend method with its URB
|
409 |
|
|
completion handler and causing the autosuspend to fail with -EBUSY if
|
410 |
|
|
an URB had completed too recently.
|
411 |
|
|
|
412 |
|
|
External suspend calls should never be allowed to fail in this way,
|
413 |
|
|
only autosuspend calls. The driver can tell them apart by checking
|
414 |
|
|
udev->auto_pm; this flag will be set to 1 for internal PM events
|
415 |
|
|
(autosuspend or autoresume) and 0 for external PM events.
|
416 |
|
|
|
417 |
|
|
Many of the ingredients in the autosuspend framework are oriented
|
418 |
|
|
towards interfaces: The usb_interface structure contains the
|
419 |
|
|
pm_usage_cnt field, and the usb_autopm_* routines take an interface
|
420 |
|
|
pointer as their argument. But somewhat confusingly, a few of the
|
421 |
|
|
pieces (usb_mark_last_busy() and udev->auto_pm) use the usb_device
|
422 |
|
|
structure instead. Drivers need to keep this straight; they can call
|
423 |
|
|
interface_to_usbdev() to find the device structure for a given
|
424 |
|
|
interface.
|
425 |
|
|
|
426 |
|
|
|
427 |
|
|
Locking requirements
|
428 |
|
|
--------------------
|
429 |
|
|
|
430 |
|
|
All three suspend/resume methods are always called while holding the
|
431 |
|
|
usb_device's PM mutex. For external events -- but not necessarily for
|
432 |
|
|
autosuspend or autoresume -- the device semaphore (udev->dev.sem) will
|
433 |
|
|
also be held. This implies that external suspend/resume events are
|
434 |
|
|
mutually exclusive with calls to probe, disconnect, pre_reset, and
|
435 |
|
|
post_reset; the USB core guarantees that this is true of internal
|
436 |
|
|
suspend/resume events as well.
|
437 |
|
|
|
438 |
|
|
If a driver wants to block all suspend/resume calls during some
|
439 |
|
|
critical section, it can simply acquire udev->pm_mutex.
|
440 |
|
|
Alternatively, if the critical section might call some of the
|
441 |
|
|
usb_autopm_* routines, the driver can avoid deadlock by doing:
|
442 |
|
|
|
443 |
|
|
down(&udev->dev.sem);
|
444 |
|
|
rc = usb_autopm_get_interface(intf);
|
445 |
|
|
|
446 |
|
|
and at the end of the critical section:
|
447 |
|
|
|
448 |
|
|
if (!rc)
|
449 |
|
|
usb_autopm_put_interface(intf);
|
450 |
|
|
up(&udev->dev.sem);
|
451 |
|
|
|
452 |
|
|
Holding the device semaphore will block all external PM calls, and the
|
453 |
|
|
usb_autopm_get_interface() will prevent any internal PM calls, even if
|
454 |
|
|
it fails. (Exercise: Why?)
|
455 |
|
|
|
456 |
|
|
The rules for locking order are:
|
457 |
|
|
|
458 |
|
|
Never acquire any device semaphore while holding any PM mutex.
|
459 |
|
|
|
460 |
|
|
Never acquire udev->pm_mutex while holding the PM mutex for
|
461 |
|
|
a device that isn't a descendant of udev.
|
462 |
|
|
|
463 |
|
|
In other words, PM mutexes should only be acquired going up the device
|
464 |
|
|
tree, and they should be acquired only after locking all the device
|
465 |
|
|
semaphores you need to hold. These rules don't matter to drivers very
|
466 |
|
|
much; they usually affect just the USB core.
|
467 |
|
|
|
468 |
|
|
Still, drivers do need to be careful. For example, many drivers use a
|
469 |
|
|
private mutex to synchronize their normal I/O activities with their
|
470 |
|
|
disconnect method. Now if the driver supports autosuspend then it
|
471 |
|
|
must call usb_autopm_put_interface() from somewhere -- maybe from its
|
472 |
|
|
close method. It should make the call while holding the private mutex,
|
473 |
|
|
since a driver shouldn't call any of the usb_autopm_* functions for an
|
474 |
|
|
interface from which it has been unbound.
|
475 |
|
|
|
476 |
|
|
But the usb_autpm_* routines always acquire the device's PM mutex, and
|
477 |
|
|
consequently the locking order has to be: private mutex first, PM
|
478 |
|
|
mutex second. Since the suspend method is always called with the PM
|
479 |
|
|
mutex held, it mustn't try to acquire the private mutex. It has to
|
480 |
|
|
synchronize with the driver's I/O activities in some other way.
|
481 |
|
|
|
482 |
|
|
|
483 |
|
|
Interaction between dynamic PM and system PM
|
484 |
|
|
--------------------------------------------
|
485 |
|
|
|
486 |
|
|
Dynamic power management and system power management can interact in
|
487 |
|
|
a couple of ways.
|
488 |
|
|
|
489 |
|
|
Firstly, a device may already be manually suspended or autosuspended
|
490 |
|
|
when a system suspend occurs. Since system suspends are supposed to
|
491 |
|
|
be as transparent as possible, the device should remain suspended
|
492 |
|
|
following the system resume. The 2.6.23 kernel obeys this principle
|
493 |
|
|
for manually suspended devices but not for autosuspended devices; they
|
494 |
|
|
do get resumed when the system wakes up. (Presumably they will be
|
495 |
|
|
autosuspended again after their idle-delay time expires.) In later
|
496 |
|
|
kernels this behavior will be fixed.
|
497 |
|
|
|
498 |
|
|
(There is an exception. If a device would undergo a reset-resume
|
499 |
|
|
instead of a normal resume, and the device is enabled for remote
|
500 |
|
|
wakeup, then the reset-resume takes place even if the device was
|
501 |
|
|
already suspended when the system suspend began. The justification is
|
502 |
|
|
that a reset-resume is a kind of remote-wakeup event. Or to put it
|
503 |
|
|
another way, a device which needs a reset won't be able to generate
|
504 |
|
|
normal remote-wakeup signals, so it ought to be resumed immediately.)
|
505 |
|
|
|
506 |
|
|
Secondly, a dynamic power-management event may occur as a system
|
507 |
|
|
suspend is underway. The window for this is short, since system
|
508 |
|
|
suspends don't take long (a few seconds usually), but it can happen.
|
509 |
|
|
For example, a suspended device may send a remote-wakeup signal while
|
510 |
|
|
the system is suspending. The remote wakeup may succeed, which would
|
511 |
|
|
cause the system suspend to abort. If the remote wakeup doesn't
|
512 |
|
|
succeed, it may still remain active and thus cause the system to
|
513 |
|
|
resume as soon as the system suspend is complete. Or the remote
|
514 |
|
|
wakeup may fail and get lost. Which outcome occurs depends on timing
|
515 |
|
|
and on the hardware and firmware design.
|
516 |
|
|
|
517 |
|
|
More interestingly, a device might undergo a manual resume or
|
518 |
|
|
autoresume during system suspend. With current kernels this shouldn't
|
519 |
|
|
happen, because manual resumes must be initiated by userspace and
|
520 |
|
|
autoresumes happen in response to I/O requests, but all user processes
|
521 |
|
|
and I/O should be quiescent during a system suspend -- thanks to the
|
522 |
|
|
freezer. However there are plans to do away with the freezer, which
|
523 |
|
|
would mean these things would become possible. If and when this comes
|
524 |
|
|
about, the USB core will carefully arrange matters so that either type
|
525 |
|
|
of resume will block until the entire system has resumed.
|