Lines Matching +full:power +full:- +full:stable +full:- +full:time
1 .. _usb-hostside-api:
4 The Linux-USB Host Side API
18 That master/slave asymmetry was designed-in for a number of reasons, one
22 distributed auto-configuration since the pre-designated master node
29 measurement and improved power management introduced.
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"
55 per device, only one of which is active at a time. Devices are supposed
60 - From USB 3.0 on configurations have one or more "functions", which
62 of power management.
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
117 .. kernel-doc:: include/linux/usb/ch9.h
122 Host-Side Data Types and Macros
130 .. kernel-doc:: include/linux/usb.h
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
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
187 based controllers (and a few non-PCI based ones) use one of those
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
217 - `libusb <http://libusb.sourceforge.net>`__ for C/C++, and
218 - `jUSB <http://jUSB.sourceforge.net>`__ for Java.
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 -----------------------------
238 - ``/dev/bus/usb/BBB/DDD`` ... magic files exposing the each device's
245 paths are not "stable" identifiers; expect them to change even if you
247 think of saving these in application configuration files.* Stable
249 them. HID and networking devices expose these stable IDs, so that for
250 example you can be sure that you told the right UPS to power down its
254 --------------------
258 - *They can be read,* producing first the device descriptor (18 bytes) and
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
281 you can't rely on them for stable access to devices. For example,
282 it's relatively common for devices to re-enumerate while they are
283 still connected (perhaps someone jostled their power supply, hub,
289 configuration of the device. Multi-byte fields in the device descriptor
297 These files may also be used to write user-level drivers for the USB
314 -------------------------------
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
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 --------------------
365 the modification time on the usbfs file to which they are applied
368 :ref:`usb-error-codes`).
373 hub_wq (in the kernel) setting a device-wide *configuration* that
374 affects things like power consumption and basic functionality. The
398 closing the file descriptor. File modification time is not updated
410 File modification time is not updated by this request.
427 File modification time is not updated by this request.
440 * 'request' becomes the driver->ioctl() 'code' parameter.
442 * is copied to or from the driver->ioctl() 'buf' parameter.
456 File modification time is not updated by this request.
461 devices what device special file should be used. Two pre-defined
471 modification time is not updated by this request.
500 You may issue this ioctl more than one time to narrow said mask.
509 a time.
537 returning ``-EPIPE`` status to a data transfer request. Do not issue
571 time is not updated by this request.
588 File modification time is not updated by this request.
600 modification time is not updated by this request.
624 (It's usually a pointer to per-request data.) Flags can modify requests
659 For these asynchronous requests, the file modification time reflects
664 *TBS* File modification time is not updated by this request.
667 *TBS* File modification time is not updated by this request.
670 *TBS* File modification time is not updated by this request.
673 *TBS* File modification time is not updated by this request.
683 - ``/sys/kernel/debug/usb/devices`` ... a text file showing each of the USB
688 -----------------------------
692 (including class and vendor status) is available from device-specific
704 /* The first time through, this call will return immediately. */
705 poll(&pfd, 1, -1);
713 udev or HAL to initialize a device or start a user-mode helper program,
724 Each line is tagged with a one-character ID for that line::
773 For reasons lost in the mists of time, the Port number is always
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
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
936 ``grep -i ^[tdp]: /sys/kernel/debug/usb/devices`` can be used to list
952 The Configuration lines could be used to list maximum power
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