driver-api/usb/usb.rst

1 .. _usb-hostside-api:
4 The Linux-USB Host Side API
7 Introduction to USB on Linux
10 A Universal Serial Bus (USB) is used to connect a host, such as a PC or
11 workstation, to a number of peripheral devices. USB uses a tree
14 support several such trees of USB devices, usually
15 a few USB 3.0 (5 GBit/s) or USB 3.1 (10 GBit/s) and some legacy
16 USB 2.0 (480 MBit/s) busses just in case.
18 That master/slave asymmetry was designed-in for a number of reasons, one
20 downstream or it does not matter with a type C plug (or they are built into the
22 distributed auto-configuration since the pre-designated master node
25 Kernel developers added USB support to Linux early in the 2.2 kernel
27 for each new generation of USB, various host controllers gained support,
31 Linux can run inside USB devices as well as on the hosts that control
32 the devices. But USB device drivers running inside those peripherals
37 USB Host-Side API Model
40 Host-side drivers for USB devices talk to the "usbcore" APIs. There are
41 two. One is intended for *general-purpose* drivers (exposed through
44 of USB devices) and several different kinds of *host controller
47 The device model seen by USB drivers is relatively complex.
49 -  USB supports four kinds of data transfers (control, bulk, interrupt,
54 -  The device description model includes one or more "configurations"
60 -  From USB 3.0 on configurations have one or more "functions", which
64 -  Configurations or functions have one or more "interfaces", each of which may have
65    "alternate settings". Interfaces may be standardized by USB "Class"
68    USB device drivers actually bind to interfaces, not devices. Think of
70    where the distinction is important. *Most USB devices are simple,
74 -  Interfaces have one or more "endpoints", each of which supports one
79 -  Data transfer on USB is packetized; each endpoint has a maximum
84 -  The Linux USB API supports synchronous calls for control and bulk
86    transfer, using request structures called "URBs" (USB Request
89 Accordingly, the USB Core API exposed to device drivers covers quite a
90 lot of territory. You'll probably need to consult the USB 3.0
91 specification, available online from www.usb.org at no cost, as well as
94 The only host-side drivers that actually touch hardware (reading/writing
101 faults (including software-induced ones like unlinking an URB) isn't yet
105 well as to make sure they aren't relying on some HCD-specific behavior.
109 USB-Standard Types
112 In ``include/uapi/linux/usb/ch9.h`` you will find the USB data types defined
113 in chapter 9 of the USB specification. These data types are used throughout
114 USB, and in APIs including this host side API, gadget APIs, usb character
116 ``include/linux/usb/ch9.h``, which also contains declarations of a few
118 are in ``drivers/usb/common/common.c``.
120 .. kernel-doc:: drivers/usb/common/common.c
124 defined in ``drivers/usb/common/debug.c``.
128 Host-Side Data Types and Macros
136 .. kernel-doc:: include/linux/usb.h
139 USB Core APIs
142 There are two basic I/O models in the USB API. The most elemental one is
144 URB's completion callback handles the next step. All USB transfer types
148 per-packet fault reports). Built on top of that is synchronous API
151 wrappers for single-buffer control and bulk transfers (which are awkward
155 USB drivers need to provide buffers that can be used for DMA, although
161 .. kernel-doc:: drivers/usb/core/urb.c
164 .. kernel-doc:: drivers/usb/core/message.c
167 .. kernel-doc:: drivers/usb/core/file.c
170 .. kernel-doc:: drivers/usb/core/driver.c
173 .. kernel-doc:: drivers/usb/core/usb.c
176 .. kernel-doc:: drivers/usb/core/hub.c
187 on). EHCI was designed with USB 2.0; its design has features that
189 of ISO support, TD list processing). XHCI was designed with USB 3.0. It
193 based controllers (and a few non-PCI based ones) use one of those
195 also a simulator and a virtual host controller to pipe USB over the network.
198 For historical reasons they are in two layers: :c:type:`struct
200 in the 2.2 kernels, while :c:type:`struct usb_hcd <usb_hcd>`
203 significantly reduce hcd-specific behaviors.
205 .. kernel-doc:: drivers/usb/core/hcd.c
208 .. kernel-doc:: drivers/usb/core/hcd-pci.c
211 .. kernel-doc:: drivers/usb/core/buffer.c
214 The USB character device nodes
218 to avoid writing new kernel code for your USB driver. User mode device
223  - `libusb <http://libusb.sourceforge.net>`__ for C/C++, and
224  - `jUSB <http://jUSB.sourceforge.net>`__ for Java.
226 Some old information about it can be seen at the "USB Device Filesystem"
227 section of the USB Guide. The latest copy of the USB Guide can be found
228 at http://www.linux-usb.org/
232   - They were used to be implemented via *usbfs*, but this is not part of
235    - This particular documentation is incomplete, especially with respect
237      (new) documentation need to be cross-reviewed.
240 -----------------------------
242 Conventionally mounted at ``/dev/bus/usb/``, usbfs features include:
244 -  ``/dev/bus/usb/BBB/DDD`` ... magic files exposing the each device's
259 /dev/bus/usb/BBB/DDD
260 --------------------
264 - *They can be read,* producing first the device descriptor (18 bytes) and
265   then the descriptors for the current configuration. See the USB 2.0 spec
269   the BCD-encoded fields, and the vendor and product IDs) will be
274 - *Perform USB operations* using *ioctl()* requests to make endpoint I/O
284 Each connected USB device has one file.  The ``BBB`` indicates the bus
288 it's relatively common for devices to re-enumerate while they are
290 or USB cable), so a device might be ``002/027`` when you first connect
295 configuration of the device.  Multi-byte fields in the device descriptor
301 in text form by the ``/sys/kernel/debug/usb/devices`` file, described later.
303 These files may also be used to write user-level drivers for the USB
304 devices.  You would open the ``/dev/bus/usb/BBB/DDD`` file read/write,
308 control, bulk, or other kinds of USB transfers.  The IOCTLs are
310 source code (``linux/drivers/usb/core/devio.c``) is the primary reference
320 -------------------------------
325 maybe it's an application that scans all the ``/dev/bus/usb`` device files,
326 and ignores most devices. In either case, it should :c:func:`read()`
339 (An example might be software using vendor-specific control requests for
343 More likely, you need a more complex style driver: one using non-control
352 Your user-mode driver should never need to worry about cleaning up
357 --------------------
362     #include <linux/usb.h>
366 The standard USB device model requests, from "Chapter 9" of the USB 2.0
367 specification, are automatically included from the ``<linux/usb/ch9.h>``
373 standard USB error code is returned (These are documented in
374 :ref:`usb-error-codes`).
379 hub_wq (in the kernel) setting a device-wide *configuration* that
381 endpoints are part of USB *interfaces*, which may have *altsettings*
452 	 * 'request' becomes the driver->ioctl() 'code' parameter.
454 	 * is copied to or from the driver->ioctl() 'buf' parameter.
473     devices what device special file should be used. Two pre-defined
549     returning ``-EPIPE`` status to a data transfer request. Do not issue
568     SETUP packet to be sent to the device; see the USB 2.0 specification
571     value (from ``linux/usb.h``). If wLength is nonzero, it describes
581     Does a USB level device reset. The ioctl parameter is ignored. After
609     Issues the :c:func:`usb_set_configuration()` call for the
626 be used for other kinds of USB requests too. In such cases, the
636 (It's usually a pointer to per-request data.) Flags can modify requests
690 The USB devices
693 The USB devices are now exported via debugfs:
695 -  ``/sys/kernel/debug/usb/devices`` ... a text file showing each of the USB
699 /sys/kernel/debug/usb/devices
700 -----------------------------
704 (including class and vendor status) is available from device-specific
713     fd = open("/sys/kernel/debug/usb/devices", O_RDONLY);
717 	poll(&pfd, 1, -1);
725 udev or HAL to initialize a device or start a user-mode helper program,
734 Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
736 Each line is tagged with a one-character ID for that line::
739 	B = Bandwidth (applies only to USB host controllers, which are
745 	C = Configuration descriptor info. (* = active configuration)
749 /sys/kernel/debug/usb/devices output format
778 	1.5	Mbit/s for low speed USB
779 	12	Mbit/s for full speed USB
780 	480	Mbit/s for high speed USB (added for USB 2.0)
781 	5000	Mbit/s for SuperSpeed USB (added for USB 3.0)
806 those transfers.  For a low or full speed bus (loosely, "USB 1.1"),
808 "USB 2.0") 80% is reserved.
827 	|   |__Device USB version
845 	|      For USB host controller drivers (virtual root hubs) this may
852 	|      For older USB host controller drivers (virtual root hubs) this
859 	|      For USB host controller drivers (virtual root hubs) this is
870 	C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA
878 USB devices may have multiple configurations, each of which act
879 rather differently.  For example, a bus-powered configuration
880 might be much less capable than one that is self-powered.  Only
886 to a different USB device driver.  One common example is a USB
909 of bus bandwidth, drivers must select a non-default altsetting.
933 the per-microframe data transfer size.  For "high bandwidth"
937 With the Linux-USB stack, periodic bandwidth reservations use the
945 example, use something like ``grep ^T: /sys/kernel/debug/usb/devices``
947 ``grep -i ^[tdp]: /sys/kernel/debug/usb/devices`` can be used to list
954 ``/sys/kernel/debug/usb/devices``.)
957 of the USB devices on a system's root hub.  (See more below
964 (in milliamps) that a system's USB devices are using.
965 For example, ``grep ^C: /sys/kernel/debug/usb/devices``.
978 	S:  Product=USB UHCI Root Hub
980 	C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr=  0mA
987 	C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
994 	C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
1002 	S:  Product=Peracom USB to Serial Converter
1003 	C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
1026                       +------------------+
1028                       +------------------+   (nn) is Mbps.
1030                       +------------------+
1033             +-----------------------+
1034   Level 1   | Dev#2: 4-port hub (12)|
1035             +-----------------------+
1037             +-----------------------+
1041                +--------------------+      +--------------------+
1043                +--------------------+      +--------------------+
1047 Or, in a more tree-like structure (ports [Connectors] without