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>hifive-unleashed-5.1
Mauro Carvalho Chehab
Jonathan Corbet
parent
4ad4b21b1b
commit
9a3c8b3545
|
|
@ -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;
|
||||
|
|
|
|||
Loading…
Reference in New Issue