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 recei