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>

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.