Commit 9a3c8b35 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 4ad4b21b

Documentation/driver-api/usb/usb.rst

+17 −31
Original line number Diff line number Diff line
@@ -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;

CRA Git | Maintained and supported by SUSTech CRA and CCSE