Commit 8a6a285d authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet

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

There's no usbfs anymore. The old features are now either
exported to /dev/bus/usb or via debugfs.

Update documentation accordingly, pointing to the new
places where the character devices and usb/devices are
now placed.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 7c2a3e94
...@@ -111,7 +111,8 @@ USB-Standard Types ...@@ -111,7 +111,8 @@ USB-Standard Types
In ``<linux/usb/ch9.h>`` you will find the USB data types defined in 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 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 .. kernel-doc:: include/linux/usb/ch9.h
:internal: :internal:
...@@ -204,40 +205,32 @@ significantly reduce hcd-specific behaviors. ...@@ -204,40 +205,32 @@ significantly reduce hcd-specific behaviors.
.. kernel-doc:: drivers/usb/core/buffer.c .. kernel-doc:: drivers/usb/core/buffer.c
:internal: :internal:
The USB Filesystem (usbfs) The USB character device nodes
========================== ==============================
This chapter presents the Linux *usbfs*. You may prefer to avoid writing This chapter presents the Linux character device nodes. You may prefer
new kernel code for your USB driver; that's the problem that usbfs set to avoid writing new kernel code for your USB driver. User mode device
out to solve. User mode device drivers are usually packaged as drivers are usually packaged as applications or libraries, and may use
applications or libraries, and may use usbfs through some programming character devices through some programming library that wraps it.
library that wraps it. Such libraries include Such libraries include
`libusb <http://libusb.sourceforge.net>`__ for C/C++, and `libusb <http://libusb.sourceforge.net>`__ for C/C++, and
`jUSB <http://jUSB.sourceforge.net>`__ for Java. `jUSB <http://jUSB.sourceforge.net>`__ for Java.
.. note:: .. note::
This particular documentation is incomplete, especially with respect - They were used to be implemented via *usbfs*, but this is not part of
to the asynchronous mode. As of kernel 2.5.66 the code and this the sysfs debug interface.
(new) documentation need to be cross-reviewed.
Configure usbfs into Linux kernels by enabling the *USB filesystem* - This particular documentation is incomplete, especially with respect
option (CONFIG_USB_DEVICEFS), and you get basic support for user mode to the asynchronous mode. As of kernel 2.5.66 the code and this
USB device drivers. Until relatively recently it was often (confusingly) (new) documentation need to be cross-reviewed.
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"? What files are in "devtmpfs"?
-------------------------- -----------------------------
Conventionally mounted at ``/proc/bus/usb``, usbfs features include: Conventionally mounted at ``/dev/bus/usb/``, usbfs features include:
- ``/proc/bus/usb/devices`` ... a text file showing each of the USB - ``/dev/bus/usb//BBB/DDD`` ... magic files exposing the each device's
devices on known to the kernel, and their configuration descriptors.
You can also poll() this to learn about new devices.
- ``/proc/bus/usb/BBB/DDD`` ... magic files exposing the each device's
configuration descriptors, and supporting a series of ioctls for configuration descriptors, and supporting a series of ioctls for
making device requests, including I/O to devices. (Purely for access making device requests, including I/O to devices. (Purely for access
by programs.) by programs.)
...@@ -252,100 +245,7 @@ them. HID and networking devices expose these stable IDs, so that for ...@@ -252,100 +245,7 @@ them. HID and networking devices expose these stable IDs, so that for
example you can be sure that you told the right UPS to power down its example you can be sure that you told the right UPS to power down its
second server. "usbfs" doesn't (yet) expose those IDs. second server. "usbfs" doesn't (yet) expose those IDs.
Mounting and Access Control /dev/bus/usb//BBB/DDD
---------------------------
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
--------------------- ---------------------
Use these files in one of these basic ways: Use these files in one of these basic ways:
...@@ -376,7 +276,7 @@ Life Cycle of User Mode Drivers ...@@ -376,7 +276,7 @@ Life Cycle of User Mode Drivers
Such a driver first needs to find a device file for a device it knows 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`` 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 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()` 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 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 knows how to handle. It might just reject everything except a particular
...@@ -734,3 +634,43 @@ USBDEVFS_REAPURBNDELAY ...@@ -734,3 +634,43 @@ USBDEVFS_REAPURBNDELAY
USBDEVFS_SUBMITURB USBDEVFS_SUBMITURB
*TBS* *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.
...@@ -332,7 +332,7 @@ References ...@@ -332,7 +332,7 @@ References
[5] "MBIM (Mobile Broadband Interface Model) Registry" [5] "MBIM (Mobile Broadband Interface Model) Registry"
- http://compliance.usb.org/mbim/ - http://compliance.usb.org/mbim/
[6] "/proc/bus/usb filesystem output" [6] "/dev/bus/usb filesystem output"
- Documentation/usb/proc_usb_info.txt - Documentation/usb/proc_usb_info.txt
[7] "/sys/bus/usb/devices/.../descriptors" [7] "/sys/bus/usb/devices/.../descriptors"
......
...@@ -64,7 +64,7 @@ minicom, ppp and mgetty with them. ...@@ -64,7 +64,7 @@ minicom, ppp and mgetty with them.
2. Verifying that it works 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: like this:
T: Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 T: Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
......
...@@ -189,7 +189,7 @@ Once the gadget serial driver is loaded and the USB device connected ...@@ -189,7 +189,7 @@ Once the gadget serial driver is loaded and the USB device connected
to the Linux host with a USB cable, the host system should recognize to the Linux host with a USB cable, the host system should recognize
the gadget serial device. For example, the command the gadget serial device. For example, the command
cat /proc/bus/usb/devices cat /sys/kernel/debug/usb/devices
should show something like this: should show something like this:
...@@ -221,7 +221,7 @@ Once the gadget serial driver is loaded and the USB device connected ...@@ -221,7 +221,7 @@ Once the gadget serial driver is loaded and the USB device connected
to the Linux host with a USB cable, the host system should recognize to the Linux host with a USB cable, the host system should recognize
the gadget serial device. For example, the command the gadget serial device. For example, the command
cat /proc/bus/usb/devices cat /sys/kernel/debug/usb/devices
should show something like this: should show something like this:
......
...@@ -4,7 +4,7 @@ ...@@ -4,7 +4,7 @@
The usbfs filesystem for USB devices is traditionally mounted at 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. the /proc/bus/usb/BBB/DDD files.
In many modern systems the usbfs filesystem isn't used at all. Instead In many modern systems the usbfs filesystem isn't used at all. Instead
...@@ -24,7 +24,7 @@ USB device nodes are created under /dev/usb/ or someplace similar. The ...@@ -24,7 +24,7 @@ USB device nodes are created under /dev/usb/ or someplace similar. The
none /proc/bus/usb usbfs defaults 0 0 none /proc/bus/usb usbfs defaults 0 0
to /etc/fstab. This will mount usbfs at each reboot. 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 USB device information, and user mode drivers can use usbfs
to interact with USB devices. to interact with USB devices.
...@@ -60,7 +60,7 @@ descriptors are in bus endian format! The configuration descriptor ...@@ -60,7 +60,7 @@ descriptors are in bus endian format! The configuration descriptor
are wTotalLength bytes apart. If a device returns less configuration are wTotalLength bytes apart. If a device returns less configuration
descriptor data than indicated by wTotalLength there will be a hole in descriptor data than indicated by wTotalLength there will be a hole in
the file for the missing bytes. This information is also shown 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 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, devices. You would open the /proc/bus/usb/BBB/DDD file read/write,
...@@ -79,9 +79,9 @@ usbfs mount options such as "devmode=0666" may be helpful. ...@@ -79,9 +79,9 @@ usbfs mount options such as "devmode=0666" may be helpful.
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. lines of ASCII output.
I made it ASCII instead of binary on purpose, so that someone I made it ASCII instead of binary on purpose, so that someone
can obtain some useful data from it without the use of an can obtain some useful data from it without the use of an
...@@ -104,7 +104,7 @@ E = Endpoint descriptor info. ...@@ -104,7 +104,7 @@ E = Endpoint descriptor info.
======================================================================= =======================================================================
/proc/bus/usb/devices output format: /sys/kernel/debug/usb/devices output format:
Legend: Legend:
d = decimal number (may have leading spaces or 0's) d = decimal number (may have leading spaces or 0's)
...@@ -277,16 +277,16 @@ E: Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss ...@@ -277,16 +277,16 @@ E: Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss
If a user or script is interested only in Topology info, for 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 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, only the lines that begin with the characters in square brackets,
where the valid characters are TDPCIE. With a slightly more able where the valid characters are TDPCIE. With a slightly more able
script, it can display any selected lines (for example, only T, D, script, it can display any selected lines (for example, only T, D,
and P lines) and change their output format. (The "procusb" and P lines) and change their output format. (The "procusb"
Perl script is the beginning of this idea. It will list only Perl script is the beginning of this idea. It will list only
selected lines [selected from TBDPSCIE] or "All" lines from 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 The Topology lines can be used to generate a graphic/pictorial
of the USB devices on a system's root hub. (See more below of the USB devices on a system's root hub. (See more below
...@@ -297,7 +297,7 @@ being used for each device, and which altsetting it activated. ...@@ -297,7 +297,7 @@ being used for each device, and which altsetting it activated.
The Configuration lines could be used to list maximum power The Configuration lines could be used to list maximum power
(in milliamps) that a system's USB devices are using. (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, Here's an example, from a system which has a UHCI root hub,
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment