Lines Matching +full:usb +full:- +full:host
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
12 structure, with the host as the root (the system's master), hubs as
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
21 peripheral). Also, the host software doesn't need to deal with
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
103 disconnect testing (while the device is active) with each different host
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
131 The host side API exposes several layers to drivers, some of which are
132 more necessary than others. These support lifecycle models for host side
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
165 .. kernel-doc:: drivers/usb/core/message.c
168 .. kernel-doc:: drivers/usb/core/file.c
171 .. kernel-doc:: drivers/usb/core/driver.c
174 .. kernel-doc:: drivers/usb/core/usb.c
177 .. kernel-doc:: drivers/usb/core/hub.c
180 Host Controller APIs
183 These APIs are only for use by host controller drivers, most of which
188 on). EHCI was designed with USB 2.0; its design has features that
190 of ISO support, TD list processing). XHCI was designed with USB 3.0. It
193 There are host controllers other than the "big three", although most PCI
194 based controllers (and a few non-PCI based ones) use one of those
195 interfaces. Not all host controllers use DMA; some use PIO, and there is
196 also a simulator and a virtual host controller to pipe USB over the network.
204 significantly reduce hcd-specific behaviors.
206 .. kernel-doc:: drivers/usb/core/hcd.c
209 .. kernel-doc:: drivers/usb/core/hcd-pci.c
212 .. kernel-doc:: drivers/usb/core/buffer.c
215 The USB character device nodes
219 to avoid writing new kernel code for your USB driver. User mode device
224 - `libusb <http://libusb.sourceforge.net>`__ for C/C++, and
225 - `jUSB <http://jUSB.sourceforge.net>`__ for Java.
227 Some old information about it can be seen at the "USB Device Filesystem"
228 section of the USB Guide. The latest copy of the USB Guide can be found
229 at http://www.linux-usb.org/
233 - They were used to be implemented via *usbfs*, but this is not part of
236 - This particular documentation is incomplete, especially with respect
238 (new) documentation need to be cross-reviewed.
241 -----------------------------
243 Conventionally mounted at ``/dev/bus/usb/``, usbfs features include:
245 - ``/dev/bus/usb/BBB/DDD`` ... magic files exposing the each device's
260 /dev/bus/usb/BBB/DDD
261 --------------------
265 - *They can be read,* producing first the device descriptor (18 bytes) and
266 then the descriptors for the current configuration. See the USB 2.0 spec
268 multibyte values from little endian format to your native host byte
270 the BCD-encoded fields, and the vendor and product IDs) will be
275 - *Perform USB operations* using *ioctl()* requests to make endpoint I/O
285 Each connected USB device has one file. The ``BBB`` indicates the bus
289 it's relatively common for devices to re-enumerate while they are
291 or USB cable), so a device might be ``002/027`` when you first connect
296 configuration of the device. Multi-byte fields in the device descriptor
297 are converted to host endianness by the kernel. The configuration
302 in text form by the ``/sys/kernel/debug/usb/devices`` file, described later.
304 These files may also be used to write user-level drivers for the USB
305 devices. You would open the ``/dev/bus/usb/BBB/DDD`` file read/write,
309 control, bulk, or other kinds of USB transfers. The IOCTLs are
311 source code (``linux/drivers/usb/core/devio.c``) is the primary reference
321 -------------------------------
326 maybe it's an application that scans all the ``/dev/bus/usb`` device files,
340 (An example might be software using vendor-specific control requests for
344 More likely, you need a more complex style driver: one using non-control
353 Your user-mode driver should never need to worry about cleaning up
358 --------------------
363 #include <linux/usb.h>
367 The standard USB device model requests, from "Chapter 9" of the USB 2.0
368 specification, are automatically included from the ``<linux/usb/ch9.h>``
374 standard USB error code is returned (These are documented in
375 :ref:`usb-error-codes`).
380 hub_wq (in the kernel) setting a device-wide *configuration* that
382 endpoints are part of USB *interfaces*, which may have *altsettings*
453 * 'request' becomes the driver->ioctl() 'code' parameter.
455 * is copied to or from the driver->ioctl() 'buf' parameter.
474 devices what device special file should be used. Two pre-defined
496 if the device's endpoint sends data to the host.
537 referring to an endpoint which sends data to the host from the
547 which sends data to the host from the device.
550 returning ``-EPIPE`` status to a data transfer request. Do not issue
551 the control request directly, since that could invalidate the host's
569 SETUP packet to be sent to the device; see the USB 2.0 specification
572 value (from ``linux/usb.h``). If wLength is nonzero, it describes
577 from a device; usbfs has a limit, and some host controller drivers
582 Does a USB level device reset. The ioctl parameter is ignored. After
627 be used for other kinds of USB requests too. In such cases, the
637 (It's usually a pointer to per-request data.) Flags can modify requests
691 The USB devices
694 The USB devices are now exported via debugfs:
696 - ``/sys/kernel/debug/usb/devices`` ... a text file showing each of the USB
700 /sys/kernel/debug/usb/devices
701 -----------------------------
705 (including class and vendor status) is available from device-specific
714 fd = open("/sys/kernel/debug/usb/devices", O_RDONLY);
718 poll(&pfd, 1, -1);
726 udev or HAL to initialize a device or start a user-mode helper program,
735 Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
737 Each line is tagged with a one-character ID for that line::
740 B = Bandwidth (applies only to USB host controllers, which are
750 /sys/kernel/debug/usb/devices output format
779 1.5 Mbit/s for low speed USB
780 12 Mbit/s for full speed USB
781 480 Mbit/s for high speed USB (added for USB 2.0)
782 5000 Mbit/s for SuperSpeed USB (added for USB 3.0)
807 those transfers. For a low or full speed bus (loosely, "USB 1.1"),
809 "USB 2.0") 80% is reserved.
828 | |__Device USB version
846 | For USB host controller drivers (virtual root hubs) this may
853 | For older USB host controller drivers (virtual root hubs) this
860 | For USB host controller drivers (virtual root hubs) this is
879 USB devices may have multiple configurations, each of which act
880 rather differently. For example, a bus-powered configuration
881 might be much less capable than one that is self-powered. Only
887 to a different USB device driver. One common example is a USB
910 of bus bandwidth, drivers must select a non-default altsetting.
934 the per-microframe data transfer size. For "high bandwidth"
938 With the Linux-USB stack, periodic bandwidth reservations use the
946 example, use something like ``grep ^T: /sys/kernel/debug/usb/devices``
948 ``grep -i ^[tdp]: /sys/kernel/debug/usb/devices`` can be used to list
955 ``/sys/kernel/debug/usb/devices``.)
958 of the USB devices on a system's root hub. (See more below
965 (in milliamps) that a system's USB devices are using.
966 For example, ``grep ^C: /sys/kernel/debug/usb/devices``.
979 S: Product=USB UHCI Root Hub
1003 S: Product=Peracom USB to Serial Converter
1027 +------------------+
1029 +------------------+ (nn) is Mbps.
1031 +------------------+
1034 +-----------------------+
1035 Level 1 | Dev#2: 4-port hub (12)|
1036 +-----------------------+
1038 +-----------------------+
1042 +--------------------+ +--------------------+
1044 +--------------------+ +--------------------+
1048 Or, in a more tree-like structure (ports [Connectors] without