Lines Matching +full:usb +full:- +full:c
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 ``<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
142 per-packet fault reports). Built on top of that is synchronous API
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.
192 For historical reasons they are in two layers: :c:type:`struct
194 in the 2.2 kernels, while :c:type:`struct usb_hcd <usb_hcd>`
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
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
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
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
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 -------------------------------
319 maybe it's an application that scans all the ``/dev/bus/usb`` device files,
320 and ignores most devices. In either case, it should :c:func:`read()`
333 (An example might be software using vendor-specific control requests for
337 More likely, you need a more complex style driver: one using non-control
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>``
367 standard USB error code is returned (These are documented in
368 :ref:`usb-error-codes`).
373 hub_wq (in the kernel) setting a device-wide *configuration* that
375 endpoints are part of USB *interfaces*, which may have *altsettings*
440 * 'request' becomes the driver->ioctl() 'code' parameter.
442 * is copied to or from the driver->ioctl() 'buf' parameter.
461 devices what device special file should be used. Two pre-defined
537 returning ``-EPIPE`` status to a data transfer request. Do not issue
556 SETUP packet to be sent to the device; see the USB 2.0 specification
559 value (from ``linux/usb.h``). If wLength is nonzero, it describes
569 Does a USB level device reset. The ioctl parameter is ignored. After
597 Issues the :c:func:`usb_set_configuration()` call for the
614 be used for other kinds of USB requests too. In such cases, the
624 (It's usually a pointer to per-request data.) Flags can modify requests
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
733 C = Configuration descriptor info. (* = active configuration)
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)
795 those transfers. For a low or full speed bus (loosely, "USB 1.1"),
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
848 | For USB host controller drivers (virtual root hubs) this is
859 C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA
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
875 to a different USB device driver. One common example is a USB
898 of bus bandwidth, drivers must select a non-default altsetting.
922 the per-microframe data transfer size. For "high bandwidth"
926 With the Linux-USB stack, periodic bandwidth reservations use the
934 example, use something like ``grep ^T: /sys/kernel/debug/usb/devices``
936 ``grep -i ^[tdp]: /sys/kernel/debug/usb/devices`` can be used to list
943 ``/sys/kernel/debug/usb/devices``.)
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``.
967 S: Product=USB UHCI Root Hub
969 C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA
976 C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
983 C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
991 S: Product=Peracom USB to Serial Converter
992 C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
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