summaryrefslogtreecommitdiff
path: root/Documentation/usb
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@s-opensource.com>2017-04-05 10:23:09 -0300
committerJonathan Corbet <corbet@lwn.net>2017-04-11 14:40:12 -0600
commit32a3bebce9d09598d4f4c5afca929a2ce148b8c4 (patch)
treea0ac3c5bddc53cc9a21575274a9711a29b4af796 /Documentation/usb
parent76f650f077f3edd7001c89da44eade2449e8f495 (diff)
usb/persist.txt: convert to ReST and add to driver-api book
This document describe some USB core features. Add it to the driver-api book. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/usb')
-rw-r--r--Documentation/usb/persist.txt165
1 files changed, 0 insertions, 165 deletions
diff --git a/Documentation/usb/persist.txt b/Documentation/usb/persist.txt
deleted file mode 100644
index 35d70eda9ad6..000000000000
--- a/Documentation/usb/persist.txt
+++ /dev/null
@@ -1,165 +0,0 @@
- USB device persistence during system suspend
-
- Alan Stern <stern@rowland.harvard.edu>
-
- September 2, 2006 (Updated February 25, 2008)
-
-
- What is the problem?
-
-According to the USB specification, when a USB bus is suspended the
-bus must continue to supply suspend current (around 1-5 mA). This
-is so that devices can maintain their internal state and hubs can
-detect connect-change events (devices being plugged in or unplugged).
-The technical term is "power session".
-
-If a USB device's power session is interrupted then the system is
-required to behave as though the device has been unplugged. It's a
-conservative approach; in the absence of suspend current the computer
-has no way to know what has actually happened. Perhaps the same
-device is still attached or perhaps it was removed and a different
-device plugged into the port. The system must assume the worst.
-
-By default, Linux behaves according to the spec. If a USB host
-controller loses power during a system suspend, then when the system
-wakes up all the devices attached to that controller are treated as
-though they had disconnected. This is always safe and it is the
-"officially correct" thing to do.
-
-For many sorts of devices this behavior doesn't matter in the least.
-If the kernel wants to believe that your USB keyboard was unplugged
-while the system was asleep and a new keyboard was plugged in when the
-system woke up, who cares? It'll still work the same when you type on
-it.
-
-Unfortunately problems _can_ arise, particularly with mass-storage
-devices. The effect is exactly the same as if the device really had
-been unplugged while the system was suspended. If you had a mounted
-filesystem on the device, you're out of luck -- everything in that
-filesystem is now inaccessible. This is especially annoying if your
-root filesystem was located on the device, since your system will
-instantly crash.
-
-Loss of power isn't the only mechanism to worry about. Anything that
-interrupts a power session will have the same effect. For example,
-even though suspend current may have been maintained while the system
-was asleep, on many systems during the initial stages of wakeup the
-firmware (i.e., the BIOS) resets the motherboard's USB host
-controllers. Result: all the power sessions are destroyed and again
-it's as though you had unplugged all the USB devices. Yes, it's
-entirely the BIOS's fault, but that doesn't do _you_ any good unless
-you can convince the BIOS supplier to fix the problem (lots of luck!).
-
-On many systems the USB host controllers will get reset after a
-suspend-to-RAM. On almost all systems, no suspend current is
-available during hibernation (also known as swsusp or suspend-to-disk).
-You can check the kernel log after resuming to see if either of these
-has happened; look for lines saying "root hub lost power or was reset".
-
-In practice, people are forced to unmount any filesystems on a USB
-device before suspending. If the root filesystem is on a USB device,
-the system can't be suspended at all. (All right, it _can_ be
-suspended -- but it will crash as soon as it wakes up, which isn't
-much better.)
-
-
- What is the solution?
-
-The kernel includes a feature called USB-persist. It tries to work
-around these issues by allowing the core USB device data structures to
-persist across a power-session disruption.
-
-It works like this. If the kernel sees that a USB host controller is
-not in the expected state during resume (i.e., if the controller was
-reset or otherwise had lost power) then it applies a persistence check
-to each of the USB devices below that controller for which the
-"persist" attribute is set. It doesn't try to resume the device; that
-can't work once the power session is gone. Instead it issues a USB
-port reset and then re-enumerates the device. (This is exactly the
-same thing that happens whenever a USB device is reset.) If the
-re-enumeration shows that the device now attached to that port has the
-same descriptors as before, including the Vendor and Product IDs, then
-the kernel continues to use the same device structure. In effect, the
-kernel treats the device as though it had merely been reset instead of
-unplugged.
-
-The same thing happens if the host controller is in the expected state
-but a USB device was unplugged and then replugged, or if a USB device
-fails to carry out a normal resume.
-
-If no device is now attached to the port, or if the descriptors are
-different from what the kernel remembers, then the treatment is what
-you would expect. The kernel destroys the old device structure and
-behaves as though the old device had been unplugged and a new device
-plugged in.
-
-The end result is that the USB device remains available and usable.
-Filesystem mounts and memory mappings are unaffected, and the world is
-now a good and happy place.
-
-Note that the "USB-persist" feature will be applied only to those
-devices for which it is enabled. You can enable the feature by doing
-(as root):
-
- echo 1 >/sys/bus/usb/devices/.../power/persist
-
-where the "..." should be filled in the with the device's ID. Disable
-the feature by writing 0 instead of 1. For hubs the feature is
-automatically and permanently enabled and the power/persist file
-doesn't even exist, so you only have to worry about setting it for
-devices where it really matters.
-
-
- Is this the best solution?
-
-Perhaps not. Arguably, keeping track of mounted filesystems and
-memory mappings across device disconnects should be handled by a
-centralized Logical Volume Manager. Such a solution would allow you
-to plug in a USB flash device, create a persistent volume associated
-with it, unplug the flash device, plug it back in later, and still
-have the same persistent volume associated with the device. As such
-it would be more far-reaching than USB-persist.
-
-On the other hand, writing a persistent volume manager would be a big
-job and using it would require significant input from the user. This
-solution is much quicker and easier -- and it exists now, a giant
-point in its favor!
-
-Furthermore, the USB-persist feature applies to _all_ USB devices, not
-just mass-storage devices. It might turn out to be equally useful for
-other device types, such as network interfaces.
-
-
- WARNING: USB-persist can be dangerous!!
-
-When recovering an interrupted power session the kernel does its best
-to make sure the USB device hasn't been changed; that is, the same
-device is still plugged into the port as before. But the checks
-aren't guaranteed to be 100% accurate.
-
-If you replace one USB device with another of the same type (same
-manufacturer, same IDs, and so on) there's an excellent chance the
-kernel won't detect the change. The serial number string and other
-descriptors are compared with the kernel's stored values, but this
-might not help since manufacturers frequently omit serial numbers
-entirely in their devices.
-
-Furthermore it's quite possible to leave a USB device exactly the same
-while changing its media. If you replace the flash memory card in a
-USB card reader while the system is asleep, the kernel will have no
-way to know you did it. The kernel will assume that nothing has
-happened and will continue to use the partition tables, inodes, and
-memory mappings for the old card.
-
-If the kernel gets fooled in this way, it's almost certain to cause
-data corruption and to crash your system. You'll have no one to blame
-but yourself.
-
-For those devices with avoid_reset_quirk attribute being set, persist
-maybe fail because they may morph after reset.
-
-YOU HAVE BEEN WARNED! USE AT YOUR OWN RISK!
-
-That having been said, most of the time there shouldn't be any trouble
-at all. The USB-persist feature can be extremely useful. Make the
-most of it.