Convert USB documentation to ReST format

index 909a73065e0a..6848f0a26fa5 100755
@@ -7,13 +7,22 @@
 # fix \_
 # title line?
 #
+set -eu
+
+if [ "$#" != "2" ]; then
+	echo "$0 <docbook file> <rst file>"
+	exit
+fi
+
+DIR=$(dirname $0)
 
 in=$1
 rst=$2
 tmp=$rst.tmp
 
 cp $in $tmp
-sed --in-place -f convert_template.sed $tmp
+sed --in-place -f $DIR/convert_template.sed $tmp
 pandoc -s -S -f docbook -t rst -o $rst $tmp
-sed --in-place -f post_convert.sed $rst
+sed --in-place -f $DIR/post_convert.sed $rst
 rm $tmp
+echo "book writen to $rst"

index 935b9b8d456c..472e7a664d13 100644
@@ -7,6 +7,12 @@ Driver Entry and Exit points
 .. kernel-doc:: include/linux/init.h
    :internal:
 
+Driver device table
+-------------------
+
+.. kernel-doc:: include/linux/mod_devicetable.h
+   :internal:
+
 Atomic and pointer manipulation
 -------------------------------
 

index 4a81e7a78e23..13056d40e11b 100644
@@ -8,12 +8,11 @@
 
 DOCBOOKS := z8530book.xml  \
 	    kernel-hacking.xml kernel-locking.xml \
-	    writing_usb_driver.xml networking.xml \
+	    networking.xml \
 	    filesystems.xml lsm.xml kgdb.xml \
-	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
+	    libata.xml mtdnand.xml librs.xml rapidio.xml \
 	    s390-drivers.xml scsi.xml \
-	    sh.xml w1.xml \
-	    writing_musb_glue_layer.xml
+	    sh.xml w1.xml
 
 ifeq ($(DOCBOOKS),)
 

793 lines not on this page · raw message

873 lines not on this page · raw message

412 lines not on this page · raw message

index 585982e36b3d..8058a87c1c74 100644
@@ -26,7 +26,7 @@ available subsections can be seen below.
    regulator
    iio/index
    input
-   usb
+   usb/index
    pci
    spi
    i2c

533 lines not on this page · raw message

new file mode 100644
index 000000000000..cf2fa2e8d236
@@ -0,0 +1,17 @@
+=============
+Linux USB API
+=============
+
+.. toctree::
+
+   usb
+   gadget
+   writing_usb_driver
+   writing_musb_glue_layer
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`

251 lines not on this page · raw message

98 lines not on this page · raw message

344 lines not on this page · raw message

index b856abb3200e..7e820768ee4f 100644
@@ -102,6 +102,8 @@ disconnect testing (while the device is active) with each different host
 controller driver, to make sure drivers don't have bugs of their own as
 well as to make sure they aren't relying on some HCD-specific behavior.
 
+.. _usb_chapter9:
+
 USB-Standard Types
 ==================
 

@@ -112,6 +114,8 @@ USB, and in APIs including this host side API, gadget APIs, and usbfs.
 .. kernel-doc:: include/linux/usb/ch9.h
    :internal:
 
+.. _usb_header:
+
 Host-Side Data Types and Macros
 ===============================
 

@@ -209,7 +213,7 @@ library that wraps it. Such libraries include
 `libusb <http://libusb.sourceforge.net>`__ for C/C++, and
 `jUSB <http://jUSB.sourceforge.net>`__ for Java.
 
-    **Note**
+.. note::
 
     This particular documentation is incomplete, especially with respect
     to the asynchronous mode. As of kernel 2.5.66 the code and this

@@ -319,9 +323,7 @@ files. For information about the current format of this file, see the
 sources.
 
 This file, in combination with the poll() system call, can also be used
-to detect when devices are added or removed:
-
-::
+to detect when devices are added or removed::
 
     int fd;
     struct pollfd pfd;

@@ -407,9 +409,7 @@ The ioctl() Requests
 --------------------
 
 To use these ioctls, you need to include the following headers in your
-userspace program:
-
-::
+userspace program::
 
     #include <linux/usb.h>
     #include <linux/usbdevice_fs.h>

@@ -458,9 +458,7 @@ USBDEVFS_CLAIMINTERFACE
 
 USBDEVFS_CONNECTINFO
     Says whether the device is lowspeed. The ioctl parameter points to a
-    structure like this:
-
-    ::
+    structure like this::
 
 	struct usbdevfs_connectinfo {
 		unsigned int   devnum;

@@ -477,9 +475,7 @@ USBDEVFS_CONNECTINFO
 USBDEVFS_GETDRIVER
     Returns the name of the kernel driver bound to a given interface (a
     string). Parameter is a pointer to this structure, which is
-    modified:
-
-    ::
+    modified::
 
 	struct usbdevfs_getdriver {
 		unsigned int  interface;

@@ -490,9 +486,7 @@ USBDEVFS_GETDRIVER
 
 USBDEVFS_IOCTL
     Passes a request from userspace through to a kernel driver that has
-    an ioctl entry in the *struct usb_driver* it registered.
-
-    ::
+    an ioctl entry in the *struct usb_driver* it registered::
 
 	struct usbdevfs_ioctl {
 		int     ifno;

@@ -534,7 +528,7 @@ USBDEVFS_RELEASEINTERFACE
     the number of the interface (bInterfaceNumber from descriptor); File
     modification time is not updated by this request.
 
-	**Warning**
+.. warning::
 
 	*No security check is made to ensure that the task which made
 	the claim is the one which is releasing it. This means that user

@@ -574,9 +568,7 @@ a time.
 
 USBDEVFS_BULK
     Issues a bulk read or write request to the device. The ioctl
-    parameter is a pointer to this structure:
-
-    ::
+    parameter is a pointer to this structure::
 
 	struct usbdevfs_bulktransfer {
 		unsigned int  ep;

@@ -606,9 +598,7 @@ USBDEVFS_CLEAR_HALT
 
 USBDEVFS_CONTROL
     Issues a control request to the device. The ioctl parameter points
-    to a structure like this:
-
-    ::
+    to a structure like this::
 
 	struct usbdevfs_ctrltransfer {
 		__u8   bRequestType;

@@ -638,7 +628,7 @@ USBDEVFS_RESET
     the reset, this rebinds all device interfaces. File modification
     time is not updated by this request.
 
-	**Warning**
+.. warning::
 
 	*Avoid using this call* until some usbcore bugs get fixed, since
 	it does not fully synchronize device, interface, and driver (not

@@ -646,9 +636,7 @@ USBDEVFS_RESET
 
 USBDEVFS_SETINTERFACE
     Sets the alternate setting for an interface. The ioctl parameter is
-    a pointer to a structure like this:
-
-    ::
+    a pointer to a structure like this::
 
 	struct usbdevfs_setinterface {
 		unsigned int  interface;

@@ -669,7 +657,7 @@ USBDEVFS_SETCONFIGURATION
     configuration (bConfigurationValue from descriptor). File
     modification time is not updated by this request.
 
-	**Warning**
+.. warning::
 
 	*Avoid using this call* until some usbcore bugs get fixed, since
 	it does not fully synchronize device, interface, and driver (not

@@ -702,9 +690,7 @@ When usbfs returns these urbs, the status value is updated, and the
 buffer may have been modified. Except for isochronous transfers, the
 actual_length is updated to say how many bytes were transferred; if the
 USBDEVFS_URB_DISABLE_SPD flag is set ("short packets are not OK"), if
-fewer bytes were read than were requested then you get an error report.
-
-::
+fewer bytes were read than were requested then you get an error report::
 
     struct usbdevfs_iso_packet_desc {
 	    unsigned int                     length;

index 52b299b1ca6d..3e8a3809c0b8 100644
@@ -38,7 +38,7 @@ address a number of important problems, including:
    resources.
 
 Most Linux developers will not be able to use this API, since they have
-USB "host" hardware in a PC, workstation, or server. Linux users with
+USB ``host`` hardware in a PC, workstation, or server. Linux users with
 embedded systems are more likely to have USB peripheral hardware. To
 distinguish drivers running inside such hardware from the more familiar
 Linux "USB device drivers", which are host side proxies for the real USB

@@ -64,7 +64,7 @@ Structure of Gadget Drivers
 
 A system running inside a USB peripheral normally has at least three
 layers inside the kernel to handle USB protocol processing, and may have
-additional layers in user space code. The "gadget" API is used by the
+additional layers in user space code. The ``gadget`` API is used by the
 middle layer to interact with the lowest level (which directly handles
 hardware).
 

@@ -143,13 +143,13 @@ In Linux, from the bottom up, these layers are:
 *Additional Layers*
     Other layers may exist. These could include kernel layers, such as
     network protocol stacks, as well as user mode applications building
-    on standard POSIX system call APIs such as *open()*, *close()*,
-    *read()* and *write()*. On newer systems, POSIX Async I/O calls may
+    on standard POSIX system call APIs such as ``open()``, ``close()``,
+    ``read()`` and ``write()``. On newer systems, POSIX Async I/O calls may
     be an option. Such user mode code will not necessarily be subject to
     the GNU General Public License (GPL).
 
 OTG-capable systems will also need to include a standard Linux-USB host
-side stack, with *usbcore*, one or more *Host Controller Drivers*
+side stack, with ``usbcore``, one or more *Host Controller Drivers*
 (HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral
 List", and so forth. There will also be an *OTG Controller Driver*,
 which is visible to gadget and device driver developers only indirectly.

@@ -174,24 +174,20 @@ combined, to implement composite devices.
 Kernel Mode Gadget API
 ======================
 
-Gadget drivers declare themselves through a *struct
-usb_gadget_driver*, which is responsible for most parts of enumeration
-for a *struct usb_gadget*. The response to a set_configuration usually
-involves enabling one or more of the *struct usb_ep* objects exposed by
-the gadget, and submitting one or more *struct usb_request* buffers to
+Gadget drivers declare themselves through a struct
+:c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration
+for a struct :c:type:`usb_gadget`. The response to a set_configuration usually
+involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by
+the gadget, and submitting one or more struct :c:type:`usb_request` buffers to
 transfer data. Understand those four data types, and their operations,
 and you will understand how this API works.
 
-    **Note**
+.. Note::
 
-    This documentation was prepared using the standard Linux kernel
-    ``docproc`` tool, which turns text and in-code comments into SGML
-    DocBook and then into usable formats such as HTML or PDF. Other than
-    the "Chapter 9" data types, most of the significant data types and
-    functions are described here.
+    Other than the "Chapter 9" data types, most of the significant data
+    types and functions are described here.
 
-    However, docproc does not understand all the C constructs that are
-    used, so some relevant information is likely omitted from what you
+    However, some relevant information is likely omitted from what you
     are reading. One example of such information is endpoint
     autoconfiguration. You'll have to read the header file, and use
     example source code (such as that for "Gadget Zero"), to fully

@@ -199,10 +195,10 @@ and you will understand how this API works.
 
     The part of the API implementing some basic driver capabilities is
     specific to the version of the Linux kernel that's in use. The 2.6
-    kernel includes a *driver model* framework that has no analogue on
-    earlier kernels; so those parts of the gadget API are not fully
-    portable. (They are implemented on 2.4 kernels, but in a different
-    way.) The driver model state is another part of this API that is
+    and upper kernel versions include a *driver model* framework that has
+    no analogue on earlier kernels; so those parts of the gadget API are
+    not fully portable. (They are implemented on 2.4 kernels, but in a
+    different way.) The driver model state is another part of this API that is
     ignored by the kerneldoc tools.
 
 The core API does not expose every possible hardware feature, only the

@@ -246,34 +242,34 @@ needs to handle some differences. Use the API like this:
 1. Register a driver for the particular device side usb controller
    hardware, such as the net2280 on PCI (USB 2.0), sa11x0 or pxa25x as
    found in Linux PDAs, and so on. At this point the device is logically
-   in the USB ch9 initial state ("attached"), drawing no power and not
+   in the USB ch9 initial state (``attached``), drawing no power and not
    usable (since it does not yet support enumeration). Any host should
    not see the device, since it's not activated the data line pullup
    used by the host to detect a device, even if VBUS power is available.
 
 2. Register a gadget driver that implements some higher level device
-   function. That will then bind() to a usb_gadget, which activates the
-   data line pullup sometime after detecting VBUS.
+   function. That will then bind() to a :c:type:`usb_gadget`, which activates
+   the data line pullup sometime after detecting VBUS.
 
 3. The hardware driver can now start enumerating. The steps it handles
-   are to accept USB power and set_address requests. Other steps are
+   are to accept USB ``power`` and ``set_address`` requests. Other steps are
    handled by the gadget driver. If the gadget driver module is unloaded
    before the host starts to enumerate, steps before step 7 are skipped.
 
-4. The gadget driver's setup() call returns usb descriptors, based both
+4. The gadget driver's ``setup()`` call returns usb descriptors, based both
    on what the bus interface hardware provides and on the functionality
    being implemented. That can involve alternate settings or
    configurations, unless the hardware prevents such operation. For OTG
    devices, each configuration descriptor includes an OTG descriptor.
 
 5. The gadget driver handles the last step of enumeration, when the USB
-   host issues a set_configuration call. It enables all endpoints used
+   host issues a ``set_configuration`` call. It enables all endpoints used
    in that configuration, with all interfaces in their default settings.
    That involves using a list of the hardware's endpoints, enabling each
    endpoint according to its descriptor. It may also involve using
-   :c:func:`usb_gadget_vbus_draw()` to let more power be drawn
-   from VBUS, as allowed by that configuration. For OTG devices, setting
-   a configuration may also involve reporting HNP capabilities through a
+   ``usb_gadget_vbus_draw`` to let more power be drawn from VBUS, as
+   allowed by that configuration. For OTG devices, setting a
+   configuration may also involve reporting HNP capabilities through a
    user interface.
 
 6. Do real work and perform data transfers, possibly involving changes

@@ -300,22 +296,18 @@ built by integrating reusable components.
 Note that the lifecycle above can be slightly different for OTG devices.
 Other than providing an additional OTG descriptor in each configuration,
 only the HNP-related differences are particularly visible to driver
-code. They involve reporting requirements during the SET_CONFIGURATION
+code. They involve reporting requirements during the ``SET_CONFIGURATION``
 request, and the option to invoke HNP during some suspend callbacks.
-Also, SRP changes the semantics of :c:func:`usb_gadget_wakeup()`
-slightly.
+Also, SRP changes the semantics of ``usb_gadget_wakeup`` slightly.
 
 USB 2.0 Chapter 9 Types and Constants
 -------------------------------------
 
 Gadget drivers rely on common USB structures and constants defined in
-the ``<linux/usb/ch9.h>`` header file, which is standard in Linux 2.6
-kernels. These are the same types and constants used by host side
+the :ref:`linux/usb/ch9.h <usb_chapter9>` header file, which is standard in
+Linux 2.6+ kernels. These are the same types and constants used by host side
 drivers (and usbcore).
 
-.. kernel-doc:: include/linux/usb/ch9.h
-   :internal:
-
 Core Objects and Methods
 ------------------------
 

@@ -347,10 +339,10 @@ multi-configuration devices (also more than one function, but not
 necessarily sharing a given configuration). There is however an optional
 framework which makes it easier to reuse and combine functions.
 
-Devices using this framework provide a *struct usb_composite_driver*,
-which in turn provides one or more *struct usb_configuration*
-instances. Each such configuration includes at least one *struct
-usb_function*, which packages a user visible role such as "network
+Devices using this framework provide a struct :c:type:`usb_composite_driver`,
+which in turn provides one or more struct :c:type:`usb_configuration`
+instances. Each such configuration includes at least one struct
+:c:type:`usb_function`, which packages a user visible role such as "network
 link" or "mass storage device". Management functions may also exist,
 such as "Device Firmware Upgrade".
 

@@ -365,22 +357,7 @@ Composite Device Functions
 
 At this writing, a few of the current gadget drivers have been converted
 to this framework. Near-term plans include converting all of them,
-except for "gadgetfs".
-
-.. kernel-doc:: drivers/usb/gadget/function/f_acm.c
-   :export:
-
-.. kernel-doc:: drivers/usb/gadget/function/f_ecm.c
-   :export:
-
-.. kernel-doc:: drivers/usb/gadget/function/f_subset.c
-   :export:
-
-.. kernel-doc:: drivers/usb/gadget/function/f_obex.c
-   :export:
-
-.. kernel-doc:: drivers/usb/gadget/function/f_serial.c
-   :export:
+except for ``gadgetfs``.
 
 Peripheral Controller Drivers
 =============================

@@ -391,7 +368,7 @@ which supports USB 2.0 high speed and is based on PCI. This is the
 and 2.6; contact NetChip Technologies for development boards and product
 information.
 
-Other hardware working in the "gadget" framework includes: Intel's PXA
+Other hardware working in the ``gadget`` framework includes: Intel's PXA
 25x and IXP42x series processors (``pxa2xx_udc``), Toshiba TC86c001
 "Goku-S" (``goku_udc``), Renesas SH7705/7727 (``sh_udc``), MediaQ 11xx
 (``mq11xx_udc``), Hynix HMS30C7202 (``h7202_udc``), National 9303/4

@@ -422,7 +399,7 @@ Gadget Drivers
 In addition to *Gadget Zero* (used primarily for testing and development
 with drivers for usb controller hardware), other gadget drivers exist.
 
-There's an *ethernet* gadget driver, which implements one of the most
+There's an ``ethernet`` gadget driver, which implements one of the most
 useful *Communications Device Class* (CDC) models. One of the standards
 for cable modem interoperability even specifies the use of this ethernet
 model as one of two mandatory options. Gadgets using this code look to a

@@ -434,16 +411,16 @@ driver also implements a "good parts only" subset of CDC Ethernet. (That
 subset doesn't advertise itself as CDC Ethernet, to avoid creating
 problems.)
 
-Support for Microsoft's *RNDIS* protocol has been contributed by
+Support for Microsoft's ``RNDIS`` protocol has been contributed by
 Pengutronix and Auerswald GmbH. This is like CDC Ethernet, but it runs
 on more slightly USB hardware (but less than the CDC subset). However,
 its main claim to fame is being able to connect directly to recent
 versions of Windows, using drivers that Microsoft bundles and supports,
 making it much simpler to network with Windows.
 
-There is also support for user mode gadget drivers, using *gadgetfs*.
+There is also support for user mode gadget drivers, using ``gadgetfs``.
 This provides a *User Mode API* that presents each endpoint as a single
-file descriptor. I/O is done using normal *read()* and *read()* calls.
+file descriptor. I/O is done using normal ``read()`` and ``read()`` calls.
 Familiar tools like GDB and pthreads can be used to develop and debug
 user mode drivers, so that once a robust controller driver is available
 many applications for it won't require new kernel mode software. Linux

@@ -479,35 +456,35 @@ Systems need specialized hardware support to implement OTG, notably
 including a special *Mini-AB* jack and associated transceiver to support
 *Dual-Role* operation: they can act either as a host, using the standard
 Linux-USB host side driver stack, or as a peripheral, using this
-"gadget" framework. To do that, the system software relies on small
+``gadget`` framework. To do that, the system software relies on small
 additions to those programming interfaces, and on a new internal
 component (here called an "OTG Controller") affecting which driver stack
 connects to the OTG port. In each role, the system can re-use the
 existing pool of hardware-neutral drivers, layered on top of the
-controller driver interfaces (*usb_bus* or *usb_gadget*). Such drivers
-need at most minor changes, and most of the calls added to support OTG
-can also benefit non-OTG products.
+controller driver interfaces (:c:type:`usb_bus` or :c:type:`usb_gadget`).
+Such drivers need at most minor changes, and most of the calls added to
+support OTG can also benefit non-OTG products.
 
--  Gadget drivers test the *is_otg* flag, and use it to determine
+-  Gadget drivers test the ``is_otg`` flag, and use it to determine
    whether or not to include an OTG descriptor in each of their
    configurations.
 
 -  Gadget drivers may need changes to support the two new OTG protocols,
-   exposed in new gadget attributes such as *b_hnp_enable* flag. HNP
+   exposed in new gadget attributes such as ``b_hnp_enable`` flag. HNP
    support should be reported through a user interface (two LEDs could
    suffice), and is triggered in some cases when the host suspends the
    peripheral. SRP support can be user-initiated just like remote
    wakeup, probably by pressing the same button.
 
 -  On the host side, USB device drivers need to be taught to trigger HNP
-   at appropriate moments, using :c:func:`usb_suspend_device()`.
-   That also conserves battery power, which is useful even for non-OTG
+   at appropriate moments, using ``usb_suspend_device()``. That also
+   conserves battery power, which is useful even for non-OTG
    configurations.
 
 -  Also on the host side, a driver must support the OTG "Targeted
    Peripheral List". That's just a whitelist, used to reject peripherals
    not supported with a given Linux OTG host. *This whitelist is
-   product-specific; each product must modify ``otg_whitelist.h`` to
+   product-specific; each product must modify* ``otg_whitelist.h`` *to
    match its interoperability specification.*
 
    Non-OTG Linux hosts, like PCs and workstations, normally have some

@@ -520,8 +497,8 @@ can also benefit non-OTG products.
    been distributed, so driver bugs can't normally be fixed if they're
    found after shipment.
 
-Additional changes are needed below those hardware-neutral *usb_bus*
-and *usb_gadget* driver interfaces; those aren't discussed here in any
+Additional changes are needed below those hardware-neutral :c:type:`usb_bus`
+and :c:type:`usb_gadget` driver interfaces; those aren't discussed here in any
 detail. Those affect the hardware-specific code for each USB Host or
 Peripheral controller, and how the HCD initializes (since OTG can be
 active only on a single port). They also involve what may be called an

index c18dbd74152b..69f077dcdb78 100644
@@ -1,3 +1,5 @@
+.. _writing-usb-driver:
+
 ==========================
 Writing USB Device Drivers
 ==========================

@@ -48,25 +50,23 @@ The first thing a Linux USB driver needs to do is register itself with
 the Linux USB subsystem, giving it some information about which devices
 the driver supports and which functions to call when a device supported
 by the driver is inserted or removed from the system. All of this
-information is passed to the USB subsystem in the usb_driver structure.
-The skeleton driver declares a usb_driver as:
-
-::
+information is passed to the USB subsystem in the :c:type:`usb_driver`
+structure. The skeleton driver declares a :c:type:`usb_driver` as::
 
     static struct usb_driver skel_driver = {
-            .name        = "skeleton",
-            .probe       = skel_probe,
-            .disconnect  = skel_disconnect,
-            .fops        = &skel_fops,
-            .minor       = USB_SKEL_MINOR_BASE,
-            .id_table    = skel_table,
+	    .name        = "skeleton",
+	    .probe       = skel_probe,
+	    .disconnect  = skel_disconnect,
+	    .fops        = &skel_fops,
+	    .minor       = USB_SKEL_MINOR_BASE,
+	    .id_table    = skel_table,
     };
 
 
 The variable name is a string that describes the driver. It is used in
 informational messages printed to the system log. The probe and
 disconnect function pointers are called when a device that matches the
-information provided in the id_table variable is either seen or
+information provided in the ``id_table`` variable is either seen or
 removed.
 
 The fops and minor variables are optional. Most USB drivers hook into

@@ -76,78 +76,70 @@ subsystem, and any user-space interactions are provided through that
 interface. But for drivers that do not have a matching kernel subsystem,
 such as MP3 players or scanners, a method of interacting with user space
 is needed. The USB subsystem provides a way to register a minor device
-number and a set of file_operations function pointers that enable this
-user-space interaction. The skeleton driver needs this kind of
+number and a set of :c:type:`file_operations` function pointers that enable
+this user-space interaction. The skeleton driver needs this kind of
 interface, so it provides a minor starting number and a pointer to its
-file_operations functions.
+:c:type:`file_operations` functions.
 
-The USB driver is then registered with a call to usb_register, usually
-in the driver's init function, as shown here:
-
-::
+The USB driver is then registered with a call to :c:func:`usb_register`,
+usually in the driver's init function, as shown here::
 
     static int __init usb_skel_init(void)
     {
-            int result;
+	    int result;
 
-            /* register this driver with the USB subsystem */
-            result = usb_register(&skel_driver);
-            if (result < 0) {
-                    err("usb_register failed for the "__FILE__ "driver."
-                        "Error number %d", result);
-                    return -1;
-            }
+	    /* register this driver with the USB subsystem */
+	    result = usb_register(&skel_driver);
+	    if (result < 0) {
+		    err("usb_register failed for the "__FILE__ "driver."
+			"Error number %d", result);
+		    return -1;
+	    }
 
-            return 0;
+	    return 0;
     }
     module_init(usb_skel_init);
 
 
 When the driver is unloaded from the system, it needs to deregister
-itself with the USB subsystem. This is done with the usb_deregister
-function:
-
-::
+itself with the USB subsystem. This is done with the :c:func:`usb_deregister`
+function::
 
     static void __exit usb_skel_exit(void)
     {
-            /* deregister this driver with the USB subsystem */
-            usb_deregister(&skel_driver);
+	    /* deregister this driver with the USB subsystem */
+	    usb_deregister(&skel_driver);
     }
     module_exit(usb_skel_exit);
 
 
 To enable the linux-hotplug system to load the driver automatically when
-the device is plugged in, you need to create a MODULE_DEVICE_TABLE.
+the device is plugged in, you need to create a ``MODULE_DEVICE_TABLE``.
 The following code tells the hotplug scripts that this module supports a
-single device with a specific vendor and product ID:
-
-::
+single device with a specific vendor and product ID::
 
     /* table of devices that work with this driver */
     static struct usb_device_id skel_table [] = {
-            { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) },
-            { }                      /* Terminating entry */
+	    { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) },
+	    { }                      /* Terminating entry */
     };
     MODULE_DEVICE_TABLE (usb, skel_table);
 
 
-There are other macros that can be used in describing a usb_device_id
-for drivers that support a whole class of USB drivers. See usb.h for
-more information on this.
+There are other macros that can be used in describing a struct
+:c:type:`usb_device_id` for drivers that support a whole class of USB
+drivers. See :ref:`usb.h <usb_header>` for more information on this.
 
 Device operation
 ================
 
 When a device is plugged into the USB bus that matches the device ID
 pattern that your driver registered with the USB core, the probe
-function is called. The usb_device structure, interface number and the
-interface ID are passed to the function:
-
-::
+function is called. The :c:type:`usb_device` structure, interface number and
+the interface ID are passed to the function::
 
     static int skel_probe(struct usb_interface *interface,
-        const struct usb_device_id *id)
+	const struct usb_device_id *id)
 
 
 The driver now needs to verify that this device is actually one that it

@@ -166,16 +158,14 @@ any private data that has been allocated at this time and to shut down
 any pending urbs that are in the USB system.
 
 Now that the device is plugged into the system and the driver is bound
-to the device, any of the functions in the file_operations structure
+to the device, any of the functions in the :c:type:`file_operations` structure
 that were passed to the USB subsystem will be called from a user program
 trying to talk to the device. The first function called will be open, as
 the program tries to open the device for I/O. We increment our private
 usage count and save a pointer to our internal structure in the file
 structure. This is done so that future calls to file operations will
 enable the driver to determine which device the user is addressing. All
-of this is done with the following code:
-
-::
+of this is done with the following code::
 
     /* increment our usage count for the module */
     ++skel->open_count;

@@ -185,16 +175,14 @@ of this is done with the following code:
 
 
 After the open function is called, the read and write functions are
-called to receive and send data to the device. In the skel_write
+called to receive and send data to the device. In the ``skel_write``
 function, we receive a pointer to some data that the user wants to send
 to the device and the size of the data. The function determines how much
 data it can send to the device based on the size of the write urb it has
 created (this size depends on the size of the bulk out end point that
 the device has). Then it copies the data from user space to kernel
 space, points the urb to the data and submits the urb to the USB
-subsystem. This can be seen in the following code:
-
-::
+subsystem. This can be seen in the following code::
 
     /* we can only write as much as 1 urb will hold */
     bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count;

@@ -204,68 +192,64 @@ subsystem. This can be seen in the following code:
 
     /* set up our urb */
     usb_fill_bulk_urb(skel->write_urb,
-                      skel->dev,
-                      usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr),
-                      skel->write_urb->transfer_buffer,
-                      bytes_written,
-                      skel_write_bulk_callback,
-                      skel);
+		      skel->dev,
+		      usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr),
+		      skel->write_urb->transfer_buffer,
+		      bytes_written,
+		      skel_write_bulk_callback,
+		      skel);
 
     /* send the data out the bulk port */
     result = usb_submit_urb(skel->write_urb);
     if (result) {
-            err("Failed submitting write urb, error %d", result);
+	    err("Failed submitting write urb, error %d", result);
     }
 
 
 When the write urb is filled up with the proper information using the
-usb_fill_bulk_urb function, we point the urb's completion callback to
-call our own skel_write_bulk_callback function. This function is
+:c:func:`usb_fill_bulk_urb` function, we point the urb's completion callback
+to call our own ``skel_write_bulk_callback`` function. This function is
 called when the urb is finished by the USB subsystem. The callback
 function is called in interrupt context, so caution must be taken not to
 do very much processing at that time. Our implementation of
-skel_write_bulk_callback merely reports if the urb was completed
+``skel_write_bulk_callback`` merely reports if the urb was completed
 successfully or not and then returns.
 
 The read function works a bit differently from the write function in
 that we do not use an urb to transfer data from the device to the
-driver. Instead we call the usb_bulk_msg function, which can be used
+driver. Instead we call the :c:func:`usb_bulk_msg` function, which can be used
 to send or receive data from a device without having to create urbs and
-handle urb completion callback functions. We call the usb_bulk_msg
+handle urb completion callback functions. We call the :c:func:`usb_bulk_msg`
 function, giving it a buffer into which to place any data received from
 the device and a timeout value. If the timeout period expires without
 receiving any data from the device, the function will fail and return an
-error message. This can be shown with the following code:
-
-::
+error message. This can be shown with the following code::
 
     /* do an immediate bulk read to get data from the device */
     retval = usb_bulk_msg (skel->dev,
-                           usb_rcvbulkpipe (skel->dev,
-                           skel->bulk_in_endpointAddr),
-                           skel->bulk_in_buffer,
-                           skel->bulk_in_size,
-                           &count, HZ*10);
+			   usb_rcvbulkpipe (skel->dev,
+			   skel->bulk_in_endpointAddr),
+			   skel->bulk_in_buffer,
+			   skel->bulk_in_size,
+			   &count, HZ*10);
     /* if the read was successful, copy the data to user space */
     if (!retval) {
-            if (copy_to_user (buffer, skel->bulk_in_buffer, count))
-                    retval = -EFAULT;
-            else
-                    retval = count;
+	    if (copy_to_user (buffer, skel->bulk_in_buffer, count))
+		    retval = -EFAULT;
+	    else
+		    retval = count;
     }
 
 
-The usb_bulk_msg function can be very useful for doing single reads or
-writes to a device; however, if you need to read or write constantly to
+The :c:func:`usb_bulk_msg` function can be very useful for doing single reads
+or writes to a device; however, if you need to read or write constantly to
 a device, it is recommended to set up your own urbs and submit them to
 the USB subsystem.
 
 When the user program releases the file handle that it has been using to
 talk to the device, the release function in the driver is called. In
 this function we decrement our private usage count and wait for possible
-pending writes:
-
-::
+pending writes::
 
     /* decrement our usage count for the device */
     --skel->open_count;

@@ -276,20 +260,18 @@ handle smoothly is the fact that the USB device may be removed from the
 system at any point in time, even if a program is currently talking to
 it. It needs to be able to shut down any current reads and writes and
 notify the user-space programs that the device is no longer there. The
-following code (function :c:func:`skel_delete()`) is an example of
-how to do this:
-
-::
+following code (function ``skel_delete``) is an example of how to do
+this::
 
     static inline void skel_delete (struct usb_skel *dev)
     {
-        kfree (dev->bulk_in_buffer);
-        if (dev->bulk_out_buffer != NULL)
-            usb_free_coherent (dev->udev, dev->bulk_out_size,
-                dev->bulk_out_buffer,
-                dev->write_urb->transfer_dma);
-        usb_free_urb (dev->write_urb);
-        kfree (dev);
+	kfree (dev->bulk_in_buffer);
+	if (dev->bulk_out_buffer != NULL)
+	    usb_free_coherent (dev->udev, dev->bulk_out_size,
+		dev->bulk_out_buffer,
+		dev->write_urb->transfer_dma);
+	usb_free_urb (dev->write_urb);
+	kfree (dev);
     }
 
 

@@ -297,10 +279,10 @@ If a program currently has an open handle to the device, we reset the
 flag ``device_present``. For every read, write, release and other
 functions that expect a device to be present, the driver first checks
 this flag to see if the device is still present. If not, it releases
-that the device has disappeared, and a -ENODEV error is returned to the
+that the device has disappeared, and a ``-ENODEV`` error is returned to the
 user-space program. When the release function is eventually called, it
 determines if there is no device and if not, it does the cleanup that
-the skel_disconnect function normally does if there are no open files
+the ``skel_disconnect`` function normally does if there are no open files
 on the device (see Listing 5).
 
 Isochronous Data

@@ -327,13 +309,13 @@ Resources
 =========
 
 The Linux USB Project:
-`http://www.linux-usb.org/ <http://www.linux-usb.org>`__
+http://www.linux-usb.org/
 
 Linux Hotplug Project:
-`http://linux-hotplug.sourceforge.net/ <http://linux-hotplug.sourceforge.net>`__
+http://linux-hotplug.sourceforge.net/
 
 Linux USB Working Devices List:
-`http://www.qbik.ch/usb/devices/ <http://www.qbik.ch/usb/devices>`__
+http://www.qbik.ch/usb/devices/
 
 linux-usb-devel Mailing List Archives:
 http://marc.theaimsgroup.com/?l=linux-usb-devel

index 52700c7031f9..e90e8fa95600 100644
@@ -1,6 +1,6 @@
-==========================
-Writing an MUSB Glue Layer
-==========================
+=========================
+Writing a MUSB Glue Layer
+=========================
 
 :Author: Apelete Seketeli
 

@@ -21,10 +21,12 @@ design.
 As a self-taught exercise I have written an MUSB glue layer for the
 Ingenic JZ4740 SoC, modelled after the many MUSB glue layers in the
 kernel source tree. This layer can be found at
-drivers/usb/musb/jz4740.c. In this documentation I will walk through the
-basics of the jz4740.c glue layer, explaining the different pieces and
+``drivers/usb/musb/jz4740.c``. In this documentation I will walk through the
+basics of the ``jz4740.c`` glue layer, explaining the different pieces and
 what needs to be done in order to write your own device glue layer.
 
+.. _musb-basics:
+
 Linux MUSB Basics
 =================
 

@@ -39,33 +41,30 @@ USB Device Drivers documentation (again, see Resources).
 
 Linux USB stack is a layered architecture in which the MUSB controller
 hardware sits at the lowest. The MUSB controller driver abstract the
-MUSB controller hardware to the Linux USB stack.
+MUSB controller hardware to the Linux USB stack::
 
-::
-
-          ------------------------
-          |                      | <------- drivers/usb/gadget
-          | Linux USB Core Stack | <------- drivers/usb/host
-          |                      | <------- drivers/usb/core
-          ------------------------
-                     ⬍
-         --------------------------
-         |                        | <------ drivers/usb/musb/musb_gadget.c
-         | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c
-         |                        | <------ drivers/usb/musb/musb_core.c
-         --------------------------
-                     ⬍
+	  ------------------------
+	  |                      | <------- drivers/usb/gadget
+	  | Linux USB Core Stack | <------- drivers/usb/host
+	  |                      | <------- drivers/usb/core
+	  ------------------------
+		     ⬍
+	 --------------------------
+	 |                        | <------ drivers/usb/musb/musb_gadget.c
+	 | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c
+	 |                        | <------ drivers/usb/musb/musb_core.c
+	 --------------------------
+		     ⬍
       ---------------------------------
       | MUSB Platform Specific Driver |
       |                               | <-- drivers/usb/musb/jz4740.c
       |       aka "Glue Layer"        |
       ---------------------------------
-                     ⬍
+		     ⬍
       ---------------------------------
       |   MUSB Controller Hardware    |
       ---------------------------------
 
-
 As outlined above, the glue layer is actually the platform specific code
 sitting in between the controller driver and the controller hardware.
 

@@ -78,37 +77,32 @@ about an embedded controller chip here, so no insertion or removal at
 run-time.
 
 All of this information is passed to the MUSB controller driver through
-a platform_driver structure defined in the glue layer as:
-
-::
+a :c:type:`platform_driver` structure defined in the glue layer as::
 
     static struct platform_driver jz4740_driver = {
-        .probe      = jz4740_probe,
-        .remove     = jz4740_remove,
-        .driver     = {
-            .name   = "musb-jz4740",
-        },
+	.probe      = jz4740_probe,
+	.remove     = jz4740_remove,
+	.driver     = {
+	    .name   = "musb-jz4740",
+	},
     };
 
-
 The probe and remove function pointers are called when a matching device
 is detected and, respectively, released. The name string describes the
 device supported by this glue layer. In the current case it matches a
-platform_device structure declared in arch/mips/jz4740/platform.c. Note
+platform_device structure declared in ``arch/mips/jz4740/platform.c``. Note
 that we are not using device tree bindings here.
 
 In order to register itself to the controller driver, the glue layer
 goes through a few steps, basically allocating the controller hardware
 resources and initialising a couple of circuits. To do so, it needs to
 keep track of the information used throughout these steps. This is done
-by defining a private jz4740_glue structure:
-
-::
+by defining a private ``jz4740_glue`` structure::
 
     struct jz4740_glue {
-        struct device           *dev;
-        struct platform_device  *musb;
-        struct clk      *clk;
+	struct device           *dev;
+	struct platform_device  *musb;
+	struct clk      *clk;
     };
 
 

@@ -121,121 +115,122 @@ information related to the device clock operation.
 Let's go through the steps of the probe function that leads the glue
 layer to register itself to the controller driver.
 
-N.B.: For the sake of readability each function will be split in logical
-parts, each part being shown as if it was independent from the others.
+.. note::
 
-::
+   For the sake of readability each function will be split in logical
+   parts, each part being shown as if it was independent from the others.
+
+.. code-block:: c
+    :emphasize-lines: 8,12,18
 
     static int jz4740_probe(struct platform_device *pdev)
     {
-        struct platform_device      *musb;
-        struct jz4740_glue      *glue;
-        struct clk                      *clk;
-        int             ret;
+	struct platform_device      *musb;
+	struct jz4740_glue      *glue;
+	struct clk                      *clk;
+	int             ret;
 
-        glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL);
-        if (!glue)
-            return -ENOMEM;
+	glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL);
+	if (!glue)
+	    return -ENOMEM;
 
-        musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO);
-        if (!musb) {
-            dev_err(&pdev->dev, "failed to allocate musb device\n");
-            return -ENOMEM;
-        }
+	musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO);
+	if (!musb) {
+	    dev_err(&pdev->dev, "failed to allocate musb device\n");
+	    return -ENOMEM;
+	}
 
-        clk = devm_clk_get(&pdev->dev, "udc");
-        if (IS_ERR(clk)) {
-            dev_err(&pdev->dev, "failed to get clock\n");
-            ret = PTR_ERR(clk);
-            goto err_platform_device_put;
-        }
+	clk = devm_clk_get(&pdev->dev, "udc");
+	if (IS_ERR(clk)) {
+	    dev_err(&pdev->dev, "failed to get clock\n");
+	    ret = PTR_ERR(clk);
+	    goto err_platform_device_put;
+	}
 
-        ret = clk_prepare_enable(clk);
-        if (ret) {
-            dev_err(&pdev->dev, "failed to enable clock\n");
-            goto err_platform_device_put;
-        }
+	ret = clk_prepare_enable(clk);
+	if (ret) {
+	    dev_err(&pdev->dev, "failed to enable clock\n");
+	    goto err_platform_device_put;
+	}
 
-        musb->dev.parent        = &pdev->dev;
+	musb->dev.parent        = &pdev->dev;
 
-        glue->dev           = &pdev->dev;
-        glue->musb          = musb;
-        glue->clk           = clk;
+	glue->dev           = &pdev->dev;
+	glue->musb          = musb;
+	glue->clk           = clk;
 
-        return 0;
+	return 0;
 
     err_platform_device_put:
-        platform_device_put(musb);
-        return ret;
+	platform_device_put(musb);
+	return ret;
     }
 
-
 The first few lines of the probe function allocate and assign the glue,
-musb and clk variables. The GFP_KERNEL flag (line 8) allows the
+musb and clk variables. The ``GFP_KERNEL`` flag (line 8) allows the
 allocation process to sleep and wait for memory, thus being usable in a
-blocking situation. The PLATFORM_DEVID_AUTO flag (line 12) allows
+locking situation. The ``PLATFORM_DEVID_AUTO`` flag (line 12) allows
 automatic allocation and management of device IDs in order to avoid
-device namespace collisions with explicit IDs. With devm_clk_get()
+device namespace collisions with explicit IDs. With :c:func:`devm_clk_get`
 (line 18) the glue layer allocates the clock -- the ``devm_`` prefix
-indicates that clk_get() is managed: it automatically frees the
+indicates that :c:func:`clk_get` is managed: it automatically frees the
 allocated clock resource data when the device is released -- and enable
 it.
 
+
+
 Then comes the registration steps:
 
-::
+.. code-block:: c
+    :emphasize-lines: 3,5,7,9,16
 
     static int jz4740_probe(struct platform_device *pdev)
     {
-        struct musb_hdrc_platform_data  *pdata = &jz4740_musb_platform_data;
+	struct musb_hdrc_platform_data  *pdata = &jz4740_musb_platform_data;
 
-        pdata->platform_ops     = &jz4740_musb_ops;
+	pdata->platform_ops     = &jz4740_musb_ops;
 
-        platform_set_drvdata(pdev, glue);
+	platform_set_drvdata(pdev, glue);
 
-        ret = platform_device_add_resources(musb, pdev->resource,
-                            pdev->num_resources);
-        if (ret) {
-            dev_err(&pdev->dev, "failed to add resources\n");
-            goto err_clk_disable;
-        }
+	ret = platform_device_add_resources(musb, pdev->resource,
+			    pdev->num_resources);
+	if (ret) {
+	    dev_err(&pdev->dev, "failed to add resources\n");
+	    goto err_clk_disable;
+	}
 
-        ret = platform_device_add_data(musb, pdata, sizeof(*pdata));
-        if (ret) {
-            dev_err(&pdev->dev, "failed to add platform_data\n");
-            goto err_clk_disable;
-        }
+	ret = platform_device_add_data(musb, pdata, sizeof(*pdata));
+	if (ret) {
+	    dev_err(&pdev->dev, "failed to add platform_data\n");
+	    goto err_clk_disable;
+	}
 
-        return 0;
+	return 0;
 
     err_clk_disable:
-        clk_disable_unprepare(clk);
+	clk_disable_unprepare(clk);
     err_platform_device_put:
-        platform_device_put(musb);
-        return ret;
+	platform_device_put(musb);
+	return ret;
     }
 
-
 The first step is to pass the device data privately held by the glue
-layer on to the controller driver through platform_set_drvdata() (line
-7). Next is passing on the device resources information, also privately
-held at that point, through platform_device_add_resources() (line 9).
+layer on to the controller driver through :c:func:`platform_set_drvdata`
+(line 7). Next is passing on the device resources information, also privately
+held at that point, through :c:func:`platform_device_add_resources` (line 9).
 
 Finally comes passing on the platform specific data to the controller
-driver (line 16). Platform data will be discussed in `Chapter
-4 <#device-platform-data>`__, but here we are looking at the
-platform_ops function pointer (line 5) in musb_hdrc_platform_data
+driver (line 16). Platform data will be discussed in
+:ref:`musb-dev-platform-data`, but here we are looking at the
+``platform_ops`` function pointer (line 5) in ``musb_hdrc_platform_data``
 structure (line 3). This function pointer allows the MUSB controller
-driver to know which function to call for device operation:
-
-::
+driver to know which function to call for device operation::
 
     static const struct musb_platform_ops jz4740_musb_ops = {
-        .init       = jz4740_musb_init,
-        .exit       = jz4740_musb_exit,
+	.init       = jz4740_musb_init,
+	.exit       = jz4740_musb_exit,
     };
 
-
 Here we have the minimal case where only init and exit functions are
 called by the controller driver when needed. Fact is the JZ4740 MUSB
 controller is a basic controller, lacking some features found in other

@@ -246,51 +241,48 @@ between OTG and non-OTG modes, for instance.
 At that point of the registration process, the controller driver
 actually calls the init function:
 
-::
+   .. code-block:: c
+    :emphasize-lines: 12,14
 
     static int jz4740_musb_init(struct musb *musb)
     {
-        musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
-        if (!musb->xceiv) {
-            pr_err("HS UDC: no transceiver configured\n");
-            return -ENODEV;
-        }
+	musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
+	if (!musb->xceiv) {
+	    pr_err("HS UDC: no transceiver configured\n");
+	    return -ENODEV;
+	}
 
-        /* Silicon does not implement ConfigData register.
-         * Set dyn_fifo to avoid reading EP config from hardware.
-         */
-        musb->dyn_fifo = true;
+	/* Silicon does not implement ConfigData register.
+	 * Set dyn_fifo to avoid reading EP config from hardware.
+	 */
+	musb->dyn_fifo = true;
 
-        musb->isr = jz4740_musb_interrupt;
+	musb->isr = jz4740_musb_interrupt;
 
-        return 0;
+	return 0;
     }
 
-
-The goal of jz4740_musb_init() is to get hold of the transceiver
+The goal of ``jz4740_musb_init()`` is to get hold of the transceiver
 driver data of the MUSB controller hardware and pass it on to the MUSB
 controller driver, as usual. The transceiver is the circuitry inside the
 controller hardware responsible for sending/receiving the USB data.
 Since it is an implementation of the physical layer of the OSI model,
 the transceiver is also referred to as PHY.
 
-Getting hold of the MUSB PHY driver data is done with usb_get_phy()
+Getting hold of the ``MUSB PHY`` driver data is done with ``usb_get_phy()``
 which returns a pointer to the structure containing the driver instance
 data. The next couple of instructions (line 12 and 14) are used as a
 quirk and to setup IRQ handling respectively. Quirks and IRQ handling
-will be discussed later in `Chapter 5 <#device-quirks>`__ and `Chapter
-3 <#handling-irqs>`__.
-
-::
+will be discussed later in :ref:`musb-dev-quirks` and
+:ref:`musb-handling-irqs`\ ::
 
     static int jz4740_musb_exit(struct musb *musb)
     {
-        usb_put_phy(musb->xceiv);
+	usb_put_phy(musb->xceiv);
 
-        return 0;
+	return 0;
     }
 
-
 Acting as the counterpart of init, the exit function releases the MUSB
 PHY driver when the controller hardware itself is about to be released.
 

@@ -300,133 +292,130 @@ musb glue layer for a more complex controller hardware, you might need
 to take care of more processing in those two functions.
 
 Returning from the init function, the MUSB controller driver jumps back
-into the probe function:
-
-::
+into the probe function::
 
     static int jz4740_probe(struct platform_device *pdev)
     {
-        ret = platform_device_add(musb);
-        if (ret) {
-            dev_err(&pdev->dev, "failed to register musb device\n");
-            goto err_clk_disable;
-        }
+	ret = platform_device_add(musb);
+	if (ret) {
+	    dev_err(&pdev->dev, "failed to register musb device\n");
+	    goto err_clk_disable;
+	}
 
-        return 0;
+	return 0;
 
     err_clk_disable:
-        clk_disable_unprepare(clk);
+	clk_disable_unprepare(clk);
     err_platform_device_put:
-        platform_device_put(musb);
-        return ret;
+	platform_device_put(musb);
+	return ret;
     }
 
-
 This is the last part of the device registration process where the glue
 layer adds the controller hardware device to Linux kernel device
 hierarchy: at this stage, all known information about the device is
-passed on to the Linux USB core stack.
+passed on to the Linux USB core stack:
 
-::
+   .. code-block:: c
+    :emphasize-lines: 5,6
 
     static int jz4740_remove(struct platform_device *pdev)
     {
-        struct jz4740_glue  *glue = platform_get_drvdata(pdev);
+	struct jz4740_glue  *glue = platform_get_drvdata(pdev);
 
-        platform_device_unregister(glue->musb);
-        clk_disable_unprepare(glue->clk);
+	platform_device_unregister(glue->musb);
+	clk_disable_unprepare(glue->clk);
 
-        return 0;
+	return 0;
     }
 
-
 Acting as the counterpart of probe, the remove function unregister the
 MUSB controller hardware (line 5) and disable the clock (line 6),
 allowing it to be gated.
 
+.. _musb-handling-irqs:
+
 Handling IRQs
 =============
 
 Additionally to the MUSB controller hardware basic setup and
 registration, the glue layer is also responsible for handling the IRQs:
 
-::
+   .. code-block:: c
+    :emphasize-lines: 7,9-11,14,24
 
     static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
     {
-        unsigned long   flags;
-        irqreturn_t     retval = IRQ_NONE;
-        struct musb     *musb = __hci;
+	unsigned long   flags;
+	irqreturn_t     retval = IRQ_NONE;
+	struct musb     *musb = __hci;
 
-        spin_lock_irqsave(&musb->lock, flags);
+	spin_lock_irqsave(&musb->lock, flags);
 
-        musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
-        musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
-        musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
+	musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
+	musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
+	musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
 
-        /*
-         * The controller is gadget only, the state of the host mode IRQ bits is
-         * undefined. Mask them to make sure that the musb driver core will
-         * never see them set
-         */
-        musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
-            MUSB_INTR_RESET | MUSB_INTR_SOF;
+	/*
+	 * The controller is gadget only, the state of the host mode IRQ bits is
+	 * undefined. Mask them to make sure that the musb driver core will
+	 * never see them set
+	 */
+	musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
+	    MUSB_INTR_RESET | MUSB_INTR_SOF;
 
-        if (musb->int_usb || musb->int_tx || musb->int_rx)
-            retval = musb_interrupt(musb);
+	if (musb->int_usb || musb->int_tx || musb->int_rx)
+	    retval = musb_interrupt(musb);
 
-        spin_unlock_irqrestore(&musb->lock, flags);
+	spin_unlock_irqrestore(&musb->lock, flags);
 
-        return retval;
+	return retval;
     }
 
-
 Here the glue layer mostly has to read the relevant hardware registers
 and pass their values on to the controller driver which will handle the
 actual event that triggered the IRQ.
 
 The interrupt handler critical section is protected by the
-spin_lock_irqsave() and counterpart spin_unlock_irqrestore()
+:c:func:`spin_lock_irqsave` and counterpart :c:func:`spin_unlock_irqrestore`
 functions (line 7 and 24 respectively), which prevent the interrupt
 handler code to be run by two different threads at the same time.
 
 Then the relevant interrupt registers are read (line 9 to 11):
 
--  MUSB_INTRUSB: indicates which USB interrupts are currently active,
+-  ``MUSB_INTRUSB``: indicates which USB interrupts are currently active,
 
--  MUSB_INTRTX: indicates which of the interrupts for TX endpoints are
+-  ``MUSB_INTRTX``: indicates which of the interrupts for TX endpoints are
    currently active,
 
--  MUSB_INTRRX: indicates which of the interrupts for TX endpoints are
+-  ``MUSB_INTRRX``: indicates which of the interrupts for TX endpoints are
    currently active.
 
-Note that musb_readb() is used to read 8-bit registers at most, while
-musb_readw() allows us to read at most 16-bit registers. There are
+Note that :c:func:`musb_readb` is used to read 8-bit registers at most, while
+:c:func:`musb_readw` allows us to read at most 16-bit registers. There are
 other functions that can be used depending on the size of your device
-registers. See musb_io.h for more information.
+registers. See ``musb_io.h`` for more information.
 
 Instruction on line 18 is another quirk specific to the JZ4740 USB
-device controller, which will be discussed later in `Chapter
-5 <#device-quirks>`__.
+device controller, which will be discussed later in :ref:`musb-dev-quirks`.
 
 The glue layer still needs to register the IRQ handler though. Remember
-the instruction on line 14 of the init function:
-
-::
+the instruction on line 14 of the init function::
 
     static int jz4740_musb_init(struct musb *musb)
     {
-        musb->isr = jz4740_musb_interrupt;
+	musb->isr = jz4740_musb_interrupt;
 
-        return 0;
+	return 0;
     }
 
-
 This instruction sets a pointer to the glue layer IRQ handler function,
 in order for the controller hardware to call the handler back when an
 IRQ comes from the controller hardware. The interrupt handler is now
 implemented and registered.
 
+.. _musb-dev-platform-data:
+
 Device Platform Data
 ====================
 

@@ -435,148 +424,149 @@ describing the hardware capabilities of your controller hardware, which
 is called the platform data.
 
 Platform data is specific to your hardware, though it may cover a broad
-range of devices, and is generally found somewhere in the arch/
+range of devices, and is generally found somewhere in the ``arch/``
 directory, depending on your device architecture.
 
 For instance, platform data for the JZ4740 SoC is found in
-arch/mips/jz4740/platform.c. In the platform.c file each device of the
+``arch/mips/jz4740/platform.c``. In the ``platform.c`` file each device of the
 JZ4740 SoC is described through a set of structures.
 
-Here is the part of arch/mips/jz4740/platform.c that covers the USB
+Here is the part of ``arch/mips/jz4740/platform.c`` that covers the USB
 Device Controller (UDC):
 
-::
+   .. code-block:: c
+    :emphasize-lines: 2,7,14-17,21,22,25,26,28,29
 
     /* USB Device Controller */
     struct platform_device jz4740_udc_xceiv_device = {
-        .name = "usb_phy_gen_xceiv",
-        .id   = 0,
+	.name = "usb_phy_gen_xceiv",
+	.id   = 0,
     };
 
     static struct resource jz4740_udc_resources[] = {
-        [0] = {
-            .start = JZ4740_UDC_BASE_ADDR,
-            .end   = JZ4740_UDC_BASE_ADDR + 0x10000 - 1,
-            .flags = IORESOURCE_MEM,
-        },
-        [1] = {
-            .start = JZ4740_IRQ_UDC,
-            .end   = JZ4740_IRQ_UDC,
-            .flags = IORESOURCE_IRQ,
-            .name  = "mc",
-        },
+	[0] = {
+	    .start = JZ4740_UDC_BASE_ADDR,
+	    .end   = JZ4740_UDC_BASE_ADDR + 0x10000 - 1,
+	    .flags = IORESOURCE_MEM,
+	},
+	[1] = {
+	    .start = JZ4740_IRQ_UDC,
+	    .end   = JZ4740_IRQ_UDC,
+	    .flags = IORESOURCE_IRQ,
+	    .name  = "mc",
+	},
     };
 
     struct platform_device jz4740_udc_device = {
-        .name = "musb-jz4740",
-        .id   = -1,
-        .dev  = {
-            .dma_mask          = &jz4740_udc_device.dev.coherent_dma_mask,
-            .coherent_dma_mask = DMA_BIT_MASK(32),
-        },
-        .num_resources = ARRAY_SIZE(jz4740_udc_resources),
-        .resource      = jz4740_udc_resources,
+	.name = "musb-jz4740",
+	.id   = -1,
+	.dev  = {
+	    .dma_mask          = &jz4740_udc_device.dev.coherent_dma_mask,
+	    .coherent_dma_mask = DMA_BIT_MASK(32),
+	},
+	.num_resources = ARRAY_SIZE(jz4740_udc_resources),
+	.resource      = jz4740_udc_resources,
     };
 
-
-The jz4740_udc_xceiv_device platform device structure (line 2)
+The ``jz4740_udc_xceiv_device`` platform device structure (line 2)
 describes the UDC transceiver with a name and id number.
 
-At the time of this writing, note that "usb_phy_gen_xceiv" is the
+At the time of this writing, note that ``usb_phy_gen_xceiv`` is the
 specific name to be used for all transceivers that are either built-in
 with reference USB IP or autonomous and doesn't require any PHY
-programming. You will need to set CONFIG_NOP_USB_XCEIV=y in the
+programming. You will need to set ``CONFIG_NOP_USB_XCEIV=y`` in the
 kernel configuration to make use of the corresponding transceiver
 driver. The id field could be set to -1 (equivalent to
-PLATFORM_DEVID_NONE), -2 (equivalent to PLATFORM_DEVID_AUTO) or
+``PLATFORM_DEVID_NONE``), -2 (equivalent to ``PLATFORM_DEVID_AUTO``) or
 start with 0 for the first device of this kind if we want a specific id
 number.
 
-The jz4740_udc_resources resource structure (line 7) defines the UDC
+The ``jz4740_udc_resources`` resource structure (line 7) defines the UDC
 registers base addresses.
 
 The first array (line 9 to 11) defines the UDC registers base memory
 addresses: start points to the first register memory address, end points
 to the last register memory address and the flags member defines the
-type of resource we are dealing with. So IORESOURCE_MEM is used to
+type of resource we are dealing with. So ``IORESOURCE_MEM`` is used to
 define the registers memory addresses. The second array (line 14 to 17)
 defines the UDC IRQ registers addresses. Since there is only one IRQ
 register available for the JZ4740 UDC, start and end point at the same
-address. The IORESOURCE_IRQ flag tells that we are dealing with IRQ
-resources, and the name "mc" is in fact hard-coded in the MUSB core in
+address. The ``IORESOURCE_IRQ`` flag tells that we are dealing with IRQ
+resources, and the name ``mc`` is in fact hard-coded in the MUSB core in
 order for the controller driver to retrieve this IRQ resource by
 querying it by its name.
 
-Finally, the jz4740_udc_device platform device structure (line 21)
+Finally, the ``jz4740_udc_device`` platform device structure (line 21)
 describes the UDC itself.
 
-The "musb-jz4740" name (line 22) defines the MUSB driver that is used
+The ``musb-jz4740`` name (line 22) defines the MUSB driver that is used
 for this device; remember this is in fact the name that we used in the
-jz4740_driver platform driver structure in `Chapter
-2 <#linux-musb-basics>`__. The id field (line 23) is set to -1
-(equivalent to PLATFORM_DEVID_NONE) since we do not need an id for the
-device: the MUSB controller driver was already set to allocate an
-automatic id in `Chapter 2 <#linux-musb-basics>`__. In the dev field we
-care for DMA related information here. The dma_mask field (line 25)
+``jz4740_driver`` platform driver structure in :ref:`musb-basics`.
+The id field (line 23) is set to -1 (equivalent to ``PLATFORM_DEVID_NONE``)
+since we do not need an id for the device: the MUSB controller driver was
+already set to allocate an automatic id in :ref:`musb-basics`. In the dev field
+we care for DMA related information here. The ``dma_mask`` field (line 25)
 defines the width of the DMA mask that is going to be used, and
-coherent_dma_mask (line 26) has the same purpose but for the
-alloc_coherent DMA mappings: in both cases we are using a 32 bits mask.
+``coherent_dma_mask`` (line 26) has the same purpose but for the
+``alloc_coherent`` DMA mappings: in both cases we are using a 32 bits mask.
 Then the resource field (line 29) is simply a pointer to the resource
-structure defined before, while the num_resources field (line 28) keeps
+structure defined before, while the ``num_resources`` field (line 28) keeps
 track of the number of arrays defined in the resource structure (in this
 case there were two resource arrays defined before).
 
-With this quick overview of the UDC platform data at the arch/ level now
+With this quick overview of the UDC platform data at the ``arch/`` level now
 done, let's get back to the MUSB glue layer specific platform data in
-drivers/usb/musb/jz4740.c:
+``drivers/usb/musb/jz4740.c``:
 
-::
+   .. code-block:: c
+    :emphasize-lines: 3,5,7-9,11
 
     static struct musb_hdrc_config jz4740_musb_config = {
-        /* Silicon does not implement USB OTG. */
-        .multipoint = 0,
-        /* Max EPs scanned, driver will decide which EP can be used. */
-        .num_eps    = 4,
-        /* RAMbits needed to configure EPs from table */
-        .ram_bits   = 9,
-        .fifo_cfg = jz4740_musb_fifo_cfg,
-        .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg),
+	/* Silicon does not implement USB OTG. */
+	.multipoint = 0,
+	/* Max EPs scanned, driver will decide which EP can be used. */
+	.num_eps    = 4,
+	/* RAMbits needed to configure EPs from table */
+	.ram_bits   = 9,
+	.fifo_cfg = jz4740_musb_fifo_cfg,
+	.fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg),
     };
 
     static struct musb_hdrc_platform_data jz4740_musb_platform_data = {
-        .mode   = MUSB_PERIPHERAL,
-        .config = &jz4740_musb_config,
+	.mode   = MUSB_PERIPHERAL,
+	.config = &jz4740_musb_config,
     };
 
-
 First the glue layer configures some aspects of the controller driver
 operation related to the controller hardware specifics. This is done
-through the jz4740_musb_config musb_hdrc_config structure.
+through the ``jz4740_musb_config`` :c:type:`musb_hdrc_config` structure.
 
 Defining the OTG capability of the controller hardware, the multipoint
 member (line 3) is set to 0 (equivalent to false) since the JZ4740 UDC
-is not OTG compatible. Then num_eps (line 5) defines the number of USB
+is not OTG compatible. Then ``num_eps`` (line 5) defines the number of USB
 endpoints of the controller hardware, including endpoint 0: here we have
-3 endpoints + endpoint 0. Next is ram_bits (line 7) which is the width
+3 endpoints + endpoint 0. Next is ``ram_bits`` (line 7) which is the width
 of the RAM address bus for the MUSB controller hardware. This
 information is needed when the controller driver cannot automatically
 configure endpoints by reading the relevant controller hardware
 registers. This issue will be discussed when we get to device quirks in
-`Chapter 5 <#device-quirks>`__. Last two fields (line 8 and 9) are also
-about device quirks: fifo_cfg points to the USB endpoints configuration
-table and fifo_cfg_size keeps track of the size of the number of
-entries in that configuration table. More on that later in `Chapter
-5 <#device-quirks>`__.
+:ref:`musb-dev-quirks`. Last two fields (line 8 and 9) are also
+about device quirks: ``fifo_cfg`` points to the USB endpoints configuration
+table and ``fifo_cfg_size`` keeps track of the size of the number of
+entries in that configuration table. More on that later in
+:ref:`musb-dev-quirks`.
 
-Then this configuration is embedded inside jz4740_musb_platform_data
-musb_hdrc_platform_data structure (line 11): config is a pointer to
+Then this configuration is embedded inside ``jz4740_musb_platform_data``
+:c:type:`musb_hdrc_platform_data` structure (line 11): config is a pointer to
 the configuration structure itself, and mode tells the controller driver
-if the controller hardware may be used as MUSB_HOST only,
-MUSB_PERIPHERAL only or MUSB_OTG which is a dual mode.
+if the controller hardware may be used as ``MUSB_HOST`` only,
+``MUSB_PERIPHERAL`` only or ``MUSB_OTG`` which is a dual mode.
 
-Remember that jz4740_musb_platform_data is then used to convey
+Remember that ``jz4740_musb_platform_data`` is then used to convey
 platform data information as we have seen in the probe function in
-`Chapter 2 <#linux-musb-basics>`__
+:ref:`musb-basics`.
+
+.. _musb-dev-quirks:
 
 Device Quirks
 =============

@@ -593,27 +583,27 @@ controller hardware you are working on.
 
 Let's get back to the init function first:
 
-::
+   .. code-block:: c
+    :emphasize-lines: 12
 
     static int jz4740_musb_init(struct musb *musb)
     {
-        musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
-        if (!musb->xceiv) {
-            pr_err("HS UDC: no transceiver configured\n");
-            return -ENODEV;
-        }
+	musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
+	if (!musb->xceiv) {
+	    pr_err("HS UDC: no transceiver configured\n");
+	    return -ENODEV;
+	}
 
-        /* Silicon does not implement ConfigData register.
-         * Set dyn_fifo to avoid reading EP config from hardware.
-         */
-        musb->dyn_fifo = true;
+	/* Silicon does not implement ConfigData register.
+	 * Set dyn_fifo to avoid reading EP config from hardware.
+	 */
+	musb->dyn_fifo = true;
 
-        musb->isr = jz4740_musb_interrupt;
+	musb->isr = jz4740_musb_interrupt;
 
-        return 0;
+	return 0;
     }
 
-
 Instruction on line 12 helps the MUSB controller driver to work around
 the fact that the controller hardware is missing registers that are used
 for USB endpoints configuration.

@@ -621,21 +611,18 @@ for USB endpoints configuration.
 Without these registers, the controller driver is unable to read the
 endpoints configuration from the hardware, so we use line 12 instruction
 to bypass reading the configuration from silicon, and rely on a
-hard-coded table that describes the endpoints configuration instead:
-
-::
+hard-coded table that describes the endpoints configuration instead::
 
     static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = {
-    { .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, },
-    { .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, },
-    { .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, },
+	{ .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, },
+	{ .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, },
+	{ .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, },
     };
 
-
 Looking at the configuration table above, we see that each endpoints is
-described by three fields: hw_ep_num is the endpoint number, style is
-its direction (either FIFO_TX for the controller driver to send packets
-in the controller hardware, or FIFO_RX to receive packets from
+described by three fields: ``hw_ep_num`` is the endpoint number, style is
+its direction (either ``FIFO_TX`` for the controller driver to send packets
+in the controller hardware, or ``FIFO_RX`` to receive packets from
 hardware), and maxpacket defines the maximum size of each data packet
 that can be transmitted over that endpoint. Reading from the table, the
 controller driver knows that endpoint 1 can be used to send and receive

@@ -646,48 +633,48 @@ at once (this is in fact an interrupt endpoint).
 Note that there is no information about endpoint 0 here: that one is
 implemented by default in every silicon design, with a predefined
 configuration according to the USB specification. For more examples of
-endpoint configuration tables, see musb_core.c.
+endpoint configuration tables, see ``musb_core.c``.
 
 Let's now get back to the interrupt handler function:
 
-::
+   .. code-block:: c
+    :emphasize-lines: 18-19
 
     static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
     {
-        unsigned long   flags;
-        irqreturn_t     retval = IRQ_NONE;
-        struct musb     *musb = __hci;
+	unsigned long   flags;
+	irqreturn_t     retval = IRQ_NONE;
+	struct musb     *musb = __hci;
 
-        spin_lock_irqsave(&musb->lock, flags);
+	spin_lock_irqsave(&musb->lock, flags);
 
-        musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
-        musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
-        musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
+	musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
+	musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
+	musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
 
-        /*
-         * The controller is gadget only, the state of the host mode IRQ bits is
-         * undefined. Mask them to make sure that the musb driver core will
-         * never see them set
-         */
-        musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
-            MUSB_INTR_RESET | MUSB_INTR_SOF;
+	/*
+	 * The controller is gadget only, the state of the host mode IRQ bits is
+	 * undefined. Mask them to make sure that the musb driver core will
+	 * never see them set
+	 */
+	musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
+	    MUSB_INTR_RESET | MUSB_INTR_SOF;
 
-        if (musb->int_usb || musb->int_tx || musb->int_rx)
-            retval = musb_interrupt(musb);
+	if (musb->int_usb || musb->int_tx || musb->int_rx)
+	    retval = musb_interrupt(musb);
 
-        spin_unlock_irqrestore(&musb->lock, flags);
+	spin_unlock_irqrestore(&musb->lock, flags);
 
-        return retval;
+	return retval;
     }
 
-
 Instruction on line 18 above is a way for the controller driver to work
 around the fact that some interrupt bits used for USB host mode
-operation are missing in the MUSB_INTRUSB register, thus left in an
+operation are missing in the ``MUSB_INTRUSB`` register, thus left in an
 undefined hardware state, since this MUSB controller hardware is used in
 peripheral mode only. As a consequence, the glue layer masks these
 missing bits out to avoid parasite interrupts by doing a logical AND
-operation between the value read from MUSB_INTRUSB and the bits that
+operation between the value read from ``MUSB_INTRUSB`` and the bits that
 are actually implemented in the register.
 
 These are only a couple of the quirks found in the JZ4740 USB device

@@ -727,8 +714,7 @@ linux-usb Mailing List Archives: http://marc.info/?l=linux-usb
 USB On-the-Go Basics:
 http://www.maximintegrated.com/app-notes/index.mvp/id/1822
 
-Writing USB Device Drivers:
-https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html
+:ref:`Writing USB Device Drivers <writing-usb-driver>`
 
 Texas Instruments USB Configuration Wiki Page:
 http://processors.wiki.ti.com/index.php/Usbgeneralpage

similarity index 75%
rename from Documentation/usb/anchors.txt
rename to Documentation/driver-api/usb/anchors.rst
index fe6a99a32bbd..4b248e691bd6 100644
@@ -1,3 +1,6 @@
+USB Anchors
+~~~~~~~~~~~
+
 What is anchor?
 ===============
 

@@ -13,7 +16,7 @@ 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
+as struct usb_anchor. :c:func:`init_usb_anchor` must be called to
 initialise the data structure.
 
 Deallocation

@@ -26,52 +29,53 @@ 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
+call to :c:func:`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()
+Furthermore, disassociation can be made with :c:func:`usb_unanchor_urb`
 
 Operations on multitudes of URBs
 ================================
 
-usb_kill_anchored_urbs()
-------------------------
+:c:func:`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()
---------------------------
+:c:func:`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.
+This is similar to :c:func:`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()
----------------------------
+:c:func:`usb_scuttle_anchored_urbs`
+-----------------------------------
 
 All URBs of an anchor are unanchored en masse.
 
-usb_wait_anchor_empty_timeout()
--------------------------------
+:c:func:`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()
-------------------
+:c:func:`usb_anchor_empty`
+--------------------------
 
 Returns true if no URBs are associated with an anchor. Locking
 is the caller's responsibility.
 
-usb_get_from_anchor()
----------------------
+:c:func:`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

index cf2fa2e8d236..5dfb04b2d730 100644
@@ -6,6 +6,7 @@ Linux USB API
 
    usb
    gadget
+   anchors
    writing_usb_driver
    writing_musb_glue_layer
 

similarity index 94%
rename from Documentation/usb/bulk-streams.txt
rename to Documentation/driver-api/usb/bulk-streams.rst
index ffc02021863e..99b515babdeb 100644
@@ -1,3 +1,6 @@
+USB bulk streams
+~~~~~~~~~~~~~~~~
+
 Background
 ==========
 

@@ -25,7 +28,9 @@ time.
 Driver implications
 ===================
 
-int usb_alloc_streams(struct usb_interface *interface,
+::
+
+  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);
 

@@ -53,7 +58,7 @@ 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.

@@ -68,9 +73,9 @@ Clean up
 ========
 
 If a driver wishes to stop using streams to communicate with the device, it
-should call
+should call::
 
-void usb_free_streams(struct usb_interface *interface,
+  void usb_free_streams(struct usb_interface *interface,
 		struct usb_host_endpoint **eps, unsigned int num_eps,
 		gfp_t mem_flags);
 

index 5dfb04b2d730..6fe7611f7332 100644
@@ -7,6 +7,7 @@ Linux USB API
    usb
    gadget
    anchors
+   bulk-streams
    writing_usb_driver
    writing_musb_glue_layer
 

similarity index 78%
rename from Documentation/usb/callbacks.txt
rename to Documentation/driver-api/usb/callbacks.rst
index 9e85846bdb98..93a8d53e27e7 100644
@@ -1,3 +1,6 @@
+USB core callbacks
+~~~~~~~~~~~~~~~~~~
+
 What callbacks will usbcore do?
 ===============================
 

@@ -11,30 +14,42 @@ 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.
+ - @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.
+ - @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.
+ - @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
+ - @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

@@ -58,7 +73,9 @@ an interface. A driver's bond to an interface is exclusive.
 The probe() callback
 --------------------
 
-int (*probe) (struct usb_interface *intf,
+::
+
+  int (*probe) (struct usb_interface *intf,
 		const struct usb_device_id *id);
 
 Accept or decline an interface. If you accept the device return 0,

@@ -75,7 +92,9 @@ initialisation that doesn't take too long is a good idea here.
 The disconnect() callback
 -------------------------
 
-void (*disconnect) (struct usb_interface *intf);
+::
+
+  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

@@ -93,7 +112,9 @@ Device level callbacks
 pre_reset
 ---------
 
-int (*pre_reset)(struct usb_interface *intf);
+::
+
+  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

@@ -107,7 +128,9 @@ are in atomic context.
 post_reset
 ----------
 
-int (*post_reset)(struct usb_interface *intf);
+::
+
+  int (*post_reset)(struct usb_interface *intf);
 
 The reset has completed.  Restore any saved device state and begin
 using the device again.

index 6fe7611f7332..441c5dacdf27 100644
@@ -8,6 +8,7 @@ Linux USB API
    gadget
    anchors
    bulk-streams
+   callbacks
    writing_usb_driver
    writing_musb_glue_layer
 

index 441c5dacdf27..23c76c17fc19 100644
@@ -9,6 +9,7 @@ Linux USB API
    anchors
    bulk-streams
    callbacks
+   power-management
    writing_usb_driver
    writing_musb_glue_layer
 

796 lines not on this page · raw message

similarity index 79%
rename from Documentation/usb/dma.txt
rename to Documentation/driver-api/usb/dma.rst
index 444651e70d95..59d5aee89e37 100644
@@ -1,16 +1,19 @@
+USB DMA
+~~~~~~~
+
 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
+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.
+``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.
 
-OR:  they can now be DMA-aware.
+DMA-aware usb drivers:
 
 - New calls enable DMA-aware drivers, letting them allocate dma buffers and
   manage dma mappings for existing dma-ready buffers (see below).

@@ -20,15 +23,15 @@ OR:  they can now be DMA-aware.
   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
+  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
+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.

@@ -41,7 +44,7 @@ and effects like cache-trashing can impose subtle penalties.
   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:
+  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);

@@ -49,15 +52,15 @@ and effects like cache-trashing can impose subtle penalties.
 	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
+  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.
+  :c:func:`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
+  ``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

@@ -75,15 +78,15 @@ and effects like cache-trashing can impose subtle penalties.
   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.
+  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
+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

@@ -92,7 +95,7 @@ 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:
+  DMA transactions::
 
 	int usb_buffer_map_sg (struct usb_device *dev, unsigned pipe,
 		struct scatterlist *sg, int nents);

@@ -103,7 +106,7 @@ of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?")
 	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
+  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

@@ -112,10 +115,10 @@ of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?")
   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):
+  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);
 

@@ -123,9 +126,9 @@ of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?")
 
 	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.
+  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

index 23c76c17fc19..d7610777784b 100644
@@ -9,6 +9,7 @@ Linux USB API
    anchors
    bulk-streams
    callbacks
+   dma
    power-management
    writing_usb_driver
    writing_musb_glue_layer

new file mode 100644
index 000000000000..9c11a0fd16cb
@@ -0,0 +1,205 @@
+USB Error codes
+~~~~~~~~~~~~~~~
+
+: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 :c:func:`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
+				:c:func:`usb_unlink_urb`
+
+``-EINPROGRESS``		URB still pending, no results yet
+				(That is, if drivers see this it's a bug.)
+
+``-EPROTO`` [#f1]_, [#f2]_	a) bitstuff error
+				b) no response packet received within the
+				   prescribed bus turn-around time
+				c) unknown USB error
+
+``-EILSEQ`` [#f1]_, [#f2]_	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`` [#f2]_		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`` [#f2]_		Endpoint stalled.  For non-control endpoints,
+				reset this status with
+				:c:func:`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`` [#f1]_		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
+				:c:func:`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.
+===============================	===============================================
+
+
+.. [#f1]
+
+   Error codes like ``-EPROTO``, ``-EILSEQ`` and ``-EOVERFLOW`` normally
+   indicate hardware problems such as bad devices (including firmware)
+   or cables.
+
+.. [#f2]
+
+   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
+=========================================
+
+.. note:: expect also other submit and transfer status codes
+
+:c:func:`usb_register`:
+
+======================= ===================================
+``-EINVAL``		error during registering new driver
+======================= ===================================
+
+``usb_get_*/usb_set_*()``,
+:c:func:`usb_control_msg`,
+:c:func:`usb_bulk_msg()`:
+
+======================= ==============================================
+``-ETIMEDOUT``		Timeout expired before the transfer completed.
+======================= ==============================================

index d7610777784b..1e2a0c54eb3d 100644
@@ -11,6 +11,7 @@ Linux USB API
    callbacks
    dma
    power-management
+   error-codes
    writing_usb_driver
    writing_musb_glue_layer
 

175 lines not on this page · raw message

similarity index 76%
rename from Documentation/usb/hotplug.txt
rename to Documentation/driver-api/usb/hotplug.rst
index 5b243f315b2c..79663e653ca1 100644
@@ -1,4 +1,9 @@
-LINUX HOTPLUGGING
+USB hotplugging
+~~~~~~~~~~~~~~~
+
+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

@@ -30,11 +35,11 @@ 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``)
+=========================================
 
-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
+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

@@ -51,26 +56,26 @@ Hotplug software and other resources is available at:
 Mailing list information is also available at that site.
 
 
---------------------------------------------------------------------------
+USB Policy Agent
+================
 
-
-USB POLICY AGENT
-
-The USB subsystem currently invokes /sbin/hotplug when USB devices
+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)
+========== ============================================
+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
+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.
 

@@ -79,19 +84,20 @@ 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
+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
+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
+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.
+macros such as these, and use driver_info to store more information::
 
     USB_DEVICE (vendorId, productId)
 	... matching devices with specified vendor and product ids

@@ -103,7 +109,7 @@ macros such as these, and use driver_info to store more information.
 	... 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:
+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 },

@@ -116,10 +122,10 @@ and their quirks, might have a MODULE_DEVICE_TABLE like this:
 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".
+need such a struct :c:type:`usb_driver`.
 
 Drivers that connect directly to the USB subsystem should be declared
-something like this:
+something like this::
 
     static struct usb_driver mydriver = {
 	.name		= "mydriver",

@@ -138,11 +144,11 @@ something like this:
 
 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.
-
+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``.

index 1e2a0c54eb3d..43f0a8b72b11 100644
@@ -11,6 +11,7 @@ Linux USB API
    callbacks
    dma
    power-management
+   hotplug
    error-codes
    writing_usb_driver
    writing_musb_glue_layer

index 43f0a8b72b11..3f08cb5d5feb 100644
@@ -12,6 +12,7 @@ Linux USB API
    dma
    power-management
    hotplug
+   persist
    error-codes
    writing_usb_driver
    writing_musb_glue_layer

similarity index 94%
rename from Documentation/usb/persist.txt
rename to Documentation/driver-api/usb/persist.rst
index 35d70eda9ad6..ea1b43f0559e 100644
@@ -1,11 +1,12 @@
-		USB device persistence during system suspend
+USB device persistence during system suspend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-		   Alan Stern <[email protected]>
+:Author: Alan Stern <[email protected]>
+:Date: September 2, 2006 (Updated February 25, 2008)
 
-		September 2, 2006 (Updated February 25, 2008)
 
-
-	What is the problem?
+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

@@ -63,7 +64,8 @@ suspended -- but it will crash as soon as it wakes up, which isn't
 much better.)
 
 
-	What is the solution?
+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

@@ -99,7 +101,7 @@ 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):
+(as root)::
 
 	echo 1 >/sys/bus/usb/devices/.../power/persist
 

@@ -110,7 +112,8 @@ doesn't even exist, so you only have to worry about setting it for
 devices where it really matters.
 
 
-	Is this the best solution?
+Is this the best solution?
+==========================
 
 Perhaps not.  Arguably, keeping track of mounted filesystems and
 memory mappings across device disconnects should be handled by a

@@ -130,7 +133,8 @@ 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!!
+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

similarity index 50%
rename from Documentation/usb/URB.txt
rename to Documentation/driver-api/usb/URB.rst
index 50da0d455444..c4a141f29477 100644
@@ -1,28 +1,35 @@
-Revised: 2000-Dec-05.
-Again:   2002-Jul-06
-Again:   2005-Sep-19
+USB Request Block (URB)
+~~~~~~~~~~~~~~~~~~~~~~~
 
-    NOTE:
+:Revised: 2000-Dec-05
+:Again:   2002-Jul-06
+:Again:   2005-Sep-19
+:Again:   2017-Mar-29
 
-    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.
 
+.. note::
 
-1.1. Basic concept or 'What is an URB?'
+    The USB subsystem now has a substantial section at :ref:`usb-hostside-api`
+    section, generated from the current source code.
+    This particular documentation file isn't complete and may not be
+    updated to the last version; don't rely on it except for a quick
+    overview.
 
-The basic idea of the new driver is message passing, the message itself is 
-called USB Request Block, or URB for short. 
+Basic concept or 'What is an URB?'
+==================================
 
-- An URB consists of all relevant information to execute any USB transaction 
-  and deliver the data and status back. 
+The basic idea of the new driver is message passing, the message itself is
+called USB Request Block, or URB for short.
 
-- Execution of an URB is inherently an asynchronous operation, i.e. the 
-  usb_submit_urb(urb) call returns immediately after it has successfully
+- 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
+  :c:func:`usb_submit_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. 
+- Transfers for one URB can be canceled with :c:func:`usb_unlink_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

@@ -35,53 +42,55 @@ called USB Request Block, or URB for short.
   of data to (or from) devices when using periodic transfer modes.
 
 
-1.2. The URB structure
+The URB structure
+=================
 
-Some of the fields in an URB are:
+Some of the fields in struct :c:type:`urb` are::
 
-struct urb
-{
-// (IN) device and pipe specify the endpoint queue
+  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.
+	unsigned int transfer_flags;    // URB_ISO_ASAP, URB_SHORT_NOT_OK, etc.
 
-// (IN) all urbs need completion routines
+  // (IN) all urbs need completion routines
 	void *context;                  // context for completion routine
-	void (*complete)(struct urb *); // pointer to completion routine
+	usb_complete_t complete;        // pointer to completion routine
 
-// (OUT) status after each completion
+  // (OUT) status after each completion
 	int status;                     // returned status
 
-// (IN) buffer used for data transfers
+  // (IN) buffer used for data transfers
 	void *transfer_buffer;          // associated data buffer
-	int transfer_buffer_length;     // data buffer length
+	u32 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
+  // (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
+	u32 actual_length;              // actual data buffer length
 
-// (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)
-	unsigned char* setup_packet;    // setup packet (control only)
+  // (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
+  // Only for PERIODIC transfers (ISO, INTERRUPT)
+    // (IN/OUT) start_frame is set unless URB_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?
+How to get an URB?
+==================
 
-URBs are allocated with the following call
+URBs are allocated by calling :c:func:`usb_alloc_urb`::
 
 	struct urb *usb_alloc_urb(int isoframes, int mem_flags)
 

@@ -91,7 +100,7 @@ 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
+To free an URB, use :c:func:`usb_free_urb`::
 
 	void usb_free_urb(struct urb *urb)
 

@@ -100,78 +109,84 @@ 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?
+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.
+Depending on the type of transaction, there are some inline functions
+defined in ``linux/usb.h`` to simplify the initialization, such as
+:c:func:`usb_fill_control_urb`, :c:func:`usb_fill_bulk_urb` and
+:c:func:`usb_fill_int_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 
+- 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?
+How to submit an URB?
+=====================
 
-Just call
+Just call :c:func:`usb_submit_urb`::
 
 	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.
+The ``mem_flags`` parameter, such as ``GFP_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)
+- 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.
+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.
+URBs to the same endpoint with the ``URB_ISO_ASAP`` flag, using
+multi-buffering, to get seamless ISO streaming.
 
 
-1.6. How to cancel an already running URB?
+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
+:c:func:`usb_unlink_urb`::
 
 	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()
+that the URB will not normally have finished when :c:func:`usb_unlink_urb`
 returns; you must still wait for the completion handler to be called.
 
-To cancel an URB synchronously, call
+To cancel an URB synchronously, call :c:func:`usb_kill_urb`::
 
 	void usb_kill_urb(struct urb *urb)
 
-It does everything usb_unlink_urb does, and in addition it waits
+It does everything :c:func:`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.
+they will get a ``-EPERM`` error.  Thus you can be sure that when
+:c:func:`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,
+while :c:func:`usb_unlink_urb` or :c:func:`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.
 

@@ -181,24 +196,25 @@ 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
+count by calling :c:func`usb_get_urb`::
 
 	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,
+decrement the reference count by calling :c:func:`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?
+What about the completion handler?
+==================================
 
-The handler is of the following type:
+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.
+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.
 

@@ -208,54 +224,65 @@ 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.
+.. 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?
+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.
+Besides the fields present on a bulk transfer, for ISO, you also
+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. You can use the :c:func:`usb_fill_int_urb` macro to fill
+most ISO transfer fields.
 
-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 ISO transfers you also have to fill a :c:type:`usb_iso_packet_descriptor`
+structure, allocated at the end of the URB by :c:func:`usb_alloc_urb`, for
+each packet you want to schedule.
+
+The :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented
+interval value that is less than or equal to the requested interval value.  If
+``URB_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 
+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 
+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).
+For scheduling you can choose your own start frame or ``URB_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?
+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.
+You can use the :c:func:`usb_fill_int_urb` macro to fill INT transfer fields.
+
+The :c:func:`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.
+s

index 3f08cb5d5feb..1bf64edc8c8a 100644
@@ -10,6 +10,7 @@ Linux USB API
    bulk-streams
    callbacks
    dma
+   URB
    power-management
    hotplug
    persist

index 7e820768ee4f..d15ab8ae5239 100644
@@ -1,3 +1,5 @@
+.. _usb-hostside-api:
+
 ===========================
 The Linux-USB Host Side API
 ===========================

index d15ab8ae5239..5ebaf669704c 100644
@@ -615,8 +615,8 @@ USBDEVFS_CONTROL
     The first eight bytes of this structure are the contents of the
     SETUP packet to be sent to the device; see the USB 2.0 specification
     for details. The bRequestType value is composed by combining a
-    USB_TYPE_\* value, a USB_DIR_\* value, and a USB_RECIP_\*
-    value (from *<linux/usb.h>*). If wLength is nonzero, it describes
+    ``USB_TYPE_*`` value, a ``USB_DIR_*`` value, and a ``USB_RECIP_*``
+    value (from ``linux/usb.h``). If wLength is nonzero, it describes
     the length of the data buffer, which is either written to the device
     (USB_DIR_OUT) or read from the device (USB_DIR_IN).
 

@@ -678,7 +678,7 @@ the blocking is separate.
 
 These requests are packaged into a structure that resembles the URB used
 by kernel device drivers. (No POSIX Async I/O support here, sorry.) It
-identifies the endpoint type (USBDEVFS_URB_TYPE_\*), endpoint
+identifies the endpoint type (``USBDEVFS_URB_TYPE_*``), endpoint
 (number, masked with USB_DIR_IN as appropriate), buffer and length,
 and a user "context" value serving to uniquely identify each request.
 (It's usually a pointer to per-request data.) Flags can modify requests

index 831f15d9672f..b832eeff9999 100644
@@ -9,7 +9,7 @@ Description:
 		hubs this facility is always enabled and their device
 		directories will not contain this file.
 
-		For more information, see Documentation/usb/persist.txt.
+		For more information, see Documentation/driver-api/usb/persist.rst.
 
 What:		/sys/bus/usb/devices/.../power/autosuspend
 Date:		March 2007

index c4a141f29477..61a54da9fce9 100644
@@ -1,3 +1,5 @@
+.. _usb-urb:
+
 USB Request Block (URB)
 ~~~~~~~~~~~~~~~~~~~~~~~
 

index 93a8d53e27e7..2b80cf54bcc3 100644
@@ -8,7 +8,7 @@ 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.
+completion callback can be found in :ref:`usb-urb`.
 
 The callbacks defined in the driver structure are:
 

@@ -53,7 +53,7 @@ The callbacks defined in the driver structure are:
 
 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.
+separately in :ref:`usb-power-management`.
 
 Calling conventions
 ===================

index 9c11a0fd16cb..a3e84bfac776 100644
@@ -1,3 +1,5 @@
+.. _usb-error-codes:
+
 USB Error codes
 ~~~~~~~~~~~~~~~
 

index ea1b43f0559e..08cafc6292c1 100644
@@ -1,3 +1,5 @@
+.. _usb-persist:
+
 USB device persistence during system suspend
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

index c068257f6d27..79beb807996b 100644
@@ -328,7 +328,7 @@ 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
+:ref:`usb-persist`) 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

index 5ebaf669704c..6824089ef4c8 100644
@@ -424,8 +424,8 @@ header.
 Unless noted otherwise, the ioctl requests described here will update
 the modification time on the usbfs file to which they are applied
 (unless they fail). A return of zero indicates success; otherwise, a
-standard USB error code is returned. (These are documented in
-``Documentation/usb/error-codes.txt`` in your kernel sources.)
+standard USB error code is returned (These are documented in
+:ref:`usb-error-codes`).
 
 Each of these files multiplexes access to several I/O streams, one per
 endpoint. Each device has one control endpoint (endpoint zero) which

index 8cc17ca71813..9f2f942a01cf 100644
@@ -406,7 +406,7 @@ Firewire, CompactFlash, MMC, external SATA, or even IDE hotplug bays)
 before suspending; then remount them after resuming.
 
 There is a work-around for this problem.  For more information, see
-Documentation/usb/persist.txt.
+Documentation/driver-api/usb/persist.rst.
 
 Q: Can I suspend-to-disk using a swap partition under LVM?
 

index 0e5a889742b3..4d75d9a80001 100644
@@ -26,7 +26,7 @@ config USB_DEFAULT_PERSIST
 	  unplugged, causing any mounted filesystems to be lost.  The
 	  persist feature can still be enabled for individual devices
 	  through the power/persist sysfs node. See
-	  Documentation/usb/persist.txt for more info.
+	  Documentation/driver-api/usb/persist.rst for more info.
 
 	  If you have any questions about this, say Y here, only say N
 	  if you know exactly what you are doing.