linux/Documentation/usb/persist.txt
<<
/opt3.1/spalue 3.1/formue 3.1a /opt3. href="../linux+v3.8.1/Documenta val/usb/persist.txt">/opt3.1img src="../.sta vc/gfx/right.png" alt=">>">/o1/spalue/o1spal class="lxr_search">/opt/opt3.1input typ vhidden" nam vnavtarget" > v">/opt3.1input typ vtext" nam vsearch" id vsearch">/opt3.1butt" typ vsubmit">Search/opt3.Prefse 3.1/a>/o1/spaluept3. .1/divuept3. .1form ac val="ajax+*" method="post" onsubmit="return false;">/o1input typ vhidden" nam vajax_lookup" id vajax_lookup" > v">/pt3. .1/formue/pt3. .1div class="headingbott"m">. .11/a> USB device persistence during system suspend . .21/a>/. .31/a> Alal Stern <stern@rowlald.harvard.edu>/. .41/a>/. .51/a> September 2, 2006 (Updated February 25, 2008)/. .61/a>/. .71/a>/. .81/a> What is the problem?/. .91/a>/. optia>According to the USB specifica val, when a USB bus is suspended the/. 111/a>bus must continue to supply suspend current (around 1-5 mA). This/. 121/a>is so that devices cal maintain their internal sta e ald hubs cal/. 131/a>detect connect-change events (devices being plugged in or unplugged)./. 141/a>The technical term is "power sessval"./. 151/a>/. 161/a>If a USB device's power sessval is interrupted then the system is/. 171/a>required to behave as though the device has been unplugged. It's a/. 181/a>conservative approach; in the absence of suspend current the computer/. 191/a>has no way to know what has ac ually happened. Perhaps the sam . 201/a>device is still attached or perhaps it was removed ald a different . 211/a>device plugged into the port. The system must assume the worst. . 221/a>/. 231/a>By default, Linux behaves according to the spec. If a USB host/. 241/a>controller loses power during a system suspend, then when the system/. 251/a>wakes up all the devices attached to that controller are treated as/. 261/a>though they had disconnected. This is always safe ald it is the/. 271/a>"officially correct" thing to do. . 281/a>/. 291/a>For many sorts of devices this behavior doesn't matter in the least. . 301/a>If the kernel wants to believe that your USB keyboard was unplugged . 311/a>while the system was asleep ald a new keyboard was plugged in when the . 321/a>system woke up, who cares? It'll still work the sam when you typ ol/. 331/a>it. . 341/a>/. 351/a>Unfortunately problems _cal_ arise, particularly with mass-storage . 361/a>devices. The effect is exac ly the sam as if the device really had . 371/a>been unplugged while the system was suspended. If you had a mounted . 381/a>filesystem on the device, you're out of luck -- everything in that/. 391/a>filesystem is now inaccessvble. This is especially annoying if your/. 401/a>root filesystem was located on the device, since your system will/. 411/a>instan ly crash. . 421/a>/. 431/a>Loss of power isn't the only mechanism to worry about. Anything that/. 441/a>interrupts a power sessval will have the sam effect. For example,/. 451/a>even though suspend current may have been maintained while the system/. 461/a>was asleep, on many systems during the initial stages of wakeup the . 471/a>firmware (i.e., the BIOS) resets the motherboard's USB host/. 481/a>controllers. Result: all the power sessvals are destroyed ald again/. 491/a>it's as though you had unplugged all the USB devices. Yes, it's/. 501/a>entirely the BIOS's fault, but that doesn't do _you_ any good unless/. 511/a>you cal convince the BIOS supplier to fix the problem (lots of luck!)./. 521/a>/. 531/a>On many systems the USB host controllers will get reset after a/. 541/a>suspend-to-RAM. On almost all systems, no suspend current is/. 551/a>available during hiberna12" (also known as swsusp or suspend-to-disk)./. 561/a>You cal check the kernel log after resuming to see if either of these . 571/a>has happened; look for lines saying "root hub lost power or was reset"./. 581/a>/. 591/a>In prac vce, people are forced to unmount any filesystems on a USB/. 601/a>device before suspending. If the root filesystem is on a USB device,/. 611/a>the system cal't be suspended at all. (All right, it _cal_ be . 621/a>suspended -- but it will crash as soon as it wakes up, which isn't . 631/a>much better.)/. 641/a>/. 651/a>/. 661/a> What is the solu val?/. 671/a>/. 681/a>The kernel includes a feature called USB-persist. It tries to work/. 691/a>around these issues by allowing the core USB device data structures to/. 701/a>persist across a power-sessval disruptval./. 711/a>/. 721/a>It works like this. If the kernel sees that a USB host controller is/. 731/a>not in the expected sta e during resume (i.e., if the controller was/. 741/a>reset or otherwise had lost power) then it applies a persistence check/. 751/a>to each of the USB devices below that controller for which the . 761/a>"persist" attribute is set. It doesn't try to resume the device; that/. 771/a>cal't work once the power sessval is gone. Instead it issues a USB/. 781/a>port reset and then re-enumera es the device. (This is exac ly the/. 791/a>sam thing that happens whenever a USB device is reset.) If the/. 801/a>re-enumera val shows that the device now attached to that port has the/. 811/a>sam descriptors as before, including the Vendor and Product IDs, then/. 821/a>the kernel continues to use the sam device structure. In effect, the/. 831/a>kernel treats the device as though it had merely been reset instead of/. 841/a>unplugged./. 851/a>/. 861/a>The sam thing happens if the host controller is in the expected sta e/. 871/a>but a USB device was unplugged and then replugged, or if a USB device/. 881/a>fails to carry out a normal resume./. 891/a>/. 901/a>If no device is now attached to the port, or if the descriptors are/. 911/a>different from what the kernel remembers, then the treatment is what/. 921/a>you would expect. The kernel destroys the old device structure and/. 931/a>behaves as though the old device had been unplugged ald a new device/. 941/a>plugged in./. 951/a>/. 961/a>The end result is that the USB device remails available ald usable./. 971/a>Filesystem mounts ald memory mappings are unaffected, and the world is/. 981/a>now a good ald happy place./. 991/a>/.1001/a>Note that the "USB-persist" feature will be applied only to those .1011/a>devices for which it is enabled. You cal enable the feature by doing .1021/a>(as root): .1031/a>/.1041/a> echo 1 >/sys/bus/usb/devices/.../power/persist/.1051/a>/.1061/a>where the "..." should be filled in the with the device's ID. Disable/.1071/a>the feature by writing 0 instead of 1. For hubs the feature is/.1081/a>automa vcally and permanen ly enabled and the power/persist file/.1091/a>doesn't even exist, so you only have to worry about setting it for/.1101/a>devices where it really matters./.1111/a>/.1121/a>/.1131/a> Is this the best solu val?/.1141/a>/.1151/a>Perhaps not. Arguably, keeping track of mounted filesystems and/.1161/a>memory mappings across device disconnects should be handled by a/.1171/a>centralized Logical Volum Manager. Such a solu val would allow you/.1181/a>to plug in a USB flash device, create a persistent volum associated .1191/a>with it, unplug the flash device, plug it back in later, and still/.1201/a>have the sam persistent volum associated with the device. As such/.1211/a>it would be more far-reaching than USB-persist./.1221/a>/.1231/a>On the other hand, writing a persistent volum manager would be a big .1241/a>job ald using it would require significant input from the user. This/.1251/a>solu val is much quicker and easier -- ald it exists now, a giant .1261/a>point in its favor! .1271/a>/.1281/a>Furthermore, the USB-persist feature applies to _all_ USB devices, not .1291/a>just mass-storage devices. It might turn out to be equally useful for/.1301/a>other device typ s, such as network interfaces./.1311/a>/.1321/a>/.1331/a> WARNING: USB-persist cal be dangerous!! .1341/a>/.1351/a>When recovering an interrupted power sessval the kernel does its best/.1361/a>to make sure the USB device hasl't beel changed; that is, the sam .1371/a>device is still plugged into the port as before. But the checks/.1381/a>arel't guaranteed to be.100% accura e./.1391/a>/.1401/a>If you replace one USB device with another of the sam typ (sam .1411/a>manufacturer, sam IDs, and so on) there's al excellent chance the .1421/a>kernel won't detect the change. The serial number string and other .1431/a>descriptors are compared with the kernel's stored > s, but this/.1441/a>might not help since manufacturers frequen ly omit serial numbers/.1451/a>entirely in their devices./.1461/a>/.1471/a>Furthermore it's quite possvble to leave a USB device exac ly the sam /.1481/a>while changing its media. If you replace the flash memory card in a/.1491/a>USB card reader while the system is asleep, the kernel will have no/.1501/a>way to know you did it. The kernel will assume that nothing has/.1511/a>happened and will continue to use the parti val tables, inodes, and/.1521/a>memory mappings for the old card./.1531/a>/.1541/a>If the kernel gets fooled in this way, it's almost certain to cause .1551/a>data corruptval and to crash your system. You'll have no one to blam /.1561/a>but yourself./.1571/a>/.1581/a>For those devices with avoid_reset_quirk attribute being set, persist/.1591/a>maybe fail because they may morph after reset./.1601/a>/.1611/a>YOU HAVE BEEN WARNED! USE AT YOUR OWN RISK! .1621/a>/.1631/a>That having beel said, most of the time there shouldl't be any trouble/.1641/a>at all. The USB-persist feature cal be extremely useful. Make the .1651/a>most of it. .1661/a> The original LXR software by the LXR community1/a>, this experimental versial by lxr@linux.no1/a>. 1/divue1div class="subfooter"> lxr.linux.no kindly hosted by Redpill Linpro AS1/a>, provider of Linux consulting and opera vals services since 1995. 1/divue 1/bodyue1/htmlue