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
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 -----------------------------
244 - ``/dev/bus/usb/BBB/DDD`` ... magic files exposing the each device's
251 paths are not "stable" identifiers; expect them to change even if you
253 think of saving these in application configuration files.* Stable
255 them. HID and networking devices expose these stable IDs, so that for
256 example you can be sure that you told the right UPS to power down its
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
278 device files at a time. This means that if you are synchronously reading
287 you can't rely on them for stable access to devices. For example,
288 it's relatively common for devices to re-enumerate while they are
289 still connected (perhaps someone jostled their power supply, hub,
295 configuration of the device. Multi-byte fields in the device descriptor
303 These files may also be used to write user-level drivers for the USB
320 -------------------------------
331 Never assume there will only be one such device on the system at a time!
332 If your code can't handle more than one device at a time, at least
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 --------------------
371 the modification time on the usbfs file to which they are applied
374 :ref:`usb-error-codes`).
379 hub_wq (in the kernel) setting a device-wide *configuration* that
380 affects things like power consumption and basic functionality. The
404 closing the file descriptor. File modification time is not updated
416 File modification time is not updated by this request.
433 File modification time is not updated by this request.
446 * 'request' becomes the driver->ioctl() 'code' parameter.
448 * is copied to or from the driver->ioctl() 'buf' parameter.
462 File modification time is not updated by this request.
467 devices what device special file should be used. Two pre-defined
477 modification time is not updated by this request.
506 You may issue this ioctl more than one time to narrow said mask.
515 a time.
543 returning ``-EPIPE`` status to a data transfer request. Do not issue
577 time is not updated by this request.
594 File modification time is not updated by this request.
606 modification time is not updated by this request.
630 (It's usually a pointer to per-request data.) Flags can modify requests
665 For these asynchronous requests, the file modification time reflects
670 *TBS* File modification time is not updated by this request.
673 *TBS* File modification time is not updated by this request.
676 *TBS* File modification time is not updated by this request.
679 *TBS* File modification time is not updated by this request.
689 - ``/sys/kernel/debug/usb/devices`` ... a text file showing each of the USB
694 -----------------------------
698 (including class and vendor status) is available from device-specific
710 /* The first time through, this call will return immediately. */
711 poll(&pfd, 1, -1);
719 udev or HAL to initialize a device or start a user-mode helper program,
730 Each line is tagged with a one-character ID for that line::
779 For reasons lost in the mists of time, the Port number is always
874 rather differently. For example, a bus-powered configuration
875 might be much less capable than one that is self-powered. Only
876 one device configuration can be active at a time; most devices
904 of bus bandwidth, drivers must select a non-default altsetting.
906 Only one setting for an interface may be active at a time, and
907 only one driver may bind to an interface at a time. Most devices
928 the per-microframe data transfer size. For "high bandwidth"
932 With the Linux-USB stack, periodic bandwidth reservations use the
942 ``grep -i ^[tdp]: /sys/kernel/debug/usb/devices`` can be used to list
958 The Configuration lines could be used to list maximum power
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