1 .. _usb-power-management: 2 3 Power Management for USB 4 ~~~~~~~~~~~~~~~~~~~~~~~~ 5 6 :Author: Alan Stern <stern@rowland.harvard.edu> 7 :Date: Last-updated: February 2014 8 9 .. 10 Contents: 11 --------- 12 * What is Power Management? 13 * What is Remote Wakeup? 14 * When is a USB device idle? 15 * Forms of dynamic PM 16 * The user interface for dynamic PM 17 * Changing the default idle-delay time 18 * Warnings 19 * The driver interface for Power Management 20 * The driver interface for autosuspend and autoresume 21 * Other parts of the driver interface 22 * Mutual exclusion 23 * Interaction between dynamic PM and system PM 24 * xHCI hardware link PM 25 * USB Port Power Control 26 * User Interface for Port Power Control 27 * Suggested Userspace Port Power Policy 28 29 30 What is Power Management? 31 ------------------------- 32 33 Power Management (PM) is the practice of saving energy by suspending 34 parts of a computer system when they aren't being used. While a 35 component is ``suspended`` it is in a nonfunctional low-power state; it 36 might even be turned off completely. A suspended component can be 37 ``resumed`` (returned to a functional full-power state) when the kernel 38 needs to use it. (There also are forms of PM in which components are 39 placed in a less functional but still usable state instead of being 40 suspended; an example would be reducing the CPU's clock rate. This 41 document will not discuss those other forms.) 42 43 When the parts being suspended include the CPU and most of the rest of 44 the system, we speak of it as a "system suspend". When a particular 45 device is turned off while the system as a whole remains running, we 46 call it a "dynamic suspend" (also known as a "runtime suspend" or 47 "selective suspend"). This document concentrates mostly on how 48 dynamic PM is implemented in the USB subsystem, although system PM is 49 covered to some extent (see ``Documentation/power/*.rst`` for more 50 information about system PM). 51 52 System PM support is present only if the kernel was built with 53 ``CONFIG_SUSPEND`` or ``CONFIG_HIBERNATION`` enabled. Dynamic PM support 54 55 for USB is present whenever 56 the kernel was built with ``CONFIG_PM`` enabled. 57 58 [Historically, dynamic PM support for USB was present only if the 59 kernel had been built with ``CONFIG_USB_SUSPEND`` enabled (which depended on 60 ``CONFIG_PM_RUNTIME``). Starting with the 3.10 kernel release, dynamic PM 61 support for USB was present whenever the kernel was built with 62 ``CONFIG_PM_RUNTIME`` enabled. The ``CONFIG_USB_SUSPEND`` option had been 63 eliminated.] 64 65 66 What is Remote Wakeup? 67 ---------------------- 68 69 When a device has been suspended, it generally doesn't resume until 70 the computer tells it to. Likewise, if the entire computer has been 71 suspended, it generally doesn't resume until the user tells it to, say 72 by pressing a power button or opening the cover. 73 74 However some devices have the capability of resuming by themselves, or 75 asking the kernel to resume them, or even telling the entire computer 76 to resume. This capability goes by several names such as "Wake On 77 LAN"; we will refer to it generically as "remote wakeup". When a 78 device is enabled for remote wakeup and it is suspended, it may resume 79 itself (or send a request to be resumed) in response to some external 80 event. Examples include a suspended keyboard resuming when a key is 81 pressed, or a suspended USB hub resuming when a device is plugged in. 82 83 84 When is a USB device idle? 85 -------------------------- 86 87 A device is idle whenever the kernel thinks it's not busy doing 88 anything important and thus is a candidate for being suspended. The 89 exact definition depends on the device's driver; drivers are allowed 90 to declare that a device isn't idle even when there's no actual 91 communication taking place. (For example, a hub isn't considered idle 92 unless all the devices plugged into that hub are already suspended.) 93 In addition, a device isn't considered idle so long as a program keeps 94 its usbfs file open, whether or not any I/O is going on. 95 96 If a USB device has no driver, its usbfs file isn't open, and it isn't 97 being accessed through sysfs, then it definitely is idle. 98 99 100 Forms of dynamic PM 101 ------------------- 102 103 Dynamic suspends occur when the kernel decides to suspend an idle 104 device. This is called ``autosuspend`` for short. In general, a device 105 won't be autosuspended unless it has been idle for some minimum period 106 of time, the so-called idle-delay time. 107 108 Of course, nothing the kernel does on its own initiative should 109 prevent the computer or its devices from working properly. If a 110 device has been autosuspended and a program tries to use it, the 111 kernel will automatically resume the device (autoresume). For the 112 same reason, an autosuspended device will usually have remote wakeup 113 enabled, if the device supports remote wakeup. 114 115 It is worth mentioning that many USB drivers don't support 116 autosuspend. In fact, at the time of this writing (Linux 2.6.23) the 117 only drivers which do support it are the hub driver, kaweth, asix, 118 usblp, usblcd, and usb-skeleton (which doesn't count). If a 119 non-supporting driver is bound to a device, the device won't be 120 autosuspended. In effect, the kernel pretends the device is never 121 idle. 122 123 We can categorize power management events in two broad classes: 124 external and internal. External events are those triggered by some 125 agent outside the USB stack: system suspend/resume (triggered by 126 userspace), manual dynamic resume (also triggered by userspace), and 127 remote wakeup (triggered by the device). Internal events are those 128 triggered within the USB stack: autosuspend and autoresume. Note that 129 all dynamic suspend events are internal; external agents are not 130 allowed to issue dynamic suspends. 131 132 133 The user interface for dynamic PM 134 --------------------------------- 135 136 The user interface for controlling dynamic PM is located in the ``power/`` 137 subdirectory of each USB device's sysfs directory, that is, in 138 ``/sys/bus/usb/devices/.../power/`` where "..." is the device's ID. The 139 relevant attribute files are: wakeup, control, and 140 ``autosuspend_delay_ms``. (There may also be a file named ``level``; this 141 file was deprecated as of the 2.6.35 kernel and replaced by the 142 ``control`` file. In 2.6.38 the ``autosuspend`` file will be deprecated 143 and replaced by the ``autosuspend_delay_ms`` file. The only difference 144 is that the newer file expresses the delay in milliseconds whereas the 145 older file uses seconds. Confusingly, both files are present in 2.6.37 146 but only ``autosuspend`` works.) 147 148 ``power/wakeup`` 149 150 This file is empty if the device does not support 151 remote wakeup. Otherwise the file contains either the 152 word ``enabled`` or the word ``disabled``, and you can 153 write those words to the file. The setting determines 154 whether or not remote wakeup will be enabled when the 155 device is next suspended. (If the setting is changed 156 while the device is suspended, the change won't take 157 effect until the following suspend.) 158 159 ``power/control`` 160 161 This file contains one of two words: ``on`` or ``auto``. 162 You can write those words to the file to change the 163 device's setting. 164 165 - ``on`` means that the device should be resumed and 166 autosuspend is not allowed. (Of course, system 167 suspends are still allowed.) 168 169 - ``auto`` is the normal state in which the kernel is 170 allowed to autosuspend and autoresume the device. 171 172 (In kernels up to 2.6.32, you could also specify 173 ``suspend``, meaning that the device should remain 174 suspended and autoresume was not allowed. This 175 setting is no longer supported.) 176 177 ``power/autosuspend_delay_ms`` 178 179 This file contains an integer value, which is the 180 number of milliseconds the device should remain idle 181 before the kernel will autosuspend it (the idle-delay 182 time). The default is 2000. 0 means to autosuspend 183 as soon as the device becomes idle, and negative 184 values mean never to autosuspend. You can write a 185 number to the file to change the autosuspend 186 idle-delay time. 187 188 Writing ``-1`` to ``power/autosuspend_delay_ms`` and writing ``on`` to 189 ``power/control`` do essentially the same thing -- they both prevent the 190 device from being autosuspended. Yes, this is a redundancy in the 191 API. 192 193 (In 2.6.21 writing ``0`` to ``power/autosuspend`` would prevent the device 194 from being autosuspended; the behavior was changed in 2.6.22. The 195 ``power/autosuspend`` attribute did not exist prior to 2.6.21, and the 196 ``power/level`` attribute did not exist prior to 2.6.22. ``power/control`` 197 was added in 2.6.34, and ``power/autosuspend_delay_ms`` was added in 198 2.6.37 but did not become functional until 2.6.38.) 199 200 201 Changing the default idle-delay time 202 ------------------------------------ 203 204 The default autosuspend idle-delay time (in seconds) is controlled by 205 a module parameter in usbcore. You can specify the value when usbcore 206 is loaded. For example, to set it to 5 seconds instead of 2 you would 207 do:: 208 209 modprobe usbcore autosuspend=5 210 211 Equivalently, you could add to a configuration file in /etc/modprobe.d 212 a line saying:: 213 214 options usbcore autosuspend=5 215 216 Some distributions load the usbcore module very early during the boot 217 process, by means of a program or script running from an initramfs 218 image. To alter the parameter value you would have to rebuild that 219 image. 220 221 If usbcore is compiled into the kernel rather than built as a loadable 222 module, you can add:: 223 224 usbcore.autosuspend=5 225 226 to the kernel's boot command line. 227 228 Finally, the parameter value can be changed while the system is 229 running. If you do:: 230 231 echo 5 >/sys/module/usbcore/parameters/autosuspend 232 233 then each new USB device will have its autosuspend idle-delay 234 initialized to 5. (The idle-delay values for already existing devices 235 will not be affected.) 236 237 Setting the initial default idle-delay to -1 will prevent any 238 autosuspend of any USB device. This has the benefit of allowing you 239 then to enable autosuspend for selected devices. 240 241 242 Warnings 243 -------- 244 245 The USB specification states that all USB devices must support power 246 management. Nevertheless, the sad fact is that many devices do not 247 support it very well. You can suspend them all right, but when you 248 try to resume them they disconnect themselves from the USB bus or 249 they stop working entirely. This seems to be especially prevalent 250 among printers and scanners, but plenty of other types of device have 251 the same deficiency. 252 253 For this reason, by default the kernel disables autosuspend (the 254 ``power/control`` attribute is initialized to ``on``) for all devices other 255 than hubs. Hubs, at least, appear to be reasonably well-behaved in 256 this regard. 257 258 (In 2.6.21 and 2.6.22 this wasn't the case. Autosuspend was enabled 259 by default for almost all USB devices. A number of people experienced 260 problems as a result.) 261 262 This means that non-hub devices won't be autosuspended unless the user 263 or a program explicitly enables it. As of this writing there aren't 264 any widespread programs which will do this; we hope that in the near 265 future device managers such as HAL will take on this added 266 responsibility. In the meantime you can always carry out the 267 necessary operations by hand or add them to a udev script. You can 268 also change the idle-delay time; 2 seconds is not the best choice for 269 every device. 270 271 If a driver knows that its device has proper suspend/resume support, 272 it can enable autosuspend all by itself. For example, the video 273 driver for a laptop's webcam might do this (in recent kernels they 274 do), since these devices are rarely used and so should normally be 275 autosuspended. 276 277 Sometimes it turns out that even when a device does work okay with 278 autosuspend there are still problems. For example, the usbhid driver, 279 which manages keyboards and mice, has autosuspend support. Tests with 280 a number of keyboards show that typing on a suspended keyboard, while 281 causing the keyboard to do a remote wakeup all right, will nonetheless 282 frequently result in lost keystrokes. Tests with mice show that some 283 of them will issue a remote-wakeup request in response to button 284 presses but not to motion, and some in response to neither. 285 286 The kernel will not prevent you from enabling autosuspend on devices 287 that can't handle it. It is even possible in theory to damage a 288 device by suspending it at the wrong time. (Highly unlikely, but 289 possible.) Take care. 290 291 292 The driver interface for Power Management 293 ----------------------------------------- 294 295 The requirements for a USB driver to support external power management 296 are pretty modest; the driver need only define:: 297 298 .suspend 299 .resume 300 .reset_resume 301 302 methods in its :c:type:`usb_driver` structure, and the ``reset_resume`` method 303 is optional. The methods' jobs are quite simple: 304 305 - The ``suspend`` method is called to warn the driver that the 306 device is going to be suspended. If the driver returns a 307 negative error code, the suspend will be aborted. Normally 308 the driver will return 0, in which case it must cancel all 309 outstanding URBs (:c:func:`usb_kill_urb`) and not submit any more. 310 311 - The ``resume`` method is called to tell the driver that the 312 device has been resumed and the driver can return to normal 313 operation. URBs may once more be submitted. 314 315 - The ``reset_resume`` method is called to tell the driver that 316 the device has been resumed and it also has been reset. 317 The driver should redo any necessary device initialization, 318 since the device has probably lost most or all of its state 319 (although the interfaces will be in the same altsettings as 320 before the suspend). 321 322 If the device is disconnected or powered down while it is suspended, 323 the ``disconnect`` method will be called instead of the ``resume`` or 324 ``reset_resume`` method. This is also quite likely to happen when 325 waking up from hibernation, as many systems do not maintain suspend 326 current to the USB host controllers during hibernation. (It's 327 possible to work around the hibernation-forces-disconnect problem by 328 using the USB Persist facility.) 329 330 The ``reset_resume`` method is used by the USB Persist facility (see 331 :ref:`usb-persist`) and it can also be used under certain 332 circumstances when ``CONFIG_USB_PERSIST`` is not enabled. Currently, if a 333 device is reset during a resume and the driver does not have a 334 ``reset_resume`` method, the driver won't receive any notification about 335 the resume. Later kernels will call the driver's ``disconnect`` method; 336 2.6.23 doesn't do this. 337 338 USB drivers are bound to interfaces, so their ``suspend`` and ``resume`` 339 methods get called when the interfaces are suspended or resumed. In 340 principle one might want to suspend some interfaces on a device (i.e., 341 force the drivers for those interface to stop all activity) without 342 suspending the other interfaces. The USB core doesn't allow this; all 343 interfaces are suspended when the device itself is suspended and all 344 interfaces are resumed when the device is resumed. It isn't possible 345 to suspend or resume some but not all of a device's interfaces. The 346 closest you can come is to unbind the interfaces' drivers. 347 348 349 The driver interface for autosuspend and autoresume 350 --------------------------------------------------- 351 352 To support autosuspend and autoresume, a driver should implement all 353 three of the methods listed above. In addition, a driver indicates 354 that it supports autosuspend by setting the ``.supports_autosuspend`` flag 355 in its usb_driver structure. It is then responsible for informing the 356 USB core whenever one of its interfaces becomes busy or idle. The 357 driver does so by calling these six functions:: 358 359 int usb_autopm_get_interface(struct usb_interface *intf); 360 void usb_autopm_put_interface(struct usb_interface *intf); 361 int usb_autopm_get_interface_async(struct usb_interface *intf); 362 void usb_autopm_put_interface_async(struct usb_interface *intf); 363 void usb_autopm_get_interface_no_resume(struct usb_interface *intf); 364 void usb_autopm_put_interface_no_suspend(struct usb_interface *intf); 365 366 The functions work by maintaining a usage counter in the 367 usb_interface's embedded device structure. When the counter is > 0 368 then the interface is deemed to be busy, and the kernel will not 369 autosuspend the interface's device. When the usage counter is = 0 370 then the interface is considered to be idle, and the kernel may 371 autosuspend the device. 372 373 Drivers must be careful to balance their overall changes to the usage 374 counter. Unbalanced "get"s will remain in effect when a driver is 375 unbound from its interface, preventing the device from going into 376 runtime suspend should the interface be bound to a driver again. On 377 the other hand, drivers are allowed to achieve this balance by calling 378 the ``usb_autopm_*`` functions even after their ``disconnect`` routine 379 has returned -- say from within a work-queue routine -- provided they 380 retain an active reference to the interface (via ``usb_get_intf`` and 381 ``usb_put_intf``). 382 383 Drivers using the async routines are responsible for their own 384 synchronization and mutual exclusion. 385 386 :c:func:`usb_autopm_get_interface` increments the usage counter and 387 does an autoresume if the device is suspended. If the 388 autoresume fails, the counter is decremented back. 389 390 :c:func:`usb_autopm_put_interface` decrements the usage counter and 391 attempts an autosuspend if the new value is = 0. 392 393 :c:func:`usb_autopm_get_interface_async` and 394 :c:func:`usb_autopm_put_interface_async` do almost the same things as 395 their non-async counterparts. The big difference is that they 396 use a workqueue to do the resume or suspend part of their 397 jobs. As a result they can be called in an atomic context, 398 such as an URB's completion handler, but when they return the 399 device will generally not yet be in the desired state. 400 401 :c:func:`usb_autopm_get_interface_no_resume` and 402 :c:func:`usb_autopm_put_interface_no_suspend` merely increment or 403 decrement the usage counter; they do not attempt to carry out 404 an autoresume or an autosuspend. Hence they can be called in 405 an atomic context. 406 407 The simplest usage pattern is that a driver calls 408 :c:func:`usb_autopm_get_interface` in its open routine and 409 :c:func:`usb_autopm_put_interface` in its close or release routine. But other 410 patterns are possible. 411 412 The autosuspend attempts mentioned above will often fail for one 413 reason or another. For example, the ``power/control`` attribute might be 414 set to ``on``, or another interface in the same device might not be 415 idle. This is perfectly normal. If the reason for failure was that 416 the device hasn't been idle for long enough, a timer is scheduled to 417 carry out the operation automatically when the autosuspend idle-delay 418 has expired. 419 420 Autoresume attempts also can fail, although failure would mean that 421 the device is no longer present or operating properly. Unlike 422 autosuspend, there's no idle-delay for an autoresume. 423 424 425 Other parts of the driver interface 426 ----------------------------------- 427 428 Drivers can enable autosuspend for their devices by calling:: 429 430 usb_enable_autosuspend(struct usb_device *udev); 431 432 in their :c:func:`probe` routine, if they know that the device is capable of 433 suspending and resuming correctly. This is exactly equivalent to 434 writing ``auto`` to the device's ``power/control`` attribute. Likewise, 435 drivers can disable autosuspend by calling:: 436 437 usb_disable_autosuspend(struct usb_device *udev); 438 439 This is exactly the same as writing ``on`` to the ``power/control`` attribute. 440 441 Sometimes a driver needs to make sure that remote wakeup is enabled 442 during autosuspend. For example, there's not much point 443 autosuspending a keyboard if the user can't cause the keyboard to do a 444 remote wakeup by typing on it. If the driver sets 445 ``intf->needs_remote_wakeup`` to 1, the kernel won't autosuspend the 446 device if remote wakeup isn't available. (If the device is already 447 autosuspended, though, setting this flag won't cause the kernel to 448 autoresume it. Normally a driver would set this flag in its ``probe`` 449 method, at which time the device is guaranteed not to be 450 autosuspended.) 451 452 If a driver does its I/O asynchronously in interrupt context, it 453 should call :c:func:`usb_autopm_get_interface_async` before starting output and 454 :c:func:`usb_autopm_put_interface_async` when the output queue drains. When 455 it receives an input event, it should call:: 456 457 usb_mark_last_busy(struct usb_device *udev); 458 459 in the event handler. This tells the PM core that the device was just 460 busy and therefore the next autosuspend idle-delay expiration should 461 be pushed back. Many of the usb_autopm_* routines also make this call, 462 so drivers need to worry only when interrupt-driven input arrives. 463 464 Asynchronous operation is always subject to races. For example, a 465 driver may call the :c:func:`usb_autopm_get_interface_async` routine at a time 466 when the core has just finished deciding the device has been idle for 467 long enough but not yet gotten around to calling the driver's ``suspend`` 468 method. The ``suspend`` method must be responsible for synchronizing with 469 the I/O request routine and the URB completion handler; it should 470 cause autosuspends to fail with -EBUSY if the driver needs to use the 471 device. 472 473 External suspend calls should never be allowed to fail in this way, 474 only autosuspend calls. The driver can tell them apart by applying 475 the :c:func:`PMSG_IS_AUTO` macro to the message argument to the ``suspend`` 476 method; it will return True for internal PM events (autosuspend) and 477 False for external PM events. 478 479 480 Mutual exclusion 481 ---------------- 482 483 For external events -- but not necessarily for autosuspend or 484 autoresume -- the device semaphore (udev->dev.sem) will be held when a 485 ``suspend`` or ``resume`` method is called. This implies that external 486 suspend/resume events are mutually exclusive with calls to ``probe``, 487 ``disconnect``, ``pre_reset``, and ``post_reset``; the USB core guarantees that 488 this is true of autosuspend/autoresume events as well. 489 490 If a driver wants to block all suspend/resume calls during some 491 critical section, the best way is to lock the device and call 492 :c:func:`usb_autopm_get_interface` (and do the reverse at the end of the 493 critical section). Holding the device semaphore will block all 494 external PM calls, and the :c:func:`usb_autopm_get_interface` will prevent any 495 internal PM calls, even if it fails. (Exercise: Why?) 496 497 498 Interaction between dynamic PM and system PM 499 -------------------------------------------- 500 501 Dynamic power management and system power management can interact in 502 a couple of ways. 503 504 Firstly, a device may already be autosuspended when a system suspend 505 occurs. Since system suspends are supposed to be as transparent as 506 possible, the device should remain suspended following the system 507 resume. But this theory may not work out well in practice; over time 508 the kernel's behavior in this regard has changed. As of 2.6.37 the 509 policy is to resume all devices during a system resume and let them 510 handle their own runtime suspends afterward. 511 512 Secondly, a dynamic power-management event may occur as a system 513 suspend is underway. The window for this is short, since system 514 suspends don't take long (a few seconds usually), but it can happen. 515 For example, a suspended device may send a remote-wakeup signal while 516 the system is suspending. The remote wakeup may succeed, which would 517 cause the system suspend to abort. If the remote wakeup doesn't 518 succeed, it may still remain active and thus cause the system to 519 resume as soon as the system suspend is complete. Or the remote 520 wakeup may fail and get lost. Which outcome occurs depends on timing 521 and on the hardware and firmware design. 522 523 524 xHCI hardware link PM 525 --------------------- 526 527 xHCI host controller provides hardware link power management to usb2.0 528 (xHCI 1.0 feature) and usb3.0 devices which support link PM. By 529 enabling hardware LPM, the host can automatically put the device into 530 lower power state(L1 for usb2.0 devices, or U1/U2 for usb3.0 devices), 531 which state device can enter and resume very quickly. 532 533 The user interface for controlling hardware LPM is located in the 534 ``power/`` subdirectory of each USB device's sysfs directory, that is, in 535 ``/sys/bus/usb/devices/.../power/`` where "..." is the device's ID. The 536 relevant attribute files are ``usb2_hardware_lpm`` and ``usb3_hardware_lpm``. 537 538 ``power/usb2_hardware_lpm`` 539 540 When a USB2 device which support LPM is plugged to a 541 xHCI host root hub which support software LPM, the 542 host will run a software LPM test for it; if the device 543 enters L1 state and resume successfully and the host 544 supports USB2 hardware LPM, this file will show up and 545 driver will enable hardware LPM for the device. You 546 can write y/Y/1 or n/N/0 to the file to enable/disable 547 USB2 hardware LPM manually. This is for test purpose mainly. 548 549 ``power/usb3_hardware_lpm_u1`` 550 ``power/usb3_hardware_lpm_u2`` 551 552 When a USB 3.0 lpm-capable device is plugged in to a 553 xHCI host which supports link PM, it will check if U1 554 and U2 exit latencies have been set in the BOS 555 descriptor; if the check is passed and the host 556 supports USB3 hardware LPM, USB3 hardware LPM will be 557 enabled for the device and these files will be created. 558 The files hold a string value (enable or disable) 559 indicating whether or not USB3 hardware LPM U1 or U2 560 is enabled for the device. 561 562 USB Port Power Control 563 ---------------------- 564 565 In addition to suspending endpoint devices and enabling hardware 566 controlled link power management, the USB subsystem also has the 567 capability to disable power to ports under some conditions. Power is 568 controlled through ``Set/ClearPortFeature(PORT_POWER)`` requests to a hub. 569 In the case of a root or platform-internal hub the host controller 570 driver translates ``PORT_POWER`` requests into platform firmware (ACPI) 571 method calls to set the port power state. For more background see the 572 Linux Plumbers Conference 2012 slides [#f1]_ and video [#f2]_: 573 574 Upon receiving a ``ClearPortFeature(PORT_POWER)`` request a USB port is 575 logically off, and may trigger the actual loss of VBUS to the port [#f3]_. 576 VBUS may be maintained in the case where a hub gangs multiple ports into 577 a shared power well causing power to remain until all ports in the gang 578 are turned off. VBUS may also be maintained by hub ports configured for 579 a charging application. In any event a logically off port will lose 580 connection with its device, not respond to hotplug events, and not 581 respond to remote wakeup events. 582 583 .. warning:: 584 585 turning off a port may result in the inability to hot add a device. 586 Please see "User Interface for Port Power Control" for details. 587 588 As far as the effect on the device itself it is similar to what a device 589 goes through during system suspend, i.e. the power session is lost. Any 590 USB device or driver that misbehaves with system suspend will be 591 similarly affected by a port power cycle event. For this reason the 592 implementation shares the same device recovery path (and honors the same 593 quirks) as the system resume path for the hub. 594 595 .. [#f1] 596 597 http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf 598 599 .. [#f2] 600 601 http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/ 602 603 .. [#f3] 604 605 USB 3.1 Section 10.12 606 607 wakeup note: if a device is configured to send wakeup events the port 608 power control implementation will block poweroff attempts on that 609 port. 610 611 612 User Interface for Port Power Control 613 ------------------------------------- 614 615 The port power control mechanism uses the PM runtime system. Poweroff is 616 requested by clearing the ``power/pm_qos_no_power_off`` flag of the port device 617 (defaults to 1). If the port is disconnected it will immediately receive a 618 ``ClearPortFeature(PORT_POWER)`` request. Otherwise, it will honor the pm 619 runtime rules and require the attached child device and all descendants to be 620 suspended. This mechanism is dependent on the hub advertising port power 621 switching in its hub descriptor (wHubCharacteristics logical power switching 622 mode field). 623 624 Note, some interface devices/drivers do not support autosuspend. Userspace may 625 need to unbind the interface drivers before the :c:type:`usb_device` will 626 suspend. An unbound interface device is suspended by default. When unbinding, 627 be careful to unbind interface drivers, not the driver of the parent usb 628 device. Also, leave hub interface drivers bound. If the driver for the usb 629 device (not interface) is unbound the kernel is no longer able to resume the 630 device. If a hub interface driver is unbound, control of its child ports is 631 lost and all attached child-devices will disconnect. A good rule of thumb is 632 that if the 'driver/module' link for a device points to 633 ``/sys/module/usbcore`` then unbinding it will interfere with port power 634 control. 635 636 Example of the relevant files for port power control. Note, in this example 637 these files are relative to a usb hub device (prefix):: 638 639 prefix=/sys/devices/pci0000:00/0000:00:14.0/usb3/3-1 640 641 attached child device + 642 hub port device + | 643 hub interface device + | | 644 v v v 645 $prefix/3-1:1.0/3-1-port1/device 646 647 $prefix/3-1:1.0/3-1-port1/power/pm_qos_no_power_off 648 $prefix/3-1:1.0/3-1-port1/device/power/control 649 $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf0>/driver/unbind 650 $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf1>/driver/unbind 651 ... 652 $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intfN>/driver/unbind 653 654 In addition to these files some ports may have a 'peer' link to a port on 655 another hub. The expectation is that all superspeed ports have a 656 hi-speed peer:: 657 658 $prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1 659 ../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1 660 661 Distinct from 'companion ports', or 'ehci/xhci shared switchover ports' 662 peer ports are simply the hi-speed and superspeed interface pins that 663 are combined into a single usb3 connector. Peer ports share the same 664 ancestor XHCI device. 665 666 While a superspeed port is powered off a device may downgrade its 667 connection and attempt to connect to the hi-speed pins. The 668 implementation takes steps to prevent this: 669 670 1. Port suspend is sequenced to guarantee that hi-speed ports are powered-off 671 before their superspeed peer is permitted to power-off. The implication is 672 that the setting ``pm_qos_no_power_off`` to zero on a superspeed port may 673 not cause the port to power-off until its highspeed peer has gone to its 674 runtime suspend state. Userspace must take care to order the suspensions 675 if it wants to guarantee that a superspeed port will power-off. 676 677 2. Port resume is sequenced to force a superspeed port to power-on prior to its 678 highspeed peer. 679 680 3. Port resume always triggers an attached child device to resume. After a 681 power session is lost the device may have been removed, or need reset. 682 Resuming the child device when the parent port regains power resolves those 683 states and clamps the maximum port power cycle frequency at the rate the 684 child device can suspend (autosuspend-delay) and resume (reset-resume 685 latency). 686 687 Sysfs files relevant for port power control: 688 689 ``<hubdev-portX>/power/pm_qos_no_power_off``: 690 This writable flag controls the state of an idle port. 691 Once all children and descendants have suspended the 692 port may suspend/poweroff provided that 693 pm_qos_no_power_off is '0'. If pm_qos_no_power_off is 694 '1' the port will remain active/powered regardless of 695 the stats of descendants. Defaults to 1. 696 697 ``<hubdev-portX>/power/runtime_status``: 698 This file reflects whether the port is 'active' (power is on) 699 or 'suspended' (logically off). There is no indication to 700 userspace whether VBUS is still supplied. 701 702 ``<hubdev-portX>/connect_type``: 703 An advisory read-only flag to userspace indicating the 704 location and connection type of the port. It returns 705 one of four values 'hotplug', 'hardwired', 'not used', 706 and 'unknown'. All values, besides unknown, are set by 707 platform firmware. 708 709 ``hotplug`` indicates an externally connectable/visible 710 port on the platform. Typically userspace would choose 711 to keep such a port powered to handle new device 712 connection events. 713 714 ``hardwired`` refers to a port that is not visible but 715 connectable. Examples are internal ports for USB 716 bluetooth that can be disconnected via an external 717 switch or a port with a hardwired USB camera. It is 718 expected to be safe to allow these ports to suspend 719 provided pm_qos_no_power_off is coordinated with any 720 switch that gates connections. Userspace must arrange 721 for the device to be connected prior to the port 722 powering off, or to activate the port prior to enabling 723 connection via a switch. 724 725 ``not used`` refers to an internal port that is expected 726 to never have a device connected to it. These may be 727 empty internal ports, or ports that are not physically 728 exposed on a platform. Considered safe to be 729 powered-off at all times. 730 731 ``unknown`` means platform firmware does not provide 732 information for this port. Most commonly refers to 733 external hub ports which should be considered 'hotplug' 734 for policy decisions. 735 736 .. note:: 737 738 - since we are relying on the BIOS to get this ACPI 739 information correct, the USB port descriptions may 740 be missing or wrong. 741 742 - Take care in clearing ``pm_qos_no_power_off``. Once 743 power is off this port will 744 not respond to new connect events. 745 746 Once a child device is attached additional constraints are 747 applied before the port is allowed to poweroff. 748 749 ``<child>/power/control``: 750 Must be ``auto``, and the port will not 751 power down until ``<child>/power/runtime_status`` 752 reflects the 'suspended' state. Default 753 value is controlled by child device driver. 754 755 ``<child>/power/persist``: 756 This defaults to ``1`` for most devices and indicates if 757 kernel can persist the device's configuration across a 758 power session loss (suspend / port-power event). When 759 this value is ``0`` (quirky devices), port poweroff is 760 disabled. 761 762 ``<child>/driver/unbind``: 763 Wakeup capable devices will block port poweroff. At 764 this time the only mechanism to clear the usb-internal 765 wakeup-capability for an interface device is to unbind 766 its driver. 767 768 Summary of poweroff pre-requisite settings relative to a port device:: 769 770 echo 0 > power/pm_qos_no_power_off 771 echo 0 > peer/power/pm_qos_no_power_off # if it exists 772 echo auto > power/control # this is the default value 773 echo auto > <child>/power/control 774 echo 1 > <child>/power/persist # this is the default value 775 776 Suggested Userspace Port Power Policy 777 ------------------------------------- 778 779 As noted above userspace needs to be careful and deliberate about what 780 ports are enabled for poweroff. 781 782 The default configuration is that all ports start with 783 ``power/pm_qos_no_power_off`` set to ``1`` causing ports to always remain 784 active. 785 786 Given confidence in the platform firmware's description of the ports 787 (ACPI _PLD record for a port populates 'connect_type') userspace can 788 clear pm_qos_no_power_off for all 'not used' ports. The same can be 789 done for 'hardwired' ports provided poweroff is coordinated with any 790 connection switch for the port. 791 792 A more aggressive userspace policy is to enable USB port power off for 793 all ports (set ``<hubdev-portX>/power/pm_qos_no_power_off`` to ``0``) when 794 some external factor indicates the user has stopped interacting with the 795 system. For example, a distro may want to enable power off all USB 796 ports when the screen blanks, and re-power them when the screen becomes 797 active. Smart phones and tablets may want to power off USB ports when 798 the user pushes the power button.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.