mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2025-01-06 05:06:29 +00:00
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: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab
Jonathan Corbet
parent
7c2a3e9448
commit
8a6a285d61
@ -111,7 +111,8 @@ USB-Standard Types
|
||||
|
||||
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:
|
||||
@ -204,40 +205,32 @@ significantly reduce hcd-specific behaviors.
|
||||
.. 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
|
||||
to the asynchronous mode. As of kernel 2.5.66 the code and this
|
||||
(new) documentation need to be cross-reviewed.
|
||||
- They were used to be implemented via *usbfs*, but this is not part of
|
||||
the sysfs debug interface.
|
||||
|
||||
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.
|
||||
- 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.
|
||||
|
||||
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
|
||||
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
|
||||
- ``/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.)
|
||||
@ -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
|
||||
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:
|
||||
@ -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
|
||||
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
|
||||
@ -734,3 +634,43 @@ USBDEVFS_REAPURBNDELAY
|
||||
|
||||
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.
|
||||
|
||||
@ -332,7 +332,7 @@ References
|
||||
[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"
|
||||
|
||||
@ -64,7 +64,7 @@ minicom, ppp and mgetty with them.
|
||||
|
||||
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
|
||||
|
||||
@ -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
|
||||
the gadget serial device. For example, the command
|
||||
|
||||
cat /proc/bus/usb/devices
|
||||
cat /sys/kernel/debug/usb/devices
|
||||
|
||||
should show something like this:
|
||||
|
||||
@ -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
|
||||
the gadget serial device. For example, the command
|
||||
|
||||
cat /proc/bus/usb/devices
|
||||
cat /sys/kernel/debug/usb/devices
|
||||
|
||||
should show something like this:
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
|
||||
|
||||
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
|
||||
@ -24,7 +24,7 @@ USB device nodes are created under /dev/usb/ or someplace similar. The
|
||||
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.
|
||||
|
||||
@ -60,7 +60,7 @@ descriptors are in bus endian format! The configuration descriptor
|
||||
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,
|
||||
@ -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.
|
||||
I made it ASCII instead of binary on purpose, so that someone
|
||||
can obtain some useful data from it without the use of an
|
||||
@ -104,7 +104,7 @@ E = Endpoint descriptor info.
|
||||
|
||||
=======================================================================
|
||||
|
||||
/proc/bus/usb/devices output format:
|
||||
/sys/kernel/debug/usb/devices output format:
|
||||
|
||||
Legend:
|
||||
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
|
||||
|
||||
|
||||
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
|
||||
@ -297,7 +297,7 @@ being used for each device, and which altsetting it activated.
|
||||
|
||||
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,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user