driver-api/usb/persist.rst

1 .. _usb-persist:
3 USB device persistence during system suspend
14 bus must continue to supply suspend current (around 1-5 mA).  This
16 detect connect-change events (devices being plugged in or unplugged).
17 The technical term is "power session".
19 If a USB device's power session is interrupted then the system is
24 device plugged into the port.  The system must assume the worst.
27 controller loses power during a system suspend, then when the system
28 wakes up all the devices attached to that controller are treated as
34 while the system was asleep and a new keyboard was plugged in when the
35 system woke up, who cares?  It'll still work the same when you type on
38 Unfortunately problems _can_ arise, particularly with mass-storage
40 been unplugged while the system was suspended.  If you had a mounted
41 filesystem on the device, you're out of luck -- everything in that
43 root filesystem was located on the device, since your system will
46 Loss of power isn't the only mechanism to worry about.  Anything that
47 interrupts a power session will have the same effect.  For example,
48 even though suspend current may have been maintained while the system
51 controllers.  Result: all the power sessions are destroyed and again
57 suspend-to-RAM.  On almost all systems, no suspend current is
58 available during hibernation (also known as swsusp or suspend-to-disk).
60 has happened; look for lines saying "root hub lost power or was reset".
64 the system can't be suspended at all.  (All right, it _can_ be
65 suspended -- but it will crash as soon as it wakes up, which isn't
72 The kernel includes a feature called USB-persist.  It tries to work
74 persist across a power-session disruption.
76 It works like this.  If the kernel sees that a USB host controller is
77 not in the expected state during resume (i.e., if the controller was
78 reset or otherwise had lost power) then it applies a persistence check
79 to each of the USB devices below that controller for which the
81 can't work once the power session is gone.  Instead it issues a USB
82 port reset and then re-enumerates the device.  (This is exactly the
84 re-enumeration shows that the device now attached to that port has the
90 The same thing happens if the host controller is in the expected state
104 Note that the "USB-persist" feature will be applied only to those
108 	echo 1 >/sys/bus/usb/devices/.../power/persist
112 automatically and permanently enabled and the power/persist file
126 it would be more far-reaching than USB-persist.
130 solution is much quicker and easier -- and it exists now, a giant
133 Furthermore, the USB-persist feature applies to _all_ USB devices, not
134 just mass-storage devices.  It might turn out to be equally useful for
138 WARNING: USB-persist can be dangerous!!
141 When recovering an interrupted power session the kernel does its best
155 USB card reader while the system is asleep, the kernel will have no
161 data corruption and to crash your system.  You'll have no one to blame
170 at all.  The USB-persist feature can be extremely useful.  Make the