usb.rst: Enrich its ReST representation
- use the proper warning and note markups;
- add references for parts of the document that will be
cross-referenced on other USB docs;
- some minor adjustments to make it better to read in
text mode and in html.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst
index b856abb..7e82076 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -102,6 +102,8 @@
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 @@
.. kernel-doc:: include/linux/usb/ch9.h
:internal:
+.. _usb_header:
+
Host-Side Data Types and Macros
===============================
@@ -209,7 +213,7 @@
`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 @@
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 @@
--------------------
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_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_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_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 @@
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 @@
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_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 @@
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_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 @@
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 @@
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;
