Merge tag 'docs-4.12' of git://git.lwn.net/linux

Pull documentation update from Jonathan Corbet:
 "A reasonably busy cycle for documentation this time around. There is a
  new guide for user-space API documents, rather sparsely populated at
  the moment, but it's a start. Markus improved the infrastructure for
  converting diagrams. Mauro has converted much of the USB documentation
  over to RST. Plus the usual set of fixes, improvements, and tweaks.

  There's a bit more than the usual amount of reaching out of
  Documentation/ to fix comments elsewhere in the tree; I have acks for
  those where I could get them"

* tag 'docs-4.12' of git://git.lwn.net/linux: (74 commits)
  docs: Fix a couple typos
  docs: Fix a spelling error in vfio-mediated-device.txt
  docs: Fix a spelling error in ioctl-number.txt
  MAINTAINERS: update file entry for HSI subsystem
  Documentation: allow installing man pages to a user defined directory
  Doc/PM: Sync with intel_powerclamp code behavior
  zr364xx.rst: usb/devices is now at /sys/kernel/debug/
  usb.rst: move documentation from proc_usb_info.txt to USB ReST book
  convert philips.txt to ReST and add to media docs
  docs-rst: usb: update old usbfs-related documentation
  arm: Documentation: update a path name
  docs: process/4.Coding.rst: Fix a couple of document refs
  docs-rst: fix usb cross-references
  usb: gadget.h: be consistent at kernel doc macros
  usb: composite.h: fix two warnings when building docs
  usb: get rid of some ReST doc build errors
  usb.rst: get rid of some Sphinx errors
  usb/URB.txt: convert to ReST and update it
  usb/persist.txt: convert to ReST and add to driver-api book
  usb/hotplug.txt: convert to ReST and add to driver-api book
  ...

12 files changed, 3 insertions, 2338 deletions

diff --git a/Documentation/usb/URB.txt b/Documentation/usb/URB.txt
deleted file mode 100644
index 50da0d455444..000000000000
--- a/Documentation/usb/URB.txt
+++ /dev/null
@@ -1,261 +0,0 @@
-Revised: 2000-Dec-05.
-Again:   2002-Jul-06
-Again:   2005-Sep-19
-
-    NOTE:
-
-    The USB subsystem now has a substantial section in "The Linux Kernel API"
-    guide (in Documentation/DocBook), generated from the current source
-    code.  This particular documentation file isn't particularly current or
-    complete; don't rely on it except for a quick overview.
-
-
-1.1. Basic concept or 'What is an URB?'
-
-The basic idea of the new driver is message passing, the message itself is 
-called USB Request Block, or URB for short. 
-
-- An URB consists of all relevant information to execute any USB transaction 
-  and deliver the data and status back. 
-
-- Execution of an URB is inherently an asynchronous operation, i.e. the 
-  usb_submit_urb(urb) call returns immediately after it has successfully
-  queued the requested action.
-
-- Transfers for one URB can be canceled with usb_unlink_urb(urb) at any time. 
-
-- Each URB has a completion handler, which is called after the action
-  has been successfully completed or canceled. The URB also contains a
-  context-pointer for passing information to the completion handler.
-
-- Each endpoint for a device logically supports a queue of requests.
-  You can fill that queue, so that the USB hardware can still transfer
-  data to an endpoint while your driver handles completion of another.
-  This maximizes use of USB bandwidth, and supports seamless streaming
-  of data to (or from) devices when using periodic transfer modes.
-
-
-1.2. The URB structure
-
-Some of the fields in an URB are:
-
-struct urb
-{
-// (IN) device and pipe specify the endpoint queue
-	struct usb_device *dev;         // pointer to associated USB device
-	unsigned int pipe;              // endpoint information
-
-	unsigned int transfer_flags;    // ISO_ASAP, SHORT_NOT_OK, etc.
-
-// (IN) all urbs need completion routines
-	void *context;                  // context for completion routine
-	void (*complete)(struct urb *); // pointer to completion routine
-
-// (OUT) status after each completion
-	int status;                     // returned status
-
-// (IN) buffer used for data transfers
-	void *transfer_buffer;          // associated data buffer
-	int transfer_buffer_length;     // data buffer length
-	int number_of_packets;          // size of iso_frame_desc
-
-// (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
-	int actual_length;              // actual data buffer length
-
-// (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)
-	unsigned char* setup_packet;    // setup packet (control only)
-
-// Only for PERIODIC transfers (ISO, INTERRUPT)
-    // (IN/OUT) start_frame is set unless ISO_ASAP isn't set
-	int start_frame;                // start frame
-	int interval;                   // polling interval
-
-    // ISO only: packets are only "best effort"; each can have errors
-	int error_count;                // number of errors
-	struct usb_iso_packet_descriptor iso_frame_desc[0];
-};
-
-Your driver must create the "pipe" value using values from the appropriate
-endpoint descriptor in an interface that it's claimed.
-
-
-1.3. How to get an URB?
-
-URBs are allocated with the following call
-
-	struct urb *usb_alloc_urb(int isoframes, int mem_flags)
-
-Return value is a pointer to the allocated URB, 0 if allocation failed.
-The parameter isoframes specifies the number of isochronous transfer frames
-you want to schedule. For CTRL/BULK/INT, use 0.  The mem_flags parameter
-holds standard memory allocation flags, letting you control (among other
-things) whether the underlying code may block or not.
-
-To free an URB, use
-
-	void usb_free_urb(struct urb *urb)
-
-You may free an urb that you've submitted, but which hasn't yet been
-returned to you in a completion callback.  It will automatically be
-deallocated when it is no longer in use.
-
-
-1.4. What has to be filled in?
-
-Depending on the type of transaction, there are some inline functions 
-defined in <linux/usb.h> to simplify the initialization, such as
-fill_control_urb() and fill_bulk_urb().  In general, they need the usb
-device pointer, the pipe (usual format from usb.h), the transfer buffer,
-the desired transfer length, the completion  handler, and its context. 
-Take a look at the some existing drivers to see how they're used.
-
-Flags:
-For ISO there are two startup behaviors: Specified start_frame or ASAP.
-For ASAP set URB_ISO_ASAP in transfer_flags.
-
-If short packets should NOT be tolerated, set URB_SHORT_NOT_OK in 
-transfer_flags.
-
-
-1.5. How to submit an URB?
-
-Just call
-
-	int usb_submit_urb(struct urb *urb, int mem_flags)
-
-The mem_flags parameter, such as SLAB_ATOMIC, controls memory allocation,
-such as whether the lower levels may block when memory is tight.
-
-It immediately returns, either with status 0 (request queued) or some
-error code, usually caused by the following:
-
-- Out of memory (-ENOMEM)
-- Unplugged device (-ENODEV)
-- Stalled endpoint (-EPIPE)
-- Too many queued ISO transfers (-EAGAIN)
-- Too many requested ISO frames (-EFBIG)
-- Invalid INT interval (-EINVAL)
-- More than one packet for INT (-EINVAL)
-
-After submission, urb->status is -EINPROGRESS; however, you should never
-look at that value except in your completion callback.
-
-For isochronous endpoints, your completion handlers should (re)submit
-URBs to the same endpoint with the ISO_ASAP flag, using multi-buffering,
-to get seamless ISO streaming.
-
-
-1.6. How to cancel an already running URB?
-
-There are two ways to cancel an URB you've submitted but which hasn't
-been returned to your driver yet.  For an asynchronous cancel, call
-
-	int usb_unlink_urb(struct urb *urb)
-
-It removes the urb from the internal list and frees all allocated
-HW descriptors. The status is changed to reflect unlinking.  Note
-that the URB will not normally have finished when usb_unlink_urb()
-returns; you must still wait for the completion handler to be called.
-
-To cancel an URB synchronously, call
-
-	void usb_kill_urb(struct urb *urb)
-
-It does everything usb_unlink_urb does, and in addition it waits
-until after the URB has been returned and the completion handler
-has finished.  It also marks the URB as temporarily unusable, so
-that if the completion handler or anyone else tries to resubmit it
-they will get a -EPERM error.  Thus you can be sure that when
-usb_kill_urb() returns, the URB is totally idle.
-
-There is a lifetime issue to consider.  An URB may complete at any
-time, and the completion handler may free the URB.  If this happens
-while usb_unlink_urb or usb_kill_urb is running, it will cause a
-memory-access violation.  The driver is responsible for avoiding this,
-which often means some sort of lock will be needed to prevent the URB
-from being deallocated while it is still in use.
-
-On the other hand, since usb_unlink_urb may end up calling the
-completion handler, the handler must not take any lock that is held
-when usb_unlink_urb is invoked.  The general solution to this problem
-is to increment the URB's reference count while holding the lock, then
-drop the lock and call usb_unlink_urb or usb_kill_urb, and then
-decrement the URB's reference count.  You increment the reference
-count by calling
-
-	struct urb *usb_get_urb(struct urb *urb)
-
-(ignore the return value; it is the same as the argument) and
-decrement the reference count by calling usb_free_urb.  Of course,
-none of this is necessary if there's no danger of the URB being freed
-by the completion handler.
-
-
-1.7. What about the completion handler?
-
-The handler is of the following type:
-
-	typedef void (*usb_complete_t)(struct urb *)
-
-I.e., it gets the URB that caused the completion call. In the completion
-handler, you should have a look at urb->status to detect any USB errors.
-Since the context parameter is included in the URB, you can pass
-information to the completion handler.
-
-Note that even when an error (or unlink) is reported, data may have been
-transferred.  That's because USB transfers are packetized; it might take
-sixteen packets to transfer your 1KByte buffer, and ten of them might
-have transferred successfully before the completion was called.
-
-
-NOTE:  ***** WARNING *****
-NEVER SLEEP IN A COMPLETION HANDLER.  These are often called in atomic
-context.
-
-In the current kernel, completion handlers run with local interrupts
-disabled, but in the future this will be changed, so don't assume that
-local IRQs are always disabled inside completion handlers.
-
-1.8. How to do isochronous (ISO) transfers?
-
-For ISO transfers you have to fill a usb_iso_packet_descriptor structure,
-allocated at the end of the URB by usb_alloc_urb(n,mem_flags), for each
-packet you want to schedule.   You also have to set urb->interval to say
-how often to make transfers; it's often one per frame (which is once
-every microframe for highspeed devices).  The actual interval used will
-be a power of two that's no bigger than what you specify.
-
-The usb_submit_urb() call modifies urb->interval to the implemented interval
-value that is less than or equal to the requested interval value.  If
-ISO_ASAP scheduling is used, urb->start_frame is also updated.
-
-For each entry you have to specify the data offset for this frame (base is
-transfer_buffer), and the length you want to write/expect to read.
-After completion, actual_length contains the actual transferred length and 
-status contains the resulting status for the ISO transfer for this frame.
-It is allowed to specify a varying length from frame to frame (e.g. for
-audio synchronisation/adaptive transfer rates). You can also use the length 
-0 to omit one or more frames (striping).
-
-For scheduling you can choose your own start frame or ISO_ASAP. As explained
-earlier, if you always keep at least one URB queued and your completion
-keeps (re)submitting a later URB, you'll get smooth ISO streaming (if usb
-bandwidth utilization allows).
-
-If you specify your own start frame, make sure it's several frames in advance
-of the current frame.  You might want this model if you're synchronizing
-ISO data with some other event stream.
-
-
-1.9. How to start interrupt (INT) transfers?
-
-Interrupt transfers, like isochronous transfers, are periodic, and happen
-in intervals that are powers of two (1, 2, 4 etc) units.  Units are frames
-for full and low speed devices, and microframes for high speed ones.
-The usb_submit_urb() call modifies urb->interval to the implemented interval
-value that is less than or equal to the requested interval value.
-
-In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically
-restarted when they complete.  They end when the completion handler is
-called, just like other URBs.  If you want an interrupt URB to be restarted,
-your completion handler must resubmit it.
diff --git a/Documentation/usb/acm.txt b/Documentation/usb/acm.txt
index 17f5c2e1a570..903abca10517 100644
--- a/Documentation/usb/acm.txt
+++ b/Documentation/usb/acm.txt
@@ -64,7 +64,7 @@ minicom, ppp and mgetty with them.
 
 2. Verifying that it works
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The first step would be to check /proc/bus/usb/devices, it should look
+  The first step would be to check /sys/kernel/debug/usb/devices, it should look
 like this:
 
 T:  Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12  MxCh= 2
diff --git a/Documentation/usb/anchors.txt b/Documentation/usb/anchors.txt
deleted file mode 100644
index fe6a99a32bbd..000000000000
--- a/Documentation/usb/anchors.txt
+++ /dev/null
@@ -1,79 +0,0 @@
-What is anchor?
-===============
-
-A USB driver needs to support some callbacks requiring
-a driver to cease all IO to an interface. To do so, a
-driver has to keep track of the URBs it has submitted
-to know they've all completed or to call usb_kill_urb
-for them. The anchor is a data structure takes care of
-keeping track of URBs and provides methods to deal with
-multiple URBs.
-
-Allocation and Initialisation
-=============================
-
-There's no API to allocate an anchor. It is simply declared
-as struct usb_anchor. init_usb_anchor() must be called to
-initialise the data structure.
-
-Deallocation
-============
-
-Once it has no more URBs associated with it, the anchor can be
-freed with normal memory management operations.
-
-Association and disassociation of URBs with anchors
-===================================================
-
-An association of URBs to an anchor is made by an explicit
-call to usb_anchor_urb(). The association is maintained until
-an URB is finished by (successful) completion. Thus disassociation
-is automatic. A function is provided to forcibly finish (kill)
-all URBs associated with an anchor.
-Furthermore, disassociation can be made with usb_unanchor_urb()
-
-Operations on multitudes of URBs
-================================
-
-usb_kill_anchored_urbs()
-------------------------
-
-This function kills all URBs associated with an anchor. The URBs
-are called in the reverse temporal order they were submitted.
-This way no data can be reordered.
-
-usb_unlink_anchored_urbs()
---------------------------
-
-This function unlinks all URBs associated with an anchor. The URBs
-are processed in the reverse temporal order they were submitted.
-This is similar to usb_kill_anchored_urbs(), but it will not sleep.
-Therefore no guarantee is made that the URBs have been unlinked when
-the call returns. They may be unlinked later but will be unlinked in
-finite time.
-
-usb_scuttle_anchored_urbs()
----------------------------
-
-All URBs of an anchor are unanchored en masse.
-
-usb_wait_anchor_empty_timeout()
--------------------------------
-
-This function waits for all URBs associated with an anchor to finish
-or a timeout, whichever comes first. Its return value will tell you
-whether the timeout was reached.
-
-usb_anchor_empty()
-------------------
-
-Returns true if no URBs are associated with an anchor. Locking
-is the caller's responsibility.
-
-usb_get_from_anchor()
----------------------
-
-Returns the oldest anchored URB of an anchor. The URB is unanchored
-and returned with a reference. As you may mix URBs to several
-destinations in one anchor you have no guarantee the chronologically
-first submitted URB is returned.
diff --git a/Documentation/usb/bulk-streams.txt b/Documentation/usb/bulk-streams.txt
deleted file mode 100644
index ffc02021863e..000000000000
--- a/Documentation/usb/bulk-streams.txt
+++ /dev/null
@@ -1,78 +0,0 @@
-Background
-==========
-
-Bulk endpoint streams were added in the USB 3.0 specification.  Streams allow a
-device driver to overload a bulk endpoint so that multiple transfers can be
-queued at once.
-
-Streams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus
-3.0 specification at http://www.usb.org/developers/docs/  The USB Attached SCSI
-Protocol, which uses streams to queue multiple SCSI commands, can be found on
-the T10 website (http://t10.org/).
-
-
-Device-side implications
-========================
-
-Once a buffer has been queued to a stream ring, the device is notified (through
-an out-of-band mechanism on another endpoint) that data is ready for that stream
-ID.  The device then tells the host which "stream" it wants to start.  The host
-can also initiate a transfer on a stream without the device asking, but the
-device can refuse that transfer.  Devices can switch between streams at any
-time.
-
-
-Driver implications
-===================
-
-int usb_alloc_streams(struct usb_interface *interface,
-		struct usb_host_endpoint **eps, unsigned int num_eps,
-		unsigned int num_streams, gfp_t mem_flags);
-
-Device drivers will call this API to request that the host controller driver
-allocate memory so the driver can use up to num_streams stream IDs.  They must
-pass an array of usb_host_endpoints that need to be setup with similar stream
-IDs.  This is to ensure that a UASP driver will be able to use the same stream
-ID for the bulk IN and OUT endpoints used in a Bi-directional command sequence.
-
-The return value is an error condition (if one of the endpoints doesn't support
-streams, or the xHCI driver ran out of memory), or the number of streams the
-host controller allocated for this endpoint.  The xHCI host controller hardware
-declares how many stream IDs it can support, and each bulk endpoint on a
-SuperSpeed device will say how many stream IDs it can handle.  Therefore,
-drivers should be able to deal with being allocated less stream IDs than they
-requested.
-
-Do NOT call this function if you have URBs enqueued for any of the endpoints
-passed in as arguments.  Do not call this function to request less than two
-streams.
-
-Drivers will only be allowed to call this API once for the same endpoint
-without calling usb_free_streams().  This is a simplification for the xHCI host
-controller driver, and may change in the future.
-
-
-Picking new Stream IDs to use
-============================
-
-Stream ID 0 is reserved, and should not be used to communicate with devices.  If
-usb_alloc_streams() returns with a value of N, you may use streams 1 though N.
-To queue an URB for a specific stream, set the urb->stream_id value.  If the
-endpoint does not support streams, an error will be returned.
-
-Note that new API to choose the next stream ID will have to be added if the xHCI
-driver supports secondary stream IDs.
-
-
-Clean up
-========
-
-If a driver wishes to stop using streams to communicate with the device, it
-should call
-
-void usb_free_streams(struct usb_interface *interface,
-		struct usb_host_endpoint **eps, unsigned int num_eps,
-		gfp_t mem_flags);
-
-All stream IDs will be deallocated when the driver releases the interface, to
-ensure that drivers that don't support streams will be able to use the endpoint.
diff --git a/Documentation/usb/callbacks.txt b/Documentation/usb/callbacks.txt
deleted file mode 100644
index 9e85846bdb98..000000000000
--- a/Documentation/usb/callbacks.txt
+++ /dev/null
@@ -1,134 +0,0 @@
-What callbacks will usbcore do?
-===============================
-
-Usbcore will call into a driver through callbacks defined in the driver
-structure and through the completion handler of URBs a driver submits.
-Only the former are in the scope of this document. These two kinds of
-callbacks are completely independent of each other. Information on the
-completion callback can be found in Documentation/usb/URB.txt.
-
-The callbacks defined in the driver structure are:
-
-1. Hotplugging callbacks:
-
- * @probe: Called to see if the driver is willing to manage a particular
- *	interface on a device.
- * @disconnect: Called when the interface is no longer accessible, usually
- *	because its device has been (or is being) disconnected or the
- *	driver module is being unloaded.
-
-2. Odd backdoor through usbfs:
-
- * @ioctl: Used for drivers that want to talk to userspace through
- *	the "usbfs" filesystem.  This lets devices provide ways to
- *	expose information to user space regardless of where they
- *	do (or don't) show up otherwise in the filesystem.
-
-3. Power management (PM) callbacks:
-
- * @suspend: Called when the device is going to be suspended.
- * @resume: Called when the device is being resumed.
- * @reset_resume: Called when the suspended device has been reset instead
- *	of being resumed.
-
-4. Device level operations:
-
- * @pre_reset: Called when the device is about to be reset.
- * @post_reset: Called after the device has been reset
-
-The ioctl interface (2) should be used only if you have a very good
-reason. Sysfs is preferred these days. The PM callbacks are covered
-separately in Documentation/usb/power-management.txt.
-
-Calling conventions
-===================
-
-All callbacks are mutually exclusive. There's no need for locking
-against other USB callbacks. All callbacks are called from a task
-context. You may sleep. However, it is important that all sleeps have a
-small fixed upper limit in time. In particular you must not call out to
-user space and await results.
-
-Hotplugging callbacks
-=====================
-
-These callbacks are intended to associate and disassociate a driver with
-an interface. A driver's bond to an interface is exclusive.
-
-The probe() callback
---------------------
-
-int (*probe) (struct usb_interface *intf,
-		const struct usb_device_id *id);
-
-Accept or decline an interface. If you accept the device return 0,
-otherwise -ENODEV or -ENXIO. Other error codes should be used only if a
-genuine error occurred during initialisation which prevented a driver
-from accepting a device that would else have been accepted.
-You are strongly encouraged to use usbcore's facility,
-usb_set_intfdata(), to associate a data structure with an interface, so
-that you know which internal state and identity you associate with a
-particular interface. The device will not be suspended and you may do IO
-to the interface you are called for and endpoint 0 of the device. Device
-initialisation that doesn't take too long is a good idea here.
-
-The disconnect() callback
--------------------------
-
-void (*disconnect) (struct usb_interface *intf);
-
-This callback is a signal to break any connection with an interface.
-You are not allowed any IO to a device after returning from this
-callback. You also may not do any other operation that may interfere
-with another driver bound the interface, eg. a power management
-operation.
-If you are called due to a physical disconnection, all your URBs will be
-killed by usbcore. Note that in this case disconnect will be called some
-time after the physical disconnection. Thus your driver must be prepared
-to deal with failing IO even prior to the callback.
-
-Device level callbacks
-======================
-
-pre_reset
----------
-
-int (*pre_reset)(struct usb_interface *intf);
-
-A driver or user space is triggering a reset on the device which
-contains the interface passed as an argument. Cease IO, wait for all
-outstanding URBs to complete, and save any device state you need to
-restore.  No more URBs may be submitted until the post_reset method
-is called.
-
-If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
-are in atomic context.
-
-post_reset
-----------
-
-int (*post_reset)(struct usb_interface *intf);
-
-The reset has completed.  Restore any saved device state and begin
-using the device again.
-
-If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
-are in atomic context.
-
-Call sequences
-==============
-
-No callbacks other than probe will be invoked for an interface
-that isn't bound to your driver.
-
-Probe will never be called for an interface bound to a driver.
-Hence following a successful probe, disconnect will be called
-before there is another probe for the same interface.
-
-Once your driver is bound to an interface, disconnect can be
-called at any time except in between pre_reset and post_reset.
-pre_reset is always followed by post_reset, even if the reset
-failed or the device has been unplugged.
-
-suspend is always followed by one of: resume, reset_resume, or
-disconnect.
diff --git a/Documentation/usb/dma.txt b/Documentation/usb/dma.txt
deleted file mode 100644
index 444651e70d95..000000000000
--- a/Documentation/usb/dma.txt
+++ /dev/null
@@ -1,133 +0,0 @@
-In Linux 2.5 kernels (and later), USB device drivers have additional control
-over how DMA may be used to perform I/O operations.  The APIs are detailed
-in the kernel usb programming guide (kerneldoc, from the source code).
-
-
-API OVERVIEW
-
-The big picture is that USB drivers can continue to ignore most DMA issues,
-though they still must provide DMA-ready buffers (see
-Documentation/DMA-API-HOWTO.txt).  That's how they've worked through
-the 2.4 (and earlier) kernels.
-
-OR:  they can now be DMA-aware.
-
-- New calls enable DMA-aware drivers, letting them allocate dma buffers and
-  manage dma mappings for existing dma-ready buffers (see below).
-
-- URBs have an additional "transfer_dma" field, as well as a transfer_flags
-  bit saying if it's valid.  (Control requests also have "setup_dma", but
-  drivers must not use it.)
-
-- "usbcore" will map this DMA address, if a DMA-aware driver didn't do
-  it first and set URB_NO_TRANSFER_DMA_MAP.  HCDs
-  don't manage dma mappings for URBs.
-
-- There's a new "generic DMA API", parts of which are usable by USB device
-  drivers.  Never use dma_set_mask() on any USB interface or device; that
-  would potentially break all devices sharing that bus.
-
-
-ELIMINATING COPIES
-
-It's good to avoid making CPUs copy data needlessly.  The costs can add up,
-and effects like cache-trashing can impose subtle penalties.
-
-- If you're doing lots of small data transfers from the same buffer all
-  the time, that can really burn up resources on systems which use an
-  IOMMU to manage the DMA mappings.  It can cost MUCH more to set up and
-  tear down the IOMMU mappings with each request than perform the I/O!
-
-  For those specific cases, USB has primitives to allocate less expensive
-  memory.  They work like kmalloc and kfree versions that give you the right
-  kind of addresses to store in urb->transfer_buffer and urb->transfer_dma.
-  You'd also set URB_NO_TRANSFER_DMA_MAP in urb->transfer_flags:
-
-	void *usb_alloc_coherent (struct usb_device *dev, size_t size,
-		int mem_flags, dma_addr_t *dma);
-
-	void usb_free_coherent (struct usb_device *dev, size_t size,
-		void *addr, dma_addr_t dma);
-
-  Most drivers should *NOT* be using these primitives; they don't need
-  to use this type of memory ("dma-coherent"), and memory returned from
-  kmalloc() will work just fine.
-
-  The memory buffer returned is "dma-coherent"; sometimes you might need to
-  force a consistent memory access ordering by using memory barriers.  It's
-  not using a streaming DMA mapping, so it's good for small transfers on
-  systems where the I/O would otherwise thrash an IOMMU mapping.  (See
-  Documentation/DMA-API-HOWTO.txt for definitions of "coherent" and
-  "streaming" DMA mappings.)
-
-  Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
-  space-efficient.
-
-  On most systems the memory returned will be uncached, because the
-  semantics of dma-coherent memory require either bypassing CPU caches
-  or using cache hardware with bus-snooping support.  While x86 hardware
-  has such bus-snooping, many other systems use software to flush cache
-  lines to prevent DMA conflicts.
-
-- Devices on some EHCI controllers could handle DMA to/from high memory.
-
-  Unfortunately, the current Linux DMA infrastructure doesn't have a sane
-  way to expose these capabilities ... and in any case, HIGHMEM is mostly a
-  design wart specific to x86_32.  So your best bet is to ensure you never
-  pass a highmem buffer into a USB driver.  That's easy; it's the default
-  behavior.  Just don't override it; e.g. with NETIF_F_HIGHDMA.
-
-  This may force your callers to do some bounce buffering, copying from
-  high memory to "normal" DMA memory.  If you can come up with a good way
-  to fix this issue (for x86_32 machines with over 1 GByte of memory),
-  feel free to submit patches.
-
-
-WORKING WITH EXISTING BUFFERS
-
-Existing buffers aren't usable for DMA without first being mapped into the
-DMA address space of the device.  However, most buffers passed to your
-driver can safely be used with such DMA mapping.  (See the first section
-of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?")
-
-- When you're using scatterlists, you can map everything at once.  On some
-  systems, this kicks in an IOMMU and turns the scatterlists into single
-  DMA transactions:
-
-	int usb_buffer_map_sg (struct usb_device *dev, unsigned pipe,
-		struct scatterlist *sg, int nents);
-
-	void usb_buffer_dmasync_sg (struct usb_device *dev, unsigned pipe,
-		struct scatterlist *sg, int n_hw_ents);
-
-	void usb_buffer_unmap_sg (struct usb_device *dev, unsigned pipe,
-		struct scatterlist *sg, int n_hw_ents);
-
-  It's probably easier to use the new usb_sg_*() calls, which do the DMA
-  mapping and apply other tweaks to make scatterlist i/o be fast.
-
-- Some drivers may prefer to work with the model that they're mapping large
-  buffers, synchronizing their safe re-use.  (If there's no re-use, then let
-  usbcore do the map/unmap.)  Large periodic transfers make good examples
-  here, since it's cheaper to just synchronize the buffer than to unmap it
-  each time an urb completes and then re-map it on during resubmission.
-
-  These calls all work with initialized urbs:  urb->dev, urb->pipe,
-  urb->transfer_buffer, and urb->transfer_buffer_length must all be
-  valid when these calls are used (urb->setup_packet must be valid too
-  if urb is a control request):
-
-	struct urb *usb_buffer_map (struct urb *urb);
-
-	void usb_buffer_dmasync (struct urb *urb);
-
-	void usb_buffer_unmap (struct urb *urb);
-
-  The calls manage urb->transfer_dma for you, and set URB_NO_TRANSFER_DMA_MAP
-  so that usbcore won't map or unmap the buffer.  They cannot be used for
-  setup_packet buffers in control requests.
-
-Note that several of those interfaces are currently commented out, since
-they don't have current users.  See the source code.  Other than the dmasync
-calls (where the underlying DMA primitives have changed), most of them can
-easily be commented back in if you want to use them.
diff --git a/Documentation/usb/error-codes.txt b/Documentation/usb/error-codes.txt
deleted file mode 100644
index 9c3eb845ebe5..000000000000
--- a/Documentation/usb/error-codes.txt
+++ /dev/null
@@ -1,175 +0,0 @@
-Revised: 2004-Oct-21
-
-This is the documentation of (hopefully) all possible error codes (and
-their interpretation) that can be returned from usbcore.
-
-Some of them are returned by the Host Controller Drivers (HCDs), which
-device drivers only see through usbcore.  As a rule, all the HCDs should
-behave the same except for transfer speed dependent behaviors and the
-way certain faults are reported.
-
-
-**************************************************************************
-*                   Error codes returned by usb_submit_urb               *
-**************************************************************************
-
-Non-USB-specific:
-
-0		URB submission went fine
-
--ENOMEM		no memory for allocation of internal structures	
-
-USB-specific:
-
--EBUSY		The URB is already active.
-
--ENODEV		specified USB-device or bus doesn't exist
-
--ENOENT		specified interface or endpoint does not exist or
-		is not enabled
-
--ENXIO		host controller driver does not support queuing of this type
-		of urb.  (treat as a host controller bug.)
-
--EINVAL		a) Invalid transfer type specified (or not supported)
-		b) Invalid or unsupported periodic transfer interval
-		c) ISO: attempted to change transfer interval
-		d) ISO: number_of_packets is < 0
-		e) various other cases
-
--EXDEV		ISO: URB_ISO_ASAP wasn't specified and all the frames
-		the URB would be scheduled in have already expired.
-
--EFBIG		Host controller driver can't schedule that many ISO frames.
-
--EPIPE		The pipe type specified in the URB doesn't match the
-		endpoint's actual type.
-
--EMSGSIZE	(a) endpoint maxpacket size is zero; it is not usable
-		    in the current interface altsetting.
-		(b) ISO packet is larger than the endpoint maxpacket.
-		(c) requested data transfer length is invalid: negative
-		    or too large for the host controller.
-
--ENOSPC		This request would overcommit the usb bandwidth reserved
-		for periodic transfers (interrupt, isochronous).
-
--ESHUTDOWN	The device or host controller has been disabled due to some
-		problem that could not be worked around.
-
--EPERM		Submission failed because urb->reject was set.
-
--EHOSTUNREACH	URB was rejected because the device is suspended.
-
--ENOEXEC	A control URB doesn't contain a Setup packet.
-
-
-**************************************************************************
-*                   Error codes returned by in urb->status               *
-*                   or in iso_frame_desc[n].status (for ISO)             *
-**************************************************************************
-
-USB device drivers may only test urb status values in completion handlers.
-This is because otherwise there would be a race between HCDs updating
-these values on one CPU, and device drivers testing them on another CPU.
-
-A transfer's actual_length may be positive even when an error has been
-reported.  That's because transfers often involve several packets, so that
-one or more packets could finish before an error stops further endpoint I/O.
-
-For isochronous URBs, the urb status value is non-zero only if the URB is
-unlinked, the device is removed, the host controller is disabled, or the total
-transferred length is less than the requested length and the URB_SHORT_NOT_OK
-flag is set.  Completion handlers for isochronous URBs should only see
-urb->status set to zero, -ENOENT, -ECONNRESET, -ESHUTDOWN, or -EREMOTEIO.
-Individual frame descriptor status fields may report more status codes.
-
-
-0			Transfer completed successfully
-
--ENOENT			URB was synchronously unlinked by usb_unlink_urb
-
--EINPROGRESS		URB still pending, no results yet
-			(That is, if drivers see this it's a bug.)
-
--EPROTO (*, **)		a) bitstuff error
-			b) no response packet received within the
-			   prescribed bus turn-around time
-			c) unknown USB error 
-
--EILSEQ (*, **)		a) CRC mismatch
-			b) no response packet received within the
-			   prescribed bus turn-around time
-			c) unknown USB error 
-
-			Note that often the controller hardware does not
-			distinguish among cases a), b), and c), so a
-			driver cannot tell whether there was a protocol
-			error, a failure to respond (often caused by
-			device disconnect), or some other fault.
-
--ETIME (**)		No response packet received within the prescribed
-			bus turn-around time.  This error may instead be
-			reported as -EPROTO or -EILSEQ.
-
--ETIMEDOUT		Synchronous USB message functions use this code
-			to indicate timeout expired before the transfer
-			completed, and no other error was reported by HC.
-
--EPIPE (**)		Endpoint stalled.  For non-control endpoints,
-			reset this status with usb_clear_halt().
-
--ECOMM			During an IN transfer, the host controller
-			received data from an endpoint faster than it
-			could be written to system memory
-
--ENOSR			During an OUT transfer, the host controller
-			could not retrieve data from system memory fast
-			enough to keep up with the USB data rate
-
--EOVERFLOW (*)		The amount of data returned by the endpoint was
-			greater than either the max packet size of the
-			endpoint or the remaining buffer size.  "Babble".
-
--EREMOTEIO		The data read from the endpoint did not fill the
-			specified buffer, and URB_SHORT_NOT_OK was set in
-			urb->transfer_flags.
-
--ENODEV			Device was removed.  Often preceded by a burst of
-			other errors, since the hub driver doesn't detect
-			device removal events immediately.
-
--EXDEV			ISO transfer only partially completed
-			(only set in iso_frame_desc[n].status, not urb->status)
-
--EINVAL			ISO madness, if this happens: Log off and go home
-
--ECONNRESET		URB was asynchronously unlinked by usb_unlink_urb
-
--ESHUTDOWN		The device or host controller has been disabled due
-			to some problem that could not be worked around,
-			such as a physical disconnect.
-
-
-(*) Error codes like -EPROTO, -EILSEQ and -EOVERFLOW normally indicate
-hardware problems such as bad devices (including firmware) or cables.
-
-(**) This is also one of several codes that different kinds of host
-controller use to indicate a transfer has failed because of device
-disconnect.  In the interval before the hub driver starts disconnect
-processing, devices may receive such fault reports for every request.
-
-
-
-**************************************************************************
-*              Error codes returned by usbcore-functions                 *
-*           (expect also other submit and transfer status codes)         *
-**************************************************************************
-
-usb_register():
--EINVAL			error during registering new driver
-
-usb_get_*/usb_set_*():
-usb_control_msg():
-usb_bulk_msg():
--ETIMEDOUT		Timeout expired before the transfer completed.
diff --git a/Documentation/usb/gadget_serial.txt b/Documentation/usb/gadget_serial.txt
index 6b4a88a8c8e3..d1def3186782 100644
--- a/Documentation/usb/gadget_serial.txt
+++ b/Documentation/usb/gadget_serial.txt
@@ -189,7 +189,7 @@ Once the gadget serial driver is loaded and the USB device connected
 to the Linux host with a USB cable, the host system should recognize
 the gadget serial device.  For example, the command
 
-  cat /proc/bus/usb/devices
+  cat /sys/kernel/debug/usb/devices
 
 should show something like this:
 
@@ -221,7 +221,7 @@ Once the gadget serial driver is loaded and the USB device connected
 to the Linux host with a USB cable, the host system should recognize
 the gadget serial device.  For example, the command
 
-  cat /proc/bus/usb/devices
+  cat /sys/kernel/debug/usb/devices
 
 should show something like this:
 
diff --git a/Documentation/usb/hotplug.txt b/Documentation/usb/hotplug.txt
deleted file mode 100644
index 5b243f315b2c..000000000000
--- a/Documentation/usb/hotplug.txt
+++ /dev/null
@@ -1,148 +0,0 @@
-LINUX HOTPLUGGING
-
-In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices
-into the bus with power on.  In most cases, users expect the devices to become
-immediately usable.  That means the system must do many things, including:
-
-    - Find a driver that can handle the device.  That may involve
-      loading a kernel module; newer drivers can use module-init-tools
-      to publish their device (and class) support to user utilities.
-
-    - Bind a driver to that device.  Bus frameworks do that using a
-      device driver's probe() routine.
-
-    - Tell other subsystems to configure the new device.  Print
-      queues may need to be enabled, networks brought up, disk
-      partitions mounted, and so on.  In some cases these will
-      be driver-specific actions.
-
-This involves a mix of kernel mode and user mode actions.  Making devices
-be immediately usable means that any user mode actions can't wait for an
-administrator to do them:  the kernel must trigger them, either passively
-(triggering some monitoring daemon to invoke a helper program) or
-actively (calling such a user mode helper program directly).
-
-Those triggered actions must support a system's administrative policies;
-such programs are called "policy agents" here.  Typically they involve
-shell scripts that dispatch to more familiar administration tools.
-
-Because some of those actions rely on information about drivers (metadata)
-that is currently available only when the drivers are dynamically linked,
-you get the best hotplugging when you configure a highly modular system.
-
-
-KERNEL HOTPLUG HELPER (/sbin/hotplug)
-
-There is a kernel parameter: /proc/sys/kernel/hotplug, which normally
-holds the pathname "/sbin/hotplug".  That parameter names a program
-which the kernel may invoke at various times.
-
-The /sbin/hotplug program can be invoked by any subsystem as part of its
-reaction to a configuration change, from a thread in that subsystem.
-Only one parameter is required: the name of a subsystem being notified of
-some kernel event.  That name is used as the first key for further event
-dispatch; any other argument and environment parameters are specified by
-the subsystem making that invocation.
-
-Hotplug software and other resources is available at:
-
-	http://linux-hotplug.sourceforge.net
-
-Mailing list information is also available at that site.
-
-
---------------------------------------------------------------------------
-
-
-USB POLICY AGENT
-
-The USB subsystem currently invokes /sbin/hotplug when USB devices
-are added or removed from system.  The invocation is done by the kernel
-hub workqueue [hub_wq], or else as part of root hub initialization
-(done by init, modprobe, kapmd, etc).  Its single command line parameter
-is the string "usb", and it passes these environment variables:
-
-    ACTION ... "add", "remove"
-    PRODUCT ... USB vendor, product, and version codes (hex)
-    TYPE ... device class codes (decimal)
-    INTERFACE ... interface 0 class codes (decimal)
-
-If "usbdevfs" is configured, DEVICE and DEVFS are also passed.  DEVICE is
-the pathname of the device, and is useful for devices with multiple and/or
-alternate interfaces that complicate driver selection.  By design, USB
-hotplugging is independent of "usbdevfs":  you can do most essential parts
-of USB device setup without using that filesystem, and without running a
-user mode daemon to detect changes in system configuration.
-
-Currently available policy agent implementations can load drivers for
-modules, and can invoke driver-specific setup scripts.  The newest ones
-leverage USB module-init-tools support.  Later agents might unload drivers.
-
-
-USB MODUTILS SUPPORT
-
-Current versions of module-init-tools will create a "modules.usbmap" file
-which contains the entries from each driver's MODULE_DEVICE_TABLE.  Such
-files can be used by various user mode policy agents to make sure all the
-right driver modules get loaded, either at boot time or later.
-
-See <linux/usb.h> for full information about such table entries; or look
-at existing drivers.  Each table entry describes one or more criteria to
-be used when matching a driver to a device or class of devices.  The
-specific criteria are identified by bits set in "match_flags", paired
-with field values.  You can construct the criteria directly, or with
-macros such as these, and use driver_info to store more information.
-
-    USB_DEVICE (vendorId, productId)
-	... matching devices with specified vendor and product ids
-    USB_DEVICE_VER (vendorId, productId, lo, hi)
-	... like USB_DEVICE with lo <= productversion <= hi
-    USB_INTERFACE_INFO (class, subclass, protocol)
-	... matching specified interface class info
-    USB_DEVICE_INFO (class, subclass, protocol)
-	... matching specified device class info
-
-A short example, for a driver that supports several specific USB devices
-and their quirks, might have a MODULE_DEVICE_TABLE like this:
-
-    static const struct usb_device_id mydriver_id_table[] = {
-	{ USB_DEVICE (0x9999, 0xaaaa), driver_info: QUIRK_X },
-	{ USB_DEVICE (0xbbbb, 0x8888), driver_info: QUIRK_Y|QUIRK_Z },
-	...
-	{ } /* end with an all-zeroes entry */
-    };
-    MODULE_DEVICE_TABLE(usb, mydriver_id_table);
-
-Most USB device drivers should pass these tables to the USB subsystem as
-well as to the module management subsystem.  Not all, though: some driver
-frameworks connect using interfaces layered over USB, and so they won't
-need such a "struct usb_driver".
-
-Drivers that connect directly to the USB subsystem should be declared
-something like this:
-
-    static struct usb_driver mydriver = {
-	.name		= "mydriver",
-	.id_table	= mydriver_id_table,
-	.probe		= my_probe,
-	.disconnect	= my_disconnect,
-
-	/*
-	if using the usb chardev framework:
-	    .minor		= MY_USB_MINOR_START,
-	    .fops		= my_file_ops,
-	if exposing any operations through usbdevfs:
-	    .ioctl		= my_ioctl,
-	*/
-    };
-
-When the USB subsystem knows about a driver's device ID table, it's used when
-choosing drivers to probe().  The thread doing new device processing checks
-drivers' device ID entries from the MODULE_DEVICE_TABLE against interface and
-device descriptors for the device.  It will only call probe() if there is a
-match, and the third argument to probe() will be the entry that matched.
-
-If you don't provide an id_table for your driver, then your driver may get
-probed for each new device; the third parameter to probe() will be null.
-
-
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.
diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt
deleted file mode 100644
index 00e706997130..000000000000
--- a/Documentation/usb/power-management.txt
+++ /dev/null
@@ -1,772 +0,0 @@
-			Power Management for USB
-
-		 Alan Stern <stern@rowland.harvard.edu>
-
-		       Last-updated: February 2014
-
-
-	Contents:
-	---------
-	* What is Power Management?
-	* What is Remote Wakeup?
-	* When is a USB device idle?
-	* Forms of dynamic PM
-	* The user interface for dynamic PM
-	* Changing the default idle-delay time
-	* Warnings
-	* The driver interface for Power Management
-	* The driver interface for autosuspend and autoresume
-	* Other parts of the driver interface
-	* Mutual exclusion
-	* Interaction between dynamic PM and system PM
-	* xHCI hardware link PM
-	* USB Port Power Control
-	* User Interface for Port Power Control
-	* Suggested Userspace Port Power Policy
-
-
-	What is Power Management?
-	-------------------------
-
-Power Management (PM) is the practice of saving energy by suspending
-parts of a computer system when they aren't being used.  While a
-component is "suspended" it is in a nonfunctional low-power state; it
-might even be turned off completely.  A suspended component can be
-"resumed" (returned to a functional full-power state) when the kernel
-needs to use it.  (There also are forms of PM in which components are
-placed in a less functional but still usable state instead of being
-suspended; an example would be reducing the CPU's clock rate.  This
-document will not discuss those other forms.)
-
-When the parts being suspended include the CPU and most of the rest of
-the system, we speak of it as a "system suspend".  When a particular
-device is turned off while the system as a whole remains running, we
-call it a "dynamic suspend" (also known as a "runtime suspend" or
-"selective suspend").  This document concentrates mostly on how
-dynamic PM is implemented in the USB subsystem, although system PM is
-covered to some extent (see Documentation/power/*.txt for more
-information about system PM).
-
-System PM support is present only if the kernel was built with CONFIG_SUSPEND
-or CONFIG_HIBERNATION enabled.  Dynamic PM support for USB is present whenever
-the kernel was built with CONFIG_PM enabled.
-
-[Historically, dynamic PM support for USB was present only if the
-kernel had been built with CONFIG_USB_SUSPEND enabled (which depended on
-CONFIG_PM_RUNTIME).  Starting with the 3.10 kernel release, dynamic PM support
-for USB was present whenever the kernel was built with CONFIG_PM_RUNTIME
-enabled.  The CONFIG_USB_SUSPEND option had been eliminated.]
-
-
-	What is Remote Wakeup?
-	----------------------
-
-When a device has been suspended, it generally doesn't resume until
-the computer tells it to.  Likewise, if the entire computer has been
-suspended, it generally doesn't resume until the user tells it to, say
-by pressing a power button or opening the cover.
-
-However some devices have the capability of resuming by themselves, or
-asking the kernel to resume them, or even telling the entire computer
-to resume.  This capability goes by several names such as "Wake On
-LAN"; we will refer to it generically as "remote wakeup".  When a
-device is enabled for remote wakeup and it is suspended, it may resume
-itself (or send a request to be resumed) in response to some external
-event.  Examples include a suspended keyboard resuming when a key is
-pressed, or a suspended USB hub resuming when a device is plugged in.
-
-
-	When is a USB device idle?
-	--------------------------
-
-A device is idle whenever the kernel thinks it's not busy doing
-anything important and thus is a candidate for being suspended.  The
-exact definition depends on the device's driver; drivers are allowed
-to declare that a device isn't idle even when there's no actual
-communication taking place.  (For example, a hub isn't considered idle
-unless all the devices plugged into that hub are already suspended.)
-In addition, a device isn't considered idle so long as a program keeps
-its usbfs file open, whether or not any I/O is going on.
-
-If a USB device has no driver, its usbfs file isn't open, and it isn't
-being accessed through sysfs, then it definitely is idle.
-
-
-	Forms of dynamic PM
-	-------------------
-
-Dynamic suspends occur when the kernel decides to suspend an idle
-device.  This is called "autosuspend" for short.  In general, a device
-won't be autosuspended unless it has been idle for some minimum period
-of time, the so-called idle-delay time.
-
-Of course, nothing the kernel does on its own initiative should
-prevent the computer or its devices from working properly.  If a
-device has been autosuspended and a program tries to use it, the
-kernel will automatically resume the device (autoresume).  For the
-same reason, an autosuspended device will usually have remote wakeup
-enabled, if the device supports remote wakeup.
-
-It is worth mentioning that many USB drivers don't support
-autosuspend.  In fact, at the time of this writing (Linux 2.6.23) the
-only drivers which do support it are the hub driver, kaweth, asix,
-usblp, usblcd, and usb-skeleton (which doesn't count).  If a
-non-supporting driver is bound to a device, the device won't be
-autosuspended.  In effect, the kernel pretends the device is never
-idle.
-
-We can categorize power management events in two broad classes:
-external and internal.  External events are those triggered by some
-agent outside the USB stack: system suspend/resume (triggered by
-userspace), manual dynamic resume (also triggered by userspace), and
-remote wakeup (triggered by the device).  Internal events are those
-triggered within the USB stack: autosuspend and autoresume.  Note that
-all dynamic suspend events are internal; external agents are not
-allowed to issue dynamic suspends.
-
-
-	The user interface for dynamic PM
-	---------------------------------
-
-The user interface for controlling dynamic PM is located in the power/
-subdirectory of each USB device's sysfs directory, that is, in
-/sys/bus/usb/devices/.../power/ where "..." is the device's ID.  The
-relevant attribute files are: wakeup, control, and
-autosuspend_delay_ms.  (There may also be a file named "level"; this
-file was deprecated as of the 2.6.35 kernel and replaced by the
-"control" file.  In 2.6.38 the "autosuspend" file will be deprecated
-and replaced by the "autosuspend_delay_ms" file.  The only difference
-is that the newer file expresses the delay in milliseconds whereas the
-older file uses seconds.  Confusingly, both files are present in 2.6.37
-but only "autosuspend" works.)
-
-	power/wakeup
-
-		This file is empty if the device does not support
-		remote wakeup.  Otherwise the file contains either the
-		word "enabled" or the word "disabled", and you can
-		write those words to the file.  The setting determines
-		whether or not remote wakeup will be enabled when the
-		device is next suspended.  (If the setting is changed
-		while the device is suspended, the change won't take
-		effect until the following suspend.)
-
-	power/control
-
-		This file contains one of two words: "on" or "auto".
-		You can write those words to the file to change the
-		device's setting.
-
-		"on" means that the device should be resumed and
-		autosuspend is not allowed.  (Of course, system
-		suspends are still allowed.)
-
-		"auto" is the normal state in which the kernel is
-		allowed to autosuspend and autoresume the device.
-
-		(In kernels up to 2.6.32, you could also specify
-		"suspend", meaning that the device should remain
-		suspended and autoresume was not allowed.  This
-		setting is no longer supported.)
-
-	power/autosuspend_delay_ms
-
-		This file contains an integer value, which is the
-		number of milliseconds the device should remain idle
-		before the kernel will autosuspend it (the idle-delay
-		time).  The default is 2000.  0 means to autosuspend
-		as soon as the device becomes idle, and negative
-		values mean never to autosuspend.  You can write a
-		number to the file to change the autosuspend
-		idle-delay time.
-
-Writing "-1" to power/autosuspend_delay_ms and writing "on" to
-power/control do essentially the same thing -- they both prevent the
-device from being autosuspended.  Yes, this is a redundancy in the
-API.
-
-(In 2.6.21 writing "0" to power/autosuspend would prevent the device
-from being autosuspended; the behavior was changed in 2.6.22.  The
-power/autosuspend attribute did not exist prior to 2.6.21, and the
-power/level attribute did not exist prior to 2.6.22.  power/control
-was added in 2.6.34, and power/autosuspend_delay_ms was added in
-2.6.37 but did not become functional until 2.6.38.)
-
-
-	Changing the default idle-delay time
-	------------------------------------
-
-The default autosuspend idle-delay time (in seconds) is controlled by
-a module parameter in usbcore.  You can specify the value when usbcore
-is loaded.  For example, to set it to 5 seconds instead of 2 you would
-do:
-
-	modprobe usbcore autosuspend=5
-
-Equivalently, you could add to a configuration file in /etc/modprobe.d
-a line saying:
-
-	options usbcore autosuspend=5
-
-Some distributions load the usbcore module very early during the boot
-process, by means of a program or script running from an initramfs
-image.  To alter the parameter value you would have to rebuild that
-image.
-
-If usbcore is compiled into the kernel rather than built as a loadable
-module, you can add
-
-	usbcore.autosuspend=5
-
-to the kernel's boot command line.
-
-Finally, the parameter value can be changed while the system is
-running.  If you do:
-
-	echo 5 >/sys/module/usbcore/parameters/autosuspend
-
-then each new USB device will have its autosuspend idle-delay
-initialized to 5.  (The idle-delay values for already existing devices
-will not be affected.)
-
-Setting the initial default idle-delay to -1 will prevent any
-autosuspend of any USB device.  This has the benefit of allowing you
-then to enable autosuspend for selected devices.
-
-
-	Warnings
-	--------
-
-The USB specification states that all USB devices must support power
-management.  Nevertheless, the sad fact is that many devices do not
-support it very well.  You can suspend them all right, but when you
-try to resume them they disconnect themselves from the USB bus or
-they stop working entirely.  This seems to be especially prevalent
-among printers and scanners, but plenty of other types of device have
-the same deficiency.
-
-For this reason, by default the kernel disables autosuspend (the
-power/control attribute is initialized to "on") for all devices other
-than hubs.  Hubs, at least, appear to be reasonably well-behaved in
-this regard.
-
-(In 2.6.21 and 2.6.22 this wasn't the case.  Autosuspend was enabled
-by default for almost all USB devices.  A number of people experienced
-problems as a result.)
-
-This means that non-hub devices won't be autosuspended unless the user
-or a program explicitly enables it.  As of this writing there aren't
-any widespread programs which will do this; we hope that in the near
-future device managers such as HAL will take on this added
-responsibility.  In the meantime you can always carry out the
-necessary operations by hand or add them to a udev script.  You can
-also change the idle-delay time; 2 seconds is not the best choice for
-every device.
-
-If a driver knows that its device has proper suspend/resume support,
-it can enable autosuspend all by itself.  For example, the video
-driver for a laptop's webcam might do this (in recent kernels they
-do), since these devices are rarely used and so should normally be
-autosuspended.
-
-Sometimes it turns out that even when a device does work okay with
-autosuspend there are still problems.  For example, the usbhid driver,
-which manages keyboards and mice, has autosuspend support.  Tests with
-a number of keyboards show that typing on a suspended keyboard, while
-causing the keyboard to do a remote wakeup all right, will nonetheless
-frequently result in lost keystrokes.  Tests with mice show that some
-of them will issue a remote-wakeup request in response to button
-presses but not to motion, and some in response to neither.
-
-The kernel will not prevent you from enabling autosuspend on devices
-that can't handle it.  It is even possible in theory to damage a
-device by suspending it at the wrong time.  (Highly unlikely, but
-possible.)  Take care.
-
-
-	The driver interface for Power Management
-	-----------------------------------------
-
-The requirements for a USB driver to support external power management
-are pretty modest; the driver need only define
-
-	.suspend
-	.resume
-	.reset_resume
-
-methods in its usb_driver structure, and the reset_resume method is
-optional.  The methods' jobs are quite simple:
-
-	The suspend method is called to warn the driver that the
-	device is going to be suspended.  If the driver returns a
-	negative error code, the suspend will be aborted.  Normally
-	the driver will return 0, in which case it must cancel all
-	outstanding URBs (usb_kill_urb()) and not submit any more.
-
-	The resume method is called to tell the driver that the
-	device has been resumed and the driver can return to normal
-	operation.  URBs may once more be submitted.
-
-	The reset_resume method is called to tell the driver that
-	the device has been resumed and it also has been reset.
-	The driver should redo any necessary device initialization,
-	since the device has probably lost most or all of its state
-	(although the interfaces will be in the same altsettings as
-	before the suspend).
-
-If the device is disconnected or powered down while it is suspended,
-the disconnect method will be called instead of the resume or
-reset_resume method.  This is also quite likely to happen when
-waking up from hibernation, as many systems do not maintain suspend
-current to the USB host controllers during hibernation.  (It's
-possible to work around the hibernation-forces-disconnect problem by
-using the USB Persist facility.)
-
-The reset_resume method is used by the USB Persist facility (see
-Documentation/usb/persist.txt) and it can also be used under certain
-circumstances when CONFIG_USB_PERSIST is not enabled.  Currently, if a
-device is reset during a resume and the driver does not have a
-reset_resume method, the driver won't receive any notification about
-the resume.  Later kernels will call the driver's disconnect method;
-2.6.23 doesn't do this.
-
-USB drivers are bound to interfaces, so their suspend and resume
-methods get called when the interfaces are suspended or resumed.  In
-principle one might want to suspend some interfaces on a device (i.e.,
-force the drivers for those interface to stop all activity) without
-suspending the other interfaces.  The USB core doesn't allow this; all
-interfaces are suspended when the device itself is suspended and all
-interfaces are resumed when the device is resumed.  It isn't possible
-to suspend or resume some but not all of a device's interfaces.  The
-closest you can come is to unbind the interfaces' drivers.
-
-
-	The driver interface for autosuspend and autoresume
-	---------------------------------------------------
-
-To support autosuspend and autoresume, a driver should implement all
-three of the methods listed above.  In addition, a driver indicates
-that it supports autosuspend by setting the .supports_autosuspend flag
-in its usb_driver structure.  It is then responsible for informing the
-USB core whenever one of its interfaces becomes busy or idle.  The
-driver does so by calling these six functions:
-
-	int  usb_autopm_get_interface(struct usb_interface *intf);
-	void usb_autopm_put_interface(struct usb_interface *intf);
-	int  usb_autopm_get_interface_async(struct usb_interface *intf);
-	void usb_autopm_put_interface_async(struct usb_interface *intf);
-	void usb_autopm_get_interface_no_resume(struct usb_interface *intf);
-	void usb_autopm_put_interface_no_suspend(struct usb_interface *intf);
-
-The functions work by maintaining a usage counter in the
-usb_interface's embedded device structure.  When the counter is > 0
-then the interface is deemed to be busy, and the kernel will not
-autosuspend the interface's device.  When the usage counter is = 0
-then the interface is considered to be idle, and the kernel may
-autosuspend the device.
-
-Drivers need not be concerned about balancing changes to the usage
-counter; the USB core will undo any remaining "get"s when a driver
-is unbound from its interface.  As a corollary, drivers must not call
-any of the usb_autopm_* functions after their disconnect() routine has
-returned.
-
-Drivers using the async routines are responsible for their own
-synchronization and mutual exclusion.
-
-	usb_autopm_get_interface() increments the usage counter and
-	does an autoresume if the device is suspended.  If the
-	autoresume fails, the counter is decremented back.
-
-	usb_autopm_put_interface() decrements the usage counter and
-	attempts an autosuspend if the new value is = 0.
-
-	usb_autopm_get_interface_async() and
-	usb_autopm_put_interface_async() do almost the same things as
-	their non-async counterparts.  The big difference is that they
-	use a workqueue to do the resume or suspend part of their
-	jobs.  As a result they can be called in an atomic context,
-	such as an URB's completion handler, but when they return the
-	device will generally not yet be in the desired state.
-
-	usb_autopm_get_interface_no_resume() and
-	usb_autopm_put_interface_no_suspend() merely increment or
-	decrement the usage counter; they do not attempt to carry out
-	an autoresume or an autosuspend.  Hence they can be called in
-	an atomic context.
-
-The simplest usage pattern is that a driver calls
-usb_autopm_get_interface() in its open routine and
-usb_autopm_put_interface() in its close or release routine.  But other
-patterns are possible.
-
-The autosuspend attempts mentioned above will often fail for one
-reason or another.  For example, the power/control attribute might be
-set to "on", or another interface in the same device might not be
-idle.  This is perfectly normal.  If the reason for failure was that
-the device hasn't been idle for long enough, a timer is scheduled to
-carry out the operation automatically when the autosuspend idle-delay
-has expired.
-
-Autoresume attempts also can fail, although failure would mean that
-the device is no longer present or operating properly.  Unlike
-autosuspend, there's no idle-delay for an autoresume.
-
-
-	Other parts of the driver interface
-	-----------------------------------
-
-Drivers can enable autosuspend for their devices by calling
-
-	usb_enable_autosuspend(struct usb_device *udev);
-
-in their probe() routine, if they know that the device is capable of
-suspending and resuming correctly.  This is exactly equivalent to
-writing "auto" to the device's power/control attribute.  Likewise,
-drivers can disable autosuspend by calling
-
-	usb_disable_autosuspend(struct usb_device *udev);
-
-This is exactly the same as writing "on" to the power/control attribute.
-
-Sometimes a driver needs to make sure that remote wakeup is enabled
-during autosuspend.  For example, there's not much point
-autosuspending a keyboard if the user can't cause the keyboard to do a
-remote wakeup by typing on it.  If the driver sets
-intf->needs_remote_wakeup to 1, the kernel won't autosuspend the
-device if remote wakeup isn't available.  (If the device is already
-autosuspended, though, setting this flag won't cause the kernel to
-autoresume it.  Normally a driver would set this flag in its probe
-method, at which time the device is guaranteed not to be
-autosuspended.)
-
-If a driver does its I/O asynchronously in interrupt context, it
-should call usb_autopm_get_interface_async() before starting output and
-usb_autopm_put_interface_async() when the output queue drains.  When
-it receives an input event, it should call
-
-	usb_mark_last_busy(struct usb_device *udev);
-
-in the event handler.  This tells the PM core that the device was just
-busy and therefore the next autosuspend idle-delay expiration should
-be pushed back.  Many of the usb_autopm_* routines also make this call,
-so drivers need to worry only when interrupt-driven input arrives.
-
-Asynchronous operation is always subject to races.  For example, a
-driver may call the usb_autopm_get_interface_async() routine at a time
-when the core has just finished deciding the device has been idle for
-long enough but not yet gotten around to calling the driver's suspend
-method.  The suspend method must be responsible for synchronizing with
-the I/O request routine and the URB completion handler; it should
-cause autosuspends to fail with -EBUSY if the driver needs to use the
-device.
-
-External suspend calls should never be allowed to fail in this way,
-only autosuspend calls.  The driver can tell them apart by applying
-the PMSG_IS_AUTO() macro to the message argument to the suspend
-method; it will return True for internal PM events (autosuspend) and
-False for external PM events.
-
-
-	Mutual exclusion
-	----------------
-
-For external events -- but not necessarily for autosuspend or
-autoresume -- the device semaphore (udev->dev.sem) will be held when a
-suspend or resume method is called.  This implies that external
-suspend/resume events are mutually exclusive with calls to probe,
-disconnect, pre_reset, and post_reset; the USB core guarantees that
-this is true of autosuspend/autoresume events as well.
-
-If a driver wants to block all suspend/resume calls during some
-critical section, the best way is to lock the device and call
-usb_autopm_get_interface() (and do the reverse at the end of the
-critical section).  Holding the device semaphore will block all
-external PM calls, and the usb_autopm_get_interface() will prevent any
-internal PM calls, even if it fails.  (Exercise: Why?)
-
-
-	Interaction between dynamic PM and system PM
-	--------------------------------------------
-
-Dynamic power management and system power management can interact in
-a couple of ways.
-
-Firstly, a device may already be autosuspended when a system suspend
-occurs.  Since system suspends are supposed to be as transparent as
-possible, the device should remain suspended following the system
-resume.  But this theory may not work out well in practice; over time
-the kernel's behavior in this regard has changed.  As of 2.6.37 the
-policy is to resume all devices during a system resume and let them
-handle their own runtime suspends afterward.
-
-Secondly, a dynamic power-management event may occur as a system
-suspend is underway.  The window for this is short, since system
-suspends don't take long (a few seconds usually), but it can happen.
-For example, a suspended device may send a remote-wakeup signal while
-the system is suspending.  The remote wakeup may succeed, which would
-cause the system suspend to abort.  If the remote wakeup doesn't
-succeed, it may still remain active and thus cause the system to
-resume as soon as the system suspend is complete.  Or the remote
-wakeup may fail and get lost.  Which outcome occurs depends on timing
-and on the hardware and firmware design.
-
-
-	xHCI hardware link PM
-	---------------------
-
-xHCI host controller provides hardware link power management to usb2.0
-(xHCI 1.0 feature) and usb3.0 devices which support link PM. By
-enabling hardware LPM, the host can automatically put the device into
-lower power state(L1 for usb2.0 devices, or U1/U2 for usb3.0 devices),
-which state device can enter and resume very quickly.
-
-The user interface for controlling hardware LPM is located in the
-power/ subdirectory of each USB device's sysfs directory, that is, in
-/sys/bus/usb/devices/.../power/ where "..." is the device's ID. The
-relevant attribute files are usb2_hardware_lpm and usb3_hardware_lpm.
-
-	power/usb2_hardware_lpm
-
-		When a USB2 device which support LPM is plugged to a
-		xHCI host root hub which support software LPM, the
-		host will run a software LPM test for it; if the device
-		enters L1 state and resume successfully and the host
-		supports USB2 hardware LPM, this file will show up and
-		driver will enable hardware LPM	for the device. You
-		can write y/Y/1 or n/N/0 to the file to	enable/disable
-		USB2 hardware LPM manually. This is for	test purpose mainly.
-
-	power/usb3_hardware_lpm_u1
-	power/usb3_hardware_lpm_u2
-
-		When a USB 3.0 lpm-capable device is plugged in to a
-		xHCI host which supports link PM, it will check if U1
-		and U2 exit latencies have been set in the BOS
-		descriptor; if the check is passed and the host
-		supports USB3 hardware LPM, USB3 hardware LPM will be
-		enabled for the device and these files will be created.
-		The files hold a string value (enable or disable)
-		indicating whether or not USB3 hardware LPM U1 or U2
-		is enabled for the device.
-
-	USB Port Power Control
-	----------------------
-
-In addition to suspending endpoint devices and enabling hardware
-controlled link power management, the USB subsystem also has the
-capability to disable power to ports under some conditions.  Power is
-controlled through Set/ClearPortFeature(PORT_POWER) requests to a hub.
-In the case of a root or platform-internal hub the host controller
-driver translates PORT_POWER requests into platform firmware (ACPI)
-method calls to set the port power state. For more background see the
-Linux Plumbers Conference 2012 slides [1] and video [2]:
-
-Upon receiving a ClearPortFeature(PORT_POWER) request a USB port is
-logically off, and may trigger the actual loss of VBUS to the port [3].
-VBUS may be maintained in the case where a hub gangs multiple ports into
-a shared power well causing power to remain until all ports in the gang
-are turned off.  VBUS may also be maintained by hub ports configured for
-a charging application.  In any event a logically off port will lose
-connection with its device, not respond to hotplug events, and not
-respond to remote wakeup events*.
-
-WARNING: turning off a port may result in the inability to hot add a device.
-Please see "User Interface for Port Power Control" for details.
-
-As far as the effect on the device itself it is similar to what a device
-goes through during system suspend, i.e. the power session is lost.  Any
-USB device or driver that misbehaves with system suspend will be
-similarly affected by a port power cycle event.  For this reason the
-implementation shares the same device recovery path (and honors the same
-quirks) as the system resume path for the hub.
-
-[1]: http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf
-[2]: http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/
-[3]: USB 3.1 Section 10.12
-* wakeup note: if a device is configured to send wakeup events the port
-  power control implementation will block poweroff attempts on that
-  port.
-
-
-	User Interface for Port Power Control
-	-------------------------------------
-
-The port power control mechanism uses the PM runtime system.  Poweroff is
-requested by clearing the power/pm_qos_no_power_off flag of the port device
-(defaults to 1).  If the port is disconnected it will immediately receive a
-ClearPortFeature(PORT_POWER) request.  Otherwise, it will honor the pm runtime
-rules and require the attached child device and all descendants to be suspended.
-This mechanism is dependent on the hub advertising port power switching in its
-hub descriptor (wHubCharacteristics logical power switching mode field).
-
-Note, some interface devices/drivers do not support autosuspend.  Userspace may
-need to unbind the interface drivers before the usb_device will suspend.  An
-unbound interface device is suspended by default.  When unbinding, be careful
-to unbind interface drivers, not the driver of the parent usb device.  Also,
-leave hub interface drivers bound.  If the driver for the usb device (not
-interface) is unbound the kernel is no longer able to resume the device.  If a
-hub interface driver is unbound, control of its child ports is lost and all
-attached child-devices will disconnect.  A good rule of thumb is that if the
-'driver/module' link for a device points to /sys/module/usbcore then unbinding
-it will interfere with port power control.
-
-Example of the relevant files for port power control.  Note, in this example
-these files are relative to a usb hub device (prefix).
-
-     prefix=/sys/devices/pci0000:00/0000:00:14.0/usb3/3-1
-
-                      attached child device +
-                  hub port device +         |
-     hub interface device +       |         |
-                          v       v         v
-                  $prefix/3-1:1.0/3-1-port1/device
-
-     $prefix/3-1:1.0/3-1-port1/power/pm_qos_no_power_off
-     $prefix/3-1:1.0/3-1-port1/device/power/control
-     $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf0>/driver/unbind
-     $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf1>/driver/unbind
-     ...
-     $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intfN>/driver/unbind
-
-In addition to these files some ports may have a 'peer' link to a port on
-another hub.  The expectation is that all superspeed ports have a
-hi-speed peer.
-
-$prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1
-../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1
-
-Distinct from 'companion ports', or 'ehci/xhci shared switchover ports'
-peer ports are simply the hi-speed and superspeed interface pins that
-are combined into a single usb3 connector.  Peer ports share the same
-ancestor XHCI device.
-
-While a superspeed port is powered off a device may downgrade its
-connection and attempt to connect to the hi-speed pins.  The
-implementation takes steps to prevent this:
-
-1/ Port suspend is sequenced to guarantee that hi-speed ports are powered-off
-   before their superspeed peer is permitted to power-off.  The implication is
-   that the setting pm_qos_no_power_off to zero on a superspeed port may not cause
-   the port to power-off until its highspeed peer has gone to its runtime suspend
-   state.  Userspace must take care to order the suspensions if it wants to
-   guarantee that a superspeed port will power-off.
-
-2/ Port resume is sequenced to force a superspeed port to power-on prior to its
-   highspeed peer.
-
-3/ Port resume always triggers an attached child device to resume.  After a
-   power session is lost the device may have been removed, or need reset.
-   Resuming the child device when the parent port regains power resolves those
-   states and clamps the maximum port power cycle frequency at the rate the child
-   device can suspend (autosuspend-delay) and resume (reset-resume latency).
-
-Sysfs files relevant for port power control:
-	<hubdev-portX>/power/pm_qos_no_power_off:
-		This writable flag controls the state of an idle port.
-		Once all children and descendants have suspended the
-		port may suspend/poweroff provided that
-		pm_qos_no_power_off is '0'.  If pm_qos_no_power_off is
-		'1' the port will remain active/powered regardless of
-		the stats of descendants.  Defaults to 1.
-
-	<hubdev-portX>/power/runtime_status:
-		This file reflects whether the port is 'active' (power is on)
-		or 'suspended' (logically off).  There is no indication to
-		userspace whether VBUS is still supplied.
-
-	<hubdev-portX>/connect_type:
-		An advisory read-only flag to userspace indicating the
-		location and connection type of the port.  It returns
-		one of four values 'hotplug', 'hardwired', 'not used',
-		and 'unknown'.  All values, besides unknown, are set by
-		platform firmware.
-
-		"hotplug" indicates an externally connectable/visible
-		port on the platform.  Typically userspace would choose
-		to keep such a port powered to handle new device
-		connection events.
-
-		"hardwired" refers to a port that is not visible but
-		connectable. Examples are internal ports for USB
-		bluetooth that can be disconnected via an external
-		switch or a port with a hardwired USB camera.  It is
-		expected to be safe to allow these ports to suspend
-		provided pm_qos_no_power_off is coordinated with any
-		switch that gates connections.  Userspace must arrange
-		for the device to be connected prior to the port
-		powering off, or to activate the port prior to enabling
-		connection via a switch.
-
-		"not used" refers to an internal port that is expected
-		to never have a device connected to it.  These may be
-		empty internal ports, or ports that are not physically
-		exposed on a platform.  Considered safe to be
-		powered-off at all times.
-
-		"unknown" means platform firmware does not provide
-		information for this port.  Most commonly refers to
-		external hub ports which should be considered 'hotplug'
-		for policy decisions.
-
-		NOTE1: since we are relying on the BIOS to get this ACPI
-		information correct, the USB port descriptions may be
-		missing or wrong.
-
-		NOTE2: Take care in clearing pm_qos_no_power_off.  Once
-		power is off this port will
-		not respond to new connect events.
-
-	Once a child device is attached additional constraints are
-	applied before the port is allowed to poweroff.
-
-	<child>/power/control:
-		Must be 'auto', and the port will not
-		power down until <child>/power/runtime_status
-		reflects the 'suspended' state.  Default
-		value is controlled by child device driver.
-
-	<child>/power/persist:
-		This defaults to '1' for most devices and indicates if
-		kernel can persist the device's configuration across a
-		power session loss (suspend / port-power event).  When
-		this value is '0' (quirky devices), port poweroff is
-		disabled.
-
-	<child>/driver/unbind:
-		Wakeup capable devices will block port poweroff.  At
-		this time the only mechanism to clear the usb-internal
-		wakeup-capability for an interface device is to unbind
-		its driver.
-
-Summary of poweroff pre-requisite settings relative to a port device:
-
-	echo 0 > power/pm_qos_no_power_off
-	echo 0 > peer/power/pm_qos_no_power_off # if it exists
-	echo auto > power/control # this is the default value
-	echo auto > <child>/power/control
-	echo 1 > <child>/power/persist # this is the default value
-
-	Suggested Userspace Port Power Policy
-	-------------------------------------
-
-As noted above userspace needs to be careful and deliberate about what
-ports are enabled for poweroff.
-
-The default configuration is that all ports start with
-power/pm_qos_no_power_off set to '1' causing ports to always remain
-active.
-
-Given confidence in the platform firmware's description of the ports
-(ACPI _PLD record for a port populates 'connect_type') userspace can
-clear pm_qos_no_power_off for all 'not used' ports.  The same can be
-done for 'hardwired' ports provided poweroff is coordinated with any
-connection switch for the port.
-
-A more aggressive userspace policy is to enable USB port power off for
-all ports (set <hubdev-portX>/power/pm_qos_no_power_off to '0') when
-some external factor indicates the user has stopped interacting with the
-system.  For example, a distro may want to enable power off all USB
-ports when the screen blanks, and re-power them when the screen becomes
-active.  Smart phones and tablets may want to power off USB ports when
-the user pushes the power button.
diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt
deleted file mode 100644
index 98be91982677..000000000000
--- a/Documentation/usb/proc_usb_info.txt
+++ /dev/null
@@ -1,390 +0,0 @@
-/proc/bus/usb filesystem output
-===============================
-(version 2010.09.13)
-
-
-The usbfs filesystem for USB devices is traditionally mounted at
-/proc/bus/usb.  It provides the /proc/bus/usb/devices file, as well as
-the /proc/bus/usb/BBB/DDD files.
-
-In many modern systems the usbfs filesystem isn't used at all.  Instead
-USB device nodes are created under /dev/usb/ or someplace similar.  The
-"devices" file is available in debugfs, typically as
-/sys/kernel/debug/usb/devices.
-
-
-**NOTE**: If /proc/bus/usb appears empty, and a host controller
-	  driver has been linked, then you need to mount the
-	  filesystem.  Issue the command (as root):
-
-      mount -t usbfs none /proc/bus/usb
-
-	  An alternative and more permanent method would be to add
-
-      none  /proc/bus/usb  usbfs  defaults  0  0
-
-	  to /etc/fstab.  This will mount usbfs at each reboot.
-	  You can then issue `cat /proc/bus/usb/devices` to extract
-	  USB device information, and user mode drivers can use usbfs
-	  to interact with USB devices.
-
-	  There are a number of mount options supported by usbfs.
-	  Consult the source code (linux/drivers/usb/core/inode.c) for
-	  information about those options.
-
-**NOTE**: The filesystem has been renamed from "usbdevfs" to
-	  "usbfs", to reduce confusion with "devfs".  You may
-	  still see references to the older "usbdevfs" name.
-
-For more information on mounting the usbfs file system, see the
-"USB Device Filesystem" section of the USB Guide. The latest copy
-of the USB Guide can be found at http://www.linux-usb.org/
-
-
-THE /proc/bus/usb/BBB/DDD FILES:
---------------------------------
-Each connected USB device has one file.  The BBB indicates the bus
-number.  The DDD indicates the device address on that bus.  Both
-of these numbers are assigned sequentially, and can be reused, so
-you can't rely on them for stable access to devices.  For example,
-it's relatively common for devices to re-enumerate while they are
-still connected (perhaps someone jostled their power supply, hub,
-or USB cable), so a device might be 002/027 when you first connect
-it and 002/048 sometime later.
-
-These files can be read as binary data.  The binary data consists
-of first the device descriptor, then the descriptors for each
-configuration of the device.  Multi-byte fields in the device descriptor
-are converted to host endianness by the kernel.  The configuration
-descriptors are in bus endian format! The configuration descriptor
-are wTotalLength bytes apart. If a device returns less configuration
-descriptor data than indicated by wTotalLength there will be a hole in
-the file for the missing bytes.  This information is also shown
-in text form by the /proc/bus/usb/devices file, described later.
-
-These files may also be used to write user-level drivers for the USB
-devices.  You would open the /proc/bus/usb/BBB/DDD file read/write,
-read its descriptors to make sure it's the device you expect, and then
-bind to an interface (or perhaps several) using an ioctl call.  You
-would issue more ioctls to the device to communicate to it using
-control, bulk, or other kinds of USB transfers.  The IOCTLs are
-listed in the <linux/usbdevice_fs.h> file, and at this writing the
-source code (linux/drivers/usb/core/devio.c) is the primary reference
-for how to access devices through those files.
-
-Note that since by default these BBB/DDD files are writable only by
-root, only root can write such user mode drivers.  You can selectively
-grant read/write permissions to other users by using "chmod".  Also,
-usbfs mount options such as "devmode=0666" may be helpful.
-
-
-
-THE /proc/bus/usb/devices FILE:
--------------------------------
-In /proc/bus/usb/devices, each device's output has multiple
-lines of ASCII output.
-I made it ASCII instead of binary on purpose, so that someone
-can obtain some useful data from it without the use of an
-auxiliary program.  However, with an auxiliary program, the numbers
-in the first 4 columns of each "T:" line (topology info:
-Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
-
-Each line is tagged with a one-character ID for that line:
-
-T = Topology (etc.)
-B = Bandwidth (applies only to USB host controllers, which are
-    virtualized as root hubs)
-D = Device descriptor info.
-P = Product ID info. (from Device descriptor, but they won't fit
-    together on one line)
-S = String descriptors.
-C = Configuration descriptor info. (* = active configuration)
-I = Interface descriptor info.
-E = Endpoint descriptor info.
-
-=======================================================================
-
-/proc/bus/usb/devices output format:
-
-Legend:
-  d = decimal number (may have leading spaces or 0's)
-  x = hexadecimal number (may have leading spaces or 0's)
-  s = string
-
-
-Topology info:
-
-T:  Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=dddd MxCh=dd
-|   |      |      |       |       |      |        |        |__MaxChildren
-|   |      |      |       |       |      |        |__Device Speed in Mbps
-|   |      |      |       |       |      |__DeviceNumber
-|   |      |      |       |       |__Count of devices at this level
-|   |      |      |       |__Connector/Port on Parent for this device
-|   |      |      |__Parent DeviceNumber
-|   |      |__Level in topology for this bus
-|   |__Bus number
-|__Topology info tag
-
-    Speed may be:
-    	1.5	Mbit/s for low speed USB
-	12	Mbit/s for full speed USB
-	480	Mbit/s for high speed USB (added for USB 2.0);
-		  also used for Wireless USB, which has no fixed speed
-	5000	Mbit/s for SuperSpeed USB (added for USB 3.0)
-
-    For reasons lost in the mists of time, the Port number is always
-    too low by 1.  For example, a device plugged into port 4 will
-    show up with "Port=03".
-
-Bandwidth info:
-B:  Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd
-|   |                       |         |__Number of isochronous requests
-|   |                       |__Number of interrupt requests
-|   |__Total Bandwidth allocated to this bus
-|__Bandwidth info tag
-
-    Bandwidth allocation is an approximation of how much of one frame
-    (millisecond) is in use.  It reflects only periodic transfers, which
-    are the only transfers that reserve bandwidth.  Control and bulk
-    transfers use all other bandwidth, including reserved bandwidth that
-    is not used for transfers (such as for short packets).
-
-    The percentage is how much of the "reserved" bandwidth is scheduled by
-    those transfers.  For a low or full speed bus (loosely, "USB 1.1"),
-    90% of the bus bandwidth is reserved.  For a high speed bus (loosely,
-    "USB 2.0") 80% is reserved.
-
-
-Device descriptor info & Product ID info:
-
-D:  Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
-P:  Vendor=xxxx ProdID=xxxx Rev=xx.xx
-
-where
-D:  Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
-|   |        |             |      |       |       |__NumberConfigurations
-|   |        |             |      |       |__MaxPacketSize of Default Endpoint
-|   |        |             |      |__DeviceProtocol
-|   |        |             |__DeviceSubClass
-|   |        |__DeviceClass
-|   |__Device USB version
-|__Device info tag #1
-
-where
-P:  Vendor=xxxx ProdID=xxxx Rev=xx.xx
-|   |           |           |__Product revision number
-|   |           |__Product ID code
-|   |__Vendor ID code
-|__Device info tag #2
-
-
-String descriptor info:
-
-S:  Manufacturer=ssss
-|   |__Manufacturer of this device as read from the device.
-|      For USB host controller drivers (virtual root hubs) this may
-|      be omitted, or (for newer drivers) will identify the kernel
-|      version and the driver which provides this hub emulation.
-|__String info tag
-
-S:  Product=ssss
-|   |__Product description of this device as read from the device.
-|      For older USB host controller drivers (virtual root hubs) this
-|      indicates the driver; for newer ones, it's a product (and vendor)
-|      description that often comes from the kernel's PCI ID database.
-|__String info tag
-
-S:  SerialNumber=ssss
-|   |__Serial Number of this device as read from the device.
-|      For USB host controller drivers (virtual root hubs) this is
-|      some unique ID, normally a bus ID (address or slot name) that
-|      can't be shared with any other device.
-|__String info tag
-
-
-
-Configuration descriptor info:
-
-C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA
-| | |       |       |      |__MaxPower in mA
-| | |       |       |__Attributes
-| | |       |__ConfiguratioNumber
-| | |__NumberOfInterfaces
-| |__ "*" indicates the active configuration (others are " ")
-|__Config info tag
-
-    USB devices may have multiple configurations, each of which act
-    rather differently.  For example, a bus-powered configuration
-    might be much less capable than one that is self-powered.  Only
-    one device configuration can be active at a time; most devices
-    have only one configuration.
-
-    Each configuration consists of one or more interfaces.  Each
-    interface serves a distinct "function", which is typically bound
-    to a different USB device driver.  One common example is a USB
-    speaker with an audio interface for playback, and a HID interface
-    for use with software volume control.
-
-
-Interface descriptor info (can be multiple per Config):
-
-I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss
-| | |      |      |       |             |      |       |__Driver name
-| | |      |      |       |             |      |          or "(none)"
-| | |      |      |       |             |      |__InterfaceProtocol
-| | |      |      |       |             |__InterfaceSubClass
-| | |      |      |       |__InterfaceClass
-| | |      |      |__NumberOfEndpoints
-| | |      |__AlternateSettingNumber
-| | |__InterfaceNumber
-| |__ "*" indicates the active altsetting (others are " ")
-|__Interface info tag
-
-    A given interface may have one or more "alternate" settings.
-    For example, default settings may not use more than a small
-    amount of periodic bandwidth.  To use significant fractions
-    of bus bandwidth, drivers must select a non-default altsetting.
-
-    Only one setting for an interface may be active at a time, and
-    only one driver may bind to an interface at a time.  Most devices
-    have only one alternate setting per interface.
-
-
-Endpoint descriptor info (can be multiple per Interface):
-
-E:  Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss
-|   |        |            |         |__Interval (max) between transfers
-|   |        |            |__EndpointMaxPacketSize
-|   |        |__Attributes(EndpointType)
-|   |__EndpointAddress(I=In,O=Out)
-|__Endpoint info tag
-
-    The interval is nonzero for all periodic (interrupt or isochronous)
-    endpoints.  For high speed endpoints the transfer interval may be
-    measured in microseconds rather than milliseconds.
-
-    For high speed periodic endpoints, the "MaxPacketSize" reflects
-    the per-microframe data transfer size.  For "high bandwidth"
-    endpoints, that can reflect two or three packets (for up to
-    3KBytes every 125 usec) per endpoint.
-
-    With the Linux-USB stack, periodic bandwidth reservations use the
-    transfer intervals and sizes provided by URBs, which can be less
-    than those found in endpoint descriptor.
-
-
-=======================================================================
-
-
-If a user or script is interested only in Topology info, for
-example, use something like "grep ^T: /proc/bus/usb/devices"
-for only the Topology lines.  A command like
-"grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list
-only the lines that begin with the characters in square brackets,
-where the valid characters are TDPCIE.  With a slightly more able
-script, it can display any selected lines (for example, only T, D,
-and P lines) and change their output format.  (The "procusb"
-Perl script is the beginning of this idea.  It will list only
-selected lines [selected from TBDPSCIE] or "All" lines from
-/proc/bus/usb/devices.)
-
-The Topology lines can be used to generate a graphic/pictorial
-of the USB devices on a system's root hub.  (See more below
-on how to do this.)
-
-The Interface lines can be used to determine what driver is
-being used for each device, and which altsetting it activated.
-
-The Configuration lines could be used to list maximum power
-(in milliamps) that a system's USB devices are using.
-For example, "grep ^C: /proc/bus/usb/devices".
-
-
-Here's an example, from a system which has a UHCI root hub,
-an external hub connected to the root hub, and a mouse and
-a serial converter connected to the external hub.
-
-T:  Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12   MxCh= 2
-B:  Alloc= 28/900 us ( 3%), #Int=  2, #Iso=  0
-D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
-P:  Vendor=0000 ProdID=0000 Rev= 0.00
-S:  Product=USB UHCI Root Hub
-S:  SerialNumber=dce0
-C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr=  0mA
-I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
-E:  Ad=81(I) Atr=03(Int.) MxPS=   8 Ivl=255ms
-
-T:  Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=12   MxCh= 4
-D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
-P:  Vendor=0451 ProdID=1446 Rev= 1.00
-C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
-I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
-E:  Ad=81(I) Atr=03(Int.) MxPS=   1 Ivl=255ms
-
-T:  Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#=  3 Spd=1.5  MxCh= 0
-D:  Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
-P:  Vendor=04b4 ProdID=0001 Rev= 0.00
-C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
-I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=01 Prot=02 Driver=mouse
-E:  Ad=81(I) Atr=03(Int.) MxPS=   3 Ivl= 10ms
-
-T:  Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#=  4 Spd=12   MxCh= 0
-D:  Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
-P:  Vendor=0565 ProdID=0001 Rev= 1.08
-S:  Manufacturer=Peracom Networks, Inc.
-S:  Product=Peracom USB to Serial Converter
-C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
-I:  If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
-E:  Ad=81(I) Atr=02(Bulk) MxPS=  64 Ivl= 16ms
-E:  Ad=01(O) Atr=02(Bulk) MxPS=  16 Ivl= 16ms
-E:  Ad=82(I) Atr=03(Int.) MxPS=   8 Ivl=  8ms
-
-
-Selecting only the "T:" and "I:" lines from this (for example, by using
-"procusb ti"), we have:
-
-T:  Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12   MxCh= 2
-T:  Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=12   MxCh= 4
-I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
-T:  Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#=  3 Spd=1.5  MxCh= 0
-I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=01 Prot=02 Driver=mouse
-T:  Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#=  4 Spd=12   MxCh= 0
-I:  If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
-
-
-Physically this looks like (or could be converted to):
-
-                      +------------------+
-                      |  PC/root_hub (12)|   Dev# = 1
-                      +------------------+   (nn) is Mbps.
-    Level 0           |  CN.0   |  CN.1  |   [CN = connector/port #]
-                      +------------------+
-                          /
-                         /
-            +-----------------------+
-  Level 1   | Dev#2: 4-port hub (12)|
-            +-----------------------+
-            |CN.0 |CN.1 |CN.2 |CN.3 |
-            +-----------------------+
-                \           \____________________
-                 \_____                          \
-                       \                          \
-               +--------------------+      +--------------------+
-  Level 2      | Dev# 3: mouse (1.5)|      | Dev# 4: serial (12)|
-               +--------------------+      +--------------------+
-
-
-
-Or, in a more tree-like structure (ports [Connectors] without
-connections could be omitted):
-
-PC:  Dev# 1, root hub, 2 ports, 12 Mbps
-|_ CN.0:  Dev# 2, hub, 4 ports, 12 Mbps
-     |_ CN.0:  Dev #3, mouse, 1.5 Mbps
-     |_ CN.1:
-     |_ CN.2:  Dev #4, serial, 12 Mbps
-     |_ CN.3:
-|_ CN.1:
-
-
-                         ### END ###