1 files changed, 363 insertions, 248 deletions

diff --git a/Documentation/usb/gadget-testing.txt b/Documentation/usb/gadget-testing.txt
index 5908a21fddb6..7d7f2340af42 100644
--- a/Documentation/usb/gadget-testing.txt
+++ b/Documentation/usb/gadget-testing.txt
@@ -1,26 +1,32 @@
+==============
+Gadget Testing
+==============
+
 This file summarizes information on basic testing of USB functions
 provided by gadgets.
 
-1. ACM function
-2. ECM function
-3. ECM subset function
-4. EEM function
-5. FFS function
-6. HID function
-7. LOOPBACK function
-8. MASS STORAGE function
-9. MIDI function
-10. NCM function
-11. OBEX function
-12. PHONET function
-13. RNDIS function
-14. SERIAL function
-15. SOURCESINK function
-16. UAC1 function (legacy implementation)
-17. UAC2 function
-18. UVC function
-19. PRINTER function
-20. UAC1 function (new API)
+.. contents
+
+   1. ACM function
+   2. ECM function
+   3. ECM subset function
+   4. EEM function
+   5. FFS function
+   6. HID function
+   7. LOOPBACK function
+   8. MASS STORAGE function
+   9. MIDI function
+   10. NCM function
+   11. OBEX function
+   12. PHONET function
+   13. RNDIS function
+   14. SERIAL function
+   15. SOURCESINK function
+   16. UAC1 function (legacy implementation)
+   17. UAC2 function
+   18. UVC function
+   19. PRINTER function
+   20. UAC1 function (new API)
 
 
 1. ACM function
@@ -44,13 +50,23 @@ There can be at most 4 ACM/generic serial/OBEX ports in the system.
 Testing the ACM function
 ------------------------
 
-On the host: cat > /dev/ttyACM<X>
-On the device : cat /dev/ttyGS<Y>
+On the host::
+
+        cat > /dev/ttyACM<X>
+
+On the device::
+
+        cat /dev/ttyGS<Y>
 
 then the other way round
 
-On the device: cat > /dev/ttyGS<Y>
-On the host: cat /dev/ttyACM<X>
+On the device::
+
+        cat > /dev/ttyGS<Y>
+
+On the host::
+
+        cat /dev/ttyACM<X>
 
 2. ECM function
 ===============
@@ -63,13 +79,15 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "ecm".
 The ECM function provides these attributes in its function directory:
 
-        ifname          - network device interface name associated with this
+        =============== ==================================================
+        ifname          network device interface name associated with this
                         function instance
-        qmult           - queue length multiplier for high and super speed
-        host_addr       - MAC address of host's end of this
+        qmult           queue length multiplier for high and super speed
+        host_addr       MAC address of host's end of this
                         Ethernet over USB link
-        dev_addr        - MAC address of device's end of this
+        dev_addr        MAC address of device's end of this
                         Ethernet over USB link
+        =============== ==================================================
 
 and after creating the functions/ecm.<instance name> they contain default
 values: qmult is 5, dev_addr and host_addr are randomly selected.
@@ -82,8 +100,13 @@ Testing the ECM function
 
 Configure IP addresses of the device and the host. Then:
 
-On the device: ping <host's IP>
-On the host: ping <device's IP>
+On the device::
+
+        ping <host's IP>
+
+On the host::
+
+        ping <device's IP>
 
 3. ECM subset function
 ======================
@@ -96,13 +119,15 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "geth".
 The ECM subset function provides these attributes in its function directory:
 
-        ifname          - network device interface name associated with this
+        =============== ==================================================
+        ifname          network device interface name associated with this
                         function instance
-        qmult           - queue length multiplier for high and super speed
-        host_addr       - MAC address of host's end of this
+        qmult           queue length multiplier for high and super speed
+        host_addr       MAC address of host's end of this
                         Ethernet over USB link
-        dev_addr        - MAC address of device's end of this
+        dev_addr        MAC address of device's end of this
                         Ethernet over USB link
+        =============== ==================================================
 
 and after creating the functions/ecm.<instance name> they contain default
 values: qmult is 5, dev_addr and host_addr are randomly selected.
@@ -115,8 +140,13 @@ Testing the ECM subset function
 
 Configure IP addresses of the device and the host. Then:
 
-On the device: ping <host's IP>
-On the host: ping <device's IP>
+On the device::
+
+        ping <host's IP>
+
+On the host::
+
+        ping <device's IP>
 
 4. EEM function
 ===============
@@ -129,13 +159,15 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "eem".
 The EEM function provides these attributes in its function directory:
 
-        ifname          - network device interface name associated with this
+        =============== ==================================================
+        ifname          network device interface name associated with this
                         function instance
-        qmult           - queue length multiplier for high and super speed
-        host_addr       - MAC address of host's end of this
+        qmult           queue length multiplier for high and super speed
+        host_addr       MAC address of host's end of this
                         Ethernet over USB link
-        dev_addr        - MAC address of device's end of this
+        dev_addr        MAC address of device's end of this
                         Ethernet over USB link
+        =============== ==================================================
 
 and after creating the functions/eem.<instance name> they contain default
 values: qmult is 5, dev_addr and host_addr are randomly selected.
@@ -148,8 +180,13 @@ Testing the EEM function
 
 Configure IP addresses of the device and the host. Then:
 
-On the device: ping <host's IP>
-On the host: ping <device's IP>
+On the device::
+
+        ping <host's IP>
+
+On the host::
+
+        ping <device's IP>
 
 5. FFS function
 ===============
@@ -172,6 +209,7 @@ Testing the FFS function
 ------------------------
 
 On the device: start the function's userspace daemon, enable the gadget
+
 On the host: use the USB function provided by the device
 
 6. HID function
@@ -185,39 +223,43 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "hid".
 The HID function provides these attributes in its function directory:
 
-        protocol        - HID protocol to use
-        report_desc     - data to be used in HID reports, except data
+        =============== ===========================================
+        protocol        HID protocol to use
+        report_desc     data to be used in HID reports, except data
                         passed with /dev/hidg<X>
-        report_length   - HID report length
-        subclass        - HID subclass to use
+        report_length   HID report length
+        subclass        HID subclass to use
+        =============== ===========================================
 
 For a keyboard the protocol and the subclass are 1, the report_length is 8,
-while the report_desc is:
+while the report_desc is::
 
-$ hd my_report_desc
-00000000  05 01 09 06 a1 01 05 07  19 e0 29 e7 15 00 25 01  |..........)...%.|
-00000010  75 01 95 08 81 02 95 01  75 08 81 03 95 05 75 01  |u.......u.....u.|
-00000020  05 08 19 01 29 05 91 02  95 01 75 03 91 03 95 06  |....).....u.....|
-00000030  75 08 15 00 25 65 05 07  19 00 29 65 81 00 c0     |u...%e....)e...|
-0000003f
+  $ hd my_report_desc
+  00000000  05 01 09 06 a1 01 05 07  19 e0 29 e7 15 00 25 01  |..........)...%.|
+  00000010  75 01 95 08 81 02 95 01  75 08 81 03 95 05 75 01  |u.......u.....u.|
+  00000020  05 08 19 01 29 05 91 02  95 01 75 03 91 03 95 06  |....).....u.....|
+  00000030  75 08 15 00 25 65 05 07  19 00 29 65 81 00 c0     |u...%e....)e...|
+  0000003f
 
-Such a sequence of bytes can be stored to the attribute with echo:
+Such a sequence of bytes can be stored to the attribute with echo::
 
-$ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
+  $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
 
 Testing the HID function
 ------------------------
 
 Device:
+
 - create the gadget
 - connect the gadget to a host, preferably not the one used
-to control the gadget
+  to control the gadget
 - run a program which writes to /dev/hidg<N>, e.g.
-a userspace program found in Documentation/usb/gadget_hid.txt:
+  a userspace program found in Documentation/usb/gadget_hid.txt::
 
-$ ./hid_gadget_test /dev/hidg0 keyboard
+        $ ./hid_gadget_test /dev/hidg0 keyboard
 
 Host:
+
 - observe the keystrokes from the gadget
 
 7. LOOPBACK function
@@ -231,13 +273,16 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "Loopback".
 The LOOPBACK function provides these attributes in its function directory:
 
-        qlen            - depth of loopback queue
-        bulk_buflen     - buffer length
+        =============== =======================
+        qlen            depth of loopback queue
+        bulk_buflen     buffer length
+        =============== =======================
 
 Testing the LOOPBACK function
 -----------------------------
 
 device: run the gadget
+
 host: test-usb (tools/usb/testusb.c)
 
 8. MASS STORAGE function
@@ -252,18 +297,20 @@ The function name to use when creating the function directory is "mass_storage".
 The MASS STORAGE function provides these attributes in its directory:
 files:
 
-        stall           - Set to permit function to halt bulk endpoints.
+        =============== ==============================================
+        stall           Set to permit function to halt bulk endpoints.
                         Disabled on some USB devices known not to work
                         correctly. You should set it to true.
-        num_buffers     - Number of pipeline buffers. Valid numbers
+        num_buffers     Number of pipeline buffers. Valid numbers
                         are 2..4. Available only if
                         CONFIG_USB_GADGET_DEBUG_FILES is set.
+        =============== ==============================================
 
 and a default lun.0 directory corresponding to SCSI LUN #0.
 
-A new lun can be added with mkdir:
+A new lun can be added with mkdir::
 
-$ mkdir functions/mass_storage.0/partition.5
+        $ mkdir functions/mass_storage.0/partition.5
 
 Lun numbering does not have to be continuous, except for lun #0 which is
 created by default. A maximum of 8 luns can be specified and they all must be
@@ -273,18 +320,20 @@ although it is not mandatory.
 
 In each lun directory there are the following attribute files:
 
-        file            - The path to the backing file for the LUN.
+        =============== ==============================================
+        file            The path to the backing file for the LUN.
                         Required if LUN is not marked as removable.
-        ro              - Flag specifying access to the LUN shall be
+        ro              Flag specifying access to the LUN shall be
                         read-only. This is implied if CD-ROM emulation
                         is enabled as well as when it was impossible
                         to open "filename" in R/W mode.
-        removable       - Flag specifying that LUN shall be indicated as
+        removable       Flag specifying that LUN shall be indicated as
                         being removable.
-        cdrom           - Flag specifying that LUN shall be reported as
+        cdrom           Flag specifying that LUN shall be reported as
                         being a CD-ROM.
-        nofua           - Flag specifying that FUA flag
+        nofua           Flag specifying that FUA flag
                         in SCSI WRITE(10,12)
+        =============== ==============================================
 
 Testing the MASS STORAGE function
 ---------------------------------
@@ -304,12 +353,14 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "midi".
 The MIDI function provides these attributes in its function directory:
 
-        buflen          - MIDI buffer length
-        id              - ID string for the USB MIDI adapter
-        in_ports        - number of MIDI input ports
-        index           - index value for the USB MIDI adapter
-        out_ports       - number of MIDI output ports
-        qlen            - USB read request queue length
+        =============== ====================================
+        buflen          MIDI buffer length
+        id              ID string for the USB MIDI adapter
+        in_ports        number of MIDI input ports
+        index           index value for the USB MIDI adapter
+        out_ports       number of MIDI output ports
+        qlen            USB read request queue length
+        =============== ====================================
 
 Testing the MIDI function
 -------------------------
@@ -317,60 +368,63 @@ Testing the MIDI function
 There are two cases: playing a mid from the gadget to
 the host and playing a mid from the host to the gadget.
 
-1) Playing a mid from the gadget to the host
-host)
+1) Playing a mid from the gadget to the host:
+
+host::
 
-$ arecordmidi -l
- Port    Client name                      Port name
- 14:0    Midi Through                     Midi Through Port-0
- 24:0    MIDI Gadget                      MIDI Gadget MIDI 1
-$ arecordmidi -p 24:0 from_gadget.mid
+  $ arecordmidi -l
+   Port    Client name                      Port name
+   14:0    Midi Through                     Midi Through Port-0
+   24:0    MIDI Gadget                      MIDI Gadget MIDI 1
+  $ arecordmidi -p 24:0 from_gadget.mid
 
-gadget)
+gadget::
 
-$ aplaymidi -l
- Port    Client name                      Port name
- 20:0    f_midi                           f_midi
+  $ aplaymidi -l
+   Port    Client name                      Port name
+   20:0    f_midi                           f_midi
 
-$ aplaymidi -p 20:0 to_host.mid
+  $ aplaymidi -p 20:0 to_host.mid
 
 2) Playing a mid from the host to the gadget
-gadget)
 
-$ arecordmidi -l
- Port    Client name                      Port name
- 20:0    f_midi                           f_midi
+gadget::
+
+  $ arecordmidi -l
+   Port    Client name                      Port name
+   20:0    f_midi                           f_midi
 
-$ arecordmidi -p 20:0 from_host.mid
+  $ arecordmidi -p 20:0 from_host.mid
 
-host)
+host::
 
-$ aplaymidi -l
- Port    Client name                      Port name
- 14:0    Midi Through                     Midi Through Port-0
- 24:0    MIDI Gadget                      MIDI Gadget MIDI 1
+  $ aplaymidi -l
+   Port    Client name                      Port name
+   14:0    Midi Through                     Midi Through Port-0
+   24:0    MIDI Gadget                      MIDI Gadget MIDI 1
 
-$ aplaymidi -p24:0 to_gadget.mid
+  $ aplaymidi -p24:0 to_gadget.mid
 
 The from_gadget.mid should sound identical to the to_host.mid.
+
 The from_host.id should sound identical to the to_gadget.mid.
 
-MIDI files can be played to speakers/headphones with e.g. timidity installed
+MIDI files can be played to speakers/headphones with e.g. timidity installed::
 
-$ aplaymidi -l
- Port    Client name                      Port name
- 14:0    Midi Through                     Midi Through Port-0
- 24:0    MIDI Gadget                      MIDI Gadget MIDI 1
-128:0    TiMidity                         TiMidity port 0
-128:1    TiMidity                         TiMidity port 1
-128:2    TiMidity                         TiMidity port 2
-128:3    TiMidity                         TiMidity port 3
+  $ aplaymidi -l
+   Port    Client name                      Port name
+   14:0    Midi Through                     Midi Through Port-0
+   24:0    MIDI Gadget                      MIDI Gadget MIDI 1
+  128:0    TiMidity                         TiMidity port 0
+  128:1    TiMidity                         TiMidity port 1
+  128:2    TiMidity                         TiMidity port 2
+  128:3    TiMidity                         TiMidity port 3
 
-$ aplaymidi -p 128:0 file.mid
+  $ aplaymidi -p 128:0 file.mid
 
-MIDI ports can be logically connected using the aconnect utility, e.g.:
+MIDI ports can be logically connected using the aconnect utility, e.g.::
 
-$ aconnect 24:0 128:0 # try it on the host
+  $ aconnect 24:0 128:0 # try it on the host
 
 After the gadget's MIDI port is connected to timidity's MIDI port,
 whatever is played at the gadget side with aplaymidi -l is audible
@@ -387,13 +441,15 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "ncm".
 The NCM function provides these attributes in its function directory:
 
-        ifname          - network device interface name associated with this
+        =============== ==================================================
+        ifname          network device interface name associated with this
                         function instance
-        qmult           - queue length multiplier for high and super speed
-        host_addr       - MAC address of host's end of this
+        qmult           queue length multiplier for high and super speed
+        host_addr       MAC address of host's end of this
                         Ethernet over USB link
-        dev_addr        - MAC address of device's end of this
+        dev_addr        MAC address of device's end of this
                         Ethernet over USB link
+        =============== ==================================================
 
 and after creating the functions/ncm.<instance name> they contain default
 values: qmult is 5, dev_addr and host_addr are randomly selected.
@@ -406,8 +462,13 @@ Testing the NCM function
 
 Configure IP addresses of the device and the host. Then:
 
-On the device: ping <host's IP>
-On the host: ping <device's IP>
+On the device::
+
+        ping <host's IP>
+
+On the host::
+
+        ping <device's IP>
 
 11. OBEX function
 =================
@@ -429,13 +490,18 @@ There can be at most 4 ACM/generic serial/OBEX ports in the system.
 Testing the OBEX function
 -------------------------
 
-On device: seriald -f /dev/ttyGS<Y> -s 1024
-On host: serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
-             -t<out endpoint addr> -r<in endpoint addr>
+On device::
+
+        seriald -f /dev/ttyGS<Y> -s 1024
+
+On host::
+
+        serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
+                -t<out endpoint addr> -r<in endpoint addr>
 
 where seriald and serialc are Felipe's utilities found here:
 
-https://github.com/felipebalbi/usb-tools.git master
+        https://github.com/felipebalbi/usb-tools.git master
 
 12. PHONET function
 ===================
@@ -448,8 +514,10 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "phonet".
 The PHONET function provides just one attribute in its function directory:
 
-        ifname          - network device interface name associated with this
+        =============== ==================================================
+        ifname          network device interface name associated with this
                         function instance
+        =============== ==================================================
 
 Testing the PHONET function
 ---------------------------
@@ -464,41 +532,41 @@ These tools are required:
 
 git://git.gitorious.org/meego-cellular/phonet-utils.git
 
-On the host:
+On the host::
 
-$ ./phonet -a 0x10 -i usbpn0
-$ ./pnroute add 0x6c usbpn0
-$./pnroute add 0x10 usbpn0
-$ ifconfig usbpn0 up
+        $ ./phonet -a 0x10 -i usbpn0
+        $ ./pnroute add 0x6c usbpn0
+        $./pnroute add 0x10 usbpn0
+        $ ifconfig usbpn0 up
 
-On the device:
+On the device::
 
-$ ./phonet -a 0x6c -i upnlink0
-$ ./pnroute add 0x10 upnlink0
-$ ifconfig upnlink0 up
+        $ ./phonet -a 0x6c -i upnlink0
+        $ ./pnroute add 0x10 upnlink0
+        $ ifconfig upnlink0 up
 
-Then a test program can be used:
+Then a test program can be used::
 
-http://www.spinics.net/lists/linux-usb/msg85690.html
+        http://www.spinics.net/lists/linux-usb/msg85690.html
 
-On the device:
+On the device::
 
-$ ./pnxmit -a 0x6c -r
+        $ ./pnxmit -a 0x6c -r
 
-On the host:
+On the host::
 
-$ ./pnxmit -a 0x10 -s 0x6c
+        $ ./pnxmit -a 0x10 -s 0x6c
 
 As a result some data should be sent from host to device.
 Then the other way round:
 
-On the host:
+On the host::
 
-$ ./pnxmit -a 0x10 -r
+        $ ./pnxmit -a 0x10 -r
 
-On the device:
+On the device::
 
-$ ./pnxmit -a 0x6c -s 0x10
+        $ ./pnxmit -a 0x6c -s 0x10
 
 13. RNDIS function
 ==================
@@ -511,13 +579,15 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "rndis".
 The RNDIS function provides these attributes in its function directory:
 
-        ifname          - network device interface name associated with this
+        =============== ==================================================
+        ifname          network device interface name associated with this
                         function instance
-        qmult           - queue length multiplier for high and super speed
-        host_addr       - MAC address of host's end of this
+        qmult           queue length multiplier for high and super speed
+        host_addr       MAC address of host's end of this
                         Ethernet over USB link
-        dev_addr        - MAC address of device's end of this
+        dev_addr        MAC address of device's end of this
                         Ethernet over USB link
+        =============== ==================================================
 
 and after creating the functions/rndis.<instance name> they contain default
 values: qmult is 5, dev_addr and host_addr are randomly selected.
@@ -530,8 +600,13 @@ Testing the RNDIS function
 
 Configure IP addresses of the device and the host. Then:
 
-On the device: ping <host's IP>
-On the host: ping <device's IP>
+On the device::
+
+        ping <host's IP>
+
+On the host::
+
+        ping <device's IP>
 
 14. SERIAL function
 ===================
@@ -553,15 +628,28 @@ There can be at most 4 ACM/generic serial/OBEX ports in the system.
 Testing the SERIAL function
 ---------------------------
 
-On host: insmod usbserial
-         echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
-On host: cat > /dev/ttyUSB<X>
-On target: cat /dev/ttyGS<Y>
+On host::
+
+        insmod usbserial
+        echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
+
+On host::
+
+        cat > /dev/ttyUSB<X>
+
+On target::
+
+        cat /dev/ttyGS<Y>
 
 then the other way round
 
-On target: cat > /dev/ttyGS<Y>
-On host: cat /dev/ttyUSB<X>
+On target::
+
+        cat > /dev/ttyGS<Y>
+
+On host::
+
+        cat /dev/ttyUSB<X>
 
 15. SOURCESINK function
 =======================
@@ -574,24 +662,27 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "SourceSink".
 The SOURCESINK function provides these attributes in its function directory:
 
-        pattern         - 0 (all zeros), 1 (mod63), 2 (none)
-        isoc_interval   - 1..16
-        isoc_maxpacket  - 0 - 1023 (fs), 0 - 1024 (hs/ss)
-        isoc_mult       - 0..2 (hs/ss only)
-        isoc_maxburst   - 0..15 (ss only)
-        bulk_buflen     - buffer length
-        bulk_qlen       - depth of queue for bulk
-        iso_qlen        - depth of queue for iso
+        =============== ==================================
+        pattern         0 (all zeros), 1 (mod63), 2 (none)
+        isoc_interval   1..16
+        isoc_maxpacket  0 - 1023 (fs), 0 - 1024 (hs/ss)
+        isoc_mult       0..2 (hs/ss only)
+        isoc_maxburst   0..15 (ss only)
+        bulk_buflen     buffer length
+        bulk_qlen       depth of queue for bulk
+        iso_qlen        depth of queue for iso
+        =============== ==================================
 
 Testing the SOURCESINK function
 -------------------------------
 
 device: run the gadget
+
 host: test-usb (tools/usb/testusb.c)
 
 
 16. UAC1 function (legacy implementation)
-=================
+=========================================
 
 The function is provided by usb_f_uac1_legacy.ko module.
 
@@ -602,12 +693,14 @@ The function name to use when creating the function directory
 is "uac1_legacy".
 The uac1 function provides these attributes in its function directory:
 
-        audio_buf_size - audio buffer size
-        fn_cap - capture pcm device file name
-        fn_cntl - control device file name
-        fn_play - playback pcm device file name
-        req_buf_size - ISO OUT endpoint request buffer size
-        req_count - ISO OUT endpoint request count
+        =============== ====================================
+        audio_buf_size  audio buffer size
+        fn_cap          capture pcm device file name
+        fn_cntl         control device file name
+        fn_play         playback pcm device file name
+        req_buf_size    ISO OUT endpoint request buffer size
+        req_count       ISO OUT endpoint request count
+        =============== ====================================
 
 The attributes have sane default values.
 
@@ -615,7 +708,10 @@ Testing the UAC1 function
 -------------------------
 
 device: run the gadget
-host: aplay -l # should list our USB Audio Gadget
+
+host::
+
+        aplay -l # should list our USB Audio Gadget
 
 17. UAC2 function
 =================
@@ -628,14 +724,16 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "uac2".
 The uac2 function provides these attributes in its function directory:
 
-        c_chmask - capture channel mask
-        c_srate - capture sampling rate
-        c_ssize - capture sample size (bytes)
-        p_chmask - playback channel mask
-        p_srate - playback sampling rate
-        p_ssize - playback sample size (bytes)
-        req_number - the number of pre-allocated request for both capture
-                     and playback
+        =============== ====================================================
+        c_chmask        capture channel mask
+        c_srate         capture sampling rate
+        c_ssize         capture sample size (bytes)
+        p_chmask        playback channel mask
+        p_srate         playback sampling rate
+        p_ssize         playback sample size (bytes)
+        req_number      the number of pre-allocated request for both capture
+                        and playback
+        =============== ====================================================
 
 The attributes have sane default values.
 
@@ -648,14 +746,14 @@ host: aplay -l # should list our USB Audio Gadget
 This function does not require real hardware support, it just
 sends a stream of audio data to/from the host. In order to
 actually hear something at the device side, a command similar
-to this must be used at the device side:
+to this must be used at the device side::
 
-$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
+        $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
 
-e.g.:
+e.g.::
 
-$ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
-aplay -D default:CARD=OdroidU3
+        $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
+          aplay -D default:CARD=OdroidU3
 
 18. UVC function
 ================
@@ -668,66 +766,73 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "uvc".
 The uvc function provides these attributes in its function directory:
 
-        streaming_interval - interval for polling endpoint for data transfers
-        streaming_maxburst - bMaxBurst for super speed companion descriptor
-        streaming_maxpacket - maximum packet size this endpoint is capable of
-                              sending or receiving when this configuration is
-                              selected
+        =================== ================================================
+        streaming_interval  interval for polling endpoint for data transfers
+        streaming_maxburst  bMaxBurst for super speed companion descriptor
+        streaming_maxpacket maximum packet size this endpoint is capable of
+                            sending or receiving when this configuration is
+                            selected
+        =================== ================================================
 
 There are also "control" and "streaming" subdirectories, each of which contain
 a number of their subdirectories. There are some sane defaults provided, but
 the user must provide the following:
 
-        control header - create in control/header, link from control/class/fs
-                        and/or control/class/ss
-        streaming header - create in streaming/header, link from
-                        streaming/class/fs and/or streaming/class/hs and/or
-                        streaming/class/ss
-        format description - create in streaming/mjpeg and/or
-                        streaming/uncompressed
-        frame description - create in streaming/mjpeg/<format> and/or in
-                        streaming/uncompressed/<format>
+        ================== ====================================================
+        control header     create in control/header, link from control/class/fs
+                           and/or control/class/ss
+        streaming header   create in streaming/header, link from
+                           streaming/class/fs and/or streaming/class/hs and/or
+                           streaming/class/ss
+        format description create in streaming/mjpeg and/or
+                           streaming/uncompressed
+        frame description  create in streaming/mjpeg/<format> and/or in
+                           streaming/uncompressed/<format>
+        ================== ====================================================
 
 Each frame description contains frame interval specification, and each
 such specification consists of a number of lines with an inverval value
-in each line. The rules stated above are best illustrated with an example:
-
-# mkdir functions/uvc.usb0/control/header/h
-# cd functions/uvc.usb0/control/
-# ln -s header/h class/fs
-# ln -s header/h class/ss
-# mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
-# cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
-666666
-1000000
-5000000
-EOF
-# cd $GADGET_CONFIGFS_ROOT
-# mkdir functions/uvc.usb0/streaming/header/h
-# cd functions/uvc.usb0/streaming/header/h
-# ln -s ../../uncompressed/u
-# cd ../../class/fs
-# ln -s ../../header/h
-# cd ../../class/hs
-# ln -s ../../header/h
-# cd ../../class/ss
-# ln -s ../../header/h
+in each line. The rules stated above are best illustrated with an example::
+
+  # mkdir functions/uvc.usb0/control/header/h
+  # cd functions/uvc.usb0/control/
+  # ln -s header/h class/fs
+  # ln -s header/h class/ss
+  # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
+  # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
+  666666
+  1000000
+  5000000
+  EOF
+  # cd $GADGET_CONFIGFS_ROOT
+  # mkdir functions/uvc.usb0/streaming/header/h
+  # cd functions/uvc.usb0/streaming/header/h
+  # ln -s ../../uncompressed/u
+  # cd ../../class/fs
+  # ln -s ../../header/h
+  # cd ../../class/hs
+  # ln -s ../../header/h
+  # cd ../../class/ss
+  # ln -s ../../header/h
 
 
 Testing the UVC function
 ------------------------
 
-device: run the gadget, modprobe vivid
+device: run the gadget, modprobe vivid::
 
-# uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
+  # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
 
 where uvc-gadget is this program:
-http://git.ideasonboard.org/uvc-gadget.git
+        http://git.ideasonboard.org/uvc-gadget.git
 
 with these patches:
-http://www.spinics.net/lists/linux-usb/msg99220.html
 
-host: luvcview -f yuv
+        http://www.spinics.net/lists/linux-usb/msg99220.html
+
+host::
+
+        luvcview -f yuv
 
 19. PRINTER function
 ====================
@@ -740,16 +845,19 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "printer".
 The printer function provides these attributes in its function directory:
 
-        pnp_string      - Data to be passed to the host in pnp string
-        q_len           - Number of requests per endpoint
+        ==========      ===========================================
+        pnp_string      Data to be passed to the host in pnp string
+        q_len           Number of requests per endpoint
+        ==========      ===========================================
 
 Testing the PRINTER function
 ----------------------------
 
 The most basic testing:
 
-device: run the gadget
-# ls -l /devices/virtual/usb_printer_gadget/
+device: run the gadget::
+
+        # ls -l /devices/virtual/usb_printer_gadget/
 
 should show g_printer<number>.
 
@@ -761,23 +869,28 @@ If udev is active, then e.g. /dev/usb/lp0 should appear.
 
 host->device transmission:
 
-device:
-# cat /dev/g_printer<number>
-host:
-# cat > /dev/usb/lp0
+device::
 
-device->host transmission:
+        # cat /dev/g_printer<number>
 
-# cat > /dev/g_printer<number>
-host:
-# cat /dev/usb/lp0
+host::
+
+        # cat > /dev/usb/lp0
+
+device->host transmission::
+
+        # cat > /dev/g_printer<number>
+
+host::
+
+        # cat /dev/usb/lp0
 
 More advanced testing can be done with the prn_example
 described in Documentation/usb/gadget_printer.txt.
 
 
 20. UAC1 function (virtual ALSA card, using u_audio API)
-=================
+========================================================
 
 The function is provided by usb_f_uac1.ko module.
 It will create a virtual ALSA card and the audio streams are simply
@@ -789,14 +902,16 @@ Function-specific configfs interface
 The function name to use when creating the function directory is "uac1".
 The uac1 function provides these attributes in its function directory:
 
-        c_chmask - capture channel mask
-        c_srate - capture sampling rate
-        c_ssize - capture sample size (bytes)
-        p_chmask - playback channel mask
-        p_srate - playback sampling rate
-        p_ssize - playback sample size (bytes)
-        req_number - the number of pre-allocated request for both capture
-                     and playback
+        ========== ====================================================
+        c_chmask   capture channel mask
+        c_srate    capture sampling rate
+        c_ssize    capture sample size (bytes)
+        p_chmask   playback channel mask
+        p_srate    playback sampling rate
+        p_ssize    playback sample size (bytes)
+        req_number the number of pre-allocated request for both capture
+                   and playback
+        ========== ====================================================
 
 The attributes have sane default values.
 
@@ -809,11 +924,11 @@ host: aplay -l # should list our USB Audio Gadget
 This function does not require real hardware support, it just
 sends a stream of audio data to/from the host. In order to
 actually hear something at the device side, a command similar
-to this must be used at the device side:
+to this must be used at the device side::
 
-$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
+        $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
 
-e.g.:
+e.g.::
 
-$ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
-aplay -D default:CARD=OdroidU3
+        $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
+          aplay -D default:CARD=OdroidU3