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
34 been given a different name: *gadget drivers*. This document does not
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"
55    per device, only one of which is active at a time. Devices are supposed
57    speeds and may provide a BOS descriptor showing the lowest speed they
60 -  From USB 3.0 on configurations have one or more "functions", which
61    provide a common functionality and are grouped together for purposes
64 -  Configurations or functions have one or more "interfaces", each of which may have
65    "alternate settings". Interfaces may be standardized by USB "Class"
66    specifications, or may be specific to a vendor or device.
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
102 fully consistent. Device driver authors should make a point of doing
105 well as to make sure they aren't relying on some HCD-specific behavior.
109 USB-Standard Types
112 In ``<linux/usb/ch9.h>`` you will find the USB data types defined in
113 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
117 .. kernel-doc:: include/linux/usb/ch9.h
122 Host-Side Data Types and Macros
130 .. kernel-doc:: include/linux/usb.h
133 USB Core APIs
136 There are two basic I/O models in the USB API. The most elemental one is
138 URB's completion callback handles the next step. All USB transfer types
140 (which always have setup and status stages, but may not have a data
142 per-packet fault reports). Built on top of that is synchronous API
143 support, where a driver calls a routine that allocates one or more URBs,
145 wrappers for single-buffer control and bulk transfers (which are awkward
149 USB drivers need to provide buffers that can be used for DMA, although
155 .. kernel-doc:: drivers/usb/core/urb.c
158 .. kernel-doc:: drivers/usb/core/message.c
161 .. kernel-doc:: drivers/usb/core/file.c
164 .. kernel-doc:: drivers/usb/core/driver.c
167 .. kernel-doc:: drivers/usb/core/usb.c
170 .. kernel-doc:: drivers/usb/core/hub.c
181 on). EHCI was designed with USB 2.0; its design has features that
183 of ISO support, TD list processing). XHCI was designed with USB 3.0. It
187 based controllers (and a few non-PCI based ones) use one of those
189 also a simulator and a virtual host controller to pipe USB over the network.
193 usb_bus <usb_bus>` is a rather thin layer that became available
195 is a more featureful layer
197 significantly reduce hcd-specific behaviors.
199 .. kernel-doc:: drivers/usb/core/hcd.c
202 .. kernel-doc:: drivers/usb/core/hcd-pci.c
205 .. kernel-doc:: drivers/usb/core/buffer.c
208 The USB character device nodes
212 to avoid writing new kernel code for your USB driver. User mode device
217  - `libusb <http://libusb.sourceforge.net>`__ for C/C++, and
218  - `jUSB <http://jUSB.sourceforge.net>`__ for Java.
220 Some old information about it can be seen at the "USB Device Filesystem"
221 section of the USB Guide. The latest copy of the USB Guide can be found
222 at http://www.linux-usb.org/
226   - They were used to be implemented via *usbfs*, but this is not part of
229    - This particular documentation is incomplete, especially with respect
231      (new) documentation need to be cross-reviewed.
234 -----------------------------
236 Conventionally mounted at ``/dev/bus/usb/``, usbfs features include:
238 -  ``/dev/bus/usb/BBB/DDD`` ... magic files exposing the each device's
239    configuration descriptors, and supporting a series of ioctls for
243 Each bus is given a number (``BBB``) based on when it was enumerated; within
244 each bus, each device is given a similar number (``DDD``). Those ``BBB/DDD``
253 /dev/bus/usb/BBB/DDD
254 --------------------
258 - *They can be read,* producing first the device descriptor (18 bytes) and
259   then the descriptors for the current configuration. See the USB 2.0 spec
262   order, although a few of the fields in the device descriptor (both of
263   the BCD-encoded fields, and the vendor and product IDs) will be
268 - *Perform USB operations* using *ioctl()* requests to make endpoint I/O
272   device files at a time. This means that if you are synchronously reading
273   an endpoint from one thread, you won't be able to write to a different
278 Each connected USB device has one file.  The ``BBB`` indicates the bus
282 it's relatively common for devices to re-enumerate while they are
284 or USB cable), so a device might be ``002/027`` when you first connect
289 configuration of the device.  Multi-byte fields in the device descriptor
292 are wTotalLength bytes apart. If a device returns less configuration
293 descriptor data than indicated by wTotalLength there will be a hole in
295 in text form by the ``/sys/kernel/debug/usb/devices`` file, described later.
297 These files may also be used to write user-level drivers for the USB
298 devices.  You would open the ``/dev/bus/usb/BBB/DDD`` file read/write,
302 control, bulk, or other kinds of USB transfers.  The IOCTLs are
304 source code (``linux/drivers/usb/core/devio.c``) is the primary reference
314 -------------------------------
316 Such a driver first needs to find a device file for a device it knows
317 how to handle. Maybe it was told about it because a ``/sbin/hotplug``
319 maybe it's an application that scans all the ``/dev/bus/usb`` device files,
322 knows how to handle. It might just reject everything except a particular
323 vendor and product ID, or need a more complex policy.
325 Never assume there will only be one such device on the system at a time!
326 If your code can't handle more than one device at a time, at least
333 (An example might be software using vendor-specific control requests for
334 some initialization or configuration tasks, with a kernel driver for the
337 More likely, you need a more complex style driver: one using non-control
344 can also be used in a synchronous "one shot" style.
346 Your user-mode driver should never need to worry about cleaning up
351 --------------------
356     #include <linux/usb.h>
360 The standard USB device model requests, from "Chapter 9" of the USB 2.0
361 specification, are automatically included from the ``<linux/usb/ch9.h>``
366 (unless they fail). A return of zero indicates success; otherwise, a
367 standard USB error code is returned (These are documented in
368 :ref:`usb-error-codes`).
372 supports a limited RPC style RPC access. Devices are configured by
373 hub_wq (in the kernel) setting a device-wide *configuration* that
375 endpoints are part of USB *interfaces*, which may have *altsettings*
377 have a single configuration and interface, so drivers for them will
383 A number of usbfs requests don't deal very directly with device I/O.
388     This is used to force usbfs to claim a specific interface, which has
397     This claim will be released by a RELEASEINTERFACE ioctl, or by
402     Says whether the device is lowspeed. The ioctl parameter points to a
412     *You can't tell whether a "not slow" device is connected at high
418     Returns the name of the kernel driver bound to a given interface (a
419     string). Parameter is a pointer to this structure, which is
430     Passes a request from userspace through to a kernel driver that has
440 	 * 'request' becomes the driver->ioctl() 'code' parameter.
442 	 * is copied to or from the driver->ioctl() 'buf' parameter.
459     filesystem operations even when they don't create a character or
461     devices what device special file should be used. Two pre-defined
468     implicitly or because of a USBDEVFS_CLAIMINTERFACE call, before the
490 	need to completely handshake with the device, using a request
495     which are considered to be privileged on a usbfs file descriptor.
496     This includes claiming arbitrary interfaces, resetting a device on
498     issuing USBDEVFS_IOCTL calls. The ioctl parameter is a 32 bit mask
509 a time.
512     Issues a bulk read or write request to the device. The ioctl
513     parameter is a pointer to this structure::
522     The ``ep`` value identifies a bulk endpoint number (1 to 15, as
537     returning ``-EPIPE`` status to a data transfer request. Do not issue
542     Issues a control request to the device. The ioctl parameter points
543     to a structure like this::
556     SETUP packet to be sent to the device; see the USB 2.0 specification
557     for details. The bRequestType value is composed by combining a
558     ``USB_TYPE_*`` value, a ``USB_DIR_*`` value, and a ``USB_RECIP_*``
559     value (from ``linux/usb.h``). If wLength is nonzero, it describes
564     from a device; usbfs has a limit, and some host controller drivers
565     have a limit. (That's not usually a problem.) *Also* there's no way
566     to say it's not OK to get a short read back from the device.
569     Does a USB level device reset. The ioctl parameter is ignored. After
581     a pointer to a structure like this::
598     device. The parameter is an integer holding the number of a
614 be used for other kinds of USB requests too. In such cases, the
619 These requests are packaged into a structure that resembles the URB used
623 and a user "context" value serving to uniquely identify each request.
624 (It's usually a pointer to per-request data.) Flags can modify requests
627 Each request can specify a realtime signal number (between SIGRTMIN and
628 SIGRTMAX, inclusive) to request a signal be sent when the request
678 The USB devices
681 The USB devices are now exported via debugfs:
683 -  ``/sys/kernel/debug/usb/devices`` ... a text file showing each of the USB
687 /sys/kernel/debug/usb/devices
688 -----------------------------
692 (including class and vendor status) is available from device-specific
701     fd = open("/sys/kernel/debug/usb/devices", O_RDONLY);
705 	poll(&pfd, 1, -1);
713 udev or HAL to initialize a device or start a user-mode helper program,
722 Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
724 Each line is tagged with a one-character ID for that line::
727 	B = Bandwidth (applies only to USB host controllers, which are
737 /sys/kernel/debug/usb/devices output format
766 	1.5	Mbit/s for low speed USB
767 	12	Mbit/s for full speed USB
768 	480	Mbit/s for high speed USB (added for USB 2.0);
769 		also used for Wireless USB, which has no fixed speed
770 	5000	Mbit/s for SuperSpeed USB (added for USB 3.0)
774 too low by 1.  For example, a device plugged into port 4 will
795 those transfers.  For a low or full speed bus (loosely, "USB 1.1"),
796 90% of the bus bandwidth is reserved.  For a high speed bus (loosely,
797 "USB 2.0") 80% is reserved.
816 	|   |__Device USB version
834 	|      For USB host controller drivers (virtual root hubs) this may
841 	|      For older USB host controller drivers (virtual root hubs) this
842 	|      indicates the driver; for newer ones, it's a product (and vendor)
848 	|      For USB host controller drivers (virtual root hubs) this is
849 	|      some unique ID, normally a bus ID (address or slot name) that
867 USB devices may have multiple configurations, each of which act
868 rather differently.  For example, a bus-powered configuration
869 might be much less capable than one that is self-powered.  Only
870 one device configuration can be active at a time; most devices
874 interface serves a distinct "function", which is typically bound
875 to a different USB device driver.  One common example is a USB
876 speaker with an audio interface for playback, and a HID interface
895 A given interface may have one or more "alternate" settings.
896 For example, default settings may not use more than a small
898 of bus bandwidth, drivers must select a non-default altsetting.
900 Only one setting for an interface may be active at a time, and
901 only one driver may bind to an interface at a time.  Most devices
922 the per-microframe data transfer size.  For "high bandwidth"
926 With the Linux-USB stack, periodic bandwidth reservations use the
933 If a user or script is interested only in Topology info, for
934 example, use something like ``grep ^T: /sys/kernel/debug/usb/devices``
935 for only the Topology lines.  A command like
936 ``grep -i ^[tdp]: /sys/kernel/debug/usb/devices`` can be used to list
938 where the valid characters are TDPCIE.  With a slightly more able
943 ``/sys/kernel/debug/usb/devices``.)
945 The Topology lines can be used to generate a graphic/pictorial
946 of the USB devices on a system's root hub.  (See more below
953 (in milliamps) that a system's USB devices are using.
954 For example, ``grep ^C: /sys/kernel/debug/usb/devices``.
957 Here's an example, from a system which has a UHCI root hub,
958 an external hub connected to the root hub, and a mouse and
959 a serial converter connected to the external hub.
967 	S:  Product=USB UHCI Root Hub
991 	S:  Product=Peracom USB to Serial Converter
1015                       +------------------+
1017                       +------------------+   (nn) is Mbps.
1019                       +------------------+
1022             +-----------------------+
1023   Level 1   | Dev#2: 4-port hub (12)|
1024             +-----------------------+
1026             +-----------------------+
1030                +--------------------+      +--------------------+
1032                +--------------------+      +--------------------+
1036 Or, in a more tree-like structure (ports [Connectors] without