docs-rst: usb: update old usbfs-related documentation

In ``<linux/usb/ch9.h>`` you will find the USB data types defined in

chapter 9 of the USB specification. These data types are used throughout

USB, and in APIs including this host side API, gadget APIs, and usbfs.

USB, and in APIs including this host side API, gadget APIs, usb character

devices and debugfs interfaces.

.. kernel-doc:: include/linux/usb/ch9.h

   :internal:

.. kernel-doc:: drivers/usb/core/buffer.c

   :internal:

The USB Filesystem (usbfs)

==========================

The USB character device nodes

==============================

This chapter presents the Linux *usbfs*. You may prefer to avoid writing

new kernel code for your USB driver; that's the problem that usbfs set

out to solve. User mode device drivers are usually packaged as

applications or libraries, and may use usbfs through some programming

library that wraps it. Such libraries include

This chapter presents the Linux character device nodes. You may prefer

to avoid writing new kernel code for your USB driver. User mode device

drivers are usually packaged as applications or libraries, and may use

character devices through some programming library that wraps it.

Such libraries include

`libusb <http://libusb.sourceforge.net>`__ for C/C++, and

`jUSB <http://jUSB.sourceforge.net>`__ for Java.

.. note::

    This particular documentation is incomplete, especially with respect

  - They were used to be implemented via *usbfs*, but this is not part of

    the sysfs debug interface.

   - This particular documentation is incomplete, especially with respect

     to the asynchronous mode. As of kernel 2.5.66 the code and this

     (new) documentation need to be cross-reviewed.

Configure usbfs into Linux kernels by enabling the *USB filesystem*

option (CONFIG_USB_DEVICEFS), and you get basic support for user mode

USB device drivers. Until relatively recently it was often (confusingly)

called *usbdevfs* although it wasn't solving what *devfs* was. Every USB

device will appear in usbfs, regardless of whether or not it has a

kernel driver.

What files are in "usbfs"?

--------------------------

Conventionally mounted at ``/proc/bus/usb``, usbfs features include:

What files are in "devtmpfs"?

-----------------------------

-  ``/proc/bus/usb/devices`` ... a text file showing each of the USB

   devices on known to the kernel, and their configuration descriptors.

   You can also poll() this to learn about new devices.

Conventionally mounted at ``/dev/bus/usb/``, usbfs features include:

-  ``/proc/bus/usb/BBB/DDD`` ... magic files exposing the each device's

-  ``/dev/bus/usb//BBB/DDD`` ... magic files exposing the each device's

   configuration descriptors, and supporting a series of ioctls for

   making device requests, including I/O to devices. (Purely for access

   by programs.)

example you can be sure that you told the right UPS to power down its

second server. "usbfs" doesn't (yet) expose those IDs.

Mounting and Access Control

---------------------------

There are a number of mount options for usbfs, which will be of most

interest to you if you need to override the default access control

policy. That policy is that only root may read or write device files

(``/proc/bus/BBB/DDD``) although anyone may read the ``devices`` or

``drivers`` files. I/O requests to the device also need the

CAP_SYS_RAWIO capability,

The significance of that is that by default, all user mode device

drivers need super-user privileges. You can change modes or ownership in

a driver setup when the device hotplugs, or maye just start the driver

right then, as a privileged server (or some activity within one). That's

the most secure approach for multi-user systems, but for single user

systems ("trusted" by that user) it's more convenient just to grant

everyone all access (using the *devmode=0666* option) so the driver can

start whenever it's needed.

The mount options for usbfs, usable in /etc/fstab or in command line

invocations of *mount*, are:

*busgid*\ =NNNNN

    Controls the GID used for the /proc/bus/usb/BBB directories.

    (Default: 0)

*busmode*\ =MMM

    Controls the file mode used for the /proc/bus/usb/BBB directories.

    (Default: 0555)

*busuid*\ =NNNNN

    Controls the UID used for the /proc/bus/usb/BBB directories.

    (Default: 0)

*devgid*\ =NNNNN

    Controls the GID used for the /proc/bus/usb/BBB/DDD files. (Default:

    0)

*devmode*\ =MMM

    Controls the file mode used for the /proc/bus/usb/BBB/DDD files.

    (Default: 0644)

*devuid*\ =NNNNN

    Controls the UID used for the /proc/bus/usb/BBB/DDD files. (Default:

    0)

*listgid*\ =NNNNN

    Controls the GID used for the /proc/bus/usb/devices and drivers

    files. (Default: 0)

*listmode*\ =MMM

    Controls the file mode used for the /proc/bus/usb/devices and

    drivers files. (Default: 0444)

*listuid*\ =NNNNN

    Controls the UID used for the /proc/bus/usb/devices and drivers

    files. (Default: 0)

Note that many Linux distributions hard-wire the mount options for usbfs

in their init scripts, such as ``/etc/rc.d/rc.sysinit``, rather than

making it easy to set this per-system policy in ``/etc/fstab``.

/proc/bus/usb/devices

---------------------

This file is handy for status viewing tools in user mode, which can scan

the text format and ignore most of it. More detailed device status

(including class and vendor status) is available from device-specific

files. For information about the current format of this file, see the

``Documentation/usb/proc_usb_info.txt`` file in your Linux kernel

sources.

This file, in combination with the poll() system call, can also be used

to detect when devices are added or removed::

    int fd;

    struct pollfd pfd;

    fd = open("/proc/bus/usb/devices", O_RDONLY);

    pfd = { fd, POLLIN, 0 };

    for (;;) {

	/* The first time through, this call will return immediately. */

	poll(&pfd, 1, -1);

	/* To see what's changed, compare the file's previous and current

	   contents or scan the filesystem.  (Scanning is more precise.) */

    }

Note that this behavior is intended to be used for informational and

debug purposes. It would be more appropriate to use programs such as

udev or HAL to initialize a device or start a user-mode helper program,

for instance.

/proc/bus/usb/BBB/DDD

/dev/bus/usb//BBB/DDD

---------------------

Use these files in one of these basic ways:

Such a driver first needs to find a device file for a device it knows

how to handle. Maybe it was told about it because a ``/sbin/hotplug``

event handling agent chose that driver to handle the new device. Or

maybe it's an application that scans all the /proc/bus/usb device files,

maybe it's an application that scans all the /dev/bus/usb/ device files,

and ignores most devices. In either case, it should :c:func:`read()`

all the descriptors from the device file, and check them against what it

knows how to handle. It might just reject everything except a particular

USBDEVFS_SUBMITURB

    *TBS*

The USB devices

===============

The USB devices are now exported via debugfs:

-  ``/sys/kernel/debug/usb/devices`` ... a text file showing each of the USB

   devices on known to the kernel, and their configuration descriptors.

   You can also poll() this to learn about new devices.

/sys/kernel/debug/usb/devices

-----------------------------

This file is handy for status viewing tools in user mode, which can scan

the text format and ignore most of it. More detailed device status

(including class and vendor status) is available from device-specific

files. For information about the current format of this file, see the

``Documentation/usb/proc_usb_info.txt`` file in your Linux kernel

sources.

This file, in combination with the poll() system call, can also be used

to detect when devices are added or removed::

    int fd;

    struct pollfd pfd;

    fd = open("/sys/kernel/debug/usb/devices", O_RDONLY);

    pfd = { fd, POLLIN, 0 };

    for (;;) {

	/* The first time through, this call will return immediately. */

	poll(&pfd, 1, -1);

	/* To see what's changed, compare the file's previous and current

	   contents or scan the filesystem.  (Scanning is more precise.) */

    }

Note that this behavior is intended to be used for informational and

debug purposes. It would be more appropriate to use programs such as

udev or HAL to initialize a device or start a user-mode helper program,

for instance.

[5] "MBIM (Mobile Broadband Interface Model) Registry"

       - http://compliance.usb.org/mbim/

[6] "/proc/bus/usb filesystem output"

[6] "/dev/bus/usb filesystem output"

       - Documentation/usb/proc_usb_info.txt

[7] "/sys/bus/usb/devices/.../descriptors"

2. Verifying that it works

~~~~~~~~~~~~~~~~~~~~~~~~~~

  The first step would be to check /proc/bus/usb/devices, it should look

  The first step would be to check /sys/kernel/debug/usb/devices, it should look

like this:

T:  Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12  MxCh= 2

to the Linux host with a USB cable, the host system should recognize

the gadget serial device.  For example, the command

  cat /proc/bus/usb/devices

  cat /sys/kernel/debug/usb/devices

should show something like this:

to the Linux host with a USB cable, the host system should recognize

the gadget serial device.  For example, the command

  cat /proc/bus/usb/devices

  cat /sys/kernel/debug/usb/devices

should show something like this:

The usbfs filesystem for USB devices is traditionally mounted at

/proc/bus/usb.  It provides the /proc/bus/usb/devices file, as well as

/proc/bus/usb.  It provides the /sys/kernel/debug/usb/devices file, as well as

the /proc/bus/usb/BBB/DDD files.

In many modern systems the usbfs filesystem isn't used at all.  Instead

      none  /proc/bus/usb  usbfs  defaults  0  0

	  to /etc/fstab.  This will mount usbfs at each reboot.

	  You can then issue `cat /proc/bus/usb/devices` to extract

	  You can then issue `cat /sys/kernel/debug/usb/devices` to extract

	  USB device information, and user mode drivers can use usbfs

	  to interact with USB devices.

are wTotalLength bytes apart. If a device returns less configuration

descriptor data than indicated by wTotalLength there will be a hole in

the file for the missing bytes.  This information is also shown

in text form by the /proc/bus/usb/devices file, described later.

in text form by the /sys/kernel/debug/usb/devices file, described later.

These files may also be used to write user-level drivers for the USB

devices.  You would open the /proc/bus/usb/BBB/DDD file read/write,

THE /proc/bus/usb/devices FILE:

THE /sys/kernel/debug/usb/devices FILE:

-------------------------------

In /proc/bus/usb/devices, each device's output has multiple

In /sys/kernel/debug/usb/devices, each device's output has multiple

lines of ASCII output.

I made it ASCII instead of binary on purpose, so that someone

can obtain some useful data from it without the use of an

=======================================================================

/proc/bus/usb/devices output format:

/sys/kernel/debug/usb/devices output format:

Legend:

  d = decimal number (may have leading spaces or 0's)

If a user or script is interested only in Topology info, for

example, use something like "grep ^T: /proc/bus/usb/devices"

example, use something like "grep ^T: /sys/kernel/debug/usb/devices"

for only the Topology lines.  A command like

"grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list

"grep -i ^[tdp]: /sys/kernel/debug/usb/devices" can be used to list

only the lines that begin with the characters in square brackets,

where the valid characters are TDPCIE.  With a slightly more able

script, it can display any selected lines (for example, only T, D,

and P lines) and change their output format.  (The "procusb"

Perl script is the beginning of this idea.  It will list only

selected lines [selected from TBDPSCIE] or "All" lines from

/proc/bus/usb/devices.)

/sys/kernel/debug/usb/devices.)

The Topology lines can be used to generate a graphic/pictorial

of the USB devices on a system's root hub.  (See more below

The Configuration lines could be used to list maximum power

(in milliamps) that a system's USB devices are using.

For example, "grep ^C: /proc/bus/usb/devices".

For example, "grep ^C: /sys/kernel/debug/usb/devices".

Here's an example, from a system which has a UHCI root hub,