Lines Matching +full:sub +full:- +full:bus
1 .. _usb-hostside-api:
4 The Linux-USB Host Side API
10 A Universal Serial Bus (USB) is used to connect a host, such as a PC or
18 That master/slave asymmetry was designed-in for a number of reasons, one
22 distributed auto-configuration since the pre-designated master node
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
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
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
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
120 .. kernel-doc:: drivers/usb/common/common.c
128 Host-Side Data Types and Macros
136 .. kernel-doc:: include/linux/usb.h
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
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
193 based controllers (and a few non-PCI based ones) use one of those
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
223 - `libusb <http://libusb.sourceforge.net>`__ for C/C++, and
224 - `jUSB <http://jUSB.sourceforge.net>`__ for Java.
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
249 Each bus is given a number (``BBB``) based on when it was enumerated; within
250 each bus, each device is given a similar number (``DDD``). Those ``BBB/DDD``
259 /dev/bus/usb/BBB/DDD
260 --------------------
264 - *They can be read,* producing first the device descriptor (18 bytes) and
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
285 number. The ``DDD`` indicates the device address on that bus. Both
288 it's relatively common for devices to re-enumerate while they are
295 configuration of the device. Multi-byte fields in the device descriptor
297 descriptors are in bus endian format! The configuration descriptor
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,
320 -------------------------------
325 maybe it's an application that scans all the ``/dev/bus/usb`` device files,
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 --------------------
374 :ref:`usb-error-codes`).
379 hub_wq (in the kernel) setting a device-wide *configuration* that
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
636 (It's usually a pointer to per-request data.) Flags can modify requests
695 - ``/sys/kernel/debug/usb/devices`` ... a text file showing each of the USB
700 -----------------------------
704 (including class and vendor status) is available from device-specific
717 poll(&pfd, 1, -1);
725 udev or HAL to initialize a device or start a user-mode helper program,
736 Each line is tagged with a one-character ID for that line::
764 T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=dddd MxCh=dd
771 | | |__Level in topology for this bus
796 | |__Total Bandwidth allocated to this bus
806 those transfers. For a low or full speed bus (loosely, "USB 1.1"),
807 90% of the bus bandwidth is reserved. For a high speed bus (loosely,
816 D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
821 D: Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
860 | some unique ID, normally a bus ID (address or slot name) that
879 rather differently. For example, a bus-powered configuration
880 might be much less capable than one that is self-powered. Only
894 I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss
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
947 ``grep -i ^[tdp]: /sys/kernel/debug/usb/devices`` can be used to list
974 T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
976 D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
981 I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
984 T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
985 D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
988 I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
991 T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
992 D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
995 I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
998 T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
999 D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
1004 I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
1015 T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
1016 T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
1017 I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
1018 T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
1019 I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
1020 T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
1021 I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
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