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 ``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*
446 * 'request' becomes the driver->ioctl() 'code' parameter.
448 * is copied to or from the driver->ioctl() 'buf' parameter.
467 devices what device special file should be used. Two pre-defined
543 returning ``-EPIPE`` status to a data transfer request. Do not issue
562 SETUP packet to be sent to the device; see the USB 2.0 specification
565 value (from ``linux/usb.h``). If wLength is nonzero, it describes
575 Does a USB level device reset. The ioctl parameter is ignored. After
603 Issues the :c:func:`usb_set_configuration()` call for the
620 be used for other kinds of USB requests too. In such cases, the
630 (It's usually a pointer to per-request data.) Flags can modify requests
684 The USB devices
687 The USB devices are now exported via debugfs:
689 - ``/sys/kernel/debug/usb/devices`` ... a text file showing each of the USB
693 /sys/kernel/debug/usb/devices
694 -----------------------------
698 (including class and vendor status) is available from device-specific
707 fd = open("/sys/kernel/debug/usb/devices", O_RDONLY);
711 poll(&pfd, 1, -1);
719 udev or HAL to initialize a device or start a user-mode helper program,
728 Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
730 Each line is tagged with a one-character ID for that line::
733 B = Bandwidth (applies only to USB host controllers, which are
739 C = Configuration descriptor info. (* = active configuration)
743 /sys/kernel/debug/usb/devices output format
772 1.5 Mbit/s for low speed USB
773 12 Mbit/s for full speed USB
774 480 Mbit/s for high speed USB (added for USB 2.0);
775 also used for Wireless USB, which has no fixed speed
776 5000 Mbit/s for SuperSpeed USB (added for USB 3.0)
801 those transfers. For a low or full speed bus (loosely, "USB 1.1"),
803 "USB 2.0") 80% is reserved.
822 | |__Device USB version
840 | For USB host controller drivers (virtual root hubs) this may
847 | For older USB host controller drivers (virtual root hubs) this
854 | For USB host controller drivers (virtual root hubs) this is
865 C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA
873 USB devices may have multiple configurations, each of which act
874 rather differently. For example, a bus-powered configuration
875 might be much less capable than one that is self-powered. Only
881 to a different USB device driver. One common example is a USB
904 of bus bandwidth, drivers must select a non-default altsetting.
928 the per-microframe data transfer size. For "high bandwidth"
932 With the Linux-USB stack, periodic bandwidth reservations use the
940 example, use something like ``grep ^T: /sys/kernel/debug/usb/devices``
942 ``grep -i ^[tdp]: /sys/kernel/debug/usb/devices`` can be used to list
949 ``/sys/kernel/debug/usb/devices``.)
952 of the USB devices on a system's root hub. (See more below
959 (in milliamps) that a system's USB devices are using.
960 For example, ``grep ^C: /sys/kernel/debug/usb/devices``.
973 S: Product=USB UHCI Root Hub
975 C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA
982 C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
989 C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
997 S: Product=Peracom USB to Serial Converter
998 C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
1021 +------------------+
1023 +------------------+ (nn) is Mbps.
1025 +------------------+
1028 +-----------------------+
1029 Level 1 | Dev#2: 4-port hub (12)|
1030 +-----------------------+
1032 +-----------------------+
1036 +--------------------+ +--------------------+
1038 +--------------------+ +--------------------+
1042 Or, in a more tree-like structure (ports [Connectors] without